博客笔记

Claude Code 节约 Tokens 技巧

24 个 Claude Code 成本控制技巧：保护 prompt cache、subagent 隔离上下文、确定性任务脚本化、按难度切换模型、/compact 与 /clear 的时机、/rewind、/btw、/context 监控、Batch API、权限分层、git worktree 并行、adversarial review、失败模式库与 CodeGraph MCP。

2026年6月30日 · 20 分钟阅读

导论

Claude Code 的成本控制核心不是“少用模型”，而是减少无效上下文、保护缓存、避免返工，并把确定性任务交给脚本处理。

最优先做三件事：

同一个 session 内不要频繁改配置，保护 prompt cache。
任务结束后及时沉淀 notes，然后 /clear。
重复、确定性的操作脚本化，不要让 LLM 当 bash 用。

注意：方法基本适用于其他Agent，并非CC专属

示列组合工作流

仅供参考，具体根据自己的需求选取使用

开 session 前：/context 看 baseline，尽可能把 CLAUDE.md 砍到 <3k token
写代码时：用 @file:行号 精准引用，让 Claude 用 rg 定位
要查 API/文档：/btw，不污染主任务 context
走错路了：/rewind 选 Summarize from here
跑批处理：脱离 Claude Code，用 Batch API 写 Python 脚本，50% off
每个模块完成：让 Claude 把决策写进 .notes/，然后 /clear

最容易立刻见效的两个：关掉用不到的 MCP server（直接砍每轮固定开销）和 /btw 替代追问。

一、直接省钱且副作用小

1. 保护 prompt cache：同一 session 内不要乱改配置

这是最重要的一条。Claude 的 prompt cache 会缓存 system prompt、CLAUDE.md、工具定义和历史前缀。缓存命中后，重复读取的 input token 成本会大幅降低。

容易打破缓存的操作包括：

上下文前缀发生较大变化
修改 CLAUDE.md 或 system prompt（CLAUDE.md 改一个字也算）
增删 MCP server（工具定义在 system prompt 里）
切换模型（Opus 和 Sonnet 不共享缓存）
缓存有最小 token 门槛——Sonnet 4.6 是 2048 token，Opus 4.5/4.6/4.7 和 Haiku 4.5 是 4096 token，CLAUDE.md 太短反而进不了缓存 Ofox

Claude Code 里可以用这些命令观察：

/context
/usage

/context 用来看当前上下文占用分布，包括 system prompt、CLAUDE.md、MCP、messages、files 和剩余空间。

/usage 用来看 token 和 cache 命中情况，重点关注：

{
  "input_tokens": 120,
  "cache_creation_input_tokens": 2048,
  "cache_read_input_tokens": 18000,
  "output_tokens": 450
}

如果 cache_read_input_tokens 很大，说明缓存正在生效。如果它是 0 或很小，大概率是缓存被打破了。

注意：Claude Code 不会显式告诉你"哪些文件被缓存了"，它缓存的是整个 prefix（system prompt + CLAUDE.md + 工具定义 + 历史消息中标记为 cacheable 的部分）。你能控制的是别去打破它——/context 数字稳定，cache_read 一直在涨，就是健康的。

2. 子 agent 只返回结论，不返回过程

这是 Anthropic 官方推荐的核心模式。Subagent 的价值在于隔离上下文。它在独立 context 中执行任务，主 session 只接收最终结论，避免把大量中间过程带回主对话。Anthropic 内部的判断标准是"我之后还需要这个 tool output 吗，还是只要结论就够了"。

适合 subagent 的任务：

代码审查
transcript schema 校验
批量文件检查
局部问题调查
不需要主 session 看到完整过程的任务

补充技巧: Claude

显式触发："use subagents to investigate X" 比让 Claude 自己决定更可靠
让 subagent 把中间产物写到磁盘文件而不是 return，主 session 需要时再读

Question：怎么正确开启subagents，以及怎么发布指令？

claude 命令进入即是。

子 agent 三种创建方式：

1. 交互式（推荐）：

/agents

