AGENTS.md and the architecture file you have not written yet

If you have used Cursor, Claude Code, Copilot, or any of the new agentic coding tools, you have probably noticed something: they are great when your project is small and obvious, and they go feral the moment the project gets interesting. Multi-app monorepo? They forget which app they are editing. Strict naming conventions? They quietly violate three of them. Pattern you used in five places? They invent a sixth.

The fix is not "use a smarter model." The fix is to write down the architecture for the agent, the same way you would for a new human teammate. That is what files like AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/, and llms.txt are for.

What goes in them

For Dentra I keep a tight set of these files at the repo root:

• AGENTS.md — vendor-neutral project objectives, architecture rules, coding expectations, conventions, do-and-don't lists.
• CLAUDE.md — Claude-specific context that I want loaded into every session.
• .cursor/rules/ — per-folder rules Cursor auto-applies based on which file you are editing.
• llms.txt — a top-level summary for any future agent that lands on the repo cold.
• ai/HANDOFF.md — what state the project is in right now and what to work on next.
• ai/SESSION_LOG.md — a running log of significant decisions, so the next session has context.

The rules that earn their keep

The rules that consistently change agent behaviour for the better are the boring ones:

"Nothing in packages/ imports from apps/. Ever."

"All new components live in packages/ui. App-specific styles use Tailwind, not inline style props."

"Every new Prisma model needs a migration committed in the same PR."

None of these are clever. All of them are the kind of rules a human teammate would learn in their first week. Writing them down means the agent learns them in the first prompt.

What it does not fix

Agent rules will not save you from a bad architecture. If the project does not have clear boundaries, the rules document will be a mess too. The exercise of writing the rules is itself diagnostic — if you cannot finish a sentence like "all authentication logic lives in…", that is a sign the architecture has a hole, not that the agent needs better instructions.

The new architecture file is the one you write so the agent does not have to guess. Most teams have not written it yet. That is the opportunity.