Pack Repository Context So Coding Agents Understand Your Codebase

Last reviewed: 2026-06-04

Coding agents only produce useful output when they understand what they are working in. Without structured context, an agent reads unfamiliar code, guesses at conventions, and generates changes that fail review or break unrelated modules. Repository context packing is the practice of writing and organizing the files, rules, and isolation boundaries that agents read before they start — so that every task begins with a shared understanding of the codebase.

This guide covers the four practical layers: instruction files that set rules once, memory and project files that scope per-session behaviour, Copilot repository instructions that deliver context inside the IDE, and git worktrees that give parallel agents clean, isolated branches to work in.

Direct answer

To pack repository context for a coding agent:

1. Write an instruction file at the repo root. For Codex-based agents, this is AGENTS.md. For Claude Code, this is CLAUDE.md. Place the file at the project root or in a subdirectory where you want rules to apply. The file should cover: coding conventions, forbidden actions, test requirements, and where to record task status.

2. Scope memory and project files to the task. Claude Code reads project memory from CLAUDE.md files at the project root and in subdirectories. You can place a subdirectory-level CLAUDE.md to override or extend root rules for a specific module or service. Verify the current file-discovery behaviour in the linked source before relying on exact read order.

3. Add Copilot repository instructions for IDE workflows. GitHub Copilot reads a .github/copilot-instructions.md file and applies its content to every Copilot interaction in that repository. Keep these instructions focused on style, naming conventions, and which files the agent should avoid touching directly.

4. Isolate parallel agents with git worktrees. When you run more than one agent at the same time, use git worktree add to give each agent its own working tree on a separate branch. Agents in different worktrees cannot overwrite each other’s in-progress files. Remove worktrees with git worktree remove when the branch is merged.

5. Verify what each agent actually read. Ask the agent to summarise the rules it received before it starts writing code. If the summary is wrong or incomplete, the context file is the problem — not the agent.

Smoke-test workflow

Setup assumptions

• A local repository with at least one instruction file (AGENTS.md or CLAUDE.md) committed at the root.
• An agent CLI installed and authenticated (exact authentication requirements vary by tool; verify with your agent’s current documentation).
• git available in the shell with at least one committed branch.

Happy-path plan

1. Run the agent on a narrow task — for example, “Add a docstring to the function in src/utils.py following the conventions in AGENTS.md.”
2. Before accepting any file change, ask the agent: “What rules from the context file apply to this task?”
3. Verify the agent’s summary matches the rules you wrote.
4. Review the diff. Confirm the agent touched only the scoped file.
5. Run the project test suite. Confirm it passes.

Error-path check

1. Temporarily rename AGENTS.md to AGENTS.md.bak and repeat the same task.
2. Compare the agent’s behaviour and diff. If the agent produces conventions-compliant output without the file, the file content was either redundant or the agent used a cached context. If the output drifts, the file is doing its job.
3. Restore the file.

Minimum assertions

• The agent’s rule summary mentions at least one constraint from the instruction file.
• The diff contains no changes outside the scoped path.
• Tests pass after the change is applied.

What this smoke test must not assert

• Do not assert specific model names, pricing, or token counts — these vary by gateway configuration.
• Do not assert that the agent will always read files in a specific order without consulting the current tool documentation.
• Do not assert that git worktrees prevent all possible conflicts; they prevent working-tree conflicts, not logical merge conflicts.

Sanitized log record template

date: YYYY-MM-DD agent_tool: task_slug: context_file_read: true | false | unknown rule_summary_accurate: true | false diff_scoped: true | false tests_passed: true | false notes: <free text, no credentials or prompts>

For broader release checks, see AI Coding Agent Setup, Security, and Model Routing .

Who this is for

This guide is for engineers and platform teams who run coding agents in real repositories — not sandboxes. If you are:

• Adopting a coding agent for the first time and want to avoid the most common failure mode (agent ignores your project conventions), start with a minimal AGENTS.md or CLAUDE.md at the repo root.
• Running multiple agents in parallel on the same codebase and seeing file conflicts or branch collisions, the git worktree section covers how to isolate them.
• Maintaining a shared repository where Copilot is used by multiple contributors, the Copilot instructions section covers how to set team-level defaults without per-user configuration.
• Debugging an agent that produces wrong output, the smoke-test workflow section gives you a structured way to separate a context problem from a model-capability problem.

For related guidance on writing the content of your instruction files, see How to Write Repository Instructions for Coding Agents.

Key takeaways

• An instruction file at the repo root (AGENTS.md for Codex, CLAUDE.md for Claude Sonnet 4.6) is the most reliable way to give a coding agent persistent rules that survive across sessions. Verify the exact filename and read behaviour in the linked source for your tool.
• Subdirectory-level files let you scope rules to a specific module without changing the root file. The read order and override behaviour depend on the agent tool — check the current documentation before assuming a specific merge strategy.
• GitHub Copilot reads .github/copilot-instructions.md and applies it to all Copilot interactions in the repository. Keep this file short, specific, and focused on actionable constraints rather than background context.
• Git worktrees give parallel agents isolated working trees on separate branches. This is the correct isolation primitive for parallel coding agents; it is not a substitute for code review.
• Always verify what context the agent received before accepting its output. A summary check before the agent starts writing code costs less than reviewing a diff produced with wrong assumptions.
• Exact file-discovery order, memory scoping rules, and worktree command flags must be verified in the linked official documentation before production use; these details change between tool releases.

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-04; purpose: verify repository instruction-file context for coding agents.
• GitHub Copilot repository instructions documentation - accessed 2026-06-04; purpose: verify repository instruction guidance.
• Claude Code memory documentation - accessed 2026-06-04; purpose: verify project memory and instruction-file context for agent workflows.
• Git worktree documentation - accessed 2026-06-04; purpose: verify parallel worktree isolation commands and constraints.

Contract details to verify

FAQ

Do I need both AGENTS.md and CLAUDE.md in the same repository? No. Use the file that matches your agent tool. AGENTS.md is read by Codex-based agents; CLAUDE.md is read by Claude Sonnet 4.6. If you use both tools in the same repository, you can maintain both files with consistent but tool-appropriate content. Verify which files each tool reads in the linked documentation.

Where should the instruction file live — root or subdirectory? Start at the root to cover the entire repository. Add subdirectory-level files only when a specific module needs rules that differ from the root. The exact read order and override behaviour depends on the agent tool, so verify before assuming subdirectory files silently extend root rules.

Does .github/copilot-instructions.md affect all contributors automatically? Once the file is committed to the repository, GitHub Copilot applies its content to all Copilot interactions in that repository for users with Copilot access. Individual users cannot currently override repository instructions with personal settings in most configurations, but verify the current behaviour in the GitHub Copilot documentation as this may change.

How many worktrees can I run at the same time? Git does not impose a hard limit on concurrent worktrees. Practical limits come from disk space, CI runner availability, and the number of branches your review process can handle. The git worktree list command shows all active worktrees. Verify command flags with the git-worktree reference for your installed version.

Will the agent automatically find my instruction file? Most coding agents look for their instruction file at a known path relative to the working directory. If the agent is launched from a subdirectory, it may not find a root-level file. Always launch the agent from the repository root or confirm the tool’s working-directory discovery behaviour in its documentation before running.

Can I use a model gateway for context-heavy agent tasks? Yes. A model gateway lets you route context-heavy agent tasks to models with larger context windows and switch routing without reconfiguring each agent. For teams running multiple agents against different model families, Start with CometAPI to explore gateway-level routing options. Verify current model availability, pricing, and endpoint behaviour in the CometAPI documentation before increasing usage.

Reader next step

Turn the next coding-agent request into a one-page task brief, then compare it with How to Write Repository Instructions for Coding Agents . For the surrounding setup and permission baseline, review AI Coding Agent Setup, Security, and Model Routing before assigning broader repository work.