Anthropic 官方推荐用 /agents 命令创建。会引导你填名字、描述、tool 权限、模型，自动写到 .claude/agents/<name>.md。 PubNub

2. 手写文件：在项目根目录创建 .claude/agents/code-reviewer.md：

---
name: code-reviewer
description: Reviews code for quality and best practices. Use proactively after writing new code.
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

tools 字段可选,留空则继承当前 session 的工具(包括 MCP)。model 可选 sonnet/opus/haiku/inherit。 Claude

放在 .claude/agents/(项目级,跟 git 走)或 ~/.claude/agents/(用户级,跨项目)。 Claude

手动新建文件需要重启 session 才能加载;通过 /agents 创建立即生效。 Claude

调用方式三种（越往下控制越强）：

# 自然语言(Claude 自己决定要不要调)
Use the code-reviewer subagent to look at my recent changes

# @-mention(强制调用)
@code-reviewer review src/auth/

# session-wide(整个 session 都跑这个 agent)
claude --agent code-reviewer

关键设计原则（这条踩坑最多）：

subagent 的 context 起步是空的,父 session 传递的唯一通道是 Agent tool 的 prompt 字符串。所以要把文件路径、错误信息、决策都写进调用提示里,否则子 agent 啥都不知道。 Claude API Docs
subagent 不支持 plan mode,接到任务立即执行;且没有透明的 thinking 输出,过程不可见。需要观察执行的任务别用 subagent。 PubNub
description 字段要包含 "use proactively" 或 "MUST BE USED for X" 这类关键词，Claude 路由判断更准。

3. 确定性任务用脚本，不用模型

agent 研究里常见误区：把 LLM 当 bash 用。

凡是输入相同、输出就应该相同的任务，都不该交给 LLM。

典型例子：

跑测试
格式化
lint
批量重命名
grep 搜索
git 状态检查
transcript JSON schema 校验
批处理音频或日志

识别标准：

每次输入相同，输出就该相同——格式化、重命名、git 操作、跑测试
判断逻辑你能写成 if-else——不需要语义理解，只需要规则
你在不同 session 里反复让 Claude 做同一件事——这是最强信号

记一下你最近三天问 Claude 的命令，重复出现 ≥3 次的，全是脚本候选。

三种脚本化层级：

Level 1：直接用 ! 执行 bash

!git status
!pytest tests/test_segmentation.py -x
!rg "TODO" src/ -n | head -20

Level 2：自定义 slash command

路径：

.claude/commands/test.md

示例：

---
description: Run audio pipeline tests with summary
allowed-tools: Bash(pytest:*), Bash(rg:*)
argument-hint: [test_file]
model: haiku
---

Run pytest on $ARGUMENTS, then summarize:
- Pass/fail count
- Failing test names with one-line reason
- Skip the full traceback unless asked

Execute:
!pytest $ARGUMENTS -v 2>&1 | tail -50

之后可以直接运行：

/test tests/test_asr.py

Level 3：Hooks 强制执行

适合“每次改完代码都必须做”的事，比如 ruff、mypy、测试、日志记录。

CLAUDE.md 是 advisory(should-do),hooks 是 mandatory(must-do)。需要"100% 必须执行"的事用 hook，比"在 CLAUDE.md 里要求 Claude 记得"靠谱得多。 DEV Community

二、方向对，但数字要打折

4. 按任务难度切换模型

不要全程用最贵模型。

更现实的策略：

默认 Sonnet
深度重构、长链 debug、架构决策时切 Opus
简单提取、校验、分类可考虑 Haiku（很少用）
Claude Code 主交互通常不适合全程用 Haiku

注意：切换模型可能打破 cache，不要在同一个 session 里频繁切。

5. 在 50–70% context 时手动 /compact

/compact 的最佳时机不是快满了才用，而是在阶段边界使用。

最合适的情况：

当前任务刚完成
下一步任务和当前内容部分相关
context 在 50–70% 左右
模型还没有明显遗忘或混乱
接下来还会继续使用这个 session

不要在 debug 中途 compact。中途 compact 很容易丢掉关键细节，让 Claude 重复踩坑。

