Repository instructions drift when every coding agent gets a separate policy. A rule added to one file may never reach the other tools. The practical fix is to keep one short source of truth and make every supported entry point refer to it.
This walkthrough uses a root AGENTS.md as the canonical policy and a small CLAUDE.md bridge. You can apply the method manually; the paid pack mentioned at the end only automates the checks and file creation.
1. Put the policy at the repository root
Create AGENTS.md beside your main project files. Keep it specific enough to test. A useful policy answers these questions:
- Which directories and files are in scope?
- Which document is authoritative when instructions conflict?
- What may an agent change?
- Which checks must run before completion?
- Which actions require approval?
- What evidence must the final report include?
Here is a compact starting point:
# Repository instructions
## Scope
These instructions apply to the entire repository.
## Source of truth
- Product behavior: `docs/product.md`
- Build and test commands: `README.md`
- Do not duplicate those facts here.
## Allowed changes
- Preserve unrelated work.
- Do not commit secrets, generated credentials, or customer data.
- Ask before adding a paid service or changing production data.
## Workflow
1. Read the nearest relevant files before editing.
2. Make the smallest coherent change.
3. Run the checks affected by the change.
## Validation
- Run the documented test command.
- Report failed or skipped checks explicitly.
## Completion evidence
- List changed files, checks run, and remaining limitations.
Replace the placeholders with real project paths and commands. A policy that says only "write good code" is difficult to verify and easy to interpret differently.
2. Bridge Claude Code to the same file
Claude Code documents file imports in CLAUDE.md. A minimal root bridge can therefore contain:
# Repository instructions
@AGENTS.md
That keeps the policy text in one place. Do not paste a second copy into CLAUDE.md; duplicated copies can diverge silently.
3. Check how each tool discovers instructions
Instruction discovery depends on the agent, version, and mode. The current primary documentation describes these entry points:
- OpenAI Codex and AGENTS.md
- Cursor rules and AGENTS.md
- GitHub Copilot repository instructions
- Claude Code memory and imports
Run one harmless, observable check in every agent you actually use. For example, add a temporary instruction to identify the repository’s test command, ask the agent to report it without editing files, and confirm the answer came from the policy. Remove the temporary line afterward.
Instruction files guide compatible agents. They do not create a sandbox, grant or deny permissions, or guarantee behavior. Keep platform permission controls and code review in place.
4. Validate before committing
Before adding the two files to version control, check:
- Neither path is a symbolic link.
- The files contain UTF-8 text and no secrets.
- CLAUDE.md imports the root AGENTS.md.
- The policy names real commands and real files.
- Every approval boundary is concrete.
- The change does not overwrite existing repository instructions.
If either file already exists, review and merge by hand. Blind replacement can discard project-specific rules.
5. Make rollback boring
Record the exact bytes you created. If nobody edits the generated files, rollback can remove them. If either file changes, stop and require a manual review. This prevents a cleanup command from deleting later human work.
Automating the safe path
Agent Repo Control Pack implements that workflow locally: preview, exclusive creation, structural validation, and exact-byte rollback. It includes the policy source and uses only the Python standard library. Version 0.1.0 passed 22 automated tests and clean extraction smoke checks on Windows 11 with Python 3.11. Python 3.9 runtime, macOS, and Linux have not been executed by the seller.
The proof page shows the generated policy excerpt, commands, limitations, primary documentation, and frozen release checksums before purchase.
Disclosure: we publish Agent Repo Control Pack. The manual procedure above is complete enough to use without buying it; the product packages and checks the workflow.