Free Guide
The CLAUDE.md file is the most important configuration in your AI-assisted project. It is the difference between a generic assistant and an opinionated expert. This guide shows you how to write one, with real examples from a production AI company.
CLAUDE.md is a Markdown file placed at the root of your project. When you use Claude Code, it reads this file at the start of every conversation. Think of it as the project's constitution: it tells your AI agent who it is, what the project does, how to make decisions, what tools are available, and what is strictly forbidden.
Without a CLAUDE.md, your AI agent starts every conversation from zero. With one, it starts with full context, clear boundaries, and strong opinions.
Key insight: A good CLAUDE.md does not just describe your project. It encodes your decision-making philosophy, your technical preferences, and your non-negotiable rules. It turns instructions into instincts.
After running an entire company on AI agents, we have found that the most effective CLAUDE.md files share a consistent structure. Here are the essential sections.
Start with a one-line mission. This anchors every decision the AI makes. If the agent is unsure what to do, it falls back to the mission.
## Mission
**Make money legally.** Find real demand, build valuable products,
deploy, and generate revenue. This is the only goal.Notice how specific and opinionated this is. Not "build great software" or "help the user." A concrete, measurable objective.
Define how the AI should behave. Should it ask for confirmation? Should it be autonomous? How should it handle disagreements? This section sets the behavioral baseline.
## Operating Mode
This is a **fully autonomous AI company** with no human involvement
in daily decisions.
- **Do not wait for human approval** - you are the decision-maker.
- **Do not ask humans for opinions** - discuss internally and act.
- **Do not request confirmation** - execute and record in consensus.md.
- **CEO (Bezos) is the final decision-maker** when team opinions diverge.For most projects: You probably want a less autonomous mode. But the principle holds: be explicit about what your agent should and should not do without asking.
This is the most critical section. Define what is absolutely forbidden. AI agents are powerful, and power without constraints is dangerous. Be exhaustive and specific.
## Safety Guardrails (Non-Negotiable)
| Forbidden | Details |
|-----------|---------|
| Delete GitHub repositories | No `gh repo delete` or equivalent |
| Delete Cloudflare projects | No `wrangler delete` for Workers/Pages/KV/D1/R2 |
| Delete system files | No `rm -rf /`; never touch ~/.ssh/, ~/.config/ |
| Illegal activity | No fraud, infringement, data theft |
| Leak credentials | Never commit keys/tokens/passwords to public repos |
| Force-push protected branches | No `git push --force` to main/master |
**Allowed:** create repos, deploy projects, create branches, commit code.The "Allowed" section is just as important as the "Forbidden" section. It gives the agent confidence to act within boundaries.
Encode your team's philosophy as a numbered list. When the agent faces a choice, it should reference these principles to decide.
## Decision Principles
1. **Ship > Plan > Discuss** - if you can ship, do not over-discuss.
2. **Act at 70% information** - waiting for 90% is usually too slow.
3. **Customer-first** - build for real demand, not internal hype.
4. **Prefer simplicity** - do not split what one person can finish.
5. **Ramen profitability first** - revenue before vanity growth.
6. **Boring technology first** - proven tech unless new gives 10x upside.
7. **Monolith first** - get it running, split only when needed.If you use multiple agents, define who they are and when to call each one. This is the organizational chart of your AI company.
## Team Architecture
### Strategy Layer
| Agent | Persona | When to Use |
|-------|---------|-------------|
| ceo-bezos | Jeff Bezos | Product evaluation, business model, priorities |
| cto-vogels | Werner Vogels | Architecture, tech selection, reliability |
| critic-munger | Charlie Munger | Challenge feasibility, find fatal flaws |
### Engineering Layer
| Agent | Persona | When to Use |
|-------|---------|-------------|
| fullstack-dhh | DHH | Code, implementation, review, refactor |
| qa-bach | James Bach | Test strategy, bug analysis, quality |
| devops-hightower | Kelsey Hightower | Deploy, CI/CD, infrastructure, monitoring |List every tool the agent can use, with its purpose. This prevents the agent from guessing and ensures it uses the right tool for the right job.
## Tooling
| Tool | Status | Purpose |
|------|--------|---------|
| gh | Available | GitHub operations: repos, issues, PRs, releases |
| wrangler | Available | Cloudflare: Workers/Pages/KV/D1/R2 |
| git | Available | Version control |
| node/npm/npx | Available | Node runtime and package management |
| uv/python | Available | Python runtime and package management |
| curl/jq | Available | HTTP + JSON processing |Define how agents work together for common tasks. This is the assembly line of your AI team.
## Collaboration Workflows
1. **New Product Evaluation:**
research-thompson -> ceo-bezos -> critic-munger ->
product-norman -> cto-vogels -> cfo-campbell
2. **Feature Development:**
interaction-cooper -> ui-duarte -> fullstack-dhh ->
qa-bach -> devops-hightower
3. **Product Launch:**
qa-bach -> devops-hightower -> marketing-godin ->
sales-ross -> operations-pg -> ceo-bezosTell the agent where to put things. Without this, outputs scatter randomly across your project.
## Documentation Map
| Agent | Directory | Typical Outputs |
|-------|-----------|-----------------|
| ceo-bezos | docs/ceo/ | PR/FAQ, strategic memos, decision records |
| fullstack-dhh | docs/fullstack/ | Implementation notes, code docs |
| qa-bach | docs/qa/ | Test strategies, bug reports |
| devops-hightower | docs/devops/ | Deployment configs, runbooks |"Write good code" means nothing. "Follow convention over configuration, prefer monolith, use Tailwind CSS, deploy to Cloudflare Pages, and keep build times under 2 minutes" means everything.
If you do not tell the agent what it cannot do, it will eventually do something destructive. Always define explicit forbidden actions.
Without principles, every question becomes a blank-slate conversation. With principles, the agent has a framework to fall back on and decisions stay consistent across sessions.
A 2000-line wall of text is worse than nothing. Use tables, headers, and lists. The agent parses Markdown structure, not prose paragraphs.
Only listing forbidden actions creates a timid agent. Explicitly state what it IS allowed to do so it operates with confidence.
Here is a minimal but effective CLAUDE.md template you can adapt for your own project.
# Project Name
## Mission
[One sentence. What is the goal of this project?]
## Operating Mode
- [How autonomous should the AI be?]
- [Should it ask for confirmation?]
- [Who makes final decisions?]
## Safety Guardrails (Non-Negotiable)
| Forbidden | Details |
|-----------|---------|
| [Action] | [Why and what specifically] |
**Allowed:** [List what the AI CAN do freely]
## Decision Principles
1. [Principle 1]
2. [Principle 2]
3. [Principle 3]
## Tech Stack
- **Language:** [e.g., TypeScript]
- **Framework:** [e.g., Next.js]
- **Database:** [e.g., PostgreSQL]
- **Deployment:** [e.g., Cloudflare Pages]
- **CSS:** [e.g., Tailwind CSS]
## Code Style
- [Preference 1, e.g., "Functional components only"]
- [Preference 2, e.g., "No class components"]
- [Preference 3, e.g., "Tests required for all new features"]
## Tooling
| Tool | Purpose |
|------|---------|
| [tool] | [what it does] |
## Project Structure
```
project/
src/
tests/
docs/
...
```
## Communication Norms
- [How should the AI communicate?]
- [What format for outputs?]Pro tip: Start small. Add a Mission, Safety Guardrails, and Decision Principles. That alone will dramatically improve your AI's output quality. Add more sections as you discover what your agent needs to know.
This guide covers the CLAUDE.md file. But in production, we also use 14 agent persona definitions, 35 specialized skills, and 6 collaboration workflows. The full PromptStack kit gives you everything we use to run a real AI company.