Instructions

Repository instruction files give agents persistent guidance about a project. They are useful for setup commands and code conventions. They also cover directory responsibilities and checks that apply across tasks.

Keep Instructions Short And Actionable

Effective guidance states behavior and boundaries in a few lines. The editor saves pipelines and must not start a run when saving. Storage access stays in the storage module. Step order survives saving and loading. The documented checks run before the agent reports completion. The agent reports any check that could not run, with a reason.

This guidance identifies behavior and boundaries. A long history of previous mistakes is harder to maintain. Move detailed architecture and task-specific decisions into linked documents you can read when needed.

Use The File The Application Reads

Codex supports an AGENTS.md file. Claude Code uses CLAUDE.md for project instructions and also supports scoped rules. Other applications have their own discovery and precedence rules. A filename is only effective when the installed application loads it.

Keep shared guidance for both tools in one maintained document and reference it through each tool's supported instruction mechanism. Check what loaded in an actual session. Avoid maintaining conflicting copies.

Every Line Competes For Attention

An AGENTS.md or CLAUDE.md file loads into every session whether the task needs it or not. Each line takes a share of the model's attention away from the work. A file with five rules gives each rule more attention than a file with fifty. Adding a rule weakens the rules already there.

Claude Code also presents the CLAUDE.md file to the model with a note that its contents may or may not be relevant. The model is primed to treat them as optional. Keep the standing file to guidance every task needs and load the rest on demand.

Load Detail On Demand

A specifications folder holds the detail that does not belong in the standing file. Each document covers one feature. It states what the feature does and where its code lives, then how to work in it, including mistakes agents tend to make there. A short README at the top of the folder maps features to documents.

Reference the relevant document at the start of a task. The agent reads the storage specification when it works on storage and skips the rest. Split any document that grows past a few hundred lines into sub-features. A specification helps only while it matches the code. A hook on each commit or a dedicated sync command can update it after each change.

Enforce Critical Rules In Code

Natural-language instructions guide model behavior; they cannot guarantee it. A rule that requires tests before release belongs in the release workflow as well. File permissions and validation should enforce boundaries that must hold even when the agent misses an instruction, and so should gates.

Place each rule at the most reliable level it fits. A rule a script can check belongs in a hook. A procedure too fuzzy for a script belongs in a skill or command that loads when invoked. Rules for certain paths belong in a path-scoped rule file. Only what remains goes in the always-loaded file.

Review changes to instruction files alongside code changes. An agent should not resolve a failing task by weakening the project's acceptance criteria.

Exercise 6: Cut Down The Instruction File

Open the instruction file of a real project and note its length in lines and words. Read each line and ask whether an agent starting an unrelated task would need it. A line that fails belongs in a specification document the agent opens only when it works on that feature, so move it there.

Choose one rule a script could check, write the check, and delete the sentence it replaces. Start a task that depends on the guidance left in the file and confirm the agent still follows it. Compare the new length with the old one, since every line removed leaves more of the model's attention for the rules that stay.

September, 2026