Keep Codex Decisions in Your Repository and Verify Code

Keeping Codex decisions in your repository gives future contributors a durable record of project rules, design choices, and verification steps. Pair that documentation with repeatable checks—such as tests, linting, and review of the final diff—to make it easier to confirm that a change fits the project before it is merged. You’ll need a Git repository, access to its files, and whatever test or build commands the project uses.

What You’ll Need

A Git repository with permission to create or edit files and commit changes.
The Codex instructions or decision you want to preserve, stated clearly enough to review.
The project’s existing test, lint, type-check, or build commands. Look in its README, contribution guide, package scripts, or CI configuration.
A way to run the project’s checks locally, if available. If setup is not possible, record that limitation and rely on the repository’s CI before merging.

Step-by-Step

Start from the repository’s current state. Open the project root and check the working tree with git status. Review any existing changes before editing. Avoid mixing unrelated work with the decision or code change; if the tree is already modified, preserve those changes and consider using a separate branch or worktree.
Find the project’s instruction files. Look for files such as AGENTS.md, CONTRIBUTING.md, and README.md, including instructions in parent directories where applicable. Follow the repository’s existing structure rather than adding a second, conflicting source of guidance. Codex can use AGENTS.md files as project instructions, but a file does not automatically make every stated decision correct: people should still review it.
Choose where the decision belongs. Put enduring, actionable rules that Codex should follow in the relevant AGENTS.md. Use a design or decision record for the reasoning behind a significant choice, especially when alternatives and consequences matter. Put user-facing setup or workflow instructions in the README or contribution guide. Link related files instead of copying the same rule into several places.
Write the decision so it can be checked. State the context, the decision, and its practical effect. Include relevant constraints, such as an API boundary, a compatibility requirement, or a preferred testing pattern. Replace vague wording like “keep things clean” with observable guidance, such as “add a regression test for each bug fix.” Include the date or status only if your team uses those fields. Do not record secrets, credentials, or sensitive data.
Keep instructions focused and scoped. Explain which paths or tasks a rule applies to when that matters. A root-level instruction can set broad expectations; a nearer instruction file can clarify rules for a subdirectory. Keep instructions concise, remove obsolete directions, and resolve contradictions. If a decision changes, update the authoritative record and any links or examples that are now misleading.
Ask Codex to inspect before it edits. Give it a specific task and ask it to identify the relevant repository instructions, summarize the applicable constraints, and propose a plan. For example: “Review the instructions for the files involved, explain how this change fits the project’s recorded decisions, then make the smallest suitable change.” Check that its summary matches the files; do not assume it found or interpreted every instruction correctly.
Make the change in a reviewable scope. Ask Codex to implement the agreed change without touching unrelated files. If it proposes a different approach from a recorded decision, pause and decide whether the task needs an exception or the documentation needs an update. Do not silently accept a mismatch. Keep code, tests, and decision changes together only when they are part of the same coherent change.
Review the diff, not just the summary. Run git diff --check to catch whitespace problems, then inspect git diff and git status. Confirm that changes are limited to intended files, instructions are accurate, tests cover the behavior, and no generated files, local configuration, or secrets were added by mistake. A clean-looking summary is not a substitute for reviewing the actual patch.
Run the project’s verification commands. Use the commands documented by the project, in the appropriate order—for example, formatting or linting, type checks, focused tests, the full test suite, and a build. Do not invent a command based on another project’s conventions. Record which commands ran and whether they passed; if a check was skipped or could not run, state why rather than implying it passed.
Commit the reviewed result and verify the committed state. Stage only the intended files, inspect the staged diff with git diff --cached, and commit with a message describing the change. Check git status afterward. If your team uses pull requests, include the decision’s location and verification results in the description, then confirm that required CI checks pass before merging.

Common Mistakes

Putting every preference in one huge instruction file. Long, repetitive guidance is harder to follow. Keep general instructions near the root and specialized guidance near the affected code.
Recording conclusions without consequences. “Use the new approach” is difficult to apply later. Explain what code or workflow it affects and how a reviewer can recognize compliance.
Assuming documentation proves correctness. A decision record explains intent; tests and review provide evidence that the implementation behaves as intended.
Claiming checks passed when they did not run. Distinguish passed, failed, skipped, and unavailable checks, including any important reason.
Committing unrelated or sensitive files. Inspect both the working tree and staged diff. Never store tokens, passwords, or private data in instructions or decision records.

Tips

Use concrete examples when a rule could be interpreted in more than one way.
Keep a decision record short enough to scan; link to detailed implementation notes when needed.
Ask for a focused test first, then broader checks, so failures are easier to diagnose.
Make verification reproducible by recording exact commands and relevant setup assumptions.
When a check depends on external services or environment-specific data, say so and identify what remains unverified.

Troubleshooting

Codex appears to ignore an instruction: Confirm the file is in the repository and applies to the files being changed. Check for more specific instructions in subdirectories and for contradictory rules elsewhere. Ask Codex to name the instructions it considered; correct the documentation or prompt if the scope is unclear.

A test command fails: Read the first meaningful error, verify the documented setup and dependencies, then rerun the narrowest relevant test. Separate pre-existing failures from failures introduced by the change. Do not remove a test merely to make the suite pass; investigate the expected behavior and update the test only when the specification has genuinely changed.

Checks pass locally but CI fails: Compare the CI command, runtime, environment variables, and dependency installation with your local setup. Follow the failure logs, reproduce the relevant command if possible, and report environmental differences. A local pass does not override a failing required CI check.

The change conflicts with a recorded decision: Stop before merging. Determine whether the implementation should follow the existing decision or whether new evidence justifies revising it. If revising, update the authoritative record and explain the reason in the same review so future contributors can follow the change in direction.

You cannot run the checks: Do not guess at the result. Document what was attempted, the blocker, and what remains to be checked. Ask a maintainer or use the repository’s CI workflow where available, and wait for required checks before treating the code as verified.

Frequently Asked Questions

Should Codex decisions go in AGENTS.md?
Put concise, actionable instructions there when Codex should apply them to future work. For decisions needing background, alternatives, and consequences, keep a separate decision record and link to it.

Do I need a separate decision record for every change?
No. Routine implementation details usually belong in code, tests, or existing documentation. Record decisions that are important to preserve, affect future work, or would otherwise be difficult to understand later.

Does a passing test suite prove the code is correct?
No. Tests provide evidence for the behavior they cover. Review the diff, consider edge cases, and run the checks relevant to the change; note any untested areas.

What should I do if the repository has no test instructions?
Inspect its CI configuration and existing scripts for the project’s actual checks. If there is no established process, ask a maintainer before adding commands or describe the verification limitation clearly.

Should I commit Codex’s conversation or full prompt?
Usually, preserve the durable decision and useful verification details rather than a full conversation. Conversations can contain temporary context, repeated material, or sensitive information.

Can instructions guarantee that Codex follows a decision?
No. Clear repository guidance makes the intended behavior easier to find, but review the proposed changes and verify them with appropriate checks.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →