AGENTS.md

English | 中文

Stop your AI agents from turning your repo into a mess.

A governance system for AI coding agents that keeps instructions stable, context organized, and your project root clean — across sessions, tools, and teams.

• One source of truth — No more scattered instructions across CLAUDE.md, .cursorrules, tool settings, and chat logs.
• Separation of concerns — Stable rules, project facts, active plans, and decision history live in the right places.
• Works everywhere — Claude Code, Codex, Cursor, Hermes Agent, or any agent that reads repository instructions.

Copy AGENTS.md into your project and run the first-run setup in minutes.

---

Why This Exists

Modern AI coding agents are powerful, but long-running projects often suffer from a few recurring problems:

• Instructions become scattered across CLAUDE.md, .cursorrules, tool-specific settings, chat history, and ad-hoc notes
• Agents create duplicate context files instead of reusing existing project documents
• Temporary plans and durable decisions get mixed together, making it hard to know what's still relevant
• Project roots accumulate loose reports, notes, scripts, and scratch files, turning the repository into a junk drawer
• Important design reasoning disappears after the conversation ends
• Agents modify governance files or sensitive areas without enough intent from the user

These problems compound over time. After a few months, the repository becomes harder to understand, harder to resume, and harder to hand off.

What AGENTS.md Changes

AGENTS.md is more than a generic instruction file. It's a governance system that separates stable rules from changing project knowledge.

The core idea:

Keep AGENTS.md stable. Put changing project knowledge into clearly named documents with clear responsibilities.

This template defines a lightweight operating system for agents inside a project:

1. Single source of truth

   • AGENTS.md holds the canonical agent instructions
   • Existing adapter files such as CLAUDE.md, .cursorrules, or other agent-specific files should only point to AGENTS.md
   • Agents should not create adapter files just to add a pointer

2. Session startup discipline

   • Agents read AGENTS.md first
   • Additional documents are read only when relevant, reducing unnecessary context loading

3. Document governance

   • Stable project docs live under docs/
   • Research notes, experiments, reports, scripts, data, and assets each have their own default locations
   • Loose ad-hoc files in the project root are discouraged

4. Context preservation

   • The right information lives in the right place, making it easy to resume work or hand off to another agent

5. Change boundaries

   • Some sections of AGENTS.md are protected from automatic modification
   • Project-specific sensitive areas can be listed under Project Specifics > Boundaries

6. Implementation discipline

   • Agents keep changes small, surface assumptions, avoid speculative abstractions, and verify non-trivial work

7. First-run setup

   • The template includes a first-run procedure for installing the documentation system into an existing project without duplicating or overwriting useful context

The Document System

AGENTS.md creates a small set of purpose-built documents that agents use to preserve context across sessions:

docs/context.md

What the project is right now.

A compact snapshot of what the project is, who it serves, what phase it is in, where it should go long term, and what constraints matter. Agents read this to understand the current state and direction without re-reading the entire codebase.

docs/index.md

Where to find durable project documents.

A stable index of long-term project documents. It should not list temporary files or active plans. Think of it as a table of contents for the project's knowledge base.

docs/active_plan.md

What we're doing right now.

A short-term resumable execution plan. Agents update it as steps are completed and clear it when the plan is done. This is where active work lives, separate from durable decisions.

docs/project-reflection.md

Why we made the decisions we made.

A decision log for why-level project decisions. It is not a changelog.

Use it for:

• Architecture decisions
• Design philosophy changes
• Important user feedback
• Market or product positioning decisions
• Tradeoffs worth remembering

Do not use it for routine bug fixes, dependency bumps, or minor implementation details.

docs/conversations/

Manually preserved discussion summaries or handoffs.

A place for conversations that need to be saved for future reference. Agents should not create conversation logs automatically — this is for user-directed preservation only.

---

Why this separation matters:

Without it, agents either:

• Ask you to repeat context every session, or
• Create duplicate "context" files with overlapping information, or
• Mix temporary plans with durable decisions, making it impossible to know what's still relevant

With it, agents know exactly where to look and where to write. Context is preserved, plans are resumable, and decisions are auditable.

