0003. The agent contract lives in Claude Code's managed layer

What I expect from an AI agent everywhere is generated into Claude Code's read-only managed file.

• Status: accepted
• Date: 15/08/2026, when rule 18 was written

Context

What I expect from an AI agent in EVERY project (incremental commits, en-US, no Co-Authored-By: trailer) was being retyped at the top of prompts, and the day it was forgotten produced a repo in two languages with one blob commit signed by a coauthor I did not want. The obvious home is the user's $CLAUDE_CONFIG_DIR/CLAUDE.md.

Decision

/etc/claude-code/CLAUDE.md, the MANAGED layer, generated by modules/nixos/services/claude-code.nix.

Consequences

• The user file was rejected for two reasons: it is per ACCOUNT, so the two accounts of modules/home/shell/claude-code.nix would hold two copies drifting apart; and Claude Code WRITES to it (the # shortcut appends a memory), so declaring it would put two owners on one file (rule 14). The managed file is read-only by nature, and Claude Code only reads it.
• It costs context in every session on this machine, so it holds the rules and nothing else; the reasoning lives in the repo.
• A project's own CLAUDE.md refines it and never contradicts it.