Beyond AGENTS.md: the six layers of a coding agent project

Once a project grows, one instructions file stops being enough for a coding agent. That may be the shared AGENTS.md that Codex, Cursor and others read, or CLAUDE.md for Claude Code. The agent repeats a mistake you corrected yesterday, ignores a convention, or fixes one thing and breaks the code next to it.

At that point the model may not be the only problem. The project may not give the agent enough context, limits or ways to check its work. In my AI-assisted development work, I’ve found that the quality of the result depends not just on the model, but on the context, constraints, tools and verification around it.

What helps is moving guidance out of that one file. Rules cover one area, skills cover work you repeat, and sub-agents take separate jobs. Hooks handle what must always happen, a few plain project docs give the why, and a check lets the agent test its own work.

Claude Code is the main example here, because its pieces have clear names. The tool behaviour below comes from each tool’s official documentation, last verified on 4 October 2026.

The environment, in six layers

An AI coding environment has six layers. Instructions (AGENTS.md or CLAUDE.md, and rules) and context (project docs) tell the agent what to do and why. Capabilities (skills, sub-agents) and tools (a CLI, MCP servers, APIs) let it do the work. Verification (tests, lint, build, the diff) and human control (review, approval, permissions) decide when it is done.

┌──────────────────────────────────────────────┐
│            AI CODING ENVIRONMENT             │
├──────────────────────────────────────────────┤
│  INSTRUCTIONS   AGENTS.md / CLAUDE.md, rules │
│  CONTEXT        PRD, architecture, decisions │
│  CAPABILITIES   skills, sub-agents           │
│  TOOLS          CLI, MCP, APIs               │
│  VERIFICATION   tests, lint, build, diff     │
│  HUMAN CONTROL  review, approval, permissions│
└──────────────────────────────────────────────┘

Put together in one repository, with Claude Code as the example, it might look like this. No agent requires this layout. AGENTS.md holds the shared instructions. CLAUDE.md, the .claude/ folder and .mcp.json are Claude Code’s own pieces; other agents keep theirs in their own files and folders (the table near the end lists their instructions files). The docs/ folder is a convention I recommend for bigger codebases.

project/
├── AGENTS.md            # shared instructions
├── CLAUDE.md            # Claude Code: @AGENTS.md
├── docs/
│   ├── PRD.md
│   ├── ARCHITECTURE.md
│   ├── DESIGN.md
│   ├── CONVENTIONS.md
│   ├── TASKS.md
│   └── DECISIONS.md
├── .claude/             # Claude Code's own folder
│   ├── rules/
│   ├── skills/
│   ├── agents/
│   └── settings.json
├── .mcp.json
├── src/
└── tests/

The instructions file is the start, not the whole system

Most coding agents read a project instructions file at the start of a session. Codex, Cursor, Antigravity and Copilot’s agents read the shared AGENTS.md. Claude Code reads its own CLAUDE.md, and reads AGENTS.md too when there is no CLAUDE.md. Each tool loads them by its own rules (the table near the end has the details).

An example for a Next.js project might look like this:

# Project instructions

## Project
Next.js application using TypeScript.

## Architecture
- App Router
- Server components by default
- API routes under src/app/api
- Shared UI components under src/components

## Coding rules
- TypeScript strict mode
- Avoid `any` unless there is a clear reason
- Prefer existing utilities before creating new ones

## Checks
Run after changes: npm run lint, npm run test, npm run build

## Before modifying code
- Read the relevant files first
- Follow existing patterns
- Do not add a dependency without a reason

Anthropic’s best practices warn that in a bloated CLAUDE.md, Claude starts ignoring instructions, because the important rules get lost in the noise. The same page gives a test for each line: would removing this cause the agent to make mistakes? If not, cut it. I’d apply the same test to any agent’s instructions file; VS Code’s Copilot docs give similar advice: keep instructions “short and self-contained”.

Move repeated guidance out of the instructions file

Rules for one area

Most agents have a place for guidance about one area: path-specific .instructions.md files under .github/instructions/ in GitHub Copilot (docs), .cursor/rules/ in Cursor (docs) and .agents/rules/ folders in Antigravity (docs). In Claude Code, rule files live in .claude/rules/. A rule without a paths field in its frontmatter loads every session, and a rule with one loads only when Claude works with files that match (docs). An example rule for API code:

---
paths:
  - "src/api/**"
---
- Validate every request body with the shared schema helper.
- Return errors in the standard error shape.

With a file pattern on each area’s rules, the agent gets the backend rules when it works on the backend, and the rest stays out of its context.

Skills for work you repeat

A skill is a folder with a SKILL.md that packages a workflow once: instructions, reference files, examples and scripts. Skills are an open format that Claude Code, Codex, Cursor, Gemini CLI and GitHub Copilot’s agents all support, so one skill can work across them. Only the skill’s short description stays in the agent’s context all the time. The full instructions load when the skill is needed, either because the agent decides it fits or because you call it by name (Claude Code skills docs). So you can keep several skills without paying for all of them in every conversation, and you stop explaining how you want a security review done for the tenth time.

Sub-agents for a separate job

A sub-agent is a specialised worker with its own context window and its own set of allowed tools. In Claude Code they live in .claude/agents/ (sub-agents docs). Cursor has subagents too, each with its own context window, in .cursor/agents/ (docs), and GitHub Copilot has custom agents in .github/agents/ (docs). Jobs that fit:

• A code reviewer looks for bugs, hard-to-maintain code and changes that break the architecture.
• A security reviewer looks for secrets in code, broken authentication or authorisation, injection risks and unsafe dependencies.
• A test writer focuses on unit tests, integration tests, edge cases and regression cover.

A fresh context helps review in particular: a reviewer that did not write the code is not biased towards it. Add a sub-agent only when the work needs a different context, responsibility or set of tools.

MCP, or a CLI, for outside tools

MCP (Model Context Protocol) is an open standard for connecting AI applications to outside tools and data sources. In a coding workflow, that can mean GitHub, a database, documentation, an issue tracker, a browser or internal tools. For services that already have a command-line tool, like gh for GitHub, Anthropic’s best practices call the CLI the most context-efficient option. Add an MCP server when it gives the agent something a CLI cannot.

Project docs: the context code cannot give

Project docs are plain documents the agent reads when a task needs them. They work the same in every agent, and each answers one question:

I prefer a DECISIONS.md to a general notes file. A short, dated decision log tells the agent, and the next human, why something is the way it is, so it does not “fix” a choice you made on purpose. I name the conventions file CONVENTIONS.md, because the agent’s rules already live in its own rules folder (.claude/rules/ in Claude Code), and the same rule in two places will drift.

Checks and hooks: what the agent cannot skip

A check the agent can run is, in the words of Anthropic’s best practices, “the difference between a session you watch and one you walk away from”. Without one, “looks done” is the only signal, and you become the test suite.

Task → implementation → tests → lint → type check → build → diff review → evidence → done

Put the check commands in the instructions file, and ask for evidence at the end: the commands run, their results and the diff. Reading evidence is faster than repeating the checks yourself.

A line in AGENTS.md or CLAUDE.md that says “never modify production config” is guidance the agent can miss, so it is not a security boundary. When an action must really be blocked, use the tool’s enforcement:

• Permissions decide which tools and commands run without asking, need your approval, or are denied outright.
• Sandboxing limits which files and network domains the agent’s shell commands can reach, enforced by the operating system.
• A hook is usually a shell script. Claude Code runs it every time a matching event happens, for example to run the linter after each edit or to block writes to a folder.

Three prompts to copy

An agent that jumps straight to coding can solve the wrong problem. So explore first, then plan, then code. That order is Anthropic’s recommended workflow for Claude Code, which has a plan mode for it (press Shift+Tab until it shows plan mode). Other agents have their own modes and commands for this, so the prompts below spell out each step in plain words.

Prompt 1: investigate before coding

Use it before any change that touches more than one file.

You are working as an AI software engineer inside an existing codebase.

Task: <describe the task>

Before making any changes, understand the project. Investigate only what this
task needs; use sub-agents for broad searches if your tool has them.

1. Identify the framework, language, package manager, build system and test setup.
2. Read the project instructions (AGENTS.md, CLAUDE.md or your agent's
   equivalent) and any rules or agent instructions that apply.
3. Read the relevant project docs when they exist: PRD, architecture,
   design, conventions, decisions and tasks.
4. Identify the files and modules relevant to the task.
5. Read existing implementations before proposing new patterns.
6. List existing utilities, components, services, hooks, types and tests
   that should be reused.
7. Check for constraints or architectural decisions that affect the task.
8. Do not modify files yet.

Do not assume a file, pattern, dependency or architectural decision exists
because it is common in similar projects. Verify it in this repository.
For important conclusions, name the files or paths you inspected.

After investigating, give me:

- Your understanding of the task
- The relevant files you found
- Existing patterns to follow
- Dependencies or constraints
- Possible risks
- Your proposed implementation approach
- The tests or checks needed

Then STOP. Do not write or change code until I approve the plan.

Prompt 2: implement and verify

Send it once you have read the plan and agree with it.

Proceed with the approved implementation plan.

Before editing:

1. Re-check the relevant files.
2. Follow existing project conventions.
3. Reuse existing abstractions where appropriate.
4. Do not add unnecessary dependencies.
5. Keep the change focused on the requested task.

While implementing:

- Make the smallest maintainable change that does the job.
- Preserve existing behaviour unless the task requires changing it.
- Add or update tests where appropriate.
- Do not change a test just to make it pass, unless the test itself is
  clearly wrong; if so, tell me which test and why.
- Do not commit, push or run destructive commands unless I ask.

After implementing:

1. Run the relevant tests.
2. Run lint, type checks and the build where they apply.
3. Inspect the final git diff and list:
   - files changed, added and deleted
   - behaviour that changed
   - tests added or modified
   - anything that remains unverified
4. Look for changes you did not intend.
5. Report which checks you ran, with their results.

If a check fails, find and fix the real cause. Do not hide or skip the
failure. If it still fails after two attempts, stop and report what you found.

Prompt 3: bootstrap the AI environment

Use it the day you prepare a repository for AI-assisted work. It asks for a proposal before any new files.

Act as a senior software architect helping me prepare this repository for
AI-assisted development.

Do not implement application features.

First inspect the repository and understand:

- technology stack
- application structure and entry points
- build system
- testing setup
- linting and type checking
- deployment and environment configuration (do not open or print secret
  values; only note where they are kept)
- existing documentation
- architectural patterns
- dependencies
- security-sensitive areas

Then propose an operating environment for AI-assisted development. Consider:

1. Project instructions (AGENTS.md or CLAUDE.md): project-wide
   instructions, coding conventions, check commands.
2. Project documentation: PRD, architecture, design, conventions, tasks,
   architectural decisions.
3. Reusable skills: code review, testing, security review, release checks,
   project-specific workflows.
4. Specialised agents: only where specialisation clearly helps.
5. Hooks, permissions and automation: only where a deterministic check or a
   hard limit is useful. Show the exact command for any hook you propose.
6. MCP integrations: only where outside tools or data would clearly improve
   the workflow.

Do not create documentation that only restates the codebase. Only write
documentation that captures what cannot be reliably inferred from the code.

Do not create anything yet. First propose the structure and explain:

- why each piece is needed
- what problem it solves
- what should NOT be added
- what should stay simple

Put minimal complexity, maintainability, security and developer control
first. Wait for my approval before creating files.

Without the line about documentation, an agent will happily write an ARCHITECTURE.md that says “the application has a frontend and a backend”, which nobody needed.

AGENTS.md in Copilot, Cursor, Codex and Antigravity

Each coding agent has its own instructions file, and most now read the shared AGENTS.md as well:

Each row comes from that tool’s own docs, last verified on 4 October 2026; none of them was tested for this post.

If your team uses more than one agent, keep the shared engineering rules in one AGENTS.md. For Claude Code, start CLAUDE.md with an @AGENTS.md import, so it reads the shared file and then its own additions (docs):

                 AGENTS.md (shared rules)
                          │
        ┌─────────────────┼─────────────────┐
        ↓                 ↓                 ↓
   Claude Code          Codex             Cursor
   CLAUDE.md starts     reads it       .cursor/rules/
   with @AGENTS.md      directly        Cursor-only

Scoped rules, skills, sub-agents and MCP exist in most of these tools too, under different names and folders. Check each tool’s docs before copying a Claude Code folder into another agent.

Which piece do you need?

There is no universal structure for AI coding projects. A small project may need only this:

AGENTS.md (or CLAUDE.md)
README.md
tests/

Start with the instructions file and your checks.

Quick answers

What is an agent instructions file?

An agent instructions file is a Markdown file of project instructions that a coding agent reads at the start of a session. Codex, Cursor, GitHub Copilot and several other tools read the shared AGENTS.md; Claude Code reads its own CLAUDE.md, or AGENTS.md when there is no CLAUDE.md. It holds the commands, conventions and checks the agent cannot work out from the code, kept short so the important rules are less likely to get lost.

What is AGENTS.md?

AGENTS.md is an open format for coding-agent instructions that many tools read, including OpenAI Codex, Cursor, GitHub Copilot and Google Antigravity. Claude Code reads it by default only when there is no CLAUDE.md, or through an @AGENTS.md import.

What is the difference between a skill and a sub-agent?

A skill is a packaged workflow the main agent follows, loaded only when it is needed. A sub-agent is a separate worker with its own context window and tools, used for a job that benefits from isolation, such as an independent code review.

Is an instructions file a security control?

No. AGENTS.md, CLAUDE.md and other instructions files are advice the agent can miss. Anything that must never happen belongs in what the tool enforces, such as permissions, sandboxing or hooks, where your tool offers them.

How should I prepare a codebase for an AI coding agent?

A codebase is ready for an AI coding agent when it has a short instructions file and a check the agent can run, such as tests, lint and a build. For any larger change, ask the agent to investigate and plan before it writes code.

More on AI coding is in the AI category.