How to Structure Your Repository for AI Coding Agents

In the previous article, we looked at how tools such as Cursor, Aider, and Claude Code discover relevant code inside large repositories.

But finding the right files is only half the problem.

An AI coding agent may successfully locate your payment service, API routes, database models, and tests—and still make the wrong change.

Finding code does not automatically tell the agent how your team expects that code to be changed.

It may not know that:

• 01 business logic belongs in services rather than controllers
• 02 database access must go through repositories
• 03 generated files should never be edited manually
• 04 a specific test suite must run after schema changes
• 05 API changes require OpenAPI documentation
• 06 a legacy module should not be used for new functionality

A human developer learns these things from teammates, documentation, code reviews, and experience. An AI agent needs those expectations made explicit.

That is the purpose of repository level agent instructions. And as coding agents become more autonomous, structuring those instructions well is becoming an important part of software engineering.

Your repository is becoming an interface for AI

Traditionally, repository structure was designed primarily for humans. A developer clones a project, reads the README.md, explores a few folders, speaks to another engineer, and gradually builds a mental model of the system.

AI agents work differently.

They use repository structure itself as a source of information. That means your repository is becoming more than a place to store source code. It is becoming an interface through which AI agents understand your software.

Fig. 01 — Structure before source

A well structured repository might look something like this:

├── AGENTS.md
├── README.md
├── package.json
├── apps/
│   ├── web/
│   │   ├── AGENTS.md
│   │   └── src/
│   └── api/
│       ├── AGENTS.md
│       └── src/
├── packages/
│   ├── billing/
│   ├── database/
│   └── auth/
├── docs/
│   ├── architecture.md
│   ├── billing.md
│   └── deployment.md
└── tests/

There are clear boundaries. There is shared documentation. There are project instructions. And individual parts of the system can provide more specific guidance when necessary.

AGENTS.md: a README for coding agents

One of the most important developments in this area is AGENTS.md. The idea is intentionally simple:

If README.md tells humans how to work with a repository, AGENTS.md tells coding agents.

The format uses ordinary Markdown and does not require a complicated schema. A basic example could look like this:

# AGENTS.md

## Project

This repository contains our SaaS platform.

- `apps/web` contains the customer facing Next.js application
- `apps/api` contains the backend API
- `packages/core` contains shared domain logic
- `packages/database` contains database access

## Commands

Install dependencies: `pnpm install`
Run development: `pnpm dev`
Run tests: `pnpm test`
Run type checking: `pnpm typecheck`

## Architecture

- Business logic belongs in service classes.
- API controllers should remain thin.
- Database access must go through repository classes.
- Shared domain logic belongs in `packages/core`.

## Testing

- Add tests for new business logic.
- Run the relevant package tests after modifications.
- Run `pnpm typecheck` before completing a task.

## Do Not Modify

- Generated files
- Build output
- Database migration history that has already been deployed

There is nothing sophisticated about the format. That is partly why it is useful. AGENTS.md has grown into a cross tool convention and is now stewarded by the Agentic AI Foundation under the Linux Foundation. The official project describes it as a predictable place for build instructions, tests, conventions, security considerations, and other information coding agents need to work reliably with a repository.

What should actually go into AGENTS.md?

This is where many teams make their first mistake.

Once they discover persistent agent instructions, they start putting everything into them: architecture documentation, formatting rules, deployment procedures, database schemas, coding standards, examples, historical decisions, API specifications.

Eventually the file becomes hundreds or thousands of lines long. The agent technically has more information. But once again, more context does not necessarily mean better context.

What information does an agent need for almost every task in this repository?

That is what belongs in the root instruction file. Usually this includes four categories.

For example:

## Repository Structure
- `apps/storefront` — customer facing application
- `apps/admin` — internal administration application
- `packages/core` — domain logic shared between applications
- `packages/database` — ORM models and repositories

## Architecture
- Controllers handle transport concerns only.
- Business logic belongs in services.
- Database access must go through repositories.
- Do not import database clients directly into API handlers.

## Verification
- Unit tests: `pnpm test`
- Type checking: `pnpm typecheck`
- Linting: `pnpm lint`
- Production build: `pnpm build`

## Important Constraints
- Never edit generated GraphQL types manually.
- Never modify a migration that has already reached production.
- Payment webhook handlers must remain idempotent.

Keep the root instructions small

Persistent instructions occupy context. That means every rule has a cost.

Claude Code’s current documentation explicitly recommends keeping CLAUDE.md concise and suggests targeting fewer than roughly 200 lines, noting that longer files consume more context and can reduce instruction adherence. Claude Code docs, “How Claude remembers your project” Cursor similarly recommends keeping rules focused and splitting large rule sets rather than creating one enormous file.

Your main agent instruction file should be a map, not an encyclopedia.

Fig. 02 — Map, not encyclopedia

Use nested instructions for monorepos

A single global file becomes especially problematic in a large monorepo. The mobile application may have completely different conventions from the backend. Putting every rule into the root AGENTS.md means an agent working on a React component may receive instructions about database migrations and background workers.

A better structure is hierarchical:

├── AGENTS.md
├── apps/
│   ├── storefront/AGENTS.md
│   └── api/AGENTS.md
└── packages/
    └── billing/AGENTS.md

The root contains instructions that apply everywhere. Then individual areas contain local rules.

Nested AGENTS.md files are part of the documented convention, with more specific instructions applying closer to the files being changed. Codex also resolves instructions hierarchically across repository directories, while Cursor currently supports nested AGENTS.md files as well.

What about CLAUDE.md?

Claude Code has its own native instruction format: CLAUDE.md. Its purpose is similar. A project level file can contain architecture, commands, conventions, workflows, naming rules, and important constraints.

