# AGENTS.md Reference

Use this reference when drafting, updating, or auditing `AGENTS.md`.

## Fact Sources

| Need | Prefer these sources |
|---|---|
| Package manager and scripts | `package.json`, `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, `bun.lockb` |
| Python commands | `pyproject.toml`, `uv.lock`, `poetry.lock`, `requirements*.txt`, `tox.ini`, `noxfile.py` |
| Go/Rust/.NET/Java commands | `go.mod`, `Cargo.toml`, `*.csproj`, `pom.xml`, `build.gradle*` |
| CI expectations | `.github/workflows/*`, `.gitlab-ci.yml`, `azure-pipelines.yml`, `Jenkinsfile` |
| Architecture and boundaries | `README.md`, `CONTRIBUTING.md`, `docs/`, existing instruction files |
| Generated or dangerous paths | `.gitignore`, generator configs, migration dirs, infra dirs, lockfiles |

Never promote a guessed command or path into final `AGENTS.md`. If a fact cannot be confirmed, omit it or list it as a final-response unknown.

## Scope Decision

Choose **root only** when:

- The repo has one main stack and one set of commands.
- Directory conventions are uniform.
- A concise root guide can cover common tasks without local exceptions.

Choose **root plus child guides** when:

- The repo is a monorepo or has separate apps, services, docs, packages, or examples.
- Commands differ by directory.
- Generated files, migrations, security code, or public API contracts are localized.
- Parent guidance would become long because of local exceptions.

Root files should orient. Child files should specialize.

## Root Template

```markdown
# Project Agent Guide

## Project Overview
[1-3 factual sentences: project type, primary stack, most important working constraint.]

## Scope
- This file applies to the whole repository.
- More specific `AGENTS.md` files in subdirectories override this file for their paths.
- User instructions in the current task override repository guidance.

## Quick Commands
- Install: `[exact command]`
- Dev: `[exact command]`
- Test: `[exact command]`
- Lint: `[exact command]`
- Build: `[exact command]`
- Typecheck: `[exact command]`

## Key Paths
- `path/` - purpose
- `path/file.ext` - purpose

## Architecture Boundaries
- [Concrete boundary or dependency rule.]
- [High-risk area and why it matters.]

## Conventions
- [Style, naming, formatting, import, or documentation rule that is specific to this repo.]
- [Testing expectation that is actually supported by the repo.]

## Definition of Done
- Run `[exact command]` before finishing changes that touch [scope].
- If a required command cannot run, report the reason and the expected follow-up.

## Boundaries
- Always: [concrete safe behavior]
- Ask first: [dependency, schema, CI, public API, security, data migration, billing, destructive operation]
- Never: [secrets, generated/vendor edits, broad refactors without request]

## Child Guides
- `subsystem/AGENTS.md` - local rules for [subsystem]

## References
- `docs/file.md` - when to read it
```

Remove sections that have no verified content. Do not leave placeholder text. `Project Overview` and `Scope` usually belong in every root guide; the other template sections are recommended when the repository has facts to support them.

## Child Template

```markdown
# Local Agent Guide

## Local Purpose
[What this directory owns. Keep it factual.]

## Inherits
- Follow the nearest parent `AGENTS.md` unless this file gives a more specific local rule.

## Local Commands
- Test: `[exact command]`
- Lint: `[exact command]`

## Local Conventions
- [Naming, code organization, generated files, docs, or test placement specific to this path.]

## Local Risks
- Ask first: [local high-risk changes]
- Never: [local forbidden edits]
```

If a child directory has no distinct commands, omit `Local Commands` rather than inventing commands. Keep `Local Purpose` and `Inherits` in normal child guides; include `Local Conventions` and `Local Risks` only when there are local facts worth capturing.

## Scoring Checklist

A strong guide passes these checks:

- **Specific:** Every command and path is concrete.
- **Verified:** Commands and paths trace to repository files.
- **Scoped:** Root guidance stays global; child guidance contains only local differences.
- **No filler:** Missing recommended sections are acceptable when there is no verified content.
- **Short:** Root is usually under 200 lines and avoids long procedures.
- **Actionable:** A new agent can find the right files, run the right checks, and avoid high-risk edits.
- **Compatible:** It states parent/child precedence and user-instruction precedence.
- **Maintainable:** It avoids duplicated docs and points to references for deep background.

## Audit Signals

Flag these during updates:

- `TODO`, `TBD`, `FIXME`, bracket placeholders, or template language.
- Commands that do not exist in manifests, Makefiles, CI, or docs.
- Paths that no longer exist.
- Duplicated or conflicting parent/child rules.
- Long release, migration, or audit procedures in the root guide.
- Tool-specific assumptions presented as cross-tool rules.
- Secrets, internal credentials, or sensitive environment details.
