Last reviewed: 2026-07-18
Direct answer
Review shared instruction changes before a coding agent starts work by checking three things: which files the tool reads, which instruction wins when files overlap, and whether the changed guidance can be verified with a harmless task. Treat instruction files like operational configuration, not casual documentation.
A workable smoke-test workflow:
- Setup assumptions: create a branch with only the instruction-file change, identify the agent surface that will read it, and keep any credential or production action out of the test.
- Happy-path request plan: ask the agent to summarize the active instruction sources and the expected behavior for one low-risk repository task, such as listing validation commands without running deployment steps.
- Error-path check: add a temporary conflicting line in a local test branch or fixture, then confirm the agent exposes the conflict or follows the documented precedence for that tool.
- Minimum assertions: record which instruction files were considered, which file had the narrowest scope, whether the agent preserved safety boundaries, and whether the answer matched the documented loading behavior.
- Pass/fail logging fields:
run_id,agent_surface,instruction_files_checked,changed_file,expected_scope,observed_scope,conflict_result,safe_task_result,decision,reviewer_initials. - Do not assert: exact model behavior, hidden system prompts, billing impact, private account settings, or future agent behavior outside the files and tool behavior you checked.
Related context: Instruction Precedence for Coding Agent Repositories .
Who this is for
This guide is for maintainers who share repository instructions across Codex, Claude Code, GitHub Copilot, or mixed coding-agent teams. It is especially useful when a small instruction edit can change how agents handle tests, secrets, pull requests, deployment commands, or directory-specific rules.
Key takeaways
- Codex documents an instruction chain for
AGENTS.mdfiles, with project files layered from broader directories toward the current working directory. - Claude Code documents
CLAUDE.mdas its main project-instruction mechanism and explains how to connect an existingAGENTS.mdfile through an import or symlink. - GitHub Copilot documents repository-wide, path-specific, and agent instruction files, so the same repository can have more than one instruction source in play.
- A useful review checks scope and conflicts before asking an agent to modify code.
- The smoke test should prove that guidance is visible and scoped correctly, not that an agent will always behave perfectly.
Failure modes
- Evidence gap: the agent cannot inspect the failing log, source page, pull request, or local command output. The safe action is to stop and record the missing evidence instead of guessing.
- Scope drift: the agent edits files that are not connected to the observed failure. Keep the repair tied to the failing signal and leave unrelated cleanup for a separate task.
- Environment mismatch: the local check uses different versions, credentials, feature flags, or runtime settings than the hosted path. Record the mismatch before treating the result as proof.
- Unreviewed fallback: the agent changes models, endpoints, permissions, or retry behavior to make a run pass without preserving the review boundary. Treat access and provider failures as operational blockers, not topic failures.
- Weak handoff: the final note says the issue is fixed but omits the command, result, changed files, and remaining uncertainty. That makes the next operator repeat the investigation.
Sources checked
- Claude Code memory documentation - accessed 2026-07-18; purpose: verify project memory and instruction-file context for agent workflows.
- OpenAI Codex AGENTS.md guidance - accessed 2026-07-18; purpose: verify repository instruction-file context for coding agents.
- GitHub Copilot repository instructions documentation - accessed 2026-07-18; purpose: verify repository instruction guidance.
Contract details to verify
| Area | What to verify | Source URL | Accessed | Safe candidate wording |
|---|---|---|---|---|
| Codex instruction discovery | Confirm which AGENTS.md or override files Codex reads for the current directory. | https://learn.chatgpt.com/docs/agent-configuration/agents-md | 2026-07-18 | Codex builds an instruction chain from global and project-level files, then layers files closer to the working directory later. |
| Claude Code shared instructions | Confirm whether the repository uses CLAUDE.md, imports an AGENTS.md file, or uses a symlink. | https://code.claude.com/docs/en/memory | 2026-07-18 | Claude Code uses CLAUDE.md for persistent project guidance, and an existing AGENTS.md can be connected through documented mechanisms. |
| GitHub Copilot instruction scope | Confirm whether guidance is repository-wide, path-specific, or agent-focused. | https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions | 2026-07-18 | Copilot supports multiple repository instruction types, and more than one type can apply to a request. |
| Conflict review | Check whether overlapping instructions conflict and which documented scope should apply. | https://code.claude.com/docs/en/memory | 2026-07-18 | Keep shared instructions concise, specific, and free of contradictions where possible. |
Reader next step
Compare the workflow against Start with CometAPI .
FAQ
Should every instruction change get the same review depth?
No. A wording fix can get a quick source and scope check. A change that affects secrets, deployment, test commands, permissions, or pull request behavior deserves a branch-level smoke test before agents use it.
Is one shared instruction file enough for every agent?
Not always. The sources show that different tools use different file names and loading behavior. Keep the shared policy consistent, but verify the tool-specific file path and precedence before relying on it.
What should the review log include?
Use sanitized placeholders only:
run_id: instruction-review-YYYYMMDD-001
agent_surface: codex-or-claude-or-copilot
changed_file: path/to/instruction-file.md
instruction_files_checked: [path/to/file-a.md, path/to/file-b.md]
expected_scope: repository-or-path-specific
observed_scope: summarized-by-agent
conflict_result: pass-or-fail
safe_task_result: pass-or-fail
decision: accept-or-revise-or-block
What is the safest first test after changing shared instructions?
Ask the agent to identify active guidance and describe the expected behavior for a harmless repository task. Do that before asking for code edits, command execution, dependency changes, or pull request work.
When should a change be blocked?
Block or revise the change when sources are unclear, scopes conflict, a tool cannot see the intended file, or the instruction asks agents to make claims or take actions that the repository cannot safely verify.