/compact 可以传指令引导,告诉它保留什么、丢弃什么。这一句话能让压缩质量天差地别。 Claude

推荐写法：

/compact Focus on the API design decisions we made and the failing tests.
Drop all the debugging discussion about the wrong import path.

不要裸跑 /compact。加 focus instructions 可以显著提高压缩质量。

什么时候不用 compact：

任务完全切换：用 /clear
session （<30%）很短：没必要
debug 正在进行：继续保留细节
已经接近 auto-compact：质量通常变差

auto-compact 触发时模型已经在 context rot 状态下，自己总结自己已经退化的对话，质量很差；手动在 phase 边界 compact 时模型还清醒，能产出更好的 summary。 SitePoint + 2

注意成本：compact 本身是一次 LLM 调用，按当前完整 context 计费，不便宜；典型 70k token 对话压到约 4k token，但要花一分钟以上。所以 compact 不是免费的"瘦身"，是用一次贵调用换后续 N 次便宜调用——只在你确定还会继续在这个 session 里干活时才划算。 SitePointMedium

6. 任务结束后 /clear，但先沉淀 notes

/clear 会清空当前上下文，不可恢复。正确做法是先让 Claude 写 session note，再 clear。

收尾 prompt：

我们今天的工作收尾了。请做以下三件事：

1. 把这次 session 的成果总结到 .notes/2026-05-05-<task-name>.md，包含：
   - 完成了什么：功能、修复、决策
   - 还没做的：显式 TODO，标注阻塞点
   - 关键决策和原因：为什么选 A 不选 B
   - 踩过的坑和解决方案

2. 检查并更新 CLAUDE.md：
   - 是否有新加的 build/test/lint 命令需要记录
   - 是否有新发现的项目约定
   - 是否有过时信息需要删除

3. 给我下次开 session 时该说的第一句话，一行即可。这句话要包含下一个窗口需要在项目里阅读的文档名字。

重启 session 的第一句话模板：

继续上次的 <task-name> 工作。请先读 .notes/2026-05-05-<task-name>.md 了解上下文，然后从 TODO 列表的第一项开始，有疑问先问我。

注意点：

不要 -continue 或 -resume 旧 session 来"接着干"——--continue 会把上一个 session 的全部 context 状态带过来,如果之前已经很长,新 session 一开始就背着包袱。新开 session 读 notes 更干净。 MindStudio
检查 CLAUDE.md 是否过大——如果你昨天往里塞了一堆细节，今天开 session 前先 /context 看下基线。
先小任务再大任务——刚开始 session 时 Claude 对项目的“新感知”不如压缩好的 notes 准确，前两轮做点确认性的小事（"先 list 一下项目结构告诉我你看到什么"），让它对齐再交大任务。
Plan Mode 起手——复杂任务先 Shift+Tab 两次进 Plan Mode，让它基于 notes + 当前代码做 plan，确认后再执行。

补充动作（手动做）：

git add -A && git commit -m "wip: <feature> - see .notes/2026-05-05.md for next steps"

三、边际收益，但好习惯

7. 精简 CLAUDE.md、Skills 和 MCP

每轮固定进入上下文的内容越多，成本越高。

优先优化顺序：

关掉不用的 MCP server
精简 CLAUDE.md，只写全局规则，白皮书和工程规范，具体执行指令等等写到其他文档
把低频规则拆进 .claude/skills/
避免把临时细节塞进长期 memory

判断方法：

/context

如果看到 MCP 占用很大，先关 MCP。

对于软件开发，Claude Code 内置的 Read、Write、Edit、Bash、Glob、Grep 已经覆盖大部分本地开发需求。可以不用 MCP。

比较有价值的 MCP：

GitHub：处理 issue / PR
Context7：查最新库文档
Playwright：需要浏览器自动化时
数据库 MCP：需要直接查数据库时

建议 MCP server 控制在 3–5 个以内。超过这个数量，token overhead 可能压过收益。

关闭方式：

claude mcp list
claude mcp remove <server-name>

