retrospective-codify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Retrospective Codify

经验固化回顾

Toward the end of a task, extract the insight of "if only I had known this first, I would not have taken detours" and pin it down as one of: a static rule, a skill, or an always-on rule. Prioritize landing it in a reproducible form that does not rely on prompts.

在任务接近尾声时，提炼出「要是一开始就知道这点，就不会走弯路了」的经验，并将其固化为以下形式之一：静态规则、Skill或长效规则。优先选择无需依赖提示的可复现形式。

When to use

适用场景

Right before task completion, or when the user says "leave the lesson behind" or "codify it"
When you arrived at the solution after trial and error (stuck on the first attempt, built a wrong hypothesis, burned time due to missing docs, etc.)
When you might perform a similar task again in the future

When not to use:

Simple tasks that passed on the first try (nothing to extract)
Project-specific one-off handling (a commit message is enough)

任务即将完成时，或用户提出「留下经验」、「固化经验」时
通过反复试错才找到解决方案时（首次尝试受阻、建立了错误假设、因缺少文档浪费时间等）
未来可能执行类似任务时

Workflow

不适用场景

Pair failure with success: From the current task, write out the following 3 points.
- The first attempt (what you did / how it failed)
- The final solution (what worked)
- The bridging insight (why the first attempt did not get there)
Verbalize "what you should have known first": Summarize the insight in 1-3 sentences. Write it not as retrospection but as an instruction to your future self (in imperative form: "do not do X" / "check Y first").
Classify: Decide the output destination following the decision table below.
Dedup check (mandatory): Before proposing, cross-check against existing knowledge. If a duplicate or nearby rule exists, choose "append to / update existing" rather than "add new." Skipping this step bloats skills / rules.
Extract 2-3 search keys from the insight (tool names, API names, symptom words, antonyms). Example: if the insight is "use pnpm v10," use
```
pnpm
```
,
```
packageManager
```
,
```
lockfile
```
.
Match targets and minimum searches:
```
# 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/
```
Classify the result into 4 tiers:
- New: no hits -> normal proposal
- Append to existing: a related skill/rule exists and the new info is complementary -> propose "append to existing"
  - "Partial overlap" (part of the insight is covered by the existing one, rest is new) also falls in this tier. Write the overlapping part under "Duplicate detected," and the new part under "Adoption candidates" (
```
[skill append]
```
    or
```
[rule]
```
    ) separately.
- Duplicate with existing (no proposal needed): the existing entry already fully covers the same insight -> zero proposals, but keep the "Duplicate detected" line in the presentation format (for auditability). Attach the existing skill name + the relevant section name (or line number) as evidence on the Duplicate detected line.
- Undecidable: the agent cannot tell whether it is a duplicate -> show the match result to the user and ask for judgment
Write out: Generate the artifact following the template (below) for the chosen format.
Confirm: Show the diff to the user and get approval. If rejected, keep it as a session note instead of a skill.

首次尝试就成功的简单任务（无经验可提炼）
项目特定的一次性处理（提交信息已足够）

Classification decision

工作流程

dot

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"];
}

Decision axis	Output destination	Example
Detectable at the code/config syntax level	`ast-grep` rule or existing linter config	"Do not use `Array.from(set).length` , use `set.size` "
Short, always-applied, no judgment involved	`CLAUDE.md` (user global / project)	"Use pnpm v10 or later"
Requires procedure, contextual judgment, or templates	New skill or append to existing skill	"Steps to write a C binding for MoonBit"
Project-specific and one-off	Do not adopt (keep in commit message / PR description)	—

Principle: prefer ast-grep: For things that are statically detectable, do not write them in prompts or docs; always make them an

ast-grep

