reflect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reflect — session retrospective

回顾 — 会话复盘

A structured self-audit after a non-trivial session: what friction did the current

.claude/

setup cause? What should be added, changed, or removed?

针对非简单会话的结构化自我审计：当前

.claude/

配置引发了哪些摩擦？应该添加、修改或移除哪些内容？

Before You Start

开始前准备

```
CLAUDE.md
```
— the ambient project context. Read it alongside this session's transcript.
```
.claude/skills/
```
— scan every active skill's description.
```
.claude/hooks/
```
and
```
.claude/settings.json
```
— see what's wired.
```
principles/
```
— the seven principles are the benchmark for any proposed change.

```
CLAUDE.md
```
— 项目环境上下文。请结合本次会话的记录阅读此文件。
```
.claude/skills/
```
— 查看每个活跃技能的描述。
```
.claude/hooks/
```
和
```
.claude/settings.json
```
— 了解已配置的内容。
```
principles/
```
— 七大原则是所有拟议变更的基准。

Step 1: collect evidence

步骤1：收集证据

Scan the session for friction signals:

User corrections — "no, not that", "don't do X", "stop doing Y" indicate either misleading guidance or a missing rule.
User confirmations on non-obvious choices — "yes, exactly", "that's the right call" validate a non-obvious pattern worth encoding.
Places the agent searched for a file repeatedly — missing directory landmark in
```
CLAUDE.md
```
.
Places the agent proposed an approach then had to back out — missing convention.
Hook blocked work in a frustrating way — hook's message was not actionable.
Skills that triggered when they shouldn't have — description is too broad.

扫描会话内容，寻找摩擦信号：

用户修正 — "不，不是那样"、"不要做X"、"停止做Y"表明指南存在误导或缺少相关规则。
用户对非显而易见选择的确认 — "对，正是如此"、"这个选择是对的"验证了某个值得编码的非显而易见模式。
Agent重复搜索同一文件的场景 —
```
CLAUDE.md
```
中缺少目录标记。
Agent提出方案后又撤回的场景 — 缺少约定规范。
Hook以令人沮丧的方式阻碍工作 — Hook的提示不具备可操作性。
技能在不应触发时被触发 — 技能描述范围过宽。

Step 2: classify findings

步骤2：分类发现

For each signal, put it into a category:

Category	What to do
Hidden invariant or gotcha the agent didn't know	Add to `CLAUDE.md` under Things to Know
Repeated multi-step workflow that isn't yet a skill	Candidate for a new skill (use `create-or-audit-skill` )
Rule that a linter/formatter should enforce	Wire a hook; don't add prose
Skill that fired wrongly / too often	Tighten the description's "Do NOT use for" clause
Rule in `CLAUDE.md` that contradicts current behavior	Update or remove — stale guidance is worse than none
Generic phrase that sneaked in	Remove it. The `create-or-audit-claude-md` skill's validator catches the common ones.

将每个信号归入对应类别：

类别	处理方式
Agent未知的隐藏约束或陷阱	在 `CLAUDE.md` 的须知事项部分添加相关内容
重复出现的多步骤工作流，尚未封装为技能	可作为新技能的候选（使用 `create-or-audit-skill` ）
应由代码检查/格式化工具强制执行的规则	配置Hook；无需添加文字说明
错误触发/过于频繁触发的技能	收紧技能描述中的"请勿用于"条款
`CLAUDE.md` 中与当前行为矛盾的规则	更新或移除——过时指南比没有指南更糟
混入的通用表述	删除此类内容。 `create-or-audit-claude-md` 技能的验证器会识别常见的通用表述。

Step 3: propose changes

步骤3：提出变更建议

Write one concrete change per finding. Example shape:

markdown

undefined

针对每个发现，撰写一条具体的变更建议。示例格式：

markdown

undefined

Finding: agent created service classes inconsistently

发现：Agent创建服务类的方式不一致

Evidence: 2 instances in this session —

src/users/service.ts

got a

ServiceBase

extension,

src/orders/service.ts

did not.

Classification: hidden invariant — the codebase uses

ServiceBase

consistently, but it's not documented.

Proposed change: add to

CLAUDE.md

under "Patterns and Conventions":

New services extend

ServiceBase

(

src/lib/service-base.ts

), which provides logging and error wrapping. See

src/users/service.ts

for the canonical example.

undefined

证据： 本次会话中出现2次此类情况 —

src/users/service.ts

继承了

ServiceBase

，

src/orders/service.ts

却没有。

分类： 隐藏约束——代码库统一使用

ServiceBase

，但未形成文档。

拟议变更： 在

CLAUDE.md

的"模式与约定"部分添加：

新服务需继承

ServiceBase

（

src/lib/service-base.ts

），该类提供日志记录和错误封装功能。可参考

src/users/service.ts

中的标准示例。

undefined

Step 4: apply with user confirmation

步骤4：经用户确认后执行

Never edit

CLAUDE.md

or skills without the user's say-so. Present all proposed changes as a single list; the user approves or rejects each. Apply only what's approved.

未经用户许可，不得编辑

CLAUDE.md

或技能。将所有拟议变更整理为单个列表呈现，由用户逐一批准或拒绝。仅执行获批准的变更。

Step 5: re-validate

步骤5：重新验证

For every file touched, re-run the artifact-specific audit skill so the mechanical gates pass:

Changed
```
CLAUDE.md
```
→ run
```
create-or-audit-claude-md
```
(Mode 2)
Changed
```
SKILL.md
```
→ run
```
create-or-audit-skill
```
(Mode 2)
Changed
```
*.sh
```
hook → run
```
create-or-audit-hook
```
(Mode 2)

A validator regression after reflection means the reflection made things worse — fix before declaring done.

对于每一个被修改的文件，重新运行对应工件的审计技能，确保通过机械验证：

修改了
```
CLAUDE.md
```
→ 运行
```
create-or-audit-claude-md
```
（模式2）
修改了
```
SKILL.md
```
→ 运行
```
create-or-audit-skill
```
（模式2）
修改了
```
*.sh
```
Hook → 运行
```
create-or-audit-hook
```
（模式2）

若复盘后验证器出现回归问题，说明复盘带来了负面影响——需修复后再宣告完成。

Verify

验证确认

For each artifact you changed, the corresponding

create-or-audit-*

skill's Mode 2 audit reports

VERDICT: PASS

. If anything regressed, the reflection has not landed cleanly.

对于每一个被修改的工件，对应的

create-or-audit-*

技能的模式2审计需返回

VERDICT: PASS

。若出现任何回归问题，说明复盘未顺利完成。

Common Mistakes

常见错误

Mistake	Correction
Turning one-off friction into a permanent rule	Reflect asks "would this happen again?" — one incident isn't a pattern. Usually two instances before codifying.
Adding a rule without deleting the stale one it contradicts	Replace, don't append. `CLAUDE.md` contradictions compound into unusable guidance.
Editing files without showing the user	Always propose; user approves. Reflection is collaborative, not autonomous.
Skipping the validator re-run	Principle 01 is evidence-based — if the validator now fails, the reflection made things worse.

错误	修正方式
将一次性摩擦转化为永久规则	复盘时需思考"这种情况会再次发生吗？"——单次事件不构成模式。通常需出现两次实例后再进行编码固化。
添加新规则但未删除与之矛盾的过时规则	替换而非追加。 `CLAUDE.md` 中的矛盾内容会导致指南完全无法使用。
未向用户展示就直接编辑文件	始终先提出建议；由用户批准。复盘是协作过程，而非自主操作。
跳过验证器重新运行步骤	原则01是基于证据的——若验证器现在失败，说明复盘带来了负面影响。