Instruction File Scope Checks for Coding Agent Repos

Last reviewed: 2026-06-10

Direct answer

Instruction files tell a coding agent what it is allowed to do, which files it may touch, and how it should behave when it encounters ambiguous situations. If those files have the wrong scope — too broad, too narrow, placed in the wrong directory, or contradicting each other — the agent either ignores them or acts on rules you did not intend.

A scope check is a deliberate audit of each instruction file in the repo: where it lives, which agent reads it, which directories and tasks it covers, and whether the rules in it are still accurate. Running a scope check before each agent session, and again before opening a pull request, catches the most common failure modes: stale rules, files placed where the agent cannot find them, and permission grants that have silently expanded beyond their original intent.

The three most widely used instruction-file conventions — Codex AGENTS.md, GitHub Copilot repository instructions, and Claude Code memory files — each use different placement conventions and different inheritance rules. Verifying scope across all three requires checking each tool’s own documentation for the current authoritative placement path before assuming a file is being read.

For broader release checks, see When to Stop, Retry, or Escalate: A Practical Guide to Coding Agent Task Control .

Who this is for

This guide is for engineers and teams who:

Run coding agents (Codex, Copilot, Claude Code, or similar) against a shared repository.
Want to confirm that instruction files are scoped to the right directories and tasks before an agent session begins.
Are setting up instruction files for the first time and need a checklist for verifying that placement and content are correct.
Have encountered an agent ignoring instructions or acting outside expected boundaries and want a structured way to diagnose the problem.

If you are writing instruction files from scratch, How to Write Repository Instructions for Coding Agents covers authoring conventions in detail. This guide focuses on the audit and verification step.

Key takeaways

Each coding agent tool has its own authoritative placement path for instruction files. Verify placement against the tool’s current documentation before assuming a file is being read.
Scope creep in instruction files is common: rules added for one task or directory gradually expand to cover the whole repo. Check that permission grants and file-path patterns still match their original intent.
Conflicting instructions across multiple files — for example, a root AGENTS.md that allows a directory and a subdirectory AGENTS.md that restricts it — can produce unpredictable agent behavior. Audit all instruction files together, not one at a time.
Instruction files that grant broad write permissions or allow running arbitrary shell commands are high-risk. Check these rules explicitly before each agent session.
A PR gate that verifies instruction files have not changed unreviewed is the most reliable way to prevent scope drift from shipping silently.

Scope check workflow

The following workflow covers the main steps for auditing instruction files in a repository before an agent session.

1. List all instruction files in the repository

Before checking scope, enumerate every file that any coding agent in your toolchain might read. Common locations include:

Repository root: AGENTS.md, CLAUDE.md, .cursorrules
.github/ directory: copilot-instructions.md, AGENTS.md
Subdirectory-level files: any AGENTS.md placed in a subdirectory to scope rules to that subtree
Project memory or config directories used by specific agent tools (verify the exact path in each tool’s documentation)

Verify current placement conventions against each tool’s official documentation before assuming a file at a given path is being read. Placement conventions can change between tool versions.

2. Check file placement against each tool’s current documentation

For each instruction file, confirm:

The file is at the path the tool expects according to its current documentation.
If the tool supports subdirectory files, confirm that the subdirectory file applies to the subtree you intend and does not unexpectedly override root rules.
If multiple tools are in use, confirm that each tool’s file is at its own expected path, not shared with another tool’s path unless both tools are documented to read it.

For AGENTS.md used with Codex, refer to the OpenAI Codex AGENTS.md documentation for current placement and inheritance rules.

For GitHub Copilot repository instructions, refer to the GitHub Copilot custom instructions documentation for the current authoritative file path and feature availability.

For Claude Code memory files, refer to the Claude Code memory documentation for current file naming, placement, and scope inheritance rules.

3. Audit the content of each instruction file

For each instruction file, review:

Scope of file-path permissions: Are the directories and file patterns listed still accurate? Have new directories been added to the repo that are not covered or should not be covered?