或用：

/mcp

临时 toggle 当前 session 的 MCP。

装一堆用不到的 MCP 是负优化。 Toolradar

8. 一次把任务说清楚

每次追问都会重新读上下文，所以复杂任务最好一次性说清楚。

好的任务描述应该包含：

目标
修改范围
不修改范围
输入文件路径
关键日志片段
验收标准
是否允许创建/移动/删除文件
是否需要先 plan 再执行

不要贴完整 build log。只贴关键错误附近的 20–50 行。

9. 精准引用文件位置

不要让 Claude 扫整个 repo。先定位，再读片段。

具体技巧： KnightLi Blog

@src/auth/login.ts:45-80 比 @src/auth/login.ts 省 90%
贴日志只贴报错相关那 20 行，别整个 build output 倒进去
复杂指令一次列完比来回追问更省（每次追问都重读全部历史）

10. Output token 要控制

Output token 比 input token 更贵，而且不会被缓存。

Output token 比 input 贵 5×（所有 Claude 模型都一样）。在API调用层设置严格的max_tokens 、要求结构化输出、避免让模型复述长片段，比省 input 更直接。

原理：output token 单价是 input 的 5×，且每生成 1 个 token 都不进缓存（缓存只对输入有效），所以"少说"比"少听"省钱。

减少 output 的方法：

把完整分析写入 .notes/analysis.md，对话里只告诉我文件路径和 3 条结论。
只输出 unified diff，不要重新打印整个函数。
只给结论，不要复述我贴的代码。
输出 JSON/YAML，不要写长篇解释。

核心原则：让 Claude 把长内容写进文件，而不是打印在对话里。

四、使用配套命令

11. Plan Mode 和网页端规划的配合

先用网页端的AI，如ChatGPT进行规划和写agent执行指令，再输入指令让claude code执行

为什么先规划再执行更省

一次 plan 调用 + 执行 N 个原子任务 → 比直接让 Claude 一边想一边改 → 节省 30–50% token
关键省的是返工成本：跑偏一次的代价远大于规划成本
Plan 阶段不写代码，可以放心切 Opus；执行阶段切回 Sonnet

什么时候用网页端

适合高层设计和白板讨论：

架构取舍
理论框架
论文结构
方法学讨论
不需要读本地代码的任务

网页端更像“白板会议”。

什么时候用 Claude Code Plan Mode

适合基于当前代码状态制定执行方案：

多文件重构
修 bug
加 feature
数据分析 pipeline
测试设计
依赖当前项目结构的任务

Plan Mode 更像“基于代码现状的执行计划”。

最佳流程

复杂任务推荐三段式：

1. 网页端：做高层设计，产出 architecture-<date>.md
2. Claude Code Plan Mode：读设计文档和当前代码，产出可执行 plan // 非复杂任务或者想节约tokens可以省略
3. Claude Code 执行模式：按 plan 分步骤实现、测试、commit

Plan Mode 的输出必须包含：

请输出一个执行计划，每一步包含：

1. 目标：这一步要达成什么
2. 修改的文件：精确到 file:line_range
3. 不修改的文件：列出容易被误改但应保留的文件
4. 验收标准：测试名、输出样例或检查方式
5. 回滚方案：出错后怎么撤销

输出后等我确认，不要立即执行。

其中“不修改的文件”很重要，可以减少 Claude 顺手改无关文件的风险。

12. /rewind 是使用

/rewind 适合处理“中途走错路”的情况。

触发方式：

/rewind

或连按两次 Esc。

最有价值的选项是：

Summarize from here

适用场景：

debug 走了 30 轮弯路
后来发现根因是别的问题
前面的项目上下文还需要保留
中间错误探索过程不想继续占上下文

和其他命令的区别：

命令	作用	适用场景
`/compact`	全部历史压缩	整个 session 过长，但内容仍相关
`/rewind` + Summarize	局部压缩	中途走偏，但前面内容还有用
`/clear`	清空上下文	任务彻底结束或切换

注意：/rewind 不能撤销外部副作用，比如数据库写入、API 调用、某些 Bash 直接修改。重要节点还是要 git commit。

