Project instructions and first permissions

Every agent session starts with no memory of your project. So that it need not be told the same things every time, most agent tools read a project instruction file at the start of a session. Its content becomes part of the system prompt: rules that apply to every request in that project.

A good instruction file is short and checkable. Compare "write clean code" with "run the relevant tests and the type check before saying you are done". The first cannot be checked; the second can. Write rules whose violation would be visible.

The most useful content is usually:

• How to check work: the test command, the type check, the build, and when each is required.
• How the team works: one branch per task, commit messages, which files belong to whom.
• Clear prohibitions: never add every file to a commit at once, never touch the database on the default port, never merge to the main branch.
• What is easy to get wrong in this project: lessons from earlier incidents, one line per lesson.

What not to write: long explanations of the programming language, motivation, or things the agent can read from the code itself. Every line in the instruction file is reread in every session and costs context, so trim what is not used.

Instructions tell the agent what it should do. Permission rules decide what it can do. The difference matters: a model can misread or be misled by instructions, but permission rules are enforced by the app, outside the model.

Draft first permission rules in three levels:

1. Allow without asking: cheap, safe actions, such as reading project files or running specific test commands. This is an allowlist in the true sense: closed, only what is named.
2. Ask first: actions that change something outside the workspace, such as pushing changes to a shared repository or installing a new package.
3. Deny: actions that must not happen in this session at all, such as reading secret files or deleting folders.

Start narrow. If the agent asks too often about actions that turn out to be safe, move those actions to the allow list one by one, after you have seen them. Do not start from "allow everything" and hope to patch later. Remember too that permission rules matter as much as the instruction file: both live in the repository, are reviewed like code and are changed with a written reason.

As a worked example, this is how it looks in Claude Code. The project instruction file is called CLAUDE.md at the project root and is read at session start. Permission rules live in .claude/settings.json (shared with the team through the repository) or in the personal local settings file in the same folder (only for you, for one project), under the permissions key with allow, ask and deny lists:

{
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  }
}

deny and ask rules in project files apply at once; allow rules from a committed file apply only after each team member trusts the folder. The /status command shows which settings files were read. A step specific to Anthropic; check the latest version in its documentation, because setting names and behaviour can change.