Create AGENTS.md
Write scoped, repo-specific instructions that make non-obvious or high-risk decisions explicit. Optimize for signal, not a fixed length.
Read references/agents-md-guidance.md when creating a new file, auditing stale instructions, handling a monorepo, or documenting multiple build, test, or review paths.
Workflow
- Inspect existing
AGENTS.md files, README, manifests, build files, scripts, CI, docs, security guidance, generated-code markers, public interfaces, test helpers, and relevant source directories.
- Set the file scope: root for shared rules, nested for a package or service with different commands or boundaries. The nearest file wins unless the user says otherwise.
- Trace representative change paths to find preferred abstractions, architectural pressure points, generated-artifact coupling, review risks, and differences between local, CI, and platform-specific checks.
- Preserve useful project facts, remove stale or duplicated guidance, and never encode a rule that conflicts with the current user request.
- Include only behavior-changing guidance: exact commands, preferred helpers or seams, repo conventions, validation triggers, review checklists, context-routing links, safety boundaries, and important generated or vendored paths.
- Write conditional rules as
when X changes, do Y; include the working directory, execution order, expected cost, and approval boundary when those affect behavior.
- Use exact paths, symbols, and short examples for non-obvious conventions. Add rationale only when it prevents a plausible wrong action.
- Validate links, paths, commands, heading structure, scope, and stale template language before finishing.
Useful Sections
Use only sections that fit the repo:
- Project context and scope
- Commands and validation
- Architecture, ownership, and preferred extension points
- Code or repository conventions
- Testing strategy, helpers, fixtures, and snapshots
- Generated artifacts and cross-platform constraints
- Review risks and compatibility surfaces
- Context loading and routing
- Boundaries, security, and data handling
- Git and PR workflow
Prefer concrete paths and commands over generic craft advice. Route detailed source-of-truth material to deeper docs instead of duplicating it.
Output
Edit the file directly when asked. Report the repo facts checked, commands and links verified, and any inferred guidance that needs maintainer confirmation.
1---2name: create-agents-md3description: Create, update, audit, or split AGENTS.md files for repositories and subdirectories. Use when Codex needs repo-specific agent instructions for commands, conventions, validation, architecture boundaries, monorepo routing, safety, or review workflows.4---56# Create AGENTS.md78Write scoped, repo-specific instructions that make non-obvious or high-risk decisions explicit. Optimize for signal, not a fixed length.910Read `references/agents-md-guidance.md` when creating a new file, auditing stale instructions, handling a monorepo, or documenting multiple build, test, or review paths.1112## Workflow13141. Inspect existing `AGENTS.md` files, README, manifests, build files, scripts, CI, docs, security guidance, generated-code markers, public interfaces, test helpers, and relevant source directories.152. Set the file scope: root for shared rules, nested for a package or service with different commands or boundaries. The nearest file wins unless the user says otherwise.163. Trace representative change paths to find preferred abstractions, architectural pressure points, generated-artifact coupling, review risks, and differences between local, CI, and platform-specific checks.174. Preserve useful project facts, remove stale or duplicated guidance, and never encode a rule that conflicts with the current user request.185. Include only behavior-changing guidance: exact commands, preferred helpers or seams, repo conventions, validation triggers, review checklists, context-routing links, safety boundaries, and important generated or vendored paths.196. Write conditional rules as `when X changes, do Y`; include the working directory, execution order, expected cost, and approval boundary when those affect behavior.207. Use exact paths, symbols, and short examples for non-obvious conventions. Add rationale only when it prevents a plausible wrong action.218. Validate links, paths, commands, heading structure, scope, and stale template language before finishing.2223## Useful Sections2425Use only sections that fit the repo:2627- Project context and scope28- Commands and validation29- Architecture, ownership, and preferred extension points30- Code or repository conventions31- Testing strategy, helpers, fixtures, and snapshots32- Generated artifacts and cross-platform constraints33- Review risks and compatibility surfaces34- Context loading and routing35- Boundaries, security, and data handling36- Git and PR workflow3738Prefer concrete paths and commands over generic craft advice. Route detailed source-of-truth material to deeper docs instead of duplicating it.3940## Output4142Edit the file directly when asked. Report the repo facts checked, commands and links verified, and any inferred guidance that needs maintainer confirmation.
jlave-dev