13. /btw 的使用

/btw 适合问临时小问题，不污染主对话上下文。

用法：

/btw 我们前面是不是已经把 error type 改成 enum 了？

适合：

查一个小概念
确认前面是否做过某事
问当前上下文里的小问题
主任务执行中临时插一句

不适合：

需要读文件
需要跑命令
需要搜索代码
需要调用工具

记忆方式：

subagent：有工具，但起步上下文为空。
/btw：能看当前上下文，但没有工具。

14. /context 命令实时看占用分布

知道是 CLAUDE.md 占了还是对话历史占了，才能针对性优化。

原理：实时看 context 占用分布，知道是哪一块在吃 token。

具体操作：

Claude Code 里直接输入 /context，会按类别给出当前对话的 token 占用 breakdown。典型输出是分块显示： DEV Community

System prompt
CLAUDE.md（Memory 部分）
MCP 工具定义
对话消息
文件附件
Free space

实操判断逻辑：

看到什么	该做什么
MCP 占 >15k token	`/mcp` 关掉本任务用不到的 server
CLAUDE.md 占 >5k	拆到 `.claude/skills/` 按需加载
Messages 占 >50% 且任务还没完	`/compact` 或 `/rewind` 选 Summarize from here
文件附件占大头	让 Claude 改用 grep 定位再读片段

配合 status line 持续监控（在 settings.json 里）：

{
  "statusLine": {
    "type": "command",
    "command": "echo \"$(date +%H:%M) | ctx: $CLAUDE_CONTEXT_USED/$CLAUDE_CONTEXT_TOTAL\""
  }
}

15. 批次处理（补充）

Batch API 全线：

是一次性提交很多个独立请求，让 Anthropic 后台异步处理，之后再取结果。

所谓 “全线 50% off”，指的是 Claude API 的 Batch API 对 input tokens 和 output tokens 都打 5 折。官方 pricing 页面明确写了：Batch API 用于异步处理大量请求，并对输入和输出 token 都提供 50% discount。

它适合这种任务：

我有 3000 条 transcript，需要逐条判断是否包含 Q&A。
我有 1000 条访谈回答，需要逐条分类主题。
我有 500 篇摘要，需要统一抽取变量、方法、结论。
我有一批 eval samples，需要逐条跑模型评分。

用 non-interactive mode 做固定流水线：

如果某个任务已经变成“输入文件 → Claude 分析 → 输出 JSON/Markdown”，就不要每次进交互式 Claude Code。

官方 common workflows 也提到可以把 Claude pipe into scripts，用于 CI 和批处理。

适合：

生成 changelog
检查 PR diff
批量审查 markdown
从 transcript 抽取结构化字段
对 evaluation result 生成摘要

它和 Batch API 的区别是：Batch API 是 Anthropic API 层面的异步便宜跑批；non-interactive Claude Code 更适合本地 repo 脚本化工作流。

五、减少 agent 误操作

16. 给权限做分层配置

codex同理

Claude Code 官方支持 /permissions，可以把工具规则分成 allow、ask、deny：常用安全命令自动允许，高风险命令必须询问，危险命令直接拒绝。这样既减少确认疲劳，也防止 agent 顺手执行破坏性操作。

推荐操作：

把权限分成三层：
- allow：pytest、ruff、rg、git diff、git status
- ask：git commit、package install、数据库命令、外部 API 调用
- deny：rm -rf、生产部署、密钥读取、系统目录写入

17. 用 git worktree 跑并行 Claude session

如果不是急需同时修改，尽可能只改一个窗口，避免工作混乱导致回退

worktree 本来是老 Git 功能，但 2025–2026 年因为 AI coding agent 并行开发重新变热。对你最有价值的不是“多开分支”，而是“隔离 code agent 的改动范围”。

如果你想让一个 Claude 修 bug，另一个 Claude 做 refactor，不要在同一个工作目录里开两个 session。官方建议用 git worktree，因为每个 worktree 有独立文件状态和分支，但共享同一个 repo history，能避免多个 Claude 实例互相覆盖文件。

