How to Structure Repository Instructions for Coding Agents

How to Structure Repository Instructions for Coding Agents

Good repository instructions are small, scoped, attributable, and connected to verification. They tell a coding agent what remains true across tasks without forcing every procedure, historical decision, and temporary status update into one permanent prompt.

The structure should answer five questions before the agent edits a file. What source controls this decision? Where does the instruction apply? Who owns it? When should it be refreshed? How will the agent prove that it followed the instruction?

The exact filenames depend on the harness. Claude Code uses CLAUDE.md, .claude/rules/, and skills. Codex uses layered AGENTS.md files and skills. Other tools have their own conventions. The architecture below is portable even when the syntax is not.

Start with information type, not tool branding

The most common failure is a giant instruction file. It begins with build commands, then gains coding preferences, release procedures, API examples, architecture history, a list of known bugs, and reminders from last week's incident. Every session pays the context cost. No one knows which sentence is still authoritative.

A better system separates information by stability and scope.

This division reduces ambiguity. A coding convention can remain stable while the task state changes every hour. A deployment skill can evolve without making every feature request load the whole release manual.

How the major harnesses load instructions

Anthropic's Claude Code extension guide says CLAUDE.md provides persistent context, .claude/rules/ can hold path-scoped guidance, and skills load on demand. Anthropic suggests keeping CLAUDE.md under 200 lines and moving reference material elsewhere as it grows.

OpenAI's Codex AGENTS.md guide describes a different discovery model. Codex first considers global instructions and then reads project instructions from the repository root toward the current working directory. Files closer to the working directory can refine earlier guidance. The default combined project-document limit is 32 KiB, so a sprawling hierarchy can still be truncated.

OpenAI's skills documentation uses SKILL.md as the entry point for reusable workflows and reference material. The full skill is loaded when selected, while its supporting files can be read as needed.

These systems share an important principle without sharing one universal file format. Persistent context should be compact. Specialized knowledge should be discoverable. Narrower scope should live closer to the work.

flowchart TD
    A["Repository charter"] --> B["Subsystem or directory rules"]
    B --> C["Task specification"]
    C --> D["Selected skill or workflow"]
    D --> E["Implementation"]
    E --> F["Generated evidence"]
    F --> G["State and handoff update"]
    G --> C

The lower layers change more often. That is why task state and evidence should not be copied back into the repository charter.

Write the repository charter

The charter is the smallest document a new human or agent needs before working safely. It should identify the project, the authoritative documentation, the supported build and test commands, the main architectural boundaries, and actions that require explicit approval.

Avoid personality prompts and vague ambitions. “Write excellent code” is not verifiable. “Run npm test after changing the parser and report any failing test by name” gives the agent an action and the reviewer an observable result.

Name authority directly. If the database schema controls data shape, say so. If an architecture decision record controls a boundary, link it. If generated API documentation is secondary to an OpenAPI file, state the precedence. An agent cannot resolve a contradiction that the repository refuses to acknowledge.

Keep the charter resistant to routine change. Active issue numbers, current branch status, and one-time debugging notes belong elsewhere.

Add scoped rules where decisions diverge

A monorepo may use one testing convention for a web application and another for a data pipeline. A global instruction that tries to explain both becomes long and easy to misapply.

Place narrower rules with the subsystem they govern when the harness supports it. Claude Code can scope rules by path. Codex can discover additional AGENTS.md files as it moves from the project root toward the working directory. Other tools may require an explicit reference from a root file.

A scoped rule should explain why it exists, which paths it controls, the expected validation, and the source of truth. It should not repeat the root charter. Duplication creates two copies that can drift.

Treat precedence as a design choice. If a local rule may override a root preference, say which parts can change and which cannot. Security boundaries and authorization limits should not disappear because a nested folder contains a friendlier instruction.

Move repeatable procedures into skills

A procedure belongs in a skill when it is needed for a class of tasks but not every task. Examples include running a release, adding a database migration, reviewing an accessibility change, or preparing a threat model.

Anthropic's skills documentation describes a required SKILL.md with optional reference files, examples, and scripts. The layout supports progressive disclosure: the entry file stays focused while detailed material is read only when needed.

A skill should define its trigger, prerequisites, permitted actions, required evidence, and stop conditions. It should not quietly expand authority. A release skill may prepare artifacts and run checks while still requiring a person to approve publication.

Scripts inside skills deserve normal code review. They execute with the user's environment and may access files, tools, or network services. The fact that a script arrived inside a Markdown-centered package does not make it inert.

Keep task specifications close to the task

The task specification describes the outcome for one piece of work. It should include acceptance criteria, constraints, dependencies, files or systems in scope, and the validation expected at handoff.

Do not convert every task into a permanent rule. If an agent discovers a recurring gap, it can propose a rule change. A human should decide whether the lesson is truly durable, whether it belongs globally or locally, and whether an existing instruction should be replaced.

This review step prevents “continuous learning” from becoming continuous accumulation. A rule that was sensible for one incident can create damage when generalized to every future task.

Separate state from evidence

Current state answers what is happening now. Evidence answers what happened during a specific run.

A state note may say that a migration is prepared but not applied, that one test remains broken, or that the next task depends on a pending API decision. Evidence contains the command output, diff, screenshot, or trace that supports those statements.

Do not let the agent overwrite raw evidence with a summary. Preserve logs or test reports when they matter, then link to them from the handoff. A concise state file can remain readable without becoming the only record.

Review imported instructions as software

Google's agent-file security analysis groups the expanded attack surface into what executes, instructs, connects, and extends. That framework is useful for any imported agent configuration.

Before adopting a community pack, identify every executable script and hook, every persistent instruction, every external connection, and every extension or plugin. Inspect environment-variable references, endpoints, tool permissions, install destinations, update behavior, and any setting that can suppress warnings.

Pin the version reviewed. Begin with the smallest useful component. Test it in an isolated repository without production credentials. Confirm which existing files the installer preserves, merges, or replaces. Popularity and an open-source license do not answer those questions.

Run a repository context audit

Use this sequence on an existing project.

1. Inventory every instruction file, rules folder, skill, hook, agent definition, MCP configuration, task-state file, and generated evidence folder.

2. Mark the owner, scope, authority, and last review date for each item. Anything with no owner is a candidate for removal or reassignment.

3. Find duplicated or conflicting instructions. Choose one controlling source and replace copies with references where the harness can resolve them.

4. Move task-specific and volatile material out of always-loaded files. Place reusable procedures in skills and current work in task state.

5. Review executable and connected surfaces. Hooks, scripts, plugins, and MCP servers need permissions, endpoints, credentials, and failure behavior documented.

6. Add a validation expectation to every instruction that can be tested. Prefer named commands, observable outputs, and explicit stop conditions.

7. Test the resulting hierarchy from a clean session in each supported harness. Ask the agent to state which instructions it loaded and verify that behavior against the tool's diagnostics or documentation.

The audit is complete when a reviewer can trace a decision from task request to controlling instruction to evidence. A smaller instruction system that people understand is more useful than a large one that appears comprehensive.

What should never enter the repository

Secrets do not belong in AGENTS.md, CLAUDE.md, skills, examples, hooks, or copied configuration. Use an approved secret store or runtime environment injection.

Private customer data, production credentials, personal paths, and raw proprietary material should also remain outside reusable public packs. Examples should use inert values and explain where real inputs are supplied.

Repository instructions should not grant themselves authority. A file can describe a deployment process without authorizing deployment. A hook can enforce a check without deciding that a business release is approved.

A durable standard

The best repository instruction is not the most detailed one. It is the smallest authoritative instruction that appears at the right scope and produces evidence a reviewer can inspect.

Episode 111A shows the motivation: repeated prompting does not scale, and a giant file becomes noisy. The structured alternative is a context system whose layers change at the pace of the information they hold.

For the component-level distinction, continue to [[Rules Commands Skills Hooks and Agents Explained|Rules, Commands, Skills, Hooks, and Agents Explained]]. For a versioned example of a large community package, read the [[ECC Review - What to Borrow and What to Review First|ECC review]].

Verification and disclosure

This guide was checked on July 27, 2026 against current Anthropic Claude Code documentation, current OpenAI Codex documentation, Google's agent-file security analysis, ECC 2.0.0 at commit 6a9f075, and the E111A transcript.

Harness discovery rules, precedence, limits, and extension behavior can change. Verify the current official documentation for every tool in use. AI assisted with research organization and drafting; evidence boundaries and final editorial decisions remain Dalton Anderson's.