Project instruction files explain durable constraints to a coding agent: how to build, where state belongs and what must be verified. They are not a substitute for source code, tests or permissions.

Put stable decisions in the project

A conversation is a poor place to keep the only copy of your build command. Put recurring facts in a short instruction file next to the project. Keep task-specific goals in the current brief. This avoids burying the important constraints under yesterday's debugging transcript.

Where project knowledge belongs
  1. 1Stable rules → instructions
  2. 2Current goal → brief
  3. 3Executable checks → scripts
  4. 4Results → evidence record

For Codex, OpenAI documents AGENTS.md instructions. Claude Code documents CLAUDE.md project memory, and Gemini CLI documents GEMINI.md context files. File discovery and precedence belong to the individual client; do not assume renaming one file guarantees identical behavior everywhere.

A useful starting document

# Project workflow
- Inspect the existing project and scheme before editing.
- Keep UI-observed state on the project's intended actor.
- Use named color assets and support Dynamic Type.
- Preserve loading, empty, content and error states.
- Run the relevant build and tests after a change.
- Report commands, failures and checks that could not run.
- Do not modify signing settings as an incidental fix.

This example describes a workflow. Add your actual project paths and tested commands after you have established them. Do not copy a deployment target or scheme from another app merely to make the file look complete.

Separate guidance from enforcement

Need Put it in Why
Stable architecture decision Project instructions The agent needs context before editing
Current feature requirements Task brief They change between tasks
Repeatable validation Test or script It can produce an executable result
Prevent editing a generated file Supported guard/hook A reminder alone does not enforce a boundary

The repository's instruction entry point asks agents to retrieve relevant local source before expanding context, preserve state transitions and report failures. Those are useful constraints to study; copying the whole library into every app instruction file would make the important local facts harder to find.

Avoid conflicting mirrors

If several clients share a project, choose a canonical instruction source and a documented way to synchronize the client-specific files. After a change, compare the mirrors. A stale file can tell one client to follow a rule that another client no longer sees.

Do not add private credentials to instructions. They are ordinary files that may be committed, indexed or read by tools. Prefer references to the project's established secret-loading mechanism, without including the values.

Check that the instructions are useful

Ask the client to identify the relevant project instructions and summarize the build/check requirements before editing. Inspect the answer against the files. Then run a small task and verify the resulting behavior; a correct summary is not proof that every instruction was enforced.

The exercise is complete when another developer can read the file and reproduce the intended check without recovering context from your chat history.

What to do next

Next: Skills, plugins, MCP servers, hooks: the four words you'll see everywhere, explained once