你不知道的 Claude Code：架构、治理与工程实践

A Chinese-language deep dive by tw93 (Alibaba/Fliggy engineer; author of kaku) into how to actually run claude-code beyond the chatbot-style usage. The frame: stop optimizing one layer at a time and treat Claude Code as a six-layer system whose layers must be co-designed.

Source file: raw/2026-04-27-claude-code-architecture-governance-engineering.md.

Summary

Tw93 spent six months running two paid Claude Code accounts ($40/mo each) and reverse-engineering the tool’s internal architecture. He distills the experience into the six-layer-agent-architecture: CLAUDE.md / rules / memory (long-term context — what is); Tools / MCP (action capability — what can be done); Skills (on-demand methodology — how to do it); Hooks (deterministic enforcement — bypass model judgment); Subagents (isolated workers — controlled autonomy); Verifiers (the loop that closes the agent’s output). Optimizing any one layer in isolation breaks the others.

The bulk of the article walks each layer:

• Context economics. The 200K context isn’t all usable. ~15–20K is fixed overhead (system prompt + Skill descriptors + MCP tool definitions + LSP state). MCP is the largest hidden tax: a typical server defines 20–30 tools at ~200 tokens each, so 5 connected servers eat ~25K tokens (12.5%) before the first user message. Tool output (e.g. raw cargo test) is the dynamic equivalent — addressed by tools like RTK that rewrite commands transparently via Hooks.
• Compaction trap. Default summarization prunes “re-readable” content first, which means architecture decisions and constraint rationale get dropped along with old tool output. Fix: declare a ## Compact Instructions block in CLAUDE.md naming what must survive. Even better: write a HANDOFF.md and start a fresh session, rather than trusting auto-summarization.
• plan-mode as engineering primitive. Separating exploration (read-only) from execution. Advanced pattern: have one Claude write the plan, have a Codex instance review it as a “senior engineer.”
• claude-skills design. Descriptors live in context permanently — must answer “when should I use this,” not “what am I.” Author lists three Skill archetypes (checklist, workflow, domain expert) with examples from kaku. disable-model-invocation: true for side-effecting Skills. Reduce descriptor tokens aggressively (45→9 tokens example). Skills < 1×/month → delete them.
• Tool design for agents ≠ API design for humans. Namespaced names (github_pr_*), response_format: concise/detailed, error messages that teach the fix. Internal Anthropic example: the AskUserQuestion tool went through three iterations (Bash parameter → markdown convention → dedicated tool) — only the dedicated-tool version was reliable. The TodoWrite tool became a limitation once the model got smart enough to plan dynamically — a lesson about revisiting old constraints.
• claude-hooks are for things you don’t trust the model with. Deterministic enforcement, not “automation.” Good fits: blocking edits to protected files, post-Edit lint, SessionStart context injection, completion notifications. Bad fits: anything requiring multi-step reasoning. Output truncation matters (| head -30) — Hook output also pollutes context.
• claude-subagents are about isolation, not parallelism. The win is keeping noisy work (codebase scans, test runs, audits) out of the main thread’s context. Built-in: Explore (read-only, runs Haiku for cost), Plan, General-purpose. Constrain explicitly via tools / disallowedTools / model / maxTurns / isolation: worktree.
• prompt-caching is the architectural backbone. Anthropic internally pages SEV when cache-hit-rate drops. Cache works by prefix match up to each cache_control breakpoint. Common cache-killers: timestamps in system prompt, tool-set churn mid-session, switching models mid-conversation (cache is per-model — switching Opus→Haiku at 100K tokens is more expensive than staying on Opus). Compaction itself runs as a forked summarization call against the cached prefix (1/10 the cost). EnterPlanMode is implemented as a model-callable tool (not a tool-set switch) precisely to avoid breaking cache. defer_loading: true ships tool stubs so the full schema only loads after the model picks the tool via ToolSearch.
• verifier-loop. “Claude said it’s done” is not a finish line. Layered: exit codes / lint / typecheck → integration tests / screenshots / contract tests → production logs / monitoring / human review. Bind acceptance criteria into the Prompt or Skill up front — if you can’t articulate “done,” the task isn’t ready for Claude.
• claude-md as contract, not wiki. Short, hard, executable. Anthropic’s own CLAUDE.md is ~2.5K tokens. Use .claude/rules/ for path/language-specific rules. Include ## Compact Instructions. Use # in chat to append a line back into CLAUDE.md. Periodically prune — old constraints expire when the model improves.

The article closes with a high-frequency command reference (/context, /clear, /compact, /memory, /mcp, /hooks, /permissions, /sandbox, /model, /simplify, /rewind, /btw, /insight, double-ESC rewind, ~/.claude/projects/ JSONL session storage), an anti-pattern table, and a pointer to Tw93’s open-source health-check Skill tw93/waza (/health command).

Notable claims

• Claude Code’s full architecture is best understood as a six-layer system; treating any layer in isolation introduces failure modes elsewhere.
• The 200K context budget has ~15–20K of fixed overhead before user content, dominated by MCP tool definitions (5 servers ≈ 25K tokens / 12.5%).
• Default compaction discards architecture decisions along with re-readable tool output unless Compact Instructions are declared.
• Cache hit rate is treated by Anthropic as a production SLO, not a nice-to-have.
• The AskUserQuestion tool’s three-version evolution generalizes: when you need the model to do X reliably, give it a dedicated tool for X — don’t add a parameter or a markdown convention.
• Tools that helped early models can become limits on later ones (TodoWrite case). Constraints need expiration dates.
• “If you can’t define done, the task isn’t ready to delegate to an agent.”

Notable quotes

单独优化任何一层都会在其他地方出岔子：CLAUDE.md 写太长，上下文先污染自己了；工具堆太多了，选择就搞不清楚了；subagents 开得到处都是，状态就漂移了；验证这步跳过了，出了问题根本不知道是哪里挂的。

(Optimizing any one layer alone breaks something elsewhere: a too-long CLAUDE.md poisons its own context; too many tools and selection breaks down; subagents fan out everywhere and state drifts; skip verification and you can’t tell what failed.)

假如一个任务你说不清楚「什么叫做完」，那大概率也不适合直接扔给 Claude 自主完成。

(If you can’t articulate what “done” means for a task, it probably isn’t a good fit for autonomous Claude execution.)

Open questions

• The author’s defer_loading mechanism account is plausible but undocumented in public Anthropic material at time of ingest — worth corroborating with a primary source before treating as authoritative.
• The “5 servers ≈ 25K tokens” number depends on which servers; would be useful to gather actual numbers from a running install via /mcp.
• The “switching models mid-session is more expensive than continuing” claim — needs a worked numeric example.

Pointers

• Author’s open-source terminal: kaku (tw93/Kaku).
• Author’s health-check Skill: tw93/waza (/health slash command).
• Mentioned third-party tool: RTK (Rust Token Killer, rtk-ai/rtk) — Hook-based command-output rewriter.
• Background reading: Andrej Karpathy’s LLM Wiki (the schema this repo is built on).