The Project Contract: AGENTS/CLAUDE Is Not an Encyclopedia
Lock project rules into project files so AI reads them every turn. But it's a navigation map, not a place to cram everything.
In vibe coding, AI doesn't know your project in any turn. The only way to make it follow the rules every turn is to write the rules into the project's own files—AGENTS.md, CLAUDE.md, or rule files in a working directory. This is the final step of "landing the spec into the project."
After reading, you should be able to answer:
- Why does a project contract save you restating context every turn?
- What should the contract file include, and what not?
- How do you stop the contract file from bloating?
What the contract file solves
You wouldn't re-introduce the project background at every meeting; you share a "project memory" with your team. AGENTS is that shared memory for AI—it appears in the context of every turn automatically.
- No more typing "directory layout, naming habits" by hand each turn
- No more re-correcting "we don't use library X, we use Y"
- New conversations, new sessions—the contract takes effect automatically
What to put in it (and what not)
Put in "information that is outside the code but still shapes AI's judgment," centered on:
| Category | Example |
|---|---|
| Project structure | how dirs split, where new files go |
| Tech constraints | which framework, which library we don't use, where source-of-truth lives |
| Code conventions | naming, interface format, style, directory conventions |
| Don'ts | mistakes AI tends to make: which files not to touch, which patterns to avoid |
The reverse: don't stuff everything in. Method-by-method, file-by-file explanations get long and go stale fast. The contract is a "navigation map," not an "encyclopedia": it carries only the navigation points and real constraints, and can link elsewhere for detail.
How to keep the contract from bloating
- Only add when "you keep correcting the same thing": fix a one-off problem first; reach a repeating path, then crystallize it into a rule
- If a machine can decide it, make it a script/check instead of a contract rule: a contract is a reminder, a script is a constraint, and the latter is more reliable
- Delete the old rules that do nothing: like code, rules rot; clean them periodically
One test: does adding a rule to the contract actually make AI better? If not, delete it anthropic-sdlc.
Small tips for writing it
- Use "do this / don't do this" checklist style, not long prose
- One rule per line; don't pack several into a paragraph
- Mark the unsure ones "to be filled in" instead of forcing them
With the project contract in place, AI has "common sense." Next is the actual building: Build in Small Steps, breaking the whole goal into verifiable chunks.