claude-code-audit

Claude Code 审计

这是什么

一套严谨的框架，用于审计大量用户的 Claude Code 会话，从中找出能带来阶跃式提升的改进——也就是能改变其工作流的 2–3 项改进，而不是 20 项锦上添花的小改动。

当用户询问“我怎样才能改进工作流”时，默认做法是列出一长串边际建议。这种输出不仅毫无帮助，甚至更糟：它用听起来悦耳的噪声掩盖了真正有价值的改进，用户最后什么也不会做。这项技能旨在避免这种结果。

保证

审计结束时，你将完成：

1. 一份简短的优先级报告——列出真正能带来显著改善的少数发现，并提供量化证据。
2. 已起草的实现方案——针对优先级最高的建议，准备好可直接安装的技能、CLAUDE.md 规则、钩子脚本或设置差异。不是建议，而是实际草案。
3. 完整的审计记录——包括提取的数据、抽样的会话列表和子 Agent 的发现，方便用户核实综合分析结果并在日后查阅。

如果审计结束时你只得出了观察结果，那就是失败。

始终区分阶跃式改进和边际改进

边际改进	阶跃式改进
“你应该更常使用技能 X。”	“技能 X 从未在这类提示词中触发，因为它的描述不包含你实际使用的措辞。这里有一份新的描述。”
“你经常纠正 Claude 的测试风格。”	“过去 30 天里，你 14 次给出了相同的纠正。根本原因是 Claude 默认编写单元测试，而你需要的是集成测试。这里有一段 CLAUDE.md 内容，可以消除反复纠正的循环。”
“考虑更早添加测试。”	“你的 60 个会话中，有 19 个出现了‘事后测试’→‘修复回归问题’→‘再修复另一个回归问题’的循环，平均耗时 35 分钟、消耗 80k 个令牌。添加一个运行现有测试脚本的提交前钩子，就能避免这个循环。”

左栏是观察。右栏是诊断、处方和证据。你要给出右栏的内容。

会话数据存放位置

• 根目录：~/.claude/projects/<encoded-project-path>/<session-id>.jsonl
• 每行代表一个事件：user、assistant、attachment（钩子结果）、system、file-history-snapshot、last-prompt。
• 用户的 ~/.claude/ 目录包含全局 CLAUDE.md、技能、设置和钩子。综合分析时需要与这些内容交叉参照。
• JSONL 架构及重要字段请参阅 references/session_format.md。

设置——工作目录

开始前，设置 SKILL_DIR 和 AUDIT_DIR：

• SKILL_DIR=~/.claude/skills/claude-code-audit（脚本所在位置——切勿修改）
• AUDIT_DIR=~/claude-audit/<date>（审计输出位置——每次运行都新建一个子目录，或使用用户指定的路径）

下文所有 python $SKILL_DIR/scripts/... 调用均假定这些变量已设置。可从任意 cwd 运行；脚本接受绝对路径。第 1 阶段开始前，先创建 AUDIT_DIR。

五个阶段

为这些阶段创建一个 TaskList，让用户能看到进度。这是一项耗时较长的分析任务，根据样本量需要 20 到 60 分钟。

阶段 1——清点

python $SKILL_DIR/scripts/inventory.py --out $AUDIT_DIR/inventory.json

为每个会话编制目录：路径、项目、时间戳、大小、大致的消息数／轮数／工具数、令牌总数、版本和 Git 分支。开销低、结果确定。阅读脚本打印的摘要。

阶段 2——抽样

python $SKILL_DIR/scripts/sample.py --inventory $AUDIT_DIR/inventory.json --count 60 --days 60 --out $AUDIT_DIR/sample.json

按分层方式抽样，侧重近期会话，同时兼顾不同项目和会话规模。打印分布情况。用一句话告知用户样本概况（“60 个会话：40 个来自过去 2 周，20 个更早的会话；涵盖 X 个项目”），然后继续，除非用户提出异议。

阶段 3 — 提取

python $SKILL_DIR/scripts/extract.py --sample $AUDIT_DIR/sample.json --out $AUDIT_DIR/extracted/

针对每个抽样会话，写入一个 JSON，其中包含：用户提示词（真实提示词，不是命令包装）、助手的工具使用顺序、错误计数、技能／命令调用、令牌用量、近似实际耗时、首条提示词的意图、「纠正」标记（出现在工具调用失败之后或使用纠正措辞的用户消息），以及会话结果提示。

然后进行汇总：

python $SKILL_DIR/scripts/extract.py --aggregate $AUDIT_DIR/extracted/ --out $AUDIT_DIR/aggregate.json

现在你有了定量分析层。快速浏览一遍，标记任何意外发现——意外发现就是线索。

阶段 4 — 通过并行子 Agent 深入阅读

