Code Agent Meta Patterns

Claude Code Meta-Patterns

CLAUDE.md Optimization

What to Include vs. Avoid

Layering Strategy

CLAUDE.md files cascade. Higher specificity wins.

~/.claude/CLAUDE.md              # Global: communication style, git conventions
project/CLAUDE.md                # Project: build commands, architecture, file map
project/.claude/CLAUDE.md        # Project (alt location): same as above
project/src/api/CLAUDE.md        # Directory: API-specific patterns, conventions

Rules:

• Global: personal preferences, style, universal workflow rules
• Project root: build/test/lint commands, project structure, tech stack decisions
• Subdirectory: module-specific conventions, local patterns, "how this subsystem works"
• Keep each file under 200 lines; link to detailed docs instead of inlining

Effective CLAUDE.md Template

# CLAUDE.md

## Build & Test
\`\`\`bash
npm run build          # TypeScript → dist/
npm test               # Jest, ~30s
npm run lint           # ESLint + Prettier
npm run test:e2e       # Playwright, requires running server
\`\`\`

## Architecture
- Monorepo: apps/ (Next.js) + packages/ (shared libs)
- API: tRPC routers in apps/api/src/routers/
- DB: Drizzle ORM, migrations in packages/db/migrations/

## Conventions
- Barrel exports from every package (index.ts)
- Zod schemas co-located with routers
- Error handling: use AppError class, never throw raw strings
- Feature flags: check packages/flags/ before adding conditionals

## Key Files
| File | Purpose |
|------|---------|
| `turbo.json` | Build pipeline config |
| `packages/db/schema.ts` | Database schema source of truth |
| `.env.example` | Required env vars with descriptions |

Skill Design

Frontmatter Conventions

---
name: kebab-case-name           # Matches directory name
description: "Use when [specific trigger scenario]. Also applies to [related scenarios]."
---

Description rules:

• Always start with "Use when" -- this is the trigger phrase Claude matches on
• Be specific: "Use when writing database migrations" not "Use for database stuff"
• Include 2-3 trigger scenarios separated by commas or "or"
• Keep under 200 characters

Skill Structure Pattern

Follow this order for consistent, scannable skills:

# Skill Title

## Decision Table
(When to use which approach — always first)

## Core Patterns
(The main content, with code examples)

## Code Examples
(Copy-pasteable, realistic examples)

## Gotchas
(Non-obvious failure modes — always last)

Sizing Guidelines

Over 350 lines: split into multiple skills.

Description Trigger Examples

Command Design

Commands are thin wrappers that invoke skills. Keep them minimal.

Command Structure

---
name: review
description: "Review code changes for quality, security, and convention compliance"
---

Use the code-review skill to review the current changes.

Focus on: $ARGUMENTS

If no arguments provided, review all staged/unstaged changes.

$ARGUMENTS Patterns

Rules

• One command = one skill invocation (usually)
• Commands in .claude/commands/ for project, ~/.claude/commands/ for global
• No logic in commands; all logic lives in skills
• Description should make the command discoverable

Hook Patterns

See references/workflow/hook-patterns.md for full examples (PreToolUse, PostToolUse JSON configs).

Key principles: hooks should be fast (<5s), fail loudly, use narrow matchers, test manually first.

Context Management

Keeping Context Small

Context Budget Rules

• CLAUDE.md files: aim for <150 lines each
• Skills: 150-300 lines typical
• If a skill needs >350 lines, it's trying to do too much
• Prefer tables and code over prose (higher information density)
• Avoid volatile content in CLAUDE.md (timestamps, changing metrics) — breaks KV cache prefix
• See references/workflow/context-efficiency for full patterns

Task Decomposition

Role-Based Analysis

When tackling complex tasks, analyze sequentially from different roles:

When to Decompose

Background Operations

• Use run_in_background for long builds/tests while continuing other work
• Collect results when notified, then synthesize

Permission Management

See references/workflow/permission-management.md for full settings hierarchy and JSON examples.

Key rules: minimal permissions by default, deny overrides allow, use glob patterns, settings.local.json for personal overrides.

Gotchas

• Context bloat: Every line in CLAUDE.md consumes context window. Ruthlessly prune. If Claude already knows it (general programming, language syntax), don't restate it.
• Over-engineering skills: A skill should solve a recurring problem. If you've only needed it once, it's not a skill -- it's a conversation. Wait for the third occurrence.
• Stale instructions: CLAUDE.md that references deleted files, old conventions, or deprecated workflows actively misleads. Review quarterly.
• Description mismatch: If the skill description doesn't match what the skill actually does, Claude will invoke it at the wrong time or skip it when needed. Test trigger phrases.
• Skill overlap: Two skills with similar descriptions cause unpredictable invocation. Deduplicate or make descriptions clearly distinct.
• Command complexity: If a command file exceeds 10 lines, the logic should be in a skill. Commands are routing, not logic.
• Hook performance: A slow hook on every file write makes the entire workflow painful. Profile hooks and keep them under 2 seconds.
• Ignoring layer precedence: Putting project-specific rules in global CLAUDE.md means they apply to every project. Keep global truly global.

Source: jlaws/dotfiles — distributed by TomeVault.