agents-md-writer

AGENTS.md Writer

Produce durable instructions at the scope that needs them. Ground additions in non-obvious repository facts, recurring failures, hard constraints, or explicit team decisions; prefer executable enforcement for mechanical rules.

Establish the effective hierarchy

Identify the requested operation and target tools. Inspect the relevant global, root, nested, tool-specific, and legacy sources and how they combine. A local wording fix needs its affected instruction chain; a hierarchy migration needs coverage of every candidate source and intended tool.

When a decision depends on filenames, discovery, precedence, overrides, size limits, or reload timing, verify current official tool documentation. For Codex, start with the AGENTS.md guide. Do not assume other clients use the same rules.

Place and revise guidance

• Keep shared guidance at the broadest intended scope inside the authorized target. User-global files are for explicitly personal or global guidance.
• Put subtree rules in the closest suitable existing file when nesting is supported. Add a file only for a distinct scope or intentional precedence change.
• Use a common cross-tool file only if every intended tool reads it. Codex's AGENTS.override.md intentionally replaces the same directory's AGENTS.md; verify other tools independently.
• Give duplicate or conflicting rules one authoritative owner where possible. Link to explanatory documentation; retain commands, invariants, and context needed to act. Consult scripts, CI, configuration, and docs for the claims being changed rather than requiring a full repository survey for every edit.
• State desired behavior directly. Preserve real authority boundaries and exact fragile steps; remove generic advice, redundant approvals, and unconditional reading that does not affect the task.

Verify and finish

Re-read the affected chains in documented load order for contradictions and stale commands. When hierarchy or discovery changes, inspect effective sources from the root and a representative nested directory through supported introspection or dry runs. Report changed scopes, validation, and any unverified client behavior. An audit remains read-only; an authorized revision finishes through fixes and verification.