retrospective-codify

复盘编码

在任务即将结束时，提炼出“要是我一开始就知道这点，就不会走弯路”的经验，并将其固化为以下形式之一：静态规则、技能或始终生效的规则。优先将其落实为可复现的形式，避免依赖提示词。

适用时机

• 在任务即将完成时，或用户说“留下经验”或“把它固化下来”时
• 通过反复试错才找到解决方案时（第一次尝试就卡住、提出了错误的假设、因缺少文档而浪费时间等）
• 未来可能再次执行类似任务时

不适用的情况：

• 一次就顺利完成的简单任务（无经验可提炼）
• 仅适用于特定项目的一次性处理（写在提交信息中即可）

工作流

1. 将失败与成功配对：针对当前任务，写出以下 3 点。

   • 第一次尝试（做了什么／失败原因）
   • 最终解决方案（什么方法奏效）
   • 过渡洞见（为什么第一次尝试没能成功）

2. 明确“应该事先知道的事”：用 1–3 句话总结经验。不要写成回顾，而要写成给未来自己的指令（使用祈使句：“不要做 X”／“先检查 Y”）。

3. 分类：根据下方的决策表决定输出位置。

4. 去重检查（必须）：提出方案前，先对照现有知识。如果已有重复或相近规则，应选择“追加到／更新现有规则”，而不是“新增”。跳过此步骤会导致技能／规则越来越臃肿。

   从经验中提取 2–3 个搜索关键词（工具名称、API 名称、症状词、反义词）。例如，若经验是“使用 pnpm v10”，可搜索 pnpm、packageManager、lockfile。

   搜索目标和最低搜索次数：

   # skill duplicates (global)
   ls ~/.claude/skills/
   Grep "<key>" ~/.claude/skills/*/SKILL.md
   
   # CLAUDE.md duplicates
   Grep "<key>" ~/.claude/CLAUDE.md
   Grep "<key>" <project-root>/CLAUDE.md   # if there is a matching project
   
   # lint rule duplicates
   ls <project-root>/rules/
   Grep "<key>" <project-root>/rules/
   

   将结果分为 4 类：

   • 全新：无匹配结果 -> 正常提出方案
   • 追加到现有条目：存在相关技能／规则，且新信息具有补充性 -> 提出“追加到现有条目”
     • 部分重叠（经验的一部分已被现有条目涵盖，其余是新内容）也属于此类。将重叠部分写在“检测到重复”下，将新内容单独写在“可采纳项”下（[skill append] 或 [rule]）。
   • 与现有内容重复（无需提出方案）：现有条目已完整涵盖相同经验 -> 不提出任何方案，但在展示格式中保留“检测到重复”一行（便于审计）。在“检测到重复”一行中附上现有技能名称和相关章节名称（或行号）作为证据。
   • 无法判定：Agent 无法判断是否重复 -> 向用户展示匹配结果并征求判断

5. 编写：按所选格式使用下方模板生成产物。

6. 确认：向用户展示差异并征求批准。如果被拒绝，则将其保留为会话笔记，而不是技能。

分类决策

digraph classify {
    "Mechanically detectable?" [shape=diamond];
    "Short instruction to apply every time?" [shape=diamond];
    "Involves multi-step procedure or judgment?" [shape=diamond];
    "ast-grep rule / lint" [shape=box];
    "CLAUDE.md rule" [shape=box];
    "skill" [shape=box];
    "keep as note" [shape=box];

    "Mechanically detectable?" -> "ast-grep rule / lint" [label="yes"];
    "Mechanically detectable?" -> "Short instruction to apply every time?" [label="no"];
    "Short instruction to apply every time?" -> "CLAUDE.md rule" [label="yes"];
    "Short instruction to apply every time?" -> "Involves multi-step procedure or judgment?" [label="no"];
    "Involves multi-step procedure or judgment?" -> "skill" [label="yes"];
    "Involves multi-step procedure or judgment?" -> "keep as note" [label="no"];
}

决策维度	输出位置	示例
可在代码／配置语法层面检测	ast-grep 规则或现有代码检查器配置	“不要使用 Array.from(set).length，改用 set.size”
简短、始终适用且无需判断	CLAUDE.md（用户全局／项目）	“使用 pnpm v10 或更高版本”
需要流程、情境判断或模板	新建技能或追加到现有技能	“为 MoonBit 编写 C 绑定的步骤”
特定项目的一次性事项	不采纳（保留在提交信息／PR 描述中）	—

原则：优先使用 ast-grep：对于可通过静态方式检测的内容，不要写入提示词或文档；始终将其设为 ast-grep 规则（作为用户的全局规则）。

CLAUDE.md 写入位置：

• 跨语言／跨工具的通用规则 -> ~/.claude/CLAUDE.md
• 仅适用于特定仓库的规则 -> 该仓库的 CLAUDE.md

输出模板

ast-grep 规则

查看 ast-grep-practice 技能。在 rules/ 目录下添加 YAML，并始终在 rule-tests/ 下编写一对有效 / 无效示例。

追加到 CLAUDE.md

# <append to existing section>
- <one imperative sentence> (reason: <short rationale>)

始终在括号中附上原因（这样未来的自己就能判断边缘情况）。

新技能

按照 writing-skills（superpowers）中的最简模板：

---
name: <kebab-case>
description: Use when <specific situation> / <symptom>
---

# <Title>

## Purpose
## When to use
## Workflow
## Pitfalls

具体示例

示例 1：编写 ast-grep 规则（可通过机械方式检测）

• 初次尝试：在 TypeScript 中，用 Array.from(set).length 获取集合的大小，但审查指出这种方式效率低下。
• 最终方案：使用 set.size。
• 经验：获取 Set / Map 的大小时，使用 .size 属性。Array.from(...).length 可以在语法层面检测出来。

-> 添加 rules/no-array-from-size.yml：

id: no-array-from-size
language: TypeScript
severity: warning
rule:
  pattern: Array.from($COLL).length
message: Set/Map のサイズは .size プロパティを使う。

示例 2：编写 CLAUDE.md 规则（简短、始终生效的规则）

• 初次尝试：运行 pnpm install，CI 因 lockfile 格式差异而失败。
• 最终方案：将 pnpm 版本与 v10 系列保持一致。
• 经验：pnpm 会因版本不同而更改 lockfile。始终使用 v10 或更高版本。

-> 追加到 ~/.claude/CLAUDE.md 的“ツール”部分：

- pnpm は v10 以上を使う（理由: lockfile 形式が v9 以前と非互換で CI 差分が出る）

示例 3：编写新技能（涉及流程与判断）

• 初次尝试：为了从 MoonBit 调用 C 库，尝试了几种方法，却始终无法确定 FFI 声明和桩代码的位置。
• 最终方案：结合使用 extern "c" 声明、使用 moonbit.h 的桩代码，以及在 moon.pkg.json 中设置 native-stub / link.native。
• 经验：这无法用单一步骤解决；需要一并理解三个层面——声明、桩代码和构建配置。

-> 将流程和模板提炼为新技能 moonbit-c-binding（由于该技能已经存在，此示例应在去重检查后选择“追加到现有技能”）。

危险信号（警惕自我合理化）

如果出现以下想法，请停下来。

出现的自我合理化	实际情况
“这是项目特有的，但还是先做成技能以防万一吧”	技能会变得臃肿，也更难搜索。提交消息 / PR 就足够了。
“先跳过审批写出来，之后再给人看”	擅自修改 CLAUDE.md / 技能会让未来的行为变得难以预测。务必遵循：提出 -> 批准 -> 编写。
“好像可以用 ast-grep 写，但用自然语言写成规则更快”	用散文描述可静态检测的内容，会导致 Agent 不遵循。优先使用 ast-grep。
“经验不够深刻，但为了面子还是得写点什么”	不提出任何建议也是正确的答案。空的回顾不会造成伤害。
“去重检查很麻烦，跳过吧，之后再删重复项”	如果重复规则仍然存在，行为就会分化。去重是必经步骤。
“省略失败过程，只写最终方案”	不描述失败过程，未来的自己就会再次掉进同一个坑。

面向用户的呈现格式

任务结束时，按以下格式汇报总结。可以有多条经验。还应明确列出重复项和未采纳项，留下判断记录。

## Retrospective

### Lesson 1: <short label>
- First failure: <1 line>
- Final solution: <1 line>
- Insight: <1 line>

### Lesson 2: <short label>      # omit this block if there is only 1 lesson
- First failure: <1 line>
- Final solution: <1 line>
- Insight: <1 line>

## Proposals

Adoption candidates:
- [lint] <rule name>: <1 line> (artifact: <path>, from lesson N)
- [skill append] <existing skill name>: <1 line> (from lesson N)
- [skill new] <skill name>: <1 line> (from lesson N)
- [rule] CLAUDE.md (global/project): <1 line> (from lesson N)

Duplicate detected (no proposal needed):
- <lesson N>: fully covered by <section name or line number> of existing <skill/rule name> -> no addition

Not adopted:
- <lesson N>: <one-line reason for non-adoption> (e.g. project-specific / hard to express in lint across files / absorbed by another lesson)

Please indicate which to adopt by number or item name. Zero proposals is also a valid conclusion.

格式规则：

• 如果只有 1 条经验，省略 ### Lesson N 标题，只写一个 Retrospective 块
• 如果“Adoption candidates”、“Duplicate detected”或“Not adopted”任一部分为空，则省略整个部分（不要写“无”）
• 每条建议都必须以“from lesson N”结尾（如涉及多条经验，可以写成“from lessons 1, 3”）
• 当“Adoption candidates”为空且只剩下“Duplicate detected”时，将结尾句从 Please indicate which to adopt 替换为 No adoption candidates. Please review for the record.
• 仅编写用户指示采纳的项目。不得在未告知用户的情况下编写。

呈现示例：所有经验均已涵盖（仅有 Duplicate detected）

## Retrospective

### Lesson 1: <label>
- First failure: ...
- Final solution: ...
- Insight: ...

## Proposals

Duplicate detected (no proposal needed):
- Lesson 1: fully covered by `<section name>` of existing skill `<skill name>` -> no addition

No adoption candidates. Please review for the record.

示例：部分重叠（追加到现有内容 + 检测到重复）

## Proposals

Adoption candidates:
- [skill append] <existing skill name>: <1 line for the new portion> (from lesson 1, complements existing section `<section name>`)

Duplicate detected (no proposal needed):
- Lesson 1 (version value portion): already covered by the tools section in `~/.claude/CLAUDE.md` -> no append needed

常见问题

• 粒度太细：将一次性的具体细节（特定函数名、特定版本）写成规范 → 提升抽象层次，概括为“需要检查什么”
• 容易写成提示词：在 CLAUDE.md 中用自然语言写静态可检测的规则 → 将其改为 ast-grep 规则
• 没有写明原因：没有留下规则的理由，未来的自己也无法判断为什么要遵循它 → 始终附上 Why:
• 擅自写入：未经用户批准就更新 CLAUDE.md 或技能 → 始终按提议 → 批准 → 写入的顺序执行
• 没有说明失败原因：只写“最终解决方案是 X”，却不说明最初的做法为何行不通 → 如果不描述失败的一面，未来的自己就会再次掉进同一个陷阱

相关技能

• superpowers:writing-skills — 编写新技能的模板和 TDD 流程
• ast-grep-practice — 将规则写成 lint 规则时的编写和测试方法
• update-config — 需要更改 settings.json / permissions 时使用