The author presents a six‑layer model for understanding and taming Claude Code:

Optimising any single layer in isolation often creates issues elsewhere: CLAUDE.md too long pollutes context; too many tools cause confusion; too many subagents breed state drift; skipping verification leaves you with bugs you can’t trace.

Claude Code runs in a repeated agent loop:

Gather context → Take action → Verify result → [Done or return to gather] ↑ ↓ CLAUDE.md Hooks/Permissions/Sandbox Skills Tools/MCP Memory

The author notes that the bottleneck is rarely model intelligence; more often it’s feeding it the wrong context, or writing code without a way to verify or roll back.

The author maps common problems to five surfaces:

These surfaces help troubleshoot: unstable results → check context loading order; runaway automation → look at control surface; quality drop in long sessions → intermediate outputs polluted context.

A clear table distinguishes the six key concepts, avoiding misuse:

Mnemonic: new actions → Tool/MCP; new methodology → Skill; isolated execution → Subagent; mandatory constraints/audit → Hook; cross‑project distribution → Plugin.

The author emphasizes that context isn’t about length but signal‑to‑noise ratio. The real hidden cost of 200K context:

• Fixed overhead (~15‑20K): system prompt ~2K, skill descriptors ~1‑5K, MCP tool definitions ~10‑20K (the biggest stealth killer), LSP state ~2‑5K.
• Semi‑fixed (~5‑10K): CLAUDE.md ~2‑5K, Memory ~1‑2K.
• Dynamic available (~160‑180K): conversation history, file contents, tool call results.

A typical MCP server like GitHub includes 20‑30 tool definitions (~200 tokens each), totaling 4‑6K tokens. With 5 servers, the fixed cost reaches 25K tokens (12.5%). In code‑reading sessions this is significant.

The recommended layering:

• Always resident → CLAUDE.md: contract, build commands, prohibitions
• Path‑loaded → rules: language/directory norms
• On‑demand → Skills: workflows/domain knowledge
• Isolated → Subagents: heavy exploration/parallel research
• Never in context → Hooks: deterministic scripts, audit, blocking

• Keep CLAUDE.md short, hard, executable: commands, constraints, architecture boundaries. Anthropic’s own CLAUDE.md is ~2.5K tokens.
• Offload large reference docs to Skills’ supporting files, not into SKILL.md body.
• Use .claude/rules/ for path/language rules; don’t let root CLAUDE.md bear all differences.
• Actively monitor token usage with /context; don’t wait for automatic compaction.

• On task switch, prefer /clear; within a task phase, use /compact.
• Write Compact Instructions into CLAUDE.md so you control what gets preserved after compaction, not the algorithm.

Tool output is another hidden context killer. Full cargo test output can be thousands of lines; git log, find, grep can flood the screen. Claude doesn’t need all of it.

The author mentions the open‑source project RTK (Rust Token Killer), which filters command output before it reaches Claude:

Claude sees:

running 262 tests test auth::test_login ... ok ... (thousands of lines)

After RTK filtering:

✓ cargo test: 262 passed (1 suite, 0.08s)

Claude only needs to know pass/fail and where failures occurred. RTK does this transparently via Hooks, without modifying the commands. It is available on GitHub.

Default compaction assumes earlier tool outputs and file contents can be discarded and later re‑read, but it often throws away architecture decisions and rationale, leading to mysterious bugs. The solution is to write explicit Compact Instructions in CLAUDE.md:

Compact Instructions

When compressing, preserve in priority order:

1. Architecture decisions (NEVER summarize)
2. Modified files and their key changes
3. Current verification status (pass/fail)
4. Open TODOs and rollback notes
5. Tool outputs (can delete, keep pass/fail only)

Additionally, before starting a new session, have Claude write a HANDOFF.md summarizing current progress, attempts, dead ends, and next steps. The next instance can continue by reading only that file.

Plan Mode separates exploration from execution: exploration is read‑only, goals and boundaries are clarified first, and the concrete plan is agreed before any changes. This reduces chasing wrong assumptions on complex refactors or migrations. Enter Plan Mode with double‑press Shift+Tab. An advanced pattern: one Claude writes the plan, another Claude (Codex) reviews it as a “senior engineer” — AI reviewing AI.

A good Skill tells the model “when to use me”, has complete steps/inputs/outputs/stop conditions, keeps only navigation and core constraints in SKILL.md body (details in supporting files), and sets disable-model‑invocation: true for side‑effect‑heavy skills.

The internal design philosophy is “progressive disclosure”: SKILL.md defines task semantics and skeleton; supporting files provide domain detail; scripts collect deterministic context.

A stable structure:

.claude/skills/ └── incident-triage/ ├── SKILL.md ├── runbook.md ├── examples.md └── scripts/ └── collect-context.sh

