CLAUDE.md as team contract
Read the field note below to see how we apply this pattern in real Claude Code projects.
F3: CLAUDE.md as team contract
Treating CLAUDE.md as personal notes undermines team consistency.
What we tried
We moved policy sections into versioned CLAUDE.md blocks and reviewed them like production code.
What happened
Decision quality improved because guidance stayed synchronized with real delivery constraints.
What we learned
CLAUDE.mdshould be reviewed, versioned, and owned.- Keep policy explicit: what to do, what not to do, and why.
- A living contract is more valuable than a long static handbook.
Result
Once we moved CLAUDE.md into the PR review cycle, the volume of "how do we handle X" Slack messages dropped — not to zero, but from several per week to roughly one or two per sprint. PR approvals got faster because reviewers could point to a line in the contract instead of re-litigating style decisions in comments. The maintenance burden is real though: the file has to be updated when decisions change, and that discipline is easy to skip under deadline pressure. We've had the file fall two or three sprints behind reality before someone flagged it. The contract only works if the team treats updating it as part of finishing a decision, not as documentation to write later.
Quick answers
What do I get from this cable?
You get a dated field note that explains how we handle this team-setup workflow in real Claude Code projects.
How much time should I budget?
Typical effort is 12 min. The cable is marked intermediate.
How do I install the artifact?
This cable is guidance-only and does not ship an installable artifact.
How fresh is the guidance?
The cable is explicitly last verified on 2026-04-15, and includes source links for traceability.
Work with FRE|Nxt
We build the production AI systems we write about.
Cables are the field notes. The playbooks come from client engagements — multi-agent systems, RAG pipelines, and LLM cost cuts that ship and hold up in production. If something here maps to a problem on your roadmap, two ways in:
Audit capacity: 5 slots/month · No pitch deck · NDA on request
Your LLM cannot read your agent state
The most common architectural mistake when building LangGraph agents is assuming the LLM can see your state fields. It cannot. The LLM only sees three things…
Prompt caching kills dynamic injection — pick one
Building a production LangGraph agent requires middleware that injects dynamic content into the system prompt every turn. Prompt caching requires that the sy…
Sub-agents are the same agent, smaller
When you add sub-agents to a production LangGraph system, the instinct is to build them as a separate agent type with its own state schema, its own graph str…