五个诊断层面#

真实上下文成本构成#

1
200K 总上下文
2
├── 固定开销 (~15-20K)
3
│   ├── 系统指令: ~2K
4
│   ├── 所有启用的 Skill 描述符: ~1-5K
5
│   ├── MCP Server 工具定义: ~10-20K  ← 最大隐形杀手
6
│   └── LSP 状态: ~2-5K
7
│
8
├── 半固定 (~5-10K)
9
│   ├── CLAUDE.md: ~2-5K
10
│   └── Memory: ~1-2K
11
│
12
└── 动态可用 (~160-180K)
13
    ├── 对话历史
14
    ├── 文件内容
15
    └── 工具调用结果

一个典型 MCP Server（如 GitHub）包含 20-30 个工具定义，每个约 200 tokens，合计 4,000-6,000 tokens。接 5 个 Server，光这部分固定开销就到了 25,000 tokens（12.5%）。

推荐的上下文分层#

• 始终常驻 → CLAUDE.md：项目契约 / 构建命令 / 禁止事项
• 按路径加载 → rules：语言 / 目录 / 文件类型特定规则
• 按需加载 → Skills：工作流 / 领域知识
• 隔离加载 → Subagents：大量探索 / 并行研究
• 不进上下文 → Hooks：确定性脚本 / 审计 / 阻断

上下文最佳实践#

1. 保持 CLAUDE.md 短、硬、可执行——Anthropic 官方自己只有 ~2.5K tokens
2. 大型参考文档拆到 Skills 的 supporting files，不要塞进 SKILL.md 正文
3. 使用 .claude/rules/ 做路径/语言规则
4. 长会话主动用 /context 观察消耗
5. 任务切换优先 /clear，同一任务进入新阶段用 /compact
6. 把 Compact Instructions 写进 CLAUDE.md

Tool Output 噪声（隐形杀手）#

cargo test 一次完整输出动辄几千行，Claude 不需要全看。推荐用 RTK（Rust Token Killer） 在命令输出到 Claude 之前自动过滤，只留决策需要的核心信息：

1
# Claude 看到的原始输出
2
running 262 tests
3
test auth::test_login ... ok
4
...（几千行）
5

6
# 走 RTK 之后
7
✓ cargo test: 262 passed (1 suite, 0.08s)

压缩机制的陷阱#

默认压缩算法会优先删掉早期 Tool Output 和文件内容，连带架构决策和约束理由也一起扔了。

解决方案：在 CLAUDE.md 里写明 Compact Instructions：

1
## Compact Instructions
2

3
When compressing, preserve in priority order:
4
1. Architecture decisions (NEVER summarize)
5
2. Modified files and their key changes
6
3. Current verification status (pass/fail)
7
4. Open TODOs and rollback notes
8
5. Tool outputs (can delete, keep pass/fail only)

另一种主动方案：开新会话前让 Claude 写 HANDOFF.md，把当前进度、试过什么、哪些走通了、哪些是死路、下一步该做什么写清楚。

Plan Mode 的工程价值#

核心是把探索和执行拆开，探索阶段不动文件。进阶玩法：开一个 Claude 写计划，再开一个 Codex 以”高级工程师”身份审这个计划——让 AI 审 AI。

一个好 Skill 的结构#

1
.claude/skills/
2
└── incident-triage/
3
    ├── SKILL.md
4
    ├── runbook.md
5
    ├── examples.md
6
    └── scripts/
7
        └── collect-context.sh

三种典型 Skill 类型#

类型一：检查清单型（质量门禁）

1
---
2
name: release-check
3
description: Use before cutting a release to verify build, version, and smoke test.
4
---
5
## Pre-flight (All must pass)
6
- [ ] `cargo build --release` passes
7
- [ ] `cargo clippy -- -D warnings` clean
8
- [ ] Version bumped in Cargo.toml
9
- [ ] CHANGELOG updated
10
- [ ] `kaku doctor` passes on clean env

类型二：工作流型（标准化操作）

1
---
2
name: config-migration
3
description: Migrate config schema. Run only when explicitly requested.
4
disable-model-invocation: true
5
---
6
## Steps
7
1. Backup: `cp ~/.config/kaku/config.toml ~/.config/kaku/config.toml.bak`
8
2. Dry run: `kaku config migrate --dry-run`
9
3. Apply: remove `--dry-run` after confirming output
10
4. Verify: `kaku doctor` all pass
11

