| name | config-architect |
| description | Use when creating, restructuring, or scaling a CLAUDE.md file. Provides tiered loading patterns, organization templates, and token measurement guidance. Prevents the "unmanageable blob" problem. |
Config Architect
Your CLAUDE.md is how Claude Code understands your project. A good one makes everything faster. A bad one wastes tokens on every single message.
Announce: "Using config-architect to structure this configuration."
Quick Start
If your CLAUDE.md doesn't exist yet, copy the starter template from references/starter-template.md and fill in the blanks. 5 minutes to a working config.
If your CLAUDE.md exists but feels messy, jump to "Migration Path" below.
The Problem
CLAUDE.md files grow. What starts as 10 helpful lines becomes 200 lines of everything you've ever told Claude. The result:
- Every message costs more tokens (CLAUDE.md is loaded on every interaction)
- Important rules get buried in noise
- Contradictory instructions accumulate
- You can't find what you need
The Solution: Tiered Loading
Not everything needs to be loaded every time. Split your config into tiers:
Tier 1: Always Loaded (~500 tokens)
Your main CLAUDE.md file. Contains only what Claude needs on EVERY interaction.
# Project Name
## Quick Reference
- Stack: Next.js 15 + TypeScript + Tailwind
- Test: npm test
- Build: npm run build
- Lint: npm run lint
## Core Rules
- Use TypeScript strict mode
- Components in src/components/
- API routes in src/app/api/
- Tests next to source files: component.test.ts
## Key Patterns
- Server components by default, "use client" only when needed
- Zod for all input validation
- Error boundaries around async components
What belongs here: Tech stack, file locations, build commands, 3-5 non-obvious rules that apply to every task.
What doesn't belong: Feature-specific instructions, one-time notes, long explanations.
Tier 2: Loaded on Match (~300 tokens each)
Rules files in .claude/rules/ that Claude loads when relevant keywords appear.
.claude/rules/
testing.md # Loaded when task involves tests
api-design.md # Loaded when task involves API routes
database.md # Loaded when task involves data models
deployment.md # Loaded when task involves deploy/CI
Each file: 10-30 lines covering one topic. Claude loads them automatically when the conversation matches.
What belongs here: Domain-specific instructions, detailed conventions for specific areas, patterns that only matter sometimes.
Tier 3: Loaded on Demand (0 tokens default)
Knowledge files referenced explicitly when needed. Not in .claude/rules/.
docs/
architecture.md # Referenced when Claude needs the big picture
api-reference.md # Referenced when building new endpoints
style-guide.md # Referenced when design questions arise
What belongs here: Long reference documents, architectural decisions, style guides, onboarding docs. Things Claude should read when asked, not on every message.
When to Use Each Tier
| Content | Tier | Why |
|---|
| Build command | 1 | Needed constantly |
| "Use Zod for validation" | 1 | Applies to every task |
| "Test API routes with supertest" | 2 | Only when writing API tests |
| "Database migration naming convention" | 2 | Only when touching DB |
| Full API documentation | 3 | Reference only |
| Architecture decision records | 3 | Background context |
Migration Path: Flat to Tiered
If your CLAUDE.md is already a blob, follow these steps:
Step 1: Measure Current Size
wc -c CLAUDE.md
| Size | Status |
|---|
| < 2KB | Fine as-is. Don't over-engineer. |
| 2-5KB | Consider splitting the largest sections into Tier 2 |
| 5-10KB | Split into tiers. You're wasting tokens. |
| 10KB+ | Urgent. Every message pays for content Claude doesn't need. |
Step 2: Categorize Every Section
Read your CLAUDE.md line by line. For each section, ask:
- "Does Claude need this on EVERY task?" -> Keep in Tier 1
- "Does Claude need this for SOME tasks?" -> Move to Tier 2 (
.claude/rules/)
- "Is this reference material?" -> Move to Tier 3 (
docs/)
- "Is this outdated or redundant?" -> Delete it
Step 3: Extract to Tiers
Move sections to their new homes. Keep Tier 1 under 500 tokens (~50 lines of concise instructions).
Step 4: Verify
After restructuring, test with a representative task:
- Does Claude still follow the rules?
- Does it pick up Tier 2 rules when relevant?
- Is the token count visibly lower?
Token Measurement
Rough estimates for planning:
| Content | Tokens (approx) |
|---|
| 1 line of instruction | ~10-15 tokens |
| 10-line section | ~100-150 tokens |
| Typical Tier 1 CLAUDE.md | ~300-500 tokens |
| Typical Tier 2 rule file | ~200-400 tokens |
| Every token in Tier 1 | Loaded on EVERY message |
The math: A 10KB CLAUDE.md is ~2,500 tokens. Over 100 messages in a session, that's 250,000 tokens spent just on config. A 2KB Tier 1 + selective Tier 2 loading cuts this by 60-80%.
When to Use This Skill
- Starting a new project (set up config right from the start)
- CLAUDE.md is over 5KB and growing
- You notice Claude ignoring rules (too much noise)
- Adding a new team member who needs to set up their config
- Migrating from a flat CLAUDE.md to tiered structure
When NOT to Use
- CLAUDE.md is under 2KB and working fine (don't fix what isn't broken)
- You're just adding one rule (just add it, no restructuring needed)
- The project is a one-off script (a 5-line CLAUDE.md is perfect)
Examples
Example 1: New Project Setup
You're starting a Next.js project. Use the starter template from references/starter-template.md:
- Copy the template to
CLAUDE.md
- Fill in: stack, build command, test command, lint command
- Add 3-5 project-specific rules
- Done. Under 500 tokens, covers 90% of interactions.
Example 2: Splitting a Bloated CLAUDE.md
Your CLAUDE.md is 8KB with sections for testing, API design, database patterns, deployment, and code style.
Before: Everything in one file. 2,000 tokens loaded on every message.
After:
CLAUDE.md (Tier 1, ~400 tokens)
- Stack, build commands, 5 core rules
.claude/rules/testing.md (Tier 2, ~250 tokens)
- Test framework, mocking patterns, coverage rules
.claude/rules/api-design.md (Tier 2, ~300 tokens)
- REST conventions, error format, auth patterns
docs/database-patterns.md (Tier 3, 0 tokens default)
- Migration naming, indexing strategy, query patterns
Result: 400 tokens per message instead of 2,000. Tier 2 loads only when relevant.
Security Note
Never put secrets in CLAUDE.md or rule files. These are committed to version control. Use environment variables or .env files (which should be in .gitignore) for API keys, tokens, and credentials.
If Claude needs to know about a secret's existence (e.g., "this API requires an API key"), reference the environment variable name, not the value: STRIPE_API_KEY is set in .env.
Anti-Patterns
| Pattern | Problem | Fix |
|---|
| Everything in CLAUDE.md | Token waste on every message | Tier 2 for domain-specific rules |
| Rules without examples | Claude interprets vaguely | Add one concrete example per rule |
| Contradictory rules | Claude picks one randomly | Audit for conflicts quarterly |
| "Don't do X" without "do Y instead" | Claude knows what to avoid but not what to do | Always pair negatives with positives |
| Copy-pasting docs into CLAUDE.md | Bloats Tier 1 with reference material | Link to docs, don't inline them |
| No CLAUDE.md at all | Claude guesses your conventions | 5 minutes with the starter template |
With Starter System
If you have the Starter System installed:
- Your Starter System IS Tier 1 for session management
- Layer project-specific CLAUDE.md on top
- Use
/context-stats to see actual token usage of your config
- Use
/remember to note config patterns that work
With Kairn (Course)
When Kairn is configured, configuration gains:
- Auto-detection of rules Claude needs based on task patterns
- Dynamic loading that goes beyond keyword matching
- Rule effectiveness tracking - which rules actually change Claude's behavior
Without Kairn: tiered loading still works, just based on static keyword matching. You manually decide what goes where.
