Skip to main content
reopt Handbook
reopt Handbook
Agentic Documentation

Paradigm Shift

Why Documentation Must ChangeAI-readable Design PrinciplesAI-assisted Writing Process

Practice by Document Type

Project Rule DocumentsFrom Docs to Skills, Plugins, and MCPAgent Documentation SecurityAPI Docs and SpecsREADME and OnboardingArchitecture Decision RecordsRunbooks and OperationsUser Guides and TutorialsKnowledge Bases and Internal Wikis

Operations

Maintenance StrategyTeam Documentation Culture

Appendix

TemplatesVerification ReportUpdates
Handbook›에이전틱 시대의 문서화 혁신›Project Rule Documents
한국어English

Project Rule Documents

Design AGENTS.md, CLAUDE.md, and path-scoped rules without conflicts or drift.

Key takeaways

  • Rule files are a control surface, not a knowledge base: keep always-needed rules short and move long procedures to Skills, runbooks, or deeper docs.
  • The surface is layered across AGENTS.md, CLAUDE.md/CLAUDE.local.md, .claude/rules/*.md, and Codex AGENTS.override.md, each with a distinct target and location.
  • Codex builds its instruction chain from global down to working directory, with AGENTS.override.md winning over AGENTS.md, closer files overriding earlier ones, and a 32 KiB default cap (project_doc_max_bytes).
  • If AGENTS.md is the shared source, keep CLAUDE.md thin (import via @AGENTS.md) and use .claude/rules/ for path-scoped rules.
  • Avoid failure patterns like subjective rules ("write clean code"), commands buried in prose, conflicting global/local rules, and copy-paste drift between AGENTS.md and CLAUDE.md.

When an agent enters a project, it first needs to know how work is done in that repository. Project rule documents provide that entry context.

The surface is now layered:

  • shared agent instructions: AGENTS.md
  • Claude Code memory and instructions: CLAUDE.md, CLAUDE.local.md
  • Claude Code path-scoped rules: .claude/rules/*.md
  • Codex directory instructions and overrides: AGENTS.md, AGENTS.override.md
  • compatibility files: .cursorrules, .windsurfrules

Core Rule

Rule files are a control surface, not a knowledge base. Keep always-needed project rules short, and move long procedures to Skills, runbooks, or deeper docs.

Surface Comparison

SurfaceTargetLocationUse
AGENTS.mdCodex and shared agentsrepo root, nested dirscommon instructions
AGENTS.override.mdCodexhome, repo, subdirstemporary or local override
CLAUDE.mdClaude Coderepo root, subdirs, homememory and instructions
CLAUDE.local.mdClaude Codelocal repopersonal settings, gitignored
.claude/rules/*.mdClaude Coderepo .claude/rules/path-scoped rules
.cursorrulesCursorrepo rootlegacy compatibility
.windsurfrulesWindsurfrepo rootlegacy compatibility

Codex AGENTS.md Loading

Codex builds an instruction chain at startup:

  1. Global scope: ~/.codex/AGENTS.override.md if present, otherwise ~/.codex/AGENTS.md.
  2. Project scope: from project root down to the current working directory.
  3. In each directory, AGENTS.override.md wins over AGENTS.md.
  4. Files closer to the working directory appear later and override earlier guidance.
  5. Empty files are skipped, and the combined project instruction size is capped by project_doc_max_bytes (32 KiB by default).
repo/
├── AGENTS.md
├── apps/
│   └── web/
│       └── AGENTS.md
└── services/
    └── payments/
        └── AGENTS.override.md

AGENTS.md Template

# AGENTS.md

## Project
[One-line project description.]

## Commands
\`\`\`bash
[install]
[dev]
[typecheck]
[test]
[build]
\`\`\`

## Where to look
| Task | Location | Notes |
|---|---|---|
| [task] | [path] | [notes] |

## Conventions
- [project-specific rule]

## Validation
- [command to run after changes]

## Do not
- [explicit prohibition]

Claude Code Rules

If AGENTS.md is the shared source, keep CLAUDE.md thin.

# CLAUDE.md

@AGENTS.md

## Claude Code
- Prefer planning before broad edits.
- Do not commit or push unless the user asks.

Use .claude/rules/ for path-scoped rules.

---
paths:
  - "src/api/**/*.ts"
  - "app/api/**/*.ts"
---

# API Rules

- Validate all inputs with schema.
- Update OpenAPI when API behavior changes.
- Run `pnpm openapi:check` after changes.

What Goes Where

ContentSurfaceReason
Overview, commands, validation, prohibitionsAGENTS.mdshared startup context
Claude-specific preferencesCLAUDE.mdtool-specific memory
file-type or path rules.claude/rules/, nested AGENTS.mdavoid global bloat
repeatable workflowSkillloaded only when needed
long API/domain referencedocs, OpenAPI, MCP Resourceavoid startup context waste
personal secrets or local URLslocal config or CLAUDE.local.mddo not commit

Failure Patterns

MistakeWhy it failsFix
"Write clean code"Too subjectiveState lint, naming, path rules
Commands in proseHard to executeUse code blocks
Conflicting global/local rulesLast-loaded rule wins unexpectedlyRemove duplicates and state overrides
Huge CLAUDE.mdConsumes startup contextMove procedures to Skills
Copy-paste between AGENTS.md and CLAUDE.mdDriftImport or link to the shared source

References

  • OpenAI Codex: Custom instructions with AGENTS.md
  • AGENTS.md
  • Claude Code: How Claude remembers your project

Related docs

Mastering CLAUDE.md

Claude Code Complete Guide · Design project memory that Claude Code can actually follow.

Cmd. /import

Codex Command Master · Import supported Claude Code setup, project files, and recent chats into Codex.

Cmd. /init

Codex Command Master · Generate an AGENTS.md scaffold for persistent repository instructions.

Cmd. /memory

Claude Code Command Master · Manages CLAUDE.md and auto memory. Saved project instructions can affect later sessions.

Cmd. /add-dir

Claude Code Command Master · Add a working directory for file access in this session.

AI-assisted Writing Process

Source scan, draft, deterministic validation, agent smoke test, owner review, and freshness monitoring.

From Docs to Skills, Plugins, and MCP

Split rules, workflows, distribution units, and external context into the right agent surface.

On this page

Surface ComparisonCodex AGENTS.md LoadingAGENTS.md TemplateClaude Code RulesWhat Goes WhereFailure PatternsReferences