12
## Rollback
13
`cp ~/.config/kaku/config.toml.bak ~/.config/kaku/config.toml`

类型三：领域专家型（封装决策框架）

1
---
2
name: runtime-diagnosis
3
description: Use when kaku crashes, hangs, or behaves unexpectedly at runtime.
4
---
5
## Evidence Collection
6
1. Run `kaku doctor` and capture full output
7
2. Last 50 lines of `~/.local/share/kaku/logs/`
8
3. Plugin state: `kaku --list-plugins`
9

10
## Decision Matrix
11
| Symptom | First Check |
12
|---|---|
13
| Crash on startup | doctor output → Lua syntax error |
14
| Rendering glitch | GPU backend / terminal capability |
15
| Config not applied | Config path + schema version |

描述符优化#

低效（~45 tokens）→ 高效（~9 tokens）：

1
# 低效
2
description: This skill helps you review code changes in Rust projects...
3

4
# 高效
5
description: Use for PR reviews with focus on correctness.

Skills 反模式#

• 描述过短（什么都能触发）
• 正文过长（几百行全塞 SKILL.md）
• 一个 Skill 覆盖 review、deploy、debug、docs、incident 五件事
• 有副作用的 Skill 允许模型自动调用

好工具 vs 坏工具#

实用设计原则#

1. 名称前缀按系统或资源分层：github_pr_*、jira_issue_*
2. 对大响应支持 response_format: concise / detailed
3. 错误响应要教模型如何修正
4. 能合并成高层任务工具时，不要暴露过多底层碎片工具

工具演进的有趣教训#

AskUserQuestion 的演进史：

1. 第一版：给 Bash 工具加 question 参数 → 模型忽略
2. 第二版：要求输出特定 markdown 格式 → 模型经常”忘了”
3. 第三版：做成独立 AskUserQuestion 工具 → 调用即暂停，没有歧义 ✅

Todo 工具的教训：早期因为模型不够强加了 TodoWrite 工具，模型变强后反而成了限制。→ 定期检查当初加的限制还成不成立。

什么时候不该再加 Tool#

• 本地 shell 可以可靠完成的事情
• 模型只需要静态知识
• 需求更适合 Skill 的工作流约束
• 还没验证过工具描述和返回格式能被模型稳定使用

Hook 配置示例#

1
{
2
  "hooks": {
3
    "PostToolUse": [
4
      {
5
        "matcher": "Edit",
6
        "pattern": "*.rs",
7
        "hooks": [{
8
          "type": "command",
9
          "command": "cargo check 2>&1 | head -30",
10
          "statusMessage": "Checking Rust..."
11
        }]
12
      }
13
    ],
14
    "Notification": [
15
      {
16
        "type": "command",
17
        "command": "osascript -e 'display notification \"Task completed\" with title \"Claude Code\"'"
18
      }
19
    ]
20
  }
21
}

Hooks + Skills + CLAUDE.md 三层叠加#

配置时要显式约束#

• tools / disallowedTools：限定工具范围
• model：探索用 Haiku/Sonnet，重要审查用 Opus
• maxTurns：防止跑飞
• isolation: worktree：需要动文件时隔离文件系统

常见反模式#

• 子代理权限和主线程一样宽
• 输出格式不固定，主线程拿到没法用
• 子任务之间强依赖，频繁共享中间状态

Prompt 顺序（缓存前缀匹配）#

1
1. System Prompt → 静态，锁定
2
2. Tool Definitions → 静态，锁定
3
3. Chat History → 动态，在后面
4
4. 当前用户输入 → 最后

破坏缓存的常见陷阱#

• 在静态 System Prompt 中放入带时间戳的内容
• 非确定性地打乱工具定义顺序
• 会话中途增删工具

技巧： 当前时间等动态信息，放到下一条消息的 <system-reminder> 标签里传进去，不动 System Prompt。

会话中途不要切换模型#

Prompt 缓存是模型唯一的。切换模型实际上比继续用原模型更贵（要重建整个缓存）。确实需要切换的话，用 Subagent 交接。