脚本无法捕捉定性信号：挫败、困惑、循环往复、突破时刻、心智模型不匹配。子 Agent 可以处理这些。

将样本拆分为每批 8–10 个会话。在单条消息中启动所有批次（并行，而非按顺序）。对于每批，启动一个 Explore 子 Agent，并提供 references/subagent_brief.md 中的说明，以及以下内容：

• 该批次中会话文件路径列表。
• $AUDIT_DIR/aggregate.json 的路径，供其了解全局情况。
• $SKILL_DIR/references/step_change_patterns.md 的路径，作为分析视角。
• 用户当前的技能目录（~/.claude/skills）、CLAUDE.md（~/.claude/CLAUDE.md）和 settings.json（~/.claude/settings.json），用于交叉参考。
• 告知它使用 python $SKILL_DIR/scripts/render.py <session-path> 获取易读的对话记录。使用 render.py 至关重要——原始 JSONL 会耗尽其上下文。

每个子 Agent 都会返回一份结构化 JSON，记录其发现。保存到 $AUDIT_DIR/batch-<N>-findings.json。

阶段 5 — 综合

这正是该技能名副其实的阶段。

1. 阅读每个批次的发现文件和汇总文件。
2. 对各批次的发现进行归类。一种模式只出现在一个会话中，是噪声；出现在八个会话中，才是信号。
3. 按频率 × 严重程度 × 修复杠杆效应为类别排序。杠杆效应 = 修复会影响多少个未来会话。只对某个小众工作流有帮助的修复没有杠杆效应；能消除每个编码会话中的阻碍的修复才有。
4. 将 references/step_change_patterns.md 作为筛选标准——每个优先级最高的类别属于边际微调，还是跨越式改进？如果只是边际改进，就把它提升为更大的改进（找出背后的原则），否则就舍弃。
5. 使用 references/report_template.md 撰写报告。
6. 起草修复方案。 每条最高优先级的建议都必须附有真正的草案，而不是对草案的描述。要新增技能？编写 SKILL.md。要新增规则？逐字写出段落。要新增钩子？编写脚本。要更改设置？展示差异。

不可妥协的要求

你必须起草修复方案。 如果你发现自己写着“用户可以考虑为 X 添加一项技能”，就停下来，直接编写这项技能。如果你写着“关于 Y 的 CLAUDE.md 规则会有所帮助”，就停下来，逐字写出确切的段落。这是此技能最重要的作用。跳过这一步，审计就毫无价值。

宁短勿全。 用户会采取行动的 3 项报告，胜过用户扫一眼便忘记的 30 项报告。删掉所有没有杠杆效应的内容。

用数字，不用形容词。“频繁”“经常”“有时”都是谎言。要说“60 个会话中有 17 个”或“样本中有 23 次纠正”。脚本会提供准确计数——请使用这些数字。

引用会话。 报告中的每条结论都必须列出作为证据的具体会话 ID。用户必须能够打开会话并验证这一模式。

审计 Claude，而不是用户。 如果用户反复纠正同一件事，说明 Claude 的默认行为不适合他们——而不是用户的问题。不要因为用户的提示方式而责备他们。找出迫使用户纠正的 Claude 行为模式，并将修复方案写入 Claude 的配置。

常见失败模式

• 观察结果堆砌。 列出 40 种模式，却没有优先级。改进方法：果断删减。
• 自我夸耀。 只描述 Claude 做得好的地方。改进方法：刻意寻找失败、挫折和原地打转的情况。
• 建议含糊。 “考虑改进 X。”改进方法：要么亲自起草改进方案，要么就别写进去。
• 项目视野狭窄。 只汇报最活跃的项目。改进方法：抽样时确保多样性，并在报告中体现。
• 忽略元层面。 只关注单次会话中的行为，遗漏跨会话模式（会话过早结束、每次都重新构建相同上下文等）。改进方法：references/step_change_patterns.md 明确列出了这些问题；综合分析前请重新阅读。

输出布局

$AUDIT_DIR/
  inventory.json            # stage 1
  sample.json               # stage 2
  extracted/<session>.json  # stage 3
  aggregate.json            # stage 3
  batch-<N>-findings.json   # stage 4
  report.md                 # stage 5 — the deliverable
  drafts/                   # stage 5 — the implementations
    skills/<skill-name>/SKILL.md
    claude-md-additions.md
    hooks/<hook-name>.sh
    settings-diff.json

除非用户另有指定，否则将 $AUDIT_DIR 默认设为 ~/claude-audit/<YYYY-MM-DD>/。所有内容都保留在磁盘上，方便用户重新运行、验证或分享。

参考文件

• references/session_format.md — JSONL 架构和字段含义
• references/step_change_patterns.md — 杠杆点分类；综合分析的视角
• references/report_template.md — 必需的输出结构
• references/subagent_brief.md — 传递给第 4 阶段子 Agent 的提示词