Command and tool permissions: Does the file grant permission to run shell commands, call external APIs, or modify CI configuration? If so, are those permissions still appropriate and as narrow as the task requires?

Task scope: Are the rules in the file written for a specific task or for all agent sessions? Rules written for a one-time task that were never removed become the permanent default.

Contradiction check: If more than one instruction file exists (root and subdirectory, or files for different tools), do the rules in each file agree? Identify any cases where one file allows something another restricts.

Staleness: Do any rules reference file paths, branch names, environment names, or configuration keys that no longer exist in the repo?

4. Check PR history for unreviewed instruction file changes

Review the git log for changes to instruction files. Changes to instruction files that were merged without explicit review by a human are a scope-drift risk. Use git log –follow – AGENTS.md (or the relevant file path) to see the change history.

For teams using GitHub pull requests, the GitHub pull request documentation describes how to require reviews for specific file paths using CODEOWNERS. Adding instruction files to CODEOWNERS ensures that any change requires an explicit human approval before merge.

5. Verify before each agent session

Before starting an agent session on a task that involves file writes, branch creation, or external calls, do a quick spot-check:

Confirm the instruction file for the tool you are using is present at the expected path.
Skim the permissions section for any rule that is broader than the task requires.
If any rule looks unexpectedly broad, narrow it before starting the session rather than after.

Smoke-test workflow

Setup assumptions: You have a local clone of the repository. At least one instruction file is present. You are not starting an agent session — this is a pre-session audit only.

Happy-path check plan:

Run find . -name ‘AGENTS.md’ -o -name ‘CLAUDE.md’ -o -name ‘copilot-instructions.md’ | sort (or equivalent for your shell) to list all candidate instruction files.
For each file found, confirm the path matches the expected path in the relevant tool’s documentation.
Open each file and check the sections that grant file-write or shell-command permissions. Record which directories and commands are allowed.
Cross-check the allowed directories against the current repo structure. Flag any allowed directory that no longer exists or that has been repurposed.
If more than one instruction file is present, compare the permission sections for contradictions.

Error-path check: If the find command returns no results but you expected instruction files to be present, check whether the files are committed to the repository (they must be tracked by git to be read by most agent tools).

Minimum assertions:

At least one instruction file is present and at the path the target tool expects.
No file-write permission covers a directory outside the intended task scope.
No rule in any instruction file has been modified in the last 30 days without a corresponding PR review.

What this smoke test must not assert: This check does not verify that the agent will behave correctly during a live session — only that the instruction files are present, placed correctly, and not obviously over-scoped. Live agent behavior depends on the model, the session context, and the tool version, none of which are verified here.

Sanitized audit log record:

audit_date: YYYY-MM-DD repo: tool: instruction_file_path: file_found: true/false path_matches_docs: true/false broad_permission_flags: [] contradiction_flags: [] stale_rule_flags: [] reviewer: action_taken: none / narrowed / removed / escalated

Do not record real file paths that contain credentials or secrets, real branch names tied to in-flight work, or model names or versions that have not been verified against current documentation.

CometAPI gateway context

If your coding agent makes model API calls — for example, to run automated review steps during a session — those calls will route through whatever gateway or endpoint is configured in the agent’s environment. Instruction files sometimes include environment variable names or base URL patterns that determine which endpoint the agent uses.

Before a session, check whether any instruction file sets or references an API base URL, model identifier, or authentication environment variable. If it does, confirm that the value is current and matches the endpoint behavior described in the relevant gateway documentation. For CometAPI-routed calls, the CometAPI chat completions reference and model overview describe the current endpoint contract areas to verify — exact endpoint paths, auth schemes, and model identifiers should be confirmed there before publishing setup claims.

If you are evaluating a unified gateway for coding agent model calls, Start with CometAPI to review the current endpoint and model options.

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

