Skip to main content
Project instruction files give an agent persistent context about a repository: how to run it, which checks matter, where important code lives, and what conventions to follow. Keep them in the project so the guidance travels with the code. The harness determines how these files load. The model provider does not choose the instruction filename. For example, using a Google model does not by itself mean you are running the Gemini CLI harness. See Models and harnesses.

​
Choose the instruction file

Codex’s instruction discovery includes AGENTS.override.md and configurable fallback filenames. These are Codex rules, not universal rules for every Kisuke harness. Refer to the official Codex instruction guide for details. Claude Code’s direct AGENTS.md support depends on its version and configuration. A root CLAUDE.md remains the explicit setup described here. See Claude Code’s instruction documentation for current version-specific behavior.

​
Write useful project guidance

Start with facts and constraints that matter to this project. For a small static site, an instruction file could contain:
For a larger project, include the actual build and test commands, links to architecture documents, and boundaries that should not change. Check each command yourself before recommending it to the agent. Update the file when the workflow changes. Keep instructions specific enough to verify. For example, “check that completed trails survive a reload” gives a clearer expected result than “test everything.” Put longer task procedures in skills when they apply only to certain requests.

​
Share guidance between Codex and Claude Code

If your repository already has an AGENTS.md, create a neighboring CLAUDE.md containing:
This uses Claude Code’s documented import syntax to read the shared file. Add any Claude-specific guidance below it. See the Claude Code import guidance. Do not assume that the @ import syntax works in every harness. Pi’s loader chooses the first readable candidate in each folder, checking AGENTS.md before CLAUDE.md; it does not combine both files from the same folder through that discovery step.

​
Check the project and working folder

Place the file in the actual working copy used by the conversation. If the project runs on another device, edit the file there. If you are using a separate worktree, confirm that its files include the instructions you expect. Nested instructions have harness-specific scope and loading behavior. For shared project rules, start at the project root. Add narrower files only when you understand the active harness’s discovery rules and have checked the result.

​
Verify before a larger task

  1. Save the instruction file in the project’s working folder.
  2. Open a new conversation for that project. Check the selected device, harness, and model before sending.
  3. Ask about a concrete instruction without copying its expected answer into your prompt.
  4. Compare the response with the saved file before requesting a larger task.
For the Trail Notes example above, use:
In this example, Pi with DeepSeek V4 Flash began with Trail Notes source review, identified index.html, and quoted the persistence instruction, including Reset after a reload. The turn completed without tool calls. The expected text came from project context; it was not included in the request.
Trail Notes source review identifies index.html and quotes the instruction to check a page reload, a fresh browser session, and Reset after a reload.

A new Pi conversation in Zen quotes the updated project instruction, including Reset after a reload.

Zen shows a completed project-instruction check using Pi and DeepSeek V4 Flash. The request does not supply the expected instruction; the response quotes it and the composer is idle.
An accurate quotation is a useful check that the conversation has the expected guidance. It does not prove that every instruction will be followed during later work. Review the actual edits, tool results, and reported checks as the task proceeds.

​
Check again after editing instructions

Saving an instruction file does not establish that an active conversation has reloaded it. With Pi, an active session can retain earlier guidance: in the example above, the existing chat still quoted the original persistence instruction after the file changed. A new conversation quoted the updated version. After changing project instructions, save the file, start a new conversation for the same project and harness, and repeat a focused check. Compare the specific detail you changed. Do not use an earlier response as evidence that the current file has loaded, or assume another harness uses the same reload behavior.

​
Troubleshoot missing guidance

If guidance is missing or unexpected, check:
  • The conversation’s project, device, working folder, and harness.
  • The filename expected by that harness.
  • Overrides or instruction files in parent folders and the harness’s user configuration.
  • Whether you changed the file after starting the conversation.
  • Whether the instructions conflict or depend on an unsupported import mechanism.
Instruction files guide the model. Use permissions for tool-approval behavior; a sentence in an instruction file is not an enforced access-control rule.