Three archetypes from the author’s open‑source terminal project Kaku:

1. Checklist (quality gate): release‑check skill.
2. Workflow (standardised operation): config‑migration with rollback.
3. Domain Expert (decision framework): runtime‑diagnosis with evidence collection and decision matrix.

Descriptor optimization matters: each enabled skill descriptor consumes context. A good descriptor is concise and tells when to trigger (≤9 tokens), not a verbose description.

Tools for agents are different from human APIs. The author contrasts good vs. bad tools:

Design principles: namespaced names (github_pr_), response_format for concise/detailed, error messages that teach the model how to fix, prefer high‑level compound tools over many low‑level fragments (avoid list_all_ forcing the model to sift).

The evolution of Claude Code’s internal tools is instructive. For “pause and ask the user”, they tried: (1) adding a question parameter to Bash → ignored; (2) markdown‑based pause → unreliable formatting; (3) dedicated AskUserQuestion tool → explicitly call to pause, most robust. For Todo tools, early TodoWrite + reminders became a straitjacket as models improved; now tools are lighter. For search, they moved from RAG (fragile) to a Grep tool that the model actively uses, enabling “progressive disclosure” as Claude reads skill files that reference other files.

When should you NOT add a tool? When local shell can do it, when static knowledge suffices, when a Skill workflow is more appropriate, or when the tool schema/returns haven’t been validated as stably used by the model.

Hooks enforce logic before or after Claude’s actions, reclaiming what shouldn’t be left to improvisation. Supported hook points: before/after tool use, session start, etc.

Suitable: blocking edits to protected files, auto‑formatting/lint after edits, injecting dynamic context at SessionStart, pushing notifications.

Unsuitable: complex semantic judgments requiring large context, long‑running business processes, multi‑step reasoning — these belong in Skills or Subagents.

Example configuration:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "pattern": "*.rs",
        "hooks": [{
          "type": "command",
          "command": "cargo check 2>&1 | head -30",
          "statusMessage": "Running cargo check..."
        }]
      }
    ],
    "Notification": [{
      "type": "command",
      "command": "osascript -e 'display notification \"Task completed\" with title \"Claude Code\"'"
    }]
  }
}

In a 100‑edit session, saving 30‑60s per edit accumulates to 1‑2 hours. Always limit hook output (e.g., | head -30) to avoid polluting context. For systematic output truncation, see RTK in §3.

Hooks + Skills + CLAUDE.md layering: CLAUDE.md states “must pass tests and lint before commit”; Skill tells the sequence and how to interpret failures; Hook enforces hard checks on critical paths and blocks if necessary.

Subagents are separate Claude instances with their own context, limited tools, and they report back. The key value is isolation: heavy output tasks (codebase scanning, testing, reviewing) stay out of the main thread’s context. Built‑in subagents: Explore (read‑only, Haiku), Plan, General‑purpose; custom subagents can be defined.

Critical configurations:

• tools/disallowedTools: limit what the subagent can use.
• model: Haiku for exploration, Sonnet/Opus for deeper work.
• maxTurns: prevent runaway.
• isolation: worktree for filesystem isolation when modifying files.

Note: long‑running bash commands can be backgrounded with Ctrl+B; subagents can be told to run in the background, and results retrieved via BashOutput.

Anti‑patterns: subagent permissions as wide as main thread, unstructured output, strong inter‑task dependencies (use sequential steps instead).

Claude Code’s architecture is built around prompt caching. High cache hit rates not only save cost but also relax rate limits. The prompt layout is designed for caching: 1) System Prompt (static), 2) Tool Definitions (static), 3) Chat History (dynamic), 4) Current User Input (last). Caching is prefix‑based.

Cache‑breaking mistakes: putting timestamps in the static system prompt, non‑deterministically shuffling tool definitions, adding/removing tools mid‑session. Dynamic content like current time should be placed in the user message as a <system‑reminder> tag.

Don’t switch models mid‑session: cache is model‑unique. Switching to a cheaper model after 100K tokens actually costs more due to cache rebuild. If necessary, use a Subagent handoff.

Compaction implementation: when context nears full, fork a call with full history + “Summarize this conversation”, hitting cache for 1/10 the price; the result replaces dozens of turns with a ~20K‑token summary, preserving System + Tools plus file references.

Plan Mode doesn’t switch toolsets (would break cache); instead, EnterPlanMode is a tool the model can call when it detects complexity. defer_loading: lightweight tool stubs with name only (defer_loading: true) keep the cache prefix stable; full schemas load only when selected via ToolSearch.

“Claude says it’s done” is useless. You need a hierarchy of verifiers:

