Use `AGENTS.md` to Teach an AI About a Repository

Use AGENTS.md for durable guidance that should apply across many agent tasks in a repository. Put project conventions, reliable setup and verification commands, scope boundaries, and review expectations there. Keep the current objective, temporary context, and one-time preferences in the task prompt.

OpenAI’s current AGENTS.md documentation explains that Codex reads instruction files before working. Instructions closer to the current directory take precedence over broader repository guidance, and an AGENTS.override.md file can replace an AGENTS.md file at the same level. Confirm the files Codex actually loaded before relying on those rules.

Record facts that remain true

Good candidates include:

• repository purpose and important directories;
• supported setup command;
• run, format, lint, and test commands;
• generated files that should not be edited;
• naming and style conventions not enforced mechanically;
• privacy and secret-handling boundaries;
• scope rules for subdirectories; and
• required review and verification.

Prefer links to maintained project documentation over copying a long manual. Use AGENTS.md as a short map to those deeper sources.

Keep temporary requests in the prompt

Do not encode:

• “fix issue 42 today”;
• a temporary branch name;
• one student’s preferred output wording;
• a deadline-specific shortcut;
• private conversation context; or
• permission for an action that normally requires review.

Repository instructions should not silently broaden an agent’s authority.

Draft a small file

# Repository guidance

## Purpose and layout
- Application code: `src/`
- Tests: `tests/`
- Generated output: `build/`; do not edit manually.

## Commands
- Install: `[verified command]`
- Test: `[verified command]`
- Format check: `[verified command]`

## Scope and review
- Keep changes within the requested component.
- Inspect `git diff` and report tests actually run.
- Never commit secrets, private course data, or generated credentials.

Replace placeholders only with commands you have run successfully. State platform and version constraints when they matter.

Verify with a bounded task

Ask Codex to inspect the file and summarize the rules without editing. Then use a disposable branch or practice repository for a small change. Confirm:

1. the intended instructions were discovered;
2. the agent stayed within scope;
3. commands existed and produced the recorded result;
4. generated and private files were protected; and
5. the final diff and report matched evidence.

Agent compliance is not guaranteed by documentation. Human review, sandboxing, approvals, and repository tests remain necessary.

Common mistakes

• Turning AGENTS.md into an encyclopedia.
• Copying stale commands from another repository.
• Mixing one-time objectives with durable rules.
• Writing vague instructions such as “follow best practices.”
• Including secrets or private course material.
• Assuming an instruction file overrides system, user, or organizational policy.

Do this now

Draft a concise AGENTS.md for a safe repository. Verify every command manually, then run an inspection-only agent task and compare what the agent reports with the file.

Log what you learned

Record only:

• Result: What did the action produce?
• Evidence: What observation, test, or source supports that result?
• Next action or unresolved question: What should happen next?

Next, decide whether a broader repeated agent workflow belongs in a skill.

When two agents need genuinely independent repository tasks, use Git worktrees with disjoint ownership and coordinated integration rather than letting both agents edit the same working tree.