Repo Context Is Architecture: AGENTS.md, CLAUDE.md, Docs, and Conventions

Why AI-ready repositories need explicit instructions, commands, architecture notes, and conventions that humans can trust too.

AI coding tools expose a truth that was already there: most repositories depend on unwritten knowledge.

The senior developer knows which test command to run. The person who set up CI knows why one package is pinned. The team lead knows that migrations have to be backward compatible. Someone remembers that a directory is legacy and should not be extended.

The AI does not know any of that unless the repo says it.

That makes repo context part of the architecture.

A clean repo is not enough

Good file organization helps, but AI tools need more than names.

They need answers to questions like:

  • How is this project built?
  • Which commands are safe to run?
  • Which directories are generated?
  • What style should new code follow?
  • What should never be touched without approval?
  • How are migrations handled?
  • How are secrets and environment variables managed?
  • What does "done" mean for a change?

Those are not AI-only questions. They are onboarding questions.

If the repo answers them well, humans benefit first.

Project instructions should be close to the code

Different tools use different instruction files and conventions. Some teams maintain AGENTS.md. Some use CLAUDE.md. Some put guidance in README files, docs folders, or tool-specific settings.

The exact file matters less than the discipline.

The repo should have a clear instruction surface for development agents and humans:

Project overview:
This is a Next.js site with Markdown-authored journal and newsletter content.

Common commands:
- npm run dev
- npm run build

Content rules:
- Journal articles live in content/journal.
- Newsletter issues live in content/newsletter.
- Drafts must use published: false or status: draft.

Safety rules:
- Do not commit .env files.
- Do not run destructive commands without explicit approval.
- Do not modify generated build output.

That context turns vague tool behavior into project-specific behavior.

Commands are contracts

One of the fastest ways to improve AI output is to document the real commands.

Put the common checks somewhere obvious:

Install:
npm install

Develop:
npm run dev

Validate:
npm run build

Database:
npm run db:generate
npm run db:migrate

If a command is slow, say so. If a command needs a service running, say so. If a command writes files, say so.

AI agents should not have to infer the workflow from package.json alone.

Conventions reduce accidental invention

When a repo does not document its patterns, AI fills the gap.

That is how a project ends up with three validation styles, two logging conventions, and a helper abstraction that almost matches the rest of the app.

Document the local pattern:

API routes:
- Validate input at the route boundary.
- Return { ok: false, error: string } for user-facing failures.
- Log provider failures server-side without exposing secrets.

Markdown content:
- Use front matter.
- Keep dates in YYYY-MM-DD format.
- Leave drafts unpublished until reviewed.

This is not busywork. It is pattern protection.

Architecture notes prevent local optimization

AI tools are good at local fixes. Architecture is often about resisting local fixes that create system problems.

If the project has important boundaries, write them down:

  • public site versus admin tooling
  • content source of truth versus send channel
  • local environment versus production environment
  • API contract versus provider-specific behavior
  • generated assets versus editable source

Without those notes, the AI may solve the immediate task in a way that violates the system shape.

Keep the instructions short enough to be used

A giant instruction file becomes another abandoned document.

Start with the essentials:

  • what this repo is
  • how to run it
  • how to test it
  • where important things live
  • what patterns to follow
  • what actions require approval

Then update it when a task reveals missing context.

Good repo instructions are living documents. They improve one incident at a time.

Documentation is agent infrastructure

Teams often treat docs as a separate deliverable. In AI-assisted development, docs are also tool configuration.

The better the docs, the better the agent can act.

That does not mean writing everything down. It means writing down the things that repeatedly affect decisions:

  • setup commands
  • coding conventions
  • deployment rules
  • migration rules
  • review expectations
  • security boundaries
  • product vocabulary

Those notes become shared memory.

The test is a new contributor

Ask a simple question: could a new developer and an AI coding agent both make a safe first change from the repo alone?

If the answer is no, the missing context is probably hurting the team already.

AI does not create the documentation problem. It makes the problem visible.

The fix is not to write more words for the model. The fix is to make the repository honest about how the team actually works.

That is architecture.

Common mistakes

  • Assuming good file organization is enough, when the agent also needs the build command, the generated directories, and the "do not touch" list.
  • Debating which instruction file to use (AGENTS.md versus CLAUDE.md) instead of writing the instructions.
  • Leaving the real commands undocumented, so the agent infers the workflow from package.json alone.
  • Not documenting the local pattern, so the AI invents a third validation style and a near-miss helper.
  • Writing a giant instruction file that no one maintains and no one reads.

Practical checklist

  • The repo has an obvious instruction surface covering what it is, how to run it, how to test it, where things live, patterns to follow, and what needs approval.
  • Real commands are documented, including which are slow, need a service running, or write files.
  • Local conventions for API routes, content, and naming are written down.
  • Important architectural boundaries are stated so local fixes do not violate the system shape.
  • Instructions are short enough to be read and are updated when a task exposes a gap.
  • A new developer and an AI agent could both make a safe first change from the repo alone.
  • Docs are treated as agent configuration, not a separate deliverable.

Previous: Reasoning Is a Company Asset, Not Chat Debris

Next: The AI Development Loop: Plan, Patch, Test, Review, Commit. The next part defines a repeatable loop that keeps AI-assisted implementation legible instead of a chat-driven blur.