178 lines
7 KiB
Markdown
178 lines
7 KiB
Markdown
---
|
||
description: Set up or optimize a large repository or monorepo for agent-first development using hierarchical AGENTS.md files and progressive disclosure
|
||
---
|
||
|
||
Set up or optimize the current repository for agent-first development, assuming it may be a large repo or monorepo. Use hierarchical `AGENTS.md` files only where they add real value. Based on principles from OpenAI's harness engineering and HumanLayer's CLAUDE.md guide.
|
||
|
||
Additional user context and constraints:
|
||
$ARGUMENTS
|
||
|
||
Before changing anything:
|
||
1. Inspect the repository structure first.
|
||
2. Identify true subsystem boundaries before proposing nested `AGENTS.md` files.
|
||
3. Prefer minimal, high-leverage, versioned changes.
|
||
4. Preserve useful project-specific guidance instead of replacing it blindly.
|
||
5. Do **not** generate `AGENTS.md` files for every directory.
|
||
|
||
## When to Use
|
||
- Large repositories with multiple domains, apps, services, or packages
|
||
- Monorepos with different build/test workflows per subtree
|
||
- Repos where one root `AGENTS.md` is too broad to stay short and useful
|
||
- Repos that need progressive disclosure for agent context
|
||
|
||
## Goal
|
||
Design an agent-legible documentation layout where:
|
||
- the root `AGENTS.md` stays short and repo-wide,
|
||
- nested `AGENTS.md` files exist only for meaningful boundaries,
|
||
- each nested file contains local rules, commands, and navigation help for that subtree,
|
||
- duplication across levels is minimized.
|
||
|
||
## Core Principles
|
||
|
||
### 1. Root AGENTS.md Is the Map
|
||
- The root `AGENTS.md` should remain a concise project-wide entry point.
|
||
- It should describe the repo, major subsystems, shared commands, verification, and where deeper context lives.
|
||
- It should point agents toward important subtrees that have their own `AGENTS.md`.
|
||
|
||
### 2. Nested AGENTS.md Files Are Scoped
|
||
Create nested `AGENTS.md` files only when a subtree has at least one of these:
|
||
- a distinct purpose or domain boundary,
|
||
- different commands or verification workflow,
|
||
- different conventions or architectural constraints,
|
||
- separate deploy/runtime concerns,
|
||
- enough complexity that local guidance reduces confusion.
|
||
|
||
If a subtree has no distinct guidance, do **not** create a nested `AGENTS.md` there.
|
||
|
||
### 3. Progressive Disclosure Over Duplication
|
||
- Parent files provide broad context.
|
||
- Child files add only local context.
|
||
- Do not copy the same rules into every nested file.
|
||
- Child files should extend or narrow the parent context, not restate it.
|
||
|
||
### 4. Repository = System of Record
|
||
- If a decision matters for agents, put it in the repo.
|
||
- Architecture, conventions, plans, and decisions should live in versioned docs.
|
||
- Avoid relying on external-only knowledge.
|
||
|
||
### 5. Enforce, Don’t Instruct
|
||
- Put invariants into CI, tests, linters, type checks, and scripts whenever possible.
|
||
- Document verification commands the agent can actually run.
|
||
- Avoid instructions that cannot be checked mechanically.
|
||
|
||
### 6. Less Instructions = Better Compliance
|
||
- Keep every `AGENTS.md` compact.
|
||
- Root file should usually stay under ~100 lines.
|
||
- Nested files should be even narrower: only the local rules that matter for that subtree.
|
||
|
||
## Suggested Hierarchy
|
||
|
||
Only as needed, not by default:
|
||
|
||
```text
|
||
project/
|
||
├── AGENTS.md # project-wide context and repo map
|
||
├── CLAUDE.md -> AGENTS.md
|
||
├── docs/
|
||
│ ├── ARCHITECTURE.md
|
||
│ ├── CONVENTIONS.md
|
||
│ ├── DECISIONS.md
|
||
│ └── PLANS.md
|
||
├── apps/
|
||
│ ├── AGENTS.md # app-layer guidance, if meaningful
|
||
│ ├── web/
|
||
│ │ └── AGENTS.md # only if web has distinct workflow/conventions
|
||
│ └── api/
|
||
│ └── AGENTS.md # only if api has distinct workflow/conventions
|
||
└── packages/
|
||
├── AGENTS.md # shared package conventions, if meaningful
|
||
└── design-system/
|
||
└── AGENTS.md # only if this subtree needs extra local guidance
|
||
```
|
||
|
||
## Heuristics for Where to Add Nested AGENTS.md
|
||
|
||
Good candidates:
|
||
- `apps/`, `services/`, `packages/`, `libs/`
|
||
- frontend vs backend boundaries
|
||
- infra / deployment / ops directories
|
||
- design systems or component libraries
|
||
- generated-code boundaries with special rules
|
||
- domains with their own test/build/dev commands
|
||
|
||
Poor candidates:
|
||
- shallow folders with no local rules
|
||
- directories that only mirror code organization but not workflow differences
|
||
- every leaf folder in the tree
|
||
- locations where the nested file would just repeat the parent file
|
||
|
||
## What Each Level Should Contain
|
||
|
||
### Root `AGENTS.md`
|
||
Include:
|
||
- project summary
|
||
- stack overview
|
||
- top-level repo map
|
||
- key shared commands
|
||
- verification commands
|
||
- links to `docs/`
|
||
- pointers to nested `AGENTS.md` files where relevant
|
||
- only universal repo-wide rules
|
||
|
||
### Nested `AGENTS.md`
|
||
Include only local details such as:
|
||
- purpose of that subtree
|
||
- important local directories/files
|
||
- local dev/build/test commands
|
||
- local patterns or constraints
|
||
- where to find deeper docs for that subsystem
|
||
- any local generated-code or migration rules
|
||
|
||
Do **not** repeat broad repo-wide guidance unless needed for clarity.
|
||
|
||
## Recommended Process
|
||
|
||
1. Inspect the repo structure and tooling.
|
||
2. Identify subsystem boundaries that actually justify local guidance.
|
||
3. Design the smallest useful hierarchy of `AGENTS.md` files.
|
||
4. Create or refine root `AGENTS.md` first.
|
||
5. Add nested `AGENTS.md` files only for meaningful subtrees.
|
||
6. Add or update `docs/` files for architecture/conventions/decisions as needed.
|
||
7. Ensure `CLAUDE.md` exists as a symlink to root `AGENTS.md`.
|
||
8. Keep files concise and avoid duplication.
|
||
|
||
## AGENTS.md ↔ CLAUDE.md Symlink
|
||
|
||
Always ensure both files exist so the repo works with any agent harness (Claude Code, OpenCode, Codex, etc.).
|
||
|
||
**Rules:**
|
||
- `AGENTS.md` is the source of truth (canonical file).
|
||
- `CLAUDE.md` is a symlink to `AGENTS.md`.
|
||
- If only `CLAUDE.md` exists, rename it to `AGENTS.md` and create the symlink.
|
||
- If both exist as separate files, merge into `AGENTS.md` and replace `CLAUDE.md` with symlink.
|
||
- Add `CLAUDE.md` symlink to git (git tracks symlinks fine).
|
||
|
||
## Checklist
|
||
|
||
When initializing or optimizing a large repo or monorepo:
|
||
|
||
- [ ] Root `AGENTS.md` exists and stays short
|
||
- [ ] Root `CLAUDE.md` is a symlink to `AGENTS.md`
|
||
- [ ] Root file contains only repo-wide guidance
|
||
- [ ] Nested `AGENTS.md` files exist only at meaningful subsystem boundaries
|
||
- [ ] Nested files add local context instead of duplicating parent guidance
|
||
- [ ] `docs/` exists with at least `ARCHITECTURE.md`
|
||
- [ ] Verification commands are documented and runnable
|
||
- [ ] CI/linters enforce important invariants where possible
|
||
- [ ] No critical workflow or architectural knowledge lives only outside the repo
|
||
|
||
## Anti-Patterns
|
||
- ❌ Generating `AGENTS.md` in every directory
|
||
- ❌ Repeating the same instructions at root and child levels
|
||
- ❌ Putting domain-specific rules into the root file when they only matter in one subtree
|
||
- ❌ Creating deep hierarchy without distinct workflow boundaries
|
||
- ❌ Letting nested files drift from actual commands and tooling
|
||
|
||
## Sources
|
||
- OpenAI: https://openai.com/index/harness-engineering/
|
||
- HumanLayer: https://www.humanlayer.dev/blog/writing-a-good-claude-md
|