Instructions and project files

Make rules concise, testable, and durable.

Result

Every new session receives the same durable project rules from a root instruction file, while the current task carries only its own goal, inputs, output, and acceptance criteria.

Root instruction file

Include the project purpose, source-of-truth locations, privacy boundary, allowed output locations, required checks, actions that need confirmation, completion evidence, and handover format. Keep case-specific names, temporary deadlines, and one-off prompts in the task brief instead.

Actions

1. Put Codex rules in root AGENTS.md or Claude Code rules in root CLAUDE.md; use both only when the project actively supports both platforms.
2. State the project purpose, accountable human, permitted data, prohibited data, and source-of-truth hierarchy.
3. Identify the locations for unchanged inputs, intermediate work, candidate outputs, and verification evidence.
4. Record mandatory checks, acceptance evidence, and the required handover format.
5. List actions that require confirmation, especially publication, messages, destructive operations, new credentials, and broader access.
6. Remove task-specific details and rules that cannot be observed or tested.
7. After every instruction change, start or simulate a fresh session and ask the agent to state the effective rules and file scope.

Check

A fresh session identifies the same purpose, data boundary, source hierarchy, writable locations, checks, and confirmation points without any pasted history. Two instructions do not contradict each other at different directory levels.

If it fails

Locate the instruction file that should govern the failed action and check its scope. Replace vague intent with an observable rule that names the file or action and expected evidence. If two rules conflict, keep the stricter data boundary and resolve the ownership conflict before continuing.

Next: Skills, plugins, and MCP.