127 lines
7.4 KiB
Markdown
127 lines
7.4 KiB
Markdown
---
|
|
title:
|
|
source:
|
|
author: shenwei
|
|
published:
|
|
created:
|
|
description:
|
|
tags: []
|
|
---
|
|
|
|
I run 5 AI agents on Claude Code. Here's how I structure the CLAUDE.md and .claude/ directory to keep each one focused.
|
|
|
|
I've been building an ecosystem of AI agents using Claude Code and Preemptively Codex, each one is just a directory with a CLAUDE.md file and some config. After a lot of trial and error, I've landed on patterns that actually work. Figured I'd share what I've learned about structuring these files.
|
|
|
|
Each agent lives in its own directory under ~/Documents/:
|
|
|
|
~/Documents/
|
|
├── planner/ # Executive function, routing, accountability
|
|
├── content/ # Content pipeline
|
|
├── youtube/ # YouTube production (scripting, SEO, metrics)
|
|
├── life/ # Personal domains (health, finance, energy)
|
|
└── control-center/ # Dashboard, database, API
|
|
|
|
Every agent follows the same template structure:
|
|
|
|
agent-name/
|
|
├── CLAUDE.md # Identity + mission + capabilities
|
|
├── .claude/
|
|
│ ├── rules/ # Auto-loaded context (always-on)
|
|
│ └── skills/ # On-demand workflows
|
|
├── inbox/ # Input from other agents
|
|
├── outputs/ # Generated output
|
|
└── archive/ # Nothing gets deleted without archiving
|
|
|
|
The key insight: rules/ vs skills/
|
|
|
|
This is the thing that took me the longest to figure out.
|
|
|
|
.claude/rules/ files are loaded automatically at the start of every session. Claude reads them as part of its context window. This is where you put things the agent needs to know always — its scope, business context, how it should behave.
|
|
|
|
.claude/skills/ files are on-demand. They only load when you invoke them with /skill-name. This is where you put specific workflows like multi-step processes, templates, structured routines.
|
|
|
|
Why this matters: Rules files load into your context window at session start and stay there. Claude Code uses prompt caching so repeated content isn't billed at full price each turn, but large rules files still increase context pressure and can cause response degradation. You're carrying that weight every interaction whether you need it or not. With skills, only the name and description live in context by default; the full workflow loads on-demand, either when you call it or when Claude decides it's relevant. And this sent me down a rabbit hole into how token usage and context costs actually work.
|
|
|
|
• Rules (always-on): Scope boundaries, business context, routing logic, naming conventions — things that affect every decision
|
|
Rules (always-on): Scope boundaries, business context, routing logic, naming conventions — things that affect every decision
|
|
|
|
• Skills (on-demand): Step-by-step workflows, templates, batch operations. Things you do occasionally
|
|
(Note: skill descriptions are always in context so Claude knows what's available; only the full content is on-demand)
|
|
Skills (on-demand): Step-by-step workflows, templates, batch operations. Things you do occasionally (Note: skill descriptions are always in context so Claude knows what's available; only the full content is on-demand)
|
|
|
|
I try to keep CLAUDE.md under 120 lines. It covers:
|
|
|
|
• Identity (2-3 lines): who this agent is and what it does
|
|
Identity (2-3 lines): who this agent is and what it does
|
|
|
|
• Current phase (2-3 lines): what we're working on right now
|
|
Current phase (2-3 lines): what we're working on right now
|
|
|
|
• Core capabilities (10-15 lines): what skills are available, what it can do
|
|
Core capabilities (10-15 lines): what skills are available, what it can do
|
|
|
|
• Key locations (10-15 lines): file paths it needs to reference
|
|
Key locations (10-15 lines): file paths it needs to reference
|
|
|
|
• What's been built (10-20 lines): history of completed work
|
|
What's been built (10-20 lines): history of completed work
|
|
|
|
• What's next (5-10 lines): immediate priorities
|
|
What's next (5-10 lines): immediate priorities
|
|
|
|
• Principles (5-10 lines): behavioral guardrails
|
|
Principles (5-10 lines): behavioral guardrails
|
|
|
|
The biggest mistake I made early on was cramming everything into CLAUDE.md. It was 300+ lines and Claude's responses got worse because of context dilution. Splitting into rules/ files fixed that.
|
|
|
|
Example rules/ structure (my Planning Agent)
|
|
|
|
.claude/rules/
|
|
├── 01-business-context.md # Revenue model, positioning, target customers
|
|
├── 02-agent-ecosystem.md # All agents, their missions, how they connect
|
|
├── 03-roadmap.md # Current phase, milestones, exit criteria
|
|
├── 04-content-architecture.md # Content channels, pillars, workflow
|
|
├── 05-daily-routine.md # Schedule, idea filtering, anti-distraction rules
|
|
├── 07-godin-strategy.md # Marketing principles, milestone tracking
|
|
├── 08-control-center.md # CLI tools reference, DB schema
|
|
├── 98-end-of-session.md # Ritual: update roadmap, capture knowledge
|
|
└── 99-content-capture.md # Auto-extract content signals from every session
|
|
|
|
The numbering is intentional, it controls load order and makes it easy to find things.
|
|
|
|
The agents don't call each other directly. They coordinate through:
|
|
|
|
• SQLite database: Source of truth for tasks, content pipeline state, sessions, metrics
|
|
SQLite database: Source of truth for tasks, content pipeline state, sessions, metrics
|
|
|
|
• Inbox files: When one agent needs to hand context to another, it drops a markdown file in the target's inbox/
|
|
Inbox files: When one agent needs to hand context to another, it drops a markdown file in the target's inbox/
|
|
|
|
• API endpoints: Dashboard reads/writes through a FastAPI backend
|
|
API endpoints: Dashboard reads/writes through a FastAPI backend
|
|
|
|
Example: when I finish a build session, the planning agent captures content signals (what was built, what was learned) and drops them in content/inbox/. The content agent picks these up during its weekly batch and drafts social posts from them.
|
|
|
|
• Too much in CLAUDE.md: Split into rules/ files. CLAUDE.md is the summary, rules/ are the details.
|
|
Too much in CLAUDE.md: Split into rules/ files. CLAUDE.md is the summary, rules/ are the details.
|
|
|
|
• No scope boundaries: Agents would try to do everything. Now every agent has a 00-scope.md rule that explicitly says what it does and does NOT do.
|
|
No scope boundaries: Agents would try to do everything. Now every agent has a 00-scope.md rule that explicitly says what it does and does NOT do.
|
|
|
|
• No archiving: I deleted old files and lost context. Now everything goes to archive/ first.
|
|
No archiving: I deleted old files and lost context. Now everything goes to archive/ first.
|
|
|
|
• Workflows in rules/: Moved to skills/ and token costs dropped noticeably.
|
|
Workflows in rules/: Moved to skills/ and token costs dropped noticeably.
|
|
|
|
• No standard template: Every agent was structured differently. Created a standard template and refactored all agents to follow it. Consistency makes everything easier.
|
|
No standard template: Every agent was structured differently. Created a standard template and refactored all agents to follow it. Consistency makes everything easier.
|
|
|
|
What I'd tell someone starting out
|
|
|
|
Start with one agent and one CLAUDE.md file. Don't build five agents on day one. Get one working well, understand the rules/ vs skills/ split, then create a second agent when you have a genuinely different domain.
|
|
|
|
The template structure above is what I'd start with for any new agent.
|
|
|
|
Anyone else running multiple Claude Code agents? What patterns have you found for keeping them organized?
|