概念：

worktree 是什么：一个 Git 仓库可以挂多个 working tree，也就是同一个仓库历史和 remote，可以同时 checkout 多个分支到不同目录里。主目录叫 main worktree，额外目录叫 linked worktree。

普通分支切换是：

git checkout feature-a
# 当前目录里的文件整体切到 feature-a

worktree 是：

git worktree add-b feature-a ../interviewdx-feature-a

结果是你会有两个目录：

~/projects/
├── interviewdx/                 # 主 worktree，例如 main/dev
└── interviewdx-feature-a/        # linked worktree，feature-a 分支

codex客户端的右上角可以点击切换

使用举例：

~/projects/
├── interviewdx/                         # 主目录：保持干净，用于 main/dev、最终验证
├── interviewdx-wt-admin-export/          # 后台导出功能
├── interviewdx-wt-feedback-ui/           # 前端反馈 UI 调整
├── interviewdx-wt-bug-session-api/       # 后端 session bug 修复
└── interviewdx-wt-agent-experiment/      # code agent 探索性改法

你的主目录不要乱动，保持为“稳定参照物”。每个新任务开一个 worktree，让 code agent 只在那个目录里工作。这样它改坏了，你直接丢掉那个 worktree，不污染主项目。

需要注意的坑：

第一，不要让多个 worktree 同时用同一套 Docker 端口启动。你的项目端口规范里前端是 localhost:3000，后端宿主机是 localhost:8010，PostgreSQL 在 Docker 网络里是 db:5432。如果你在两个 worktree 同时 docker compose up，大概率会端口冲突。初期最稳妥：一次只启动一个 worktree 的 Docker 环境。

第二，依赖需要分别安装。每个 worktree 是独立文件目录，所以 frontend/node_modules、Python .venv、构建产物通常不会共享。Google Cloud 那篇文章也明确提到这个成本。对你来说可以接受，因为换来的是隔离和可回滚。

第三，不要用 worktree 并行做强耦合任务。例如两个 agent 同时改数据库 migration、实验分组逻辑、权限控制、phase 状态机、反馈 schema，这些容易互相冲突。你的项目规范本身也要求涉及数据库、权限、真实数据、生产部署或重大重构时先说明影响面、风险和回滚思路。

第四，不要把 worktree 当成删除保护机制。它不是备份。未 commit 的改动仍然可能丢。特别是你的项目规则明确不应随意删除、移动或新建项目文档，废弃文档也要优先归档而不是删除。

什么时候该用，什么时候不该用:

适合用:

场景	是否适合
code agent 并行修两个独立 bug	很适合
前端 UI 调整 + 后端 API 小修分别推进	适合
临时验证一个外部 PR / 分支	适合
当前改动未完成，但要紧急修 bug	很适合
探索性重构，不确定能不能成功	适合

不适合用：

场景	原因
5 分钟内的小改动	没必要增加目录管理成本
多个任务都改同一批核心文件	冲突仍然会发生
数据库 migration / 实验条件 / 权限改动并行做	风险高，不建议
生产部署操作	不应该靠 worktree 隔离风险

18. 加一个 adversarial review step

不是普通 code review，而是让 Claude 专门找反例、边界条件、隐含假设和测试缺口。Anthropic 的 best practices 里也把 adversarial review 作为自动化和规模化工作流的一部分。

推荐模板：

请做 adversarial review。不要表扬实现。只检查：
1. 哪些需求可能没有被满足
2. 哪些边界条件会失败
3. 哪些文件被不必要地改动了
4. 哪些测试缺失
5. 有没有数据丢失、权限扩大、破坏性操作风险
只输出问题和证据，不要重写代码。

19. 先让 Claude 解释 repo 的“局部地图”，再让它动手

这和 Plan Mode 不一样。Plan Mode 是计划修改；局部地图是确认它真的理解了相关模块。对于大项目，官方也强调要把 Claude 的工作范围限定到任务相关的 codebase 区域，避免它把上下文窗口塞满无关文件。

