📁 Adopt a predictable structure
A predictable repository reduces the context the agent needs to load and the number of assumptions it makes. The same goes for someone who joined the team yesterday— both audiences want the same thing.
How to read: AGENTS.md at the center points to to the four folders — it doesn’t copy their contents. The arrows go from outside to inside because each folder owns its own truth; the map only says where to look. An AGENTS.md that tries to contain everything becomes yet another outdated source.
Predictable
Discoverable without a guided tour
Convention
Beyond configuration
Name
It’s infrastructure
Two audiences
New human and agent
🚧 Make Module Boundaries Explicit
An agent respects the boundaries it can see. A boundary that exists only in the architect’s head will be crossed—and, worse, crossed consistently and with well-written code, making it difficult to notice.
Example structure
/docs arquitetura.md dominios.md decisoes/ playbooks/ /specs pagamentos/ usuarios/ /skills criar-migracao/ revisar-api/ corrigir-bug/ /scripts validate.sh test-changed.sh AGENTS.md README.md
Each folder has an owner and a purpose. An agent entering this repository knows where to look for the spec, where to find decisions, and what to run to validate.
💡 Practical tip
Write the boundaries as an executable import rule (what /pagamentos may import, what it can't). That way, it becomes a gate in CI, not a recommendation in a document—exactly the principle of module 3.3.
Visible
Otherwise, it gets overridden
Verifiable
Import rule
Contract
Across domains
Scope
The boundary limits the task
📚 Keep documentation close to the code
Documentation versioned in the repository is reviewed alongside the code and becomes available in the agent’s context with no extra effort. Documentation in an external tool turns into folklore within three months.
✓ Documentation that stays up to date
- ✓Lives in the repository and changes in the same PR as the code
- ✓Records decisions and the why, not the framework syntax
- ✓Short enough to read in full
- ✓References the code instead of repeating what it does
✗ Documentation that gets in the way
- ✗Describes the system that was intended, not what exists
- ✗Duplicates information that’s already in the code
- ✗It exists in three places, in three different versions
- ✗Nobody knows which one is current—not even the agent
In the repo
Go to the review
Decision
Record the why
Outdated
Worse than missing
Short
The one that’s read is the one that serves
⌨️ Standardize commands and quick local tests
One command per intent, the same on everyone’s machine and in CI. That’s what lets the agent close the loop on its own— without a default command, it makes one up—and gets it wrong.
🧪 Copyable exercise — audit your repository’s readability
Objective: find out what an agent can’t infer from your repo today. Run this in a clean session without giving any prior explanation.
Você acabou de entrar neste repositório e não tem nenhum contexto além dele. Não pergunte nada agora; responda com o que conseguir deduzir dos arquivos. 1. o que este sistema faz? (3 linhas) 2. como eu instalo, testo, linto e builduei? (comandos exatos) 3. onde ficam: regras de negócio, decisões de arquitetura, specs? 4. quais são as fronteiras entre módulos e o que NÃO pode importar o quê? 5. o que eu NÃO devo alterar sem aprovação? 6. liste tudo que você teve que SUPOR para responder acima. Seja honesto no item 6 — é o item mais importante da resposta.
How to verify: the list in item 6 is your readability backlog. Each assumption is something the next agent (and the next person you hire) will get wrong. Fix the repository — not the prompt.
A command
By intent
Local = CI
Same result
Fast
Enables the loop
Assumption
It’s your backlog
📄 Write AGENTS.md as a map
The AGENTS.md can contain an overview of the system, main commands, project rules, documentation location, limitations, quality criteria, prohibited actions, and references to skills and playbooks. It shouldn’t hold all the knowledge—it should serve as a map.
🧭 Good AGENTS.md test
- •Does it fit on a screen and a half? If not, you’re duplicating another source.
- •Does it include the exact, copyable commands, without "it's probably npm test"?
- •Are the prohibitions explicit and prominent?
- •Does it point to where the truth about each topic lives instead of repeating it?
- •Was it reviewed in the last quarter?
⚠️ Attention
A 900-line AGENTS.md won’t be read in full—not by people, and not usefully by an agent that needs to quickly find what matters. An instruction nobody reads is an instruction that doesn’t exist, with the added downside of creating a false sense of control.
Map
Point, don’t describe
Commands
Precise and copyable
Prohibitions
Featured
Reviewed
How code
🎯 Ensure there is a single source of truth
When faced with two conflicting sources, the agent silently chooses one. You discover which one during review, and usually at the worst possible time.
One owner per area
Commands go in AGENTS.md; the contract goes in the spec; the decision goes in /docs/decisoes. Anyone who needs the topic references its owner.
Reference instead of copy
Every copy diverges — it’s only a matter of time. A link to the right file ages much better than a pasted excerpt.
Deleting obsolete things is real work
Old documents don’t disappear on their own and keep entering the agent’s context. Removing the old version is more valuable than writing the new one.
Quick check: what’s the best AGENTS.md?
An owner
By topic
Reference
Never copy
Delete
Outdated things get in the way
Conflict
It chooses on its own
📌 Module Summary
Next Module:
4.3 - Overengineering and technical debt generated by AI.