OpenAI Codex AGENTS.md guidance - accessed 2026-06-10; purpose: verify repository instruction-file context for coding agents.
GitHub Copilot repository instructions documentation - accessed 2026-06-10; purpose: verify repository instruction guidance.
Claude Code memory documentation - accessed 2026-06-10; purpose: verify project memory and instruction-file context for agent workflows.
GitHub pull requests documentation - accessed 2026-06-10; purpose: verify pull request review and collaboration boundaries.
CometAPI chat completions reference - accessed 2026-06-10; purpose: gateway endpoint contract context for instruction files that reference API base URLs.
CometAPI model overview - accessed 2026-06-10; purpose: model identifier verification context for instruction files that specify model names.

Contract details to verify

Area	What to verify	Source URL	Accessed	Safe candidate wording
AGENTS.md placement path	Confirm the exact file path(s) Codex reads, including whether subdirectory files override or extend root rules	https://github.com/openai/codex/blob/main/docs/agents_md.md	2026-06-10	“Refer to the Codex AGENTS.md documentation for the current authoritative placement path”
Copilot instruction file path	Confirm current path for repository-level Copilot instructions and whether the feature requires a specific GitHub plan	https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions	2026-06-10	“Refer to the GitHub Copilot custom instructions documentation for the current file path and plan requirements”
Claude Code memory file naming	Confirm current filename convention and whether project-level vs. user-level memory files have different scope	https://code.claude.com/docs/en/memory	2026-06-10	“Refer to the Claude Code memory documentation for current file naming and scope inheritance rules”
CODEOWNERS syntax for instruction files	Confirm CODEOWNERS pattern syntax for protecting AGENTS.md and similar files in required-review workflows	https://docs.github.com/en/pull-requests	2026-06-10	“Refer to the GitHub pull request documentation for CODEOWNERS syntax and required-reviewer configuration”
CometAPI endpoint base URL in instruction files	Confirm current base URL and auth header name if instruction files set OPENAI_BASE_URL or equivalent	https://apidoc.cometapi.com/api/text/chat	2026-06-10	“Verify the current base URL and auth scheme in the CometAPI chat completions documentation before setting these values in instruction files”

Reader next step

Compare the workflow against Start with CometAPI .

Use When to Stop, Retry, or Escalate: A Practical Guide to Coding Agent Task Control as the next comparison point. Keep AI Coding Agent Setup, Security, and Model Routing nearby for setup and permission checks.

FAQ

What is the difference between an instruction file and a task brief? An instruction file lives in the repository and sets persistent rules that apply to all agent sessions, or to all sessions within a subtree. A task brief is a per-session or per-PR document that scopes a specific unit of work. Scope checks apply to instruction files; task brief authoring is covered in Write Coding Agent Task Briefs That Produce Reviewable Changes.

Do all coding agent tools read the same instruction files? No. Each tool defines its own placement convention and file name. AGENTS.md, copilot-instructions.md, and CLAUDE.md are not interchangeable. Verify the expected file path in each tool’s documentation before assuming a file is being read.

How often should I run a scope check? At minimum, before any agent session that involves file writes or external calls, and before merging any PR that modifies an instruction file. For high-churn repos, adding instruction file paths to CODEOWNERS so they require explicit review on every PR change is more reliable than manual spot-checks.

Can I have both a root AGENTS.md and subdirectory AGENTS.md files? Some tools support subdirectory instruction files that extend or override the root file for that subtree. The exact inheritance behavior — whether subdirectory rules extend, override, or are ignored — depends on the tool version. Verify the current inheritance model in the tool’s documentation before relying on subdirectory files to restrict permissions granted at the root.

What should I do if I find a rule that looks too broad? Narrow or remove the rule before starting the agent session, then commit and push the change. Do not start a session with a known over-scoped rule and plan to fix it afterwards. If you are unsure whether narrowing the rule will break something, open a PR with the change and get it reviewed before running the agent.

How do instruction file scope checks relate to permission boundaries? Instruction files are one layer of scope control, but they are not the only one. The agent tool’s own permission model, the shell environment it runs in, and the credentials available to it all constrain what it can actually do. For a broader view of permission and secret controls, see Set Safe Permission and Secret Boundaries for Coding Agents.