Claude Code can also discover more specific CLAUDE.md files in subdirectories as it enters those parts of a repository. For larger projects, it supports modular rules under .claude/rules/, including rules scoped to particular paths.

That creates an obvious problem for teams using multiple agents.

Do you maintain AGENTS.md, CLAUDE.md, and .cursor/rules/ with copies of the same instructions? Ideally, no. Duplicated instructions eventually drift.

Fig. 03 — Instruction drift

Use one source of truth where possible

A better pattern is to keep shared guidance in one place and add tool specific configuration only where necessary.

The main project guidance lives in AGENTS.md. Then Claude Code can use a small CLAUDE.md that imports it:

@AGENTS.md

## Claude Specific Instructions

Use the Explore agent when investigating unfamiliar areas of the monorepo.

Claude Code’s documentation explicitly recommends this approach for repositories already using AGENTS.md: a CLAUDE.md can import the shared file and append Claude specific guidance.

An import is useful for avoiding duplicated maintenance, but importing a large document does not magically save context. Imported files still occupy the context window. Keep the shared source small for the same reason you keep any persistent instruction file small.

Cursor has a more structured project rules system under .cursor/rules/. These .mdc files can be scoped according to relevance or file patterns.

├── api.mdc          → packages/database/**
├── frontend.mdc     → apps/web/**/*.tsx
└── database.mdc     → packages/database/**

Cursor’s documentation recommends keeping rules focused, version controlling project rules, and using scoped rules instead of applying everything to every conversation.

1. Portable instructionsCommon engineering knowledge in AGENTS.md.
2. Tool specific behaviourConditional rules in .cursor/rules/ and .claude/rules/.
3. Use proprietary config only when neededPrefer portable documentation unless the tool provides functionality you actually require.

Don't put formatting rules in AI context

An AI can follow indentation, quote style, trailing commas, and line length rules. It should not have to. These are deterministic problems. Use deterministic tools: Prettier, ESLint, Biome, Ruff, Black, gofmt, rustfmt.

Then your agent instructions can simply say:

Run `pnpm lint` before completing the task.

The formatter becomes the source of truth. The agent’s context can remain focused on decisions that actually require reasoning.

Turn instructions into automation. A rule asks the agent to behave correctly. Automation tests whether it actually did.

Documentation should be discoverable, not permanently loaded

A healthy AI ready repository might contain architecture, authentication, billing, database, deployment, and integration notes under docs/. Your main instructions do not need to contain all of this information. They simply need to help the agent discover it.

## Documentation

Before changing authentication:
read `docs/authentication.md`.

Before modifying billing or subscription behaviour:
read `docs/billing.md`.

Shopify integration architecture:
`docs/integrations/shopify.md`.

This creates progressive disclosure. The agent begins with minimal context. It loads deeper knowledge only when the task requires it. That is exactly the behaviour we want.

Give agents canonical examples

Documentation is not the only source of truth. Code itself is often better. Suppose your repository contains 120 React components. Instead of writing 50 rules describing the ideal component architecture, tell the agent:

For new dashboard components, follow the structure used in `apps/web/components/dashboard/RevenueCard.tsx`.

Fig. 04 — Canonical example

Cursor’s own guidance similarly recommends pointing rules toward canonical files rather than copying large examples directly into persistent instructions.

Treat agent instructions like production code

There is another mistake teams eventually make. They create agent rules once and never maintain them again. Six months later, commands have changed, directories have moved, architectural decisions have evolved, and instructions contradict the actual code.

The agent is now being confidently given outdated information. That can be worse than giving it no information at all.

Your agent configuration should therefore be treated as living engineering infrastructure. Review it when architecture changes. Modify it when an agent repeatedly makes the same mistake. Delete rules that no longer matter. Keep the files in version control so changes are reviewed alongside the code they affect.

If you have corrected an agent twice for the same repository specific mistake, ask whether the repository should teach that rule automatically.

An AI friendly repository is usually a human friendly repository

Very little of this is exclusively about AI. Clear directory structure, meaningful names, explicit architecture, small modules, documented commands, reliable tests, automated formatting, predictable conventions, up to date documentation, and clearly defined boundaries also describe a repository that is easier for a new developer to understand.

AI agents expose poor repository structure because they cannot rely on years of institutional knowledge to compensate for it. If three senior developers know that nobody should use LegacyPaymentService, but that fact exists only in their heads, the repository has a documentation problem. The AI agent simply makes that problem visible.

A practical repository structure

For many modern projects, a good starting point looks like this:

├── AGENTS.md
├── README.md
├── docs/
├── apps/
│   ├── web/AGENTS.md
│   └── api/AGENTS.md
├── packages/
├── .cursor/rules/
├── .claude/rules/
└── tests/

The important part is not copying this exact directory tree. The important part is the separation of responsibilities:

1. Root instructionsExplain what matters everywhere.
2. Nested instructionsExplain what matters locally.
3. DocumentationContains deeper knowledge, loaded on demand.
4. Tool specific rulesAdd conditional behaviour where useful.
5. Linters, tests, and the codeEnforce deterministic requirements. The code remains the ultimate source of truth.

The key principle

A coding agent should not need a 50-page manual before touching your repository. It needs:

1. enough information to understand the project
2. enough structure to locate the relevant code
3. enough instruction to respect architectural boundaries
4. enough documentation to investigate unfamiliar areas
5. enough automation to prove its changes are correct

The objective is not to document everything twice for the benefit of AI. It is to build a repository where knowledge is structured, discoverable, scoped, and verifiable.

That is a much stronger system than trying to write one enormous prompt that explains your entire application.