Before and After AGENTS.md

Without AGENTS.md	With AGENTS.md
Instructions drift across CLAUDE.md, .cursorrules, tool settings, and chat logs.	AGENTS.md becomes the stable source of truth, while adapter files simply point to it.
Context gets rewritten as context.md, project-summary.md, notes-final.md, and other duplicates.	docs/context.md owns the current project snapshot, and docs/index.md points agents to durable documents.
Short-term TODOs and long-term decisions live in the same messy notes.	docs/active_plan.md tracks active work; docs/project-reflection.md records why-level decisions.
Root directories collect one-off reports, scripts, scratch files, and agent artifacts.	Every artifact has an intended home: docs/, research/, reports/, experiments/, scripts/, data/, or assets/.
Each tool has its own memory and rules, so behavior changes from agent to agent.	Claude Code, Codex, Cursor, Hermes Agent, and other agents can share the same project contract.

AGENTS.md does not replace tool-specific files. It gives them something stable to point to.

Use Cases

This template is useful for projects where one or more AI agents will work repeatedly over time, especially when:

• The project has multiple sessions or long-running implementation plans
• Multiple agents or tools may touch the same repository
• You want a consistent documentation structure
• You want to prevent root-directory clutter
• You need durable decision records, not just chat logs
• You want agents to resume work without asking you to repeat context

It can be used with tools such as Claude Code, Codex, Cursor, Hermes Agent, or any agent that can read repository instructions.

Repository Structure

A typical project using this template may contain:

AGENTS.md
README.md
CLAUDE.md                    # optional existing adapter file; should point to AGENTS.md only
docs/
  context.md                 # project snapshot and long-term direction
  index.md                   # stable document index
  active_plan.md             # current resumable plan
  project-reflection.md      # why-level decision log
  conversations/
    _example.md              # format for manually saved conversation logs
research/                    # source material and research notes
reports/                     # durable audits, evaluations, validation reports
experiments/ or spikes/      # temporary explorations
scripts/                     # reusable helper scripts
data/                        # data, fixtures, or project datasets
assets/                      # media and static assets

Not every project needs every directory. Agents should reuse existing conventions before creating new folders.

How to Use

1. Copy AGENTS.md into the root of your project.
2. If adapter files already exist (like CLAUDE.md or .cursorrules), update them to point to AGENTS.md only.
3. Do not create adapter files solely to add pointers.
4. Follow the First Run section in AGENTS.md to set up the document system.
5. Create or reuse the core documents under docs/.
6. Fill in Project Specifics with the real stack, commands, and boundaries for your project.
7. After first-run setup is complete in a real project, delete the First Run section from that project's AGENTS.md.

The First Run section is intentionally included in this template for downstream projects. It is installation guidance, not repository setup residue; remove it only after copying the template into a real project and completing the setup steps there.

What This Template Is Not

This template is not:

• A coding style guide
• A replacement for README, architecture docs, or tests
• A universal folder structure that every project must follow exactly
• A reason for agents to create unnecessary documents
• A permission slip for agents to modify sensitive files

It is a governance layer that helps agents behave predictably and preserve useful project context over time.

Recommended Customization

After installing the template into a project, customize:

## Project Specifics

### Tech Stack
<!-- languages, frameworks, key dependencies, versions -->

### Commands
<!-- install, test, lint, build, typecheck, run, deploy commands -->

### Boundaries

#### Never modify without explicit user instruction:
<!-- protected files, models, scoring logic, contracts, production config -->

#### Confirm before modifying:
<!-- sensitive but occasionally editable areas -->

The quality of Project Specifics determines how safely and effectively agents can work in the repository.

Guiding Principle

Agents should make projects easier to understand and continue — not harder.

This template exists to make agent work:

• Resumable — Context is preserved across sessions
• Auditable — Decisions are recorded with reasoning
• Organized — Documents have clear responsibilities
• Minimally invasive — No root-directory clutter
• Aligned with explicit user intent — Boundaries are respected

License

This project is licensed under the MIT License.