do-agent-first-repo

Start with an AGENTS.md entry point containing dev commands and repo structure, plus an ARCHITECTURE.md codemap with boundaries and invariants. Grow a docs/ tree with design docs, exec plans, and product specs as complexity demands, keeping all knowledge versioned in the repo.

Progressive disclosure structures documentation in three layers: a ~100-line AGENTS.md entry point, an ARCHITECTURE.md for module relationships, and on-demand domain docs in docs/. Agents start with minimal context and drill deeper through index files and cross-links instead of loading everything upfront.

Encode rules as custom linters with remediation messages, structural dependency tests, and layer boundary checks that fail CI. Prose documentation gets ignored by agents, while CI failures block merges and the lint error messages themselves tell the agent how to fix violations.

Agents replicate existing patterns including bad ones, so a suboptimal pattern used 15 times becomes the dominant convention. Counter this with golden principles, automated violation scans, small continuous refactoring PRs, and quality scores tracked per domain in the repo.

Small projects do not need the full docs/ tree; start with just AGENTS.md and ARCHITECTURE.md and grow as complexity demands. Subjective rules like preferring composition over inheritance cannot be mechanically enforced and are better left as documentation.