Most CLAUDE.md advice online is vague. "Be specific." "Use TypeScript." "Follow best practices."
None of that changes how your agent actually behaves. Here's what does: a structured system of files that work together.
I'll walk you through the exact file structure we use in production.
The File Structure
playbook/
├── 01-foundations/
│ ├── constrained-autonomy-model.md
│ └── trust-levels.md
├── 02-configuration-templates/
│ ├── CLAUDE.md.template
│ ├── AGENTS.md.template
│ ├── cursorrules.template
│ ├── aider-conventions.template
│ └── windsurf-rules.template
├── 03-skill-system/
│ ├── SKILL-TEMPLATE.md
│ ├── skill-design-checklist.md
│ └── examples/
│ ├── code-review.md
│ ├── deploy-guard.md
│ ├── bug-triage.md
│ └── content-writer.md
├── 04-multi-agent-patterns/
│ ├── parallel-agents.md
│ ├── worktree-strategy.md
│ └── conflict-resolution.md
├── 05-safety-and-governance/
│ ├── security-checklist.md
│ ├── cost-control.md
│ └── audit-trail.md
└── 06-real-world-examples/
├── autonomous-business-agent.md
├── ci-cd-agent.md
├── customer-support-agent.md
└── filled-claude-md.md
24 files. All Markdown. Every one of them exists because we hit a real problem without it.
1. The Constrained Autonomy Model
This is the foundation. Everything else builds on it.
## Constrained Autonomy
### Actions You May Take Without Approval
- Run tests, format code, fix lint errors
- Create commits within the current branch
- Install dependencies from package.json
- Read any file in the repository
### Actions That Require Approval
- Push to main or release branches
- Delete files or directories
- Modify CI/CD pipeline configuration
- Changes affecting billing or payments
- Bulk operations affecting 5+ resources
The key insight: you need two explicit lists. What the agent can do freely, and what needs a human check. Without this, agents either do nothing (waiting for permission) or do everything (breaking production).
The "5+ resources" threshold came from an incident where an agent tried to close 50 GitHub issues in one operation. Now the rule is: if it touches more than 5 things, show the count and ask first.
2. Skill Modules
Instead of one massive CLAUDE.md file, we split agent behaviors into separate skill files:
---
name: code-review
description: "Automated code review for pull requests"
---
# Code Review Skill
## When This Skill Applies
- A pull request is open and awaiting review
- You are asked to evaluate changes before merge
## When This Skill Does NOT Apply
- During initial feature development
- For documentation-only changes
## Rules
### Do
- Review the diff systematically, file by file
- Check that new code has corresponding tests
- Flag security concerns immediately
- Provide specific feedback with file paths and line numbers
### Do Not
- Block a PR for style issues the linter doesn't catch
- Suggest refactoring code not changed in this PR
- Approve a PR with failing tests
- Leave vague feedback without explaining how to fix
The agent loads 2-3 relevant skills per task. A debugging task loads the bug-triage skill. A PR loads code-review. A deployment loads deploy-guard.
This is dramatically more predictable than dumping everything into one giant configuration file.
3. Multi-Agent Safety
If you run multiple Claude Code instances on the same repo (and you should — it's incredibly productive), you need explicit rules:
## Multi-Agent Safety
- Never `git stash` — destroys other agents' work in progress
- Never switch branches without explicit permission
- Only stage your own files when committing
- Run `git pull --rebase` before every push
- If you see unfamiliar files, ignore them — another agent is working
Every single rule exists because of a real incident. The git stash one was particularly painful — one agent stashed another's work, then the stash got dropped during cleanup.
4. The Trust Spectrum
Full Manual ────────────────────── Full Autopilot
Ask Read Format Test Commit Deploy Business
Most teams start on the far left (ask for everything) and never move. The goal is finding your team's comfort zone and encoding it in configuration.
For a new project, we start at "Commit" — the agent can read, format, test, and commit freely. Deploys and business decisions need approval. As trust builds, the boundary shifts right.
5. Real-World Example: A Filled-In CLAUDE.md
The playbook includes a complete, working CLAUDE.md for a fictional SaaS called "Acme SaaS":
# Acme SaaS — AI Agent Configuration
You are Atlas, the lead engineer for Acme SaaS.
You operate autonomously within the boundaries
defined in this document.
## Core Responsibilities
1. Deliver working features that pass code review
2. Maintain test coverage above 80%
3. Keep the codebase clean — no lint errors, no type errors
## Guiding Principles
- Act on your own judgment within the guardrails
- Never guess. Read the code, check the data, then decide
- 1 PR = 1 topic. Do not bundle unrelated changes
- Ship working increments over perfect solutions
This isn't a template with [INSERT HERE] placeholders. It's a working configuration that shows how every section fits together.
Want all 24 files?
The full playbook includes everything above plus configuration templates for 5 tools (Claude Code, Cursor, Windsurf, Aider, multi-agent setups), 4 example skills, safety checklists, cost controls, and 3 complete real-world agent configurations.
All Markdown. Drop into your project. Start using immediately.
50% off this week with code LAUNCH50: hideyoshi.app/playbook
Or grab the free CLAUDE.md starter template to get started.
Top comments (0)