• Lowest: exit codes, lint, typecheck, unit tests
• Middle: integration tests, screenshot diffing, contract tests, smoke tests
• Higher: production log validation, monitoring metrics, human review checklists

Define verification explicitly in prompts, Skills, and CLAUDE.md:

## Verification
For backend changes:
- Run `make test` and `make lint`
- For API changes, update contract tests under `tests/contracts/`
For UI changes:
- Capture before/after screenshots if visual
Definition of done:
- All tests pass
- Lint passes
- No TODO left behind unless explicitly tracked

Embed acceptance criteria early: which commands to run, what to check on failure, what screenshots/logs to see as passing.

The author groups useful commands into context management ( /context, /clear, /compact, /memory ), capability & governance ( /mcp, /hooks, /permissions, /sandbox, /model ), session continuity & parallelism ( claude --continue, --resume, --fork, --worktree, -p, --output-format json ), and several lesser‑known but valuable ones:

• /simplify: reviews recently changed code for reuse, quality, efficiency.
• /rewind: returns to a session checkpoint and re‑summarizes, useful when Claude has gone too far down a wrong path.
• /btw: ask a quick side question without disturbing the main task.
• /insight: Claude analyzes the session and suggests what to persist into CLAUDE.md.
• Double‑press ESC: go back to edit previous input, faster than restarting.
• Session history stored in ~/.claude/projects/ as .jsonl files; grep or ask Claude to search.

CLAUDE.md is a collaboration contract, not a knowledge base. Start empty, add only things you find yourself repeating. Use # to append or simply tell Claude “add this to the project’s CLAUDE.md.”

What to put: how to build, test, run; key directory structure & module boundaries; coding style & naming constraints; non‑obvious environment pitfalls; NEVER lists; Compact Instructions.

What NOT to put: large background intros, full API docs, vague principles (“write high‑quality code”), obvious information inferable from the repo, large references (offload to Skills).

A high‑quality template:

# Project Contract
## Build And Test
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint`
## Architecture Boundaries
- HTTP handlers in `src/http/handlers/`
- Domain logic in `src/domain/`
- No persistence logic in handlers
- Shared types in `src/contracts/`
## Coding Conventions
- Pure functions in domain layer
- No new global state without justification
- Reuse existing error types
## Safety Rails
### NEVER
- Modify `.env`, lockfiles, or CI secrets without approval
- Remove feature flags without searching all call sites
- Commit without running tests
### ALWAYS
- Show diff before committing
- Update CHANGELOG for user‑facing changes
## Verification
- Backend: `make test` + `make lint`
- API: update contract tests
- UI: before/after screenshots
## Compact Instructions
Preserve: 1. Architecture decisions 2. Modified files and changes 3. Verification status 4. Open risks, TODOs, rollback notes

A favorite trick: after correcting a mistake, tell Claude “Update your CLAUDE.md so you don’t make that mistake again.”

The author built an open‑source terminal project (Kaku, Rust + Lua) using Claude Code and shares practical insights:

Environment transparency: Claude Code calls real shell, git, package managers. Opaque environment layers force guessing. A doctor command that reports environment state, dependencies, and configuration before work starts reduces errors. CLI commands with clear semantics (init, config, reset) give Claude stable entry points.

Hooks for multi‑language projects: Post‑edit hooks trigger language‑specific checks (cargo check for .rs, luajit syntax for .lua), catching errors immediately.

Recommended project layout for engineering with Claude Code:

Project/
├── CLAUDE.md
├── .claude/
│   ├── rules/
│   │   ├── core.md
│   │   ├── config.md
│   │   └── release.md
│   ├── skills/
│   │   ├── runtime-diagnosis/
│   │   ├── config-migration/
│   │   ├── release-check/
│   │   └── incident-triage/
│   ├── agents/
│   │   ├── reviewer.md
│   │   └── explorer.md
│   └── settings.json
└── docs/
    └── ai/
        ├── architecture.md
        └── release-runbook.md

Common anti‑patterns: CLAUDE.md as wiki, skill mish‑mash, tool bloat, no verification loop, excessive autonomy, no context segmentation, over‑autonomy without governance, stale dangerous approved commands.

Configuration health check: The author released an open‑source Skill tw93/waza that audits your Claude Code configuration against the six‑layer framework, producing a prioritized report.

The author concludes with a three‑stage maturity model:

1. Tool User – “How does this feature work?” Helpful but limited.
2. Process Optimizer – “How do I smooth collaboration?” Writing CLAUDE.md and Skills; efficiency noticeably improves.
3. System Designer – “How do I make the agent operate autonomously within constraints?” Qualitative leap.

A key question: if you can’t clearly define “done” for a task, it probably isn’t suitable for autonomous Claude.