Coding agents read your repository before they modify it. The instruction file (AGENTS.md, CLAUDE.md, .cursorrules) is the only place you can set defaults for that reading phase. Most teams skip this step and rely on per-prompt instructions, which means every agent invocation starts from zero context.
The pattern mirrors .editorconfig or .prettierrc: a repository-level configuration file that tools parse before execution. The difference is that coding agents execute arbitrary file operations, so the configuration surface is larger and the failure modes are more expensive.
The Configuration Primitive
Repository instruction files sit between three layers:
- System prompts (vendor-controlled, opaque)
- Repository instructions (developer-controlled, versioned)
- Inline comments (context-specific, scattered)
When an agent assembles a prompt, it merges these layers. The repository instruction file is the only one you control that applies to every agent invocation in that repository.
The file format is unstructured Markdown. No schema, no validation, no standard parser. Each agent tool reads it differently:
- Cursor reads
.cursorrulesfirst, then falls back to system instructions - Aider reads
CONVENTIONS.mdorAIDER.mdif present - Claude Code looks for
CLAUDE.mdin the repository root - Copilot Workspace ignores repository files entirely and relies on system prompts
This creates a versioning problem: if your team uses multiple agent tools, you need multiple instruction files or a lowest-common-denominator format that all tools can parse.
The Ten-Line Baseline
The original Dev.to post proposes a minimal configuration that covers the most common failure modes. Here’s the structure, with the plumbing exposed:
1. Scope Sentence
One line describing what the repository is. This anchors every prompt the agent assembles.
This repo is a Python CLI for log reconciliation. Python 3.12. No web framework.Why it matters: Without this line, the agent infers project shape from file names. A server.py file might trigger web framework assumptions even if the project is a batch processor.
2. Verification Command
The exact command that proves the work. Not “run the tests” but the literal shell invocation.
Verify with: pytest tests/test_parser.py -k "failing_case"Why it matters: Agents cannot distinguish between “tests passed” and “tests ran.” A verification command that exits with code 0 on success gives the agent a boolean signal it can use in its execution loop.
3. Smallest-Command Rule
Run only what the current step requires. No full test suites between steps.
Run only the tests affected by the current change. No full suites between steps.Why it matters: Agents default to over-verification because they have no cost model for CI time. This line creates a heuristic that reduces feedback loop latency.
4. Do-Not-Touch List
Explicit paths that must never be regenerated or edited.
Never edit: docs/generated/, .env*, pnpm-lock.yaml, CHANGELOG.mdWhy it matters: Agents cannot infer sacred paths from file metadata. A lockfile looks like any other YAML file. A generated directory looks like source code.
5. Ticket Workflow
Test-first workflow: write the test, watch it fail, write the code, watch it pass.
Test first: write the test, watch it fail, write the code, watch it pass. One ticket at a time.Why it matters: This converts the agent from a code generator into a TDD machine. Even if the agent executes this poorly, the structure holds.
6. Reporting Format
How the agent should report what it did.
After each change: list files modified, tests run, exit codes.Why it matters: Agents default to verbose natural language summaries. A structured reporting format makes it easier to parse agent output in CI logs or observability tools.
Conflict Resolution
Repository instruction files conflict with existing tooling in three ways:
| Conflict Type | Example | Resolution Strategy |
|---|---|---|
| Linting rules | Agent instruction says “use single quotes,” ESLint config says double quotes | Linter wins. Instruction file should reference linter config, not duplicate rules |
| Pre-commit hooks | Agent modifies files that trigger formatter hooks | Agent should run formatters before committing, or instruction file should disable auto-commit |
| CI/CD policies | Agent runs partial test suite, CI requires full suite | Instruction file controls agent behavior, CI controls merge gates. No conflict if both are explicit |
The failure mode is silent divergence: the agent follows its instruction file, CI fails, and the developer has to reconcile the two manually.
Parsing Priority
When an agent assembles a prompt, it merges multiple instruction sources. The priority order varies by tool, but the general pattern is:
- System prompt (vendor-controlled, always present)
- Repository instruction file (developer-controlled, optional)
- Inline comments (context-specific, optional)
- User prompt (per-invocation, always present)
If these layers conflict, the agent uses the last one it parsed. This means a user prompt can override a repository instruction, which can override a system prompt.
Observability gap: Most agent tools do not expose the merged prompt they actually send to the model. You cannot inspect what the agent “saw” when it made a decision.
State Management
Repository instruction files are stateless. They do not track:
- Which files the agent has already modified
- Which tests have already passed
- Which verification commands have already run
This creates a coordination problem when multiple developers use agents in the same repository. If Developer A’s agent modifies a file, Developer B’s agent has no way to know that without reading git history.
Workaround: Some teams add a .agent-state/ directory to .gitignore and let agents write execution logs there. This is not standardized and breaks when agents run in ephemeral environments (CI, Codespaces).
Security Boundaries
Repository instruction files have no enforcement mechanism. An agent can ignore them entirely. The file is a convention, not a sandbox.
If you need hard boundaries, you need:
- File system permissions (read-only mounts for sacred directories)
- Pre-commit hooks (block commits that violate rules)
- CI checks (fail builds that touch forbidden paths)
The instruction file is a hint to the agent. The enforcement layer is separate.
Deployment Shape
Repository instruction files are committed to version control. This means:
- They are versioned with the code
- They can be reviewed in pull requests
- They can diverge across branches
Merge conflict risk: If two developers modify the instruction file in parallel, git will flag a conflict. This is rare in practice because instruction files change infrequently, but it is a failure mode that does not exist with system prompts.
Code Example: Minimal Instruction File
# Agent Instructions
This repo is a TypeScript API server. Node 20. Express. PostgreSQL.
Verify with: npm test -- --testPathPattern=src/__tests__/integration
Run only the tests affected by the current change.
Never edit:
- dist/
- .env*
- package-lock.json
- migrations/
Test first: write the test, watch it fail, write the code, watch it pass.
After each change: list files modified, tests run, exit codes.
Database changes require a migration file. Never edit the schema directly.
API changes require an OpenAPI spec update in docs/openapi.yaml.
Use existing error handling patterns from src/errors/. Do not introduce new error types without discussion.
Logging goes through src/logger.ts. No console.log in production code.This file is 14 lines. It covers scope, verification, boundaries, workflow, and reporting. It references existing patterns (error handling, logging) instead of duplicating them.
Technical Verdict
Use repository instruction files when:
- Multiple developers use coding agents in the same repository
- The repository has sacred paths (generated code, lockfiles, secrets)
- You need consistent agent behavior across different tools
- You want to version-control agent constraints alongside code
Avoid repository instruction files when:
- You are the only developer and you use one agent tool
- Your repository has no forbidden paths or special workflows
- You prefer per-prompt instructions over repository-level defaults
- You need hard enforcement (use file permissions and CI checks instead)
Repository instruction files are a coordination primitive, not a security primitive. They work best when combined with enforcement layers (linters, hooks, CI) that catch violations the agent missed.