How to Write Repository Instructions for Coding Agents

Last reviewed: 2026-05-20

Direct answer

Repository instructions for coding agents are the durable rules that tell an AI coding tool how to work inside one codebase. They should explain where project context lives, which commands are safe to run, how to handle tests, how to protect secrets, how to avoid unrelated refactors, and what evidence a human reviewer needs before accepting a change.

A good instruction set is short enough for the agent to follow, specific enough to prevent risky guesses, and paired with a task brief for each piece of work. Use repository instructions for standing rules, and use task briefs for the current objective, acceptance criteria, files in scope, and known blockers.

If you already maintain context files for agents, connect this article with the broader workflow in Repository Context and Parallel Agent Workflows .

A practical smoke-test workflow for repository instructions:

1. Setup assumptions: the repository has a clean working tree, a visible instruction file, a small safe task, and at least one verification command that does not require private credentials.
2. Happy-path request plan: ask the coding agent to make a tiny documentation or test-only change while following the repository rules.
3. Error-path check: include one instruction that forbids a tempting but unsafe action, such as editing unrelated files or printing secret-like values, then confirm the agent avoids it.
4. Minimum assertions: record whether the agent found the instructions, stayed within scope, ran or explained the verification step, summarized changed files, and named any skipped check.
5. Pass/fail logging fields: keep a short record with placeholder values only.
6. What not to assert: do not claim model reliability, cost, speed, security coverage, or tool compatibility beyond what the checked sources explicitly document.

Sanitized log-record template:

instruction_file: "AGENTS.md or repository instruction file"
agent_tool: "example-agent-name"
task_type: "small-doc-change"
allowed_files: "docs/example.md"
forbidden_actions_checked: "no unrelated edits; no secret output"
verification_command: "placeholder test or lint command"
result: "pass | fail | needs-human-review"
changed_files: "placeholder list"
notes: "short observation without credentials, prompts, or full responses"

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

Who this is for

This guide is for engineering leads, developer-experience teams, staff engineers, and solo maintainers who want coding agents to make safer changes in real repositories. It is especially useful when multiple tools may touch the same codebase, such as terminal agents, IDE assistants, cloud coding environments, or human-created worktrees.

Key takeaways

• Put standing project rules in one predictable repository instruction file instead of repeating them in every prompt.
• Separate durable rules from one-time task briefs so the agent can distinguish project policy from the current assignment.
• Include verification commands, file-scope boundaries, secret-handling rules, and handoff expectations.
• Make instructions tool-aware without assuming every coding agent reads the same file name, memory layer, or cloud environment.
• Use Git worktrees or equivalent isolation when running parallel agent tasks, and verify branch state before merging.
• Keep claims modest: exact behavior depends on the agent, repository host, editor, cloud environment, and current documentation for each tool.

Sources checked

• OpenAI Codex AGENTS.md documentation - accessed 2026-05-20; purpose: verify AGENTS.md-style repository instruction guidance for Codex-oriented workflows.
• GitHub Copilot repository instructions documentation - accessed 2026-05-20; purpose: verify GitHub repository custom instruction concepts and placement guidance.
• Claude Code memory documentation - accessed 2026-05-20; purpose: verify Claude Code memory and project-instruction concepts.
• OpenAI Codex cloud documentation - accessed 2026-05-20; purpose: verify cloud coding environment context at a high level.
• Git worktree reference - accessed 2026-05-20; purpose: verify worktree terminology and isolation mechanics for parallel repository work.

Contract details to verify

A repository instruction file should usually cover these areas:

• Project overview: what the repository does and where the main systems live.
• Authority order: which documents or maintainers override other instructions.
• Scope control: files the agent may edit, files it should avoid, and when to ask for human input.
• Verification: exact test, lint, build, or smoke-check commands that are safe to run.
• Secrets: where credentials must not be printed, copied, committed, or inferred.
• Git behavior: branch naming, commit rules, pull request expectations, and worktree cleanup.
• Handoff: required summary format, changed files, checks run, skipped checks, and remaining risks.

A task brief should be narrower:

task: "Add a small validation test for the parser"
context: "Parser rules are in src/parser; existing tests are in tests/parser"
in_scope: "tests/parser only unless implementation bug is proven"
out_of_scope: "formatting-only refactors, dependency upgrades, deployment files"
verification: "run the parser test command documented by the repository"
acceptance: "new failing case is covered; all relevant parser tests pass"
stop_conditions: "missing fixture, unclear expected behavior, or credential request"

This split keeps the standing rules stable while making each agent run easier to review.

Failure modes

The common failure mode is not that the agent ignores every rule. It is that the instruction file is too vague, stale, or broad, so the agent applies a real rule to the wrong task. Watch for these patterns:

• The instructions name old commands that no longer run.
• The file tells the agent to be careful but does not name forbidden files or approval boundaries.
• The task brief asks for a feature, but the repository rules still describe an old architecture.
• Two tools read different instruction locations, and the team assumes they share the same context.
• Parallel agent sessions work in one checkout and overwrite each other’s assumptions.

Treat those as maintenance bugs in the instruction system. Fix the rule, run a small smoke test, and only then ask the agent to handle a larger change.

Reader next step

Start with the setup and model-routing guide , then compare this instruction-file pattern with the repository context and parallel workflow guide . If a change reaches review, finish with the test repair and PR workflow .

FAQ

Should every repository have an AGENTS.md file?

Not automatically. Use the instruction filename that your selected tool documents. AGENTS.md-style rules are useful when the coding agent supports them, but other tools may use repository custom instructions, memory files, editor settings, or cloud environment configuration instead.

What belongs in repository instructions instead of a task prompt?

Put durable rules in repository instructions: coding standards, verification commands, security boundaries, review expectations, and handoff format. Put temporary goals in the task prompt: the specific bug, feature, file list, acceptance criteria, and deadline.

How long should repository instructions be?

Long enough to prevent common mistakes, but short enough for an agent and a reviewer to scan. Prefer concrete rules over general advice. If a rule is rarely relevant, link to a deeper document instead of placing every detail in the main instruction file.

Can one instruction file work across Codex, Copilot, Claude Code, and other agents?

A shared policy can help, but do not assume identical behavior across tools. Verify each tool’s current documentation for file names, loading behavior, memory behavior, and cloud execution assumptions.

How do worktrees help with coding agents?

Git worktrees can give separate working directories to separate tasks while sharing one repository. That can reduce branch conflicts when several agent sessions run in parallel, but maintainers still need branch discipline, cleanup steps, and human review before merging.

What is the safest first test of new repository instructions?

Start with a small documentation or test-only change. Confirm the agent reads the instructions, stays within scope, avoids forbidden actions, reports verification results, and produces a reviewable handoff. Expand only after the basic behavior is repeatable.