可以这样用：

先不要修改代码。请只做局部代码地图：
1. 这个任务相关的入口文件
2. 核心函数调用链
3. 配置文件
4. 测试文件
5. 你认为不相关、不会读取的目录

这条很适合多模块项目。

20. 把 status line 做成“驾驶仪表盘”

前面提到了 statusLine，但可以升级成固定监控：模型、context 百分比、git branch、cost、当前目录。Claude Code 官方支持 /statusline 自动生成脚本，也可以手动在 settings 里配置。

建议显示这几个字段：

model | branch | cwd | context% | cost | duration

这样你不用等到模型变蠢才发现 context 已经太长。

注意：如果怕麻烦，至少记得及时/clear和/conpact

21. 高风险任务强制新分支 + 小 commit

依靠git进行版本控制

因为 agent 的一次操作可能跨多个文件，回滚粒度必须靠 git 控制，而不能只靠 /rewind。

推荐规则：

超过 3 个文件的修改，必须：
1. 新建分支
2. 先 plan
3. 每个 atomic step 后 git diff
4. 测试通过后小 commit

22. 维护一个“失败模式库”

维护 agent failure patterns，沉淀你自己的防护规则

管理你自己的 agent 失败模式。比如“Claude 经常乱改文档”“容易忽略 transcript schema”“喜欢删除 debug 文件”“会把测试 mock 写得过度理想化”。这些比通用技巧更值钱。

建议文件：

.notes/agent-failure-patterns.md

格式：

## Failure pattern: 顺手修改无关文档

触发场景：
- 让 Claude 整理 repo
- 让 Claude 清理 debug artifacts

防护 prompt：
- 不要删除、移动、创建文档，除非我明确确认
- 可疑文件只移动到 docs/archived，不要删除

验证：
- git diff --name-status

六、其他技巧的使用

23. grill-me skill

https://www.cnblogs.com/guangzan/p/20774394？
https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md

grill-me “拷问我”——解决的是需求和设计阶段，而不是编码阶段。

事实上，要找的不是“最强 grill-me-skill”，而是先理解 grill-me 的机制，再把它改成工作流。

机制解析：

它不是让 AI 直接给计划，而是让 AI 在动手前沿着设计树逐个追问；一次只问一个问题；每个问题给推荐答案；如果能通过代码库判断，就先读代码库；直到双方对计划达成共识。这个机制比具体措辞重要。

触发条件：主动提及使用。适用于产品功能、实验设计、数据结构、后台权限、用户行为记录、论文研究设计、代码实现前的需求澄清。
追问方式：不是每次问十几个问题，而是只问当前最关键的一个问题；等你回答后再继续；不要提前生成完整执行计划。
推荐机制：每个问题后面必须给一个推荐选择，并说明为什么，但不要替你拍板。
停止条件：很多追问型 prompt 最大问题是没完没了。需要写清楚当核心目标、边界、数据影响、验收标准、风险和未决事项都清楚后，就停止追问，并输出一份简短决策摘要。
使用方式：Codex 版本可以读代码库，直接安装SKILL；ChatGPT 网页端适合讨论想法，非Business无法使用SKILL，可以用ChatGPT Project instructions 代替；

24. CodeGraph MCP

https://zhuanlan.zhihu.com/p/2043160358018348348
https://github.com/colbymchenry/codegraph

CodeGraph MCP 本质不是“让模型变聪明”，而是给 code agent 多挂了一个代码结构查询工具。只有 agent 主动调用这个工具时，它才会影响结果。

机制解析：

先在项目里跑 codegraph init，生成本地 .codegraph/ 索引。
它用 Tree-sitter 解析代码，抽取函数、类、方法、调用、import、继承等关系。
把这些结构存进本地 SQLite 图数据库和 FTS5 全文索引。
Claude Code / Codex / opencode 通过 MCP 调用 codegraph_explore，一次性拿到相关源码、调用链、影响范围，而不是一遍遍 grep / read file。

意义：CodeGraph不是替代 agent，而是减少“反复 grep/read”的探索成本。