rule (as the user's global rule).

CLAUDE.md write destinations:

Cross-language / cross-tool general rules ->
```
~/.claude/CLAUDE.md
```
Limited to a specific repository -> that repository's
```
CLAUDE.md
```

失败与成功配对：从当前任务中，写出以下三点。
- 首次尝试（你做了什么/如何失败）
- 最终解决方案（有效的做法）
- 核心经验（首次尝试失败的原因）
明确「本该提前知道的内容」：用1-3句话总结经验。不要以回顾的语气写，而是以命令式语气写给未来的自己：「不要做X」/「先检查Y」。
分类：根据下方决策表确定输出目标。
去重检查（必填）：在提出方案前，对照现有知识进行交叉检查。如果存在重复或类似规则，选择「追加到现有内容/更新现有内容」而非「新增」。跳过此步骤会导致Skill/规则冗余。
从经验中提取2-3个搜索关键词（工具名称、API名称、症状词、反义词）。示例：如果经验是「使用pnpm v10」，则使用
```
pnpm
```
、
```
packageManager
```
、
```
lockfile
```
作为关键词。
匹配目标与最低搜索要求：
```
# skill重复检查（全局）
ls ~/.claude/skills/
Grep "<key>" ~/.claude/skills/*/SKILL.md

# CLAUDE.md重复检查
Grep "<key>" ~/.claude/CLAUDE.md
Grep "<key>" <project-root>/CLAUDE.md   # 如果有匹配的项目

# lint规则重复检查
ls <project-root>/rules/
Grep "<key>" <project-root>/rules/
```
将结果分为四个层级：
- 新增：无匹配结果 -> 正常提出方案
- 追加到现有内容：存在相关Skill/规则，且新信息具有补充性 -> 提出「追加到现有内容」
  - 「部分重叠」（经验的部分内容已被现有规则覆盖，其余为新内容）也属于此层级。在「检测到重复」下写出重叠部分，在「待采纳候选」（
```
[skill append]
```
    或
```
[rule]
```
    ）下单独写出新内容。
- 与现有内容重复（无需提出方案）：现有条目已完全覆盖相同经验 -> 不提出方案，但需在展示格式中保留「检测到重复」行（用于可审计性）。在该行附上现有Skill名称 + 相关章节名称（或行号）作为证据。
- 无法判定：Agent无法判断是否重复 -> 将匹配结果展示给用户并请求判断
生成内容：根据所选格式，按照下方模板生成产物。
确认：向用户展示差异并获得批准。如果被拒绝，则将其作为会话笔记而非Skill保存。

Output templates

分类决策

ast-grep rule

—

See the

ast-grep-practice

skill. Add YAML under the

rules/

directory and always write a valid / invalid pair under

rule-tests/

dot

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` 规则或现有linter配置	「不要使用 `Array.from(set).length` ，请使用 `set.size` 」
简短、需始终遵循、无需判断	`CLAUDE.md` （用户全局/项目级）	「使用pnpm v10或更高版本」
需要流程、上下文判断或模板	新增Skill或追加到现有Skill	「为MoonBit编写C语言绑定的步骤」
项目特定的一次性内容	不采纳（保留在提交信息/PR描述中）	—

原则：优先选择ast-grep：对于可静态检测的内容，不要写在提示或文档中；始终将其设为

ast-grep

规则（作为用户的全局规则）。

CLAUDE.md写入目标：

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

Append to CLAUDE.md

输出模板

—

ast-grep规则

markdown

undefined

参考

ast-grep-practice

Skill。在

rules/

目录下添加YAML文件，并始终在

rule-tests/

下编写有效/无效用例对。

<append to existing section>

追加到CLAUDE.md

<one imperative sentence> (reason: <short rationale>)

Always attach the reason in parentheses (so that your future self can judge edge cases).

markdown

undefined

New skill

<追加到现有章节>

Follow the minimal template from

writing-skills

(superpowers):

markdown

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

<一句命令式语句> (理由：<简短说明>)

始终在括号中附上理由（以便未来的你能判断边缘情况）。

<Title>

新增Skill

Purpose

—

When to use

—

Workflow

—

Pitfalls

—

undefined

遵循

writing-skills

（超能力）的最小模板：

markdown

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

Concrete examples

<Title>

Example 1: Codify as an ast-grep rule (mechanically detectable)

Purpose

—

When to use

—

Workflow

—

Pitfalls

First attempt: In TypeScript, retrieved a set's size with
```
Array.from(set).length
```
, but review pointed out this is inefficient.
Final solution: Use
```
set.size
```
.
Insight: For
```
Set
```
/
```
Map
```
size, use the
```
.size
```
property.
```
Array.from(...).length
```
is detectable at the syntax level.

-> Add

rules/no-array-from-size.yml

yaml

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

undefined

Example 2: Codify as a CLAUDE.md rule (short always-on rule)

具体示例

—

示例1：固化为ast-grep规则（可机械检测）

First attempt: Ran
```
pnpm install
```
and CI broke due to a lockfile format diff.
Final solution: Aligned pnpm's version to the v10 line.
Insight: pnpm changes its lockfile across versions. Always use v10 or later.

-> Append to the "ツール" section of

~/.claude/CLAUDE.md

markdown

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

首次尝试：在TypeScript中，使用
```
Array.from(set).length
```
获取集合的大小，但代码评审指出这种方式效率低下。
最终解决方案：使用
```
set.size
```
。
经验：对于
```
Set
```
/
```
Map
```
的大小，使用
```
.size
```
属性。
```
Array.from(...).length
```
可通过语法层面检测。

-> 添加

rules/no-array-from-size.yml

yaml

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

Example 3: Codify as a new skill (procedure + judgment involved)

示例2：固化为CLAUDE.md规则（简短长效规则）

First attempt: To call a C library from MoonBit, tried several approaches and got stuck on the placement of FFI declarations and stubs.
Final solution: The combination of an
```
extern "c"
```
declaration + a stub using
```
moonbit.h
```
+
```
native-stub
```
/
```
link.native
```
settings in
```
moon.pkg.json
```
.
Insight: It does not fit in a single step; you need to understand the three layers — declaration, stub, and build config — together.

-> Carve out the procedure and templates as a new skill

moonbit-c-binding

(since it already exists, this example is the case of choosing "append to existing" via the dedup check).

首次尝试：运行
```
pnpm install
```
后，CI因锁文件格式差异失败。
最终解决方案：将pnpm版本统一到v10系列。
经验：pnpm不同版本的锁文件格式不同。请始终使用v10或更高版本。

-> 追加到

~/.claude/CLAUDE.md

的「ツール」章节：

markdown

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

Red flags (watch out for rationalizations)

示例3：固化为新Skill（涉及流程+判断）

Stop once if the following thoughts appear.

Rationalization that surfaces	Reality
"It is project-specific but let's make a skill just in case"	Skills bloat and searchability drops. A commit message / PR is enough.
"Skip approval and write it out first; I can show it later"	Modifying CLAUDE.md / skills on your own makes future behavior unpredictable. Always: propose -> approve -> write out.
"I kind of could write it in ast-grep, but writing it in natural language as a rule is faster"	Writing statically detectable things in prose means agents do not follow them. Prefer ast-grep.
"The insight is thin, but I have to write something to save face"	Zero proposals is also a correct answer. An empty retrospective causes no harm.
"Dedup checks are tedious; skip them, erase duplicates later"	If duplicate rules remain, behavior splits. Dedup is a mandatory step.
"Omit the failure side and only write the final solution"	Without describing the failure, your future self will fall into the same pitfall again.

首次尝试：要从MoonBit调用C语言库，尝试了多种方法，但在FFI声明和存根的放置上受阻。
最终解决方案：结合
```
extern "c"
```
声明 + 使用
```
moonbit.h
```
的存根 +
```
moon.pkg.json
```
中的
```
native-stub
```
/
```
link.native
```
设置。
经验：这无法通过单一步骤完成；你需要同时理解三个层面——声明、存根和构建配置。

-> 将流程和模板提炼为新Skill

moonbit-c-binding

（由于该Skill已存在，本示例属于通过去重检查选择「追加到现有内容」的情况）。

Presentation format to the user

警示信号（注意自我合理化）

At the end of a task, present the stock-taking in the following form. Multiple lessons are fine. Explicitly list duplicates and non-adoptions too, to leave a trace of the judgment.

undefined

如果出现以下想法，请立即停止。

出现的自我合理化想法	实际情况
「这是项目特定内容，但以防万一还是做成Skill吧」	Skill会变得冗余，搜索效率下降。提交信息/PR描述已足够。
「跳过批准直接写入，之后再展示给用户」	擅自修改CLAUDE.md/Skill会导致未来行为不可预测。请始终遵循：提出方案 -> 获得批准 -> 写入内容的顺序。
「我可以用ast-grep实现，但用自然语言写成规则更快」	将可静态检测的内容写成自然语言会导致Agent无法遵循。优先选择ast-grep。
「经验很单薄，但为了面子还是得写点什么」	不提出任何方案也是正确的选择。空的回顾不会造成危害。
「去重检查太繁琐，先跳过，之后再删除重复内容」	如果保留重复规则，行为会出现分歧。去重是必填步骤。
「省略失败部分，只写最终解决方案」	不描述失败情况，未来的你会再次落入同样的陷阱。

Retrospective

向用户展示的格式

Lesson 1: <short label>

—

First failure: <1 line>
Final solution: <1 line>
Insight: <1 line>

在任务结束时，按照以下形式呈现总结内容。可以有多条经验。请明确列出重复项和未采纳项，留下判断痕迹。

undefined

Lesson 2: <short label> # omit this block if there is only 1 lesson

回顾

—

经验1：<简短标签>

First failure: <1 line>
Final solution: <1 line>
Insight: <1 line>

首次失败：<1行>
最终解决方案：<1行>
经验：<1行>

Proposals

经验2：<简短标签> # 如果只有1条经验，省略此块

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.


**Format rules:**
- If there is only 1 lesson, omit the `### Lesson N` heading and write only one Retrospective block
- If any of "Adoption candidates," "Duplicate detected," or "Not adopted" is empty, omit the whole section (do not write a "none" line)
- Always end each proposal line with "from lesson N" (if it spans multiple lessons, you may enumerate as "from lessons 1, 3")
- When "Adoption candidates" is empty and only "Duplicate detected" remains, replace the closing sentence from `Please indicate which to adopt` with `No adoption candidates. Please review for the record.`
- Write out only items the user instructs you to adopt. Do not write silently.

首次失败：<1行>
最终解决方案：<1行>
经验：<1行>

Presentation example: all lessons already covered (Duplicate detected only)

方案建议

undefined

待采纳候选：

[lint] <规则名称>: <1行> (产物：<路径>，来自经验N)
[skill append] <现有Skill名称>: <1行> (来自经验N)
[skill new] <Skill名称>: <1行> (来自经验N)
[rule] CLAUDE.md (全局/项目级): <1行> (来自经验N)

检测到重复（无需提出方案）：

<经验N>: 已完全被现有<Skill/规则名称>的<章节名称或行号>覆盖 -> 无需新增

未采纳：

<经验N>: <一行未采纳理由>（例如：项目特定内容 / 难以跨文件用lint表达 / 已被其他经验覆盖）

请通过编号或项目名称指出要采纳的内容。不提出任何方案也是有效的结论。


**格式规则：**
- 如果只有1条经验，省略`### 经验N`标题，只写一个回顾块
- 如果「待采纳候选」、「检测到重复」或「未采纳」中的任何一个为空，省略整个章节（不要写「无」）
- 每条方案建议行末尾必须写上「来自经验N」（如果涉及多条经验，可以列举为「来自经验1、3」）
- 当「待采纳候选」为空且只有「检测到重复」时，将结尾句子从「请指出要采纳的内容」替换为「无待采纳候选。请审阅备案。」
- 仅写入用户指示采纳的内容。不要擅自写入。

Retrospective

展示示例：所有经验已被覆盖（仅检测到重复）

Lesson 1: <label>

—

First failure: ...
Final solution: ...
Insight: ...

undefined

Proposals

回顾

—

经验1：<标签>

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.

undefined

首次失败：...
最终解决方案：...
经验：...

Presentation example: partial overlap (append to existing + Duplicate detected)

方案建议

undefined

检测到重复（无需提出方案）：

经验1：已完全被现有Skill <Skill名称>的<章节名称>覆盖 -> 无需新增

无待采纳候选。请审阅备案。

undefined

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

undefined

undefined

Common failures

方案建议

Granularity too fine: codifying the one-off specifics (a specific function name, a specific version) -> abstract it up to the level of "what to check"
Tends to be written as a prompt: writing a statically detectable rule in natural language in CLAUDE.md -> move it to an
```
ast-grep
```
rule
Does not write the reason: the rule's rationale is not left behind, and the future self cannot judge why to follow it -> always attach a
```
Why:
```
Writes out on its own: updates CLAUDE.md or skills without user approval -> always follow propose -> approve -> write out in that order
Omits verbalizing the failure: writes only "the final solution is X" and does not leave why the first move got stuck -> without a description on the failure side, your future self will fall into the same pitfall again

待采纳候选：

[skill append] <现有Skill名称>: <一行新增内容> (来自经验1，补充现有<章节名称>部分)

检测到重复（无需提出方案）：

经验1（版本值部分）：已被
```
~/.claude/CLAUDE.md
```
的工具章节覆盖 -> 无需追加

undefined

Related skills

常见错误

```
superpowers:writing-skills
```
— template and TDD flow for writing a new skill
```
ast-grep-practice
```
— how to write and test when codifying as a lint rule
```
update-config
```
— when changes to settings.json / permissions are required

粒度太细：固化一次性的具体细节（特定函数名、特定版本）-> 抽象到「需要检查什么」的层面
倾向于写成提示：将可静态检测的规则用自然语言写在CLAUDE.md中 -> 转移到ast-grep规则
未写入理由：未留下规则的依据，未来的你无法判断为何要遵循该规则 -> 始终附上「理由：」
擅自写入：未获得用户批准就更新CLAUDE.md或Skill -> 始终遵循提出方案 -> 获得批准 -> 写入内容的顺序
省略失败描述：只写「最终解决方案是X」，未说明首次尝试为何受阻 -> 没有失败描述，未来的你会再次落入同样的陷阱

—

retrospective-codify

Original

Translation

Retrospective Codify

经验固化回顾

When to use

适用场景

Workflow

不适用场景

Classification decision

工作流程

Output templates

分类决策

ast-grep rule

Append to CLAUDE.md

输出模板

ast-grep规则

<append to existing section>

追加到CLAUDE.md

New skill

<追加到现有章节>

<Title>

新增Skill

Purpose

When to use

Workflow

Pitfalls

Concrete examples

<Title>

Example 1: Codify as an ast-grep rule (mechanically detectable)

Purpose

When to use

Workflow

Pitfalls

Example 2: Codify as a CLAUDE.md rule (short always-on rule)

具体示例

示例1：固化为ast-grep规则（可机械检测）

Example 3: Codify as a new skill (procedure + judgment involved)

示例2：固化为CLAUDE.md规则（简短长效规则）

Red flags (watch out for rationalizations)

示例3：固化为新Skill（涉及流程+判断）

Presentation format to the user

警示信号（注意自我合理化）

Retrospective

向用户展示的格式

Lesson 1: <short label>

Lesson 2: <short label> # omit this block if there is only 1 lesson

回顾

经验1：<简短标签>

Proposals

经验2：<简短标签> # 如果只有1条经验，省略此块

Presentation example: all lessons already covered (Duplicate detected only)

方案建议

Retrospective

展示示例：所有经验已被覆盖（仅检测到重复）

Lesson 1: <label>

Proposals

回顾

经验1：<标签>

Presentation example: partial overlap (append to existing + Duplicate detected)

方案建议

Proposals

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

Common failures

方案建议

Related skills

常见错误

相关Skill