defer_loading：工具的延迟加载#

Claude Code 有数十个 MCP 工具，通过发送轻量级 stub（只有工具名，标记 defer_loading: true），完整 schema 只在模型选择后才加载，缓存前缀保持稳定。

Verifier 的层级#

• 最低层：命令退出码、lint、typecheck、unit test
• 中间层：集成测试、截图对比、contract test、smoke test
• 更高层：生产日志验证、监控指标、人工审查清单

在 Prompt 中显式定义验证#

1
## Verification
2

3
For backend changes:
4
- Run `make test` and `make lint`
5
- For API changes, update contract tests under `tests/contracts/`
6

7
For UI changes:
8
- Capture before/after screenshots if visual
9

10
Definition of done:
11
- All tests pass
12
- Lint passes
13
- No TODO left behind unless explicitly tracked

上下文管理#

能力与治理#

会话连续性与并行#

不常见但很好用的命令#

应该放什么#

• 怎么 build、怎么 test、怎么跑（最核心）
• 关键目录结构与模块边界
• 代码风格和命名约束
• 那些不明显的环境坑
• 绝对不能干的事（NEVER 列表）
• 压缩时必须保留的信息（Compact Instructions）

不该放什么#

• 大段背景介绍
• 完整 API 文档
• 空泛原则（如”写高质量代码”）
• 显然信息（Claude 读仓库即可推断）
• 大量背景资料和低频任务知识（放到 Skills）

高质量模板#

1
# Project Contract
2

3
## Build And Test
4
- Install: `pnpm install`
5
- Dev: `pnpm dev`
6
- Test: `pnpm test`
7
- Typecheck: `pnpm typecheck`
8
- Lint: `pnpm lint`
9

10
## Architecture Boundaries
11
- HTTP handlers live in `src/http/handlers/`
12
- Domain logic lives in `src/domain/`
13
- Do not put persistence logic in handlers
14
- Shared types live in `src/contracts/`
15

16
## Coding Conventions
17
- Prefer pure functions in domain layer
18
- Do not introduce new global state without explicit justification
19
- Reuse existing error types from `src/errors/`
20

21
## NEVER
22
- Modify `.env`, lockfiles, or CI secrets without explicit approval
23
- Remove feature flags without searching all call sites
24
- Commit without running tests
25

26
## ALWAYS
27
- Show diff before committing
28
- Update CHANGELOG for user-facing changes
29

30
## Verification
31
- Backend changes: `make test` + `make lint`
32
- API changes: update contract tests under `tests/contracts/`
33
- UI changes: capture before/after screenshots
34

35
## Compact Instructions
36
Preserve:
37
1. Architecture decisions (NEVER summarize)
38
2. Modified files and key changes
39
3. Current verification status (pass/fail commands)
40
4. Open risks, TODOs, rollback notes

让 Claude 维护自己的 CLAUDE.md#

每次纠正错误后，让它更新 CLAUDE.md：

“Update your CLAUDE.md so you don’t make that mistake again.”

Claude 在给自己补规则时还挺好用，但也要定期 review，过时的限制要及时清理。

”环境透明”比你想象中重要#

Claude Code 调用的是真实的 shell、git、package manager。只要有一层不透明，它就猜，一猜可靠性就掉。

做法：在项目里加个 doctor 命令，把环境状态统一收上来。Claude Code 开始做事前先跑一次 doctor。

混合语言项目的 Hooks 实践#

两套语言、两套检查，用 Hooks 按文件类型分别触发：

• *.rs → cargo check
• *.lua → luajit -b

完整工程化布局参考#

1
Project/
2
├── CLAUDE.md
3
├── .claude/
4
│   ├── rules/
5
│   │   ├── core.md
6
│   │   ├── config.md
7
│   │   └── release.md
8
│   ├── skills/
9
│   │   ├── runtime-diagnosis/
10
│   │   ├── config-migration/
11
│   │   ├── release-check/
12
│   │   └── incident-triage/
13
│   ├── agents/
14
│   │   ├── reviewer.md
15
│   │   └── explorer.md
16
│   └── settings.json
17
└── docs/
18
    └── ai/
19
        ├── architecture.md
20
        └── release-runbook.md