config-architect

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:

1. Copy the template to CLAUDE.md
2. Fill in: stack, build command, test command, lint command
3. Add 3-5 project-specific rules
4. 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.