AGENTS.md for Codex: project instructions that last

A contract for the working environment

AGENTS.md describes what a coding agent should understand before changing the repository: architecture boundaries, mandatory checks, file conventions and actions that require approval. It guides behaviour but does not replace technical access controls.

Move from general to local

Put broad conventions at the repository root and add instructions only inside specialised folders. A data migration can then require different checks from a visual change without burdening every session with every detail.

Write observable rules

Phrase instructions as actions and outcomes: run a named test command, preserve an API contract or never hand-edit generated files. Avoid words such as “clean” or “good” unless an acceptance criterion explains them.

Provide a safe route through the code

Name entry points, source files and generated outputs. Explain which area owns data, where migrations belong and how local services start. This reduces both search time and changes in the wrong place.

No. Treat it as ordinary repository content and use a secure process for secrets.

Prevent conflicting instructions

Do not duplicate one rule across several files. Local instructions should refine higher-level rules and exceptions should be explicit. After restructuring, check which files remain active.

Verify instead of trusting

Require linting, tests or a focused browser check after each relevant change. Review the outcome and the route taken. Strong instructions make verification normal rather than optional.

# Working agreements - Read the local guide before editing - Run pnpm lint and pnpm test - Preserve unrelated worktree changes

Make AGENTS.md for Codex verifiable

The decision review for AGENTS.md for Codex first focuses on one nested repository path where root and local AGENTS.md rules define the allowed change and checks. Define the acceptable user outcome, essential inputs and authorised approver for AGENTS.md for Codex before the trial starts. Keep the first AGENTS.md for Codex trial small enough to separate causes from effects.

Build evidence for AGENTS.md for Codex around one realistic successful route and also simulate conflicting instructions, hand-edited generated output and a missing verification command. For every AGENTS.md for Codex check, record the expected outcome, visible evidence and recovery action when it fails. The final decision question for AGENTS.md for Codex is: “Can AGENTS.md contain secrets?”

AGENTS.md for Codex: from trial to everyday operation

Assign AGENTS.md for Codex one operational owner, one subject reviewer and a clear fallback route. Treat the AGENTS.md for Codex checklist as separate evidenced steps, so punctuation or phrasing never becomes part of the process logic. Ask the relevant user to complete AGENTS.md for Codex without spoken help and record every point that still needs explanation or manual recovery.

Keep change rights, logging, support and review dates for AGENTS.md for Codex in one operating plan. Repeat the AGENTS.md for Codex trial after a change to source data, configuration, model, integration or user role. Expand AGENTS.md for Codex only when the team can also detect, contain and recover conflicting instructions, hand-edited generated output and a missing verification command.

Stop the AGENTS.md for Codex rollout while conflicting instructions, hand-edited generated output and a missing verification command is not reported visibly and recoverable by the assigned owner.