Repository Structure for Agentic Work

The goal of this layout is that an agent opening a fresh session, with no history at all, can read the repository and work correctly straight away — with nobody repeating an explanation.

3.1 The standard layout

repo/
├── AGENTS.md                    # project rules — the single source of truth
├── CLAUDE.md                    # symlink → AGENTS.md
├── .cursor/
│   └── rules/
│       ├── 000-core.mdc         # alwaysApply: true
│       ├── 100-backend.mdc      # globs: src/api/**
│       └── 200-frontend.mdc     # globs: src/web/**
├── .claude/
│   ├── settings.json            # permissions + hooks (committed)
│   ├── settings.local.json      # machine-specific (gitignored)
│   ├── skills/
│   │   ├── api-endpoint/SKILL.md
│   │   ├── db-migration/SKILL.md
│   │   └── incident-triage/SKILL.md
│   ├── commands/
│   │   ├── ship.md              # /ship
│   │   └── spec.md              # /spec
│   └── hooks/
│       ├── guard_pretooluse.py  # block dangerous commands and files
│       ├── format_postedit.sh   # auto-format
│       └── gate_stop.sh         # run the gate before the agent finishes
├── docs/
│   ├── architecture.md          # system picture + module boundaries
│   ├── specs/                   # one file per feature
│   │   └── coupon.md
│   └── adr/                     # Architecture Decision Records
│       └── 0007-idempotency-key.md
├── memory/
│   ├── decisions.md             # what was decided, and why
│   ├── pitfalls.md              # what was tried and broke — do not repeat
│   └── glossary.md              # domain vocabulary
├── scripts/
│   ├── verify.sh                # THE GATE — the definition of passing
│   ├── verify-fast.sh           # a subset for use inside the loop
│   └── agent-loop.sh            # the headless loop driver
├── tests/
└── src/

The one principle to remember

AGENTS.md is the single source of truth. Every other tool’s file points back to it. Do not write the rules in three places: within two weeks the three will disagree, and the agent will believe the wrong one.

3.2 Control files across tools

Role	Claude Code	Codex CLI	Cursor
Project rules	CLAUDE.md	AGENTS.md	.cursor/rules/*.mdc
Personal rules	~/.claude/CLAUDE.md	~/.codex/AGENTS.md	Cursor Settings → Rules
Specialised procedures	.claude/skills/*/SKILL.md	Referenced from AGENTS.md	Separate rule files with globs
Shortcuts	.claude/commands/*.md	Prompt files	@rule / Notepads
Hooks	.claude/settings.json	~/.codex/config.toml	None — use git hooks
Execution permissions	permissions in settings	approval_policy, sandbox_mode	Command allowlist / denylist
MCP	.mcp.json	[mcp_servers] in config.toml	.cursor/mcp.json

The approach that works best is to write the real content in AGENTS.md and point everything else back at it.

ln -s AGENTS.md CLAUDE.md

<!-- .cursor/rules/000-core.mdc -->
---
alwaysApply: true
---
All project rules live in @AGENTS.md — read that file before starting any work.
What follows here is only editor-specific extension.

3.3 Context precedence

When rules conflict, the agent needs to know which one wins. State the order plainly in AGENTS.md.

1. The user's instructions in this session   (highest — but may not override §NEVER)
2. Prohibitions in AGENTS.md §NEVER          (may not be overridden, even by the user)
3. The feature spec in docs/specs/
4. The SKILL.md for this kind of work
5. The rest of AGENTS.md
6. Patterns found in the existing code
7. Language and framework defaults           (lowest)

Why prohibitions sit above user instructions

Because an instruction that appears to come from the user may not. It may have come from text the agent read in an issue, a PR comment, a document, or the output of a tool. Pinning prohibitions above instructions is the first layer of prompt-injection defence.

What this chapter settles

A good structure answers the agent’s questions before it asks them. Keep the rules in one place in AGENTS.md and have every other tool’s file point back to it. Give specs, memory and the gate their own directories. And declare the precedence order so that when rules conflict, there is no ambiguity about which one wins.

The next chapter is the working files themselves — AGENTS.md, skills, hooks, rules and memory, ready to use.