# Retrospect Session

> 基于当前会话进行复盘，提炼可复用教训并沉淀到 docs/rules/，并同步更新项目级 AGENTS.md / CLAUDE.md 的规则索引与说明。当用户提到“反思”“复盘”“沉淀规则”“lessons learned”“把经验写进规则”时都应触发。

- Skill: `vamdawn/retrospect-session` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add vamdawn/retrospect-session`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vamdawn/retrospect-session/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vamdawn (https://skillmd.com/u/vamdawn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vamdawn/retrospect-session

---


# Retrospect Session

## Overview

将会话经验沉淀为长期可执行规则，统一维护在 `docs/rules/`，并让项目级提示词始终引用最新规则。

## Goals

1. 从当前会话中提炼“可迁移、可执行”的教训。
2. 合并并反思 `docs/rules/` 既有内容，而不是只追加新条目。
3. 更新（或创建）项目级提示词 `AGENTS.md` 与 `CLAUDE.md`，建立 `docs/rules/*.md` 引用并说明规则范围。
4. 按最佳实践规范规则文档格式，控制规模，保证可执行性与可维护性。

## Mandatory Outcomes

1. 本技能完成时，必须同时检查并同步：
   - `docs/rules/*.md`
   - `AGENTS.md`
   - `CLAUDE.md`
2. 若 `AGENTS.md` 或 `CLAUDE.md` 不存在，必须创建最小可用版本（见下方模板）。
3. 若发现新增规则文件未被项目级提示词引用，必须补齐引用与一句话摘要。
4. 不允许只更新 `docs/rules/` 而跳过项目级提示词同步。

## Operating Modes

### Incremental Update

- 仅在本次改动涉及 `1-2` 个 `docs/rules/*.md` 文件，且未发现跨文件重复、职责冲突或明显主题漂移时使用。
- 仅在现有主题边界仍然清晰，且 `AGENTS.md` / `CLAUDE.md` 只需要小幅同步引用或摘要时使用。
- 以局部补充、轻量合并和小范围修订为主，不引入结构重排。

### System Restructure

- 以完整盘点、目标结构定稿和治理动作重写为主，不再依赖局部补丁式追加。
- 适用于需要重写、合并、拆分、`Retire` 或 `Migrate` 规则的场景。
- 默认优先判断是否需要 `System Restructure`，而不是默认走 `Incremental Update`。

## Restructure Triggers

- 涉及 `3` 个及以上规则文件。
- 同义规则跨文件重复。
- 单个文件承载多个主题。
- 现有主题边界已无法容纳新教训。
- 项目级索引描述与实际职责不一致。
- 需要决定保留、合并、迁移或 `Retire` 旧规则。

## Workflow

1. **Assess Current System**
   - 回顾当前会话中的目标、关键决策、失败尝试、返工点和有效做法，明确本次要治理的结构问题。
   - 读取 `docs/rules/**/*.md`、`AGENTS.md`、`CLAUDE.md`，先判断是否满足 `Restructure Triggers`；满足则进入 `System Restructure`，否则走 `Incremental Update`。
   - `Incremental Update` 以局部更新、轻量合并和小范围修订为主；`System Restructure` 才进入完整的目标结构设计与重整动作。

2. **Build Rule Inventory**
   - `Incremental Update` 下，只盘点与本次局部更新直接相关的规则文件；`System Restructure` 下，盘点全部相关规则文件的职责边界、覆盖范围与文件间关系。
   - 标注重复规则、表述冲突、主题漂移、职责交叉，以及项目级索引与真实结构不一致的地方。
   - 不只记录文件名，而是形成“哪些规则在管什么、哪里已经失真”的结构视图。

3. **Design Target Structure**
   - `System Restructure` 下，在动手改写之前，先决定哪些内容应保留、新增、合并、拆分、迁移或 `Retire`。
   - `Incremental Update` 下，只对本次局部范围内需要调整的条目做最小结构决策，不展开全局重整。
   - 明确每个主题文件的最终职责边界，再确定写入顺序和落盘方式。
   - 如果目标结构需要调整项目级提示词的索引范围，先完成结构定稿，再进入同步步骤。

4. **Apply Rewrite / Merge / Split / Retire / Migrate**
   - 按目标结构执行重写、合并、拆分、`Retire` 与 `Migrate`，优先处理结构性问题，而不是在原文件上无序追加。
   - `Rewrite:` 文件职责混杂或局部 patch 无法恢复结构时，整体重写该主题文件。
   - `Merge:` 两个文件约束同类决策、只是历史表述不同，合并为一个更稳定主题。
   - `Split:` 一个文件同时覆盖多个独立场景，继续共存会降低可检索性时，拆分为多个文件。
   - `Retire:` 旧规则已被更稳定、更可执行的规则完全覆盖时，退役旧条目，不再并列保留。
   - `Migrate:` 规则仍有效但归属主题不再合适时，迁移到更合适的文件，并记录原因。
   - 当主题文件预计超过 `200` 行时，提前拆分为 `topic-part-1.md`、`topic-part-2.md` 等分片，主文件保留目录索引和适用说明。

5. **Sync Project Prompts**
   - 在规则结构定稿后，再同步 `AGENTS.md` / `CLAUDE.md`。
   - 更新 `## Rules Index` 的文件路径、用途摘要和读取约定，确保索引反映当前真实结构。
   - 如果两份项目级提示词存在描述差异，统一改成与当前治理结果一致的版本。

6. **Run Consistency Checks**
   - 检查是否仍有跨文件重复、职责边界不清、规则漂移，或一次性经验被误写成长期规则。
   - 检查 `AGENTS.md` 与 `CLAUDE.md` 中的 `Rules Index` 是否与 `docs/rules/*.md` 保持一致。
   - 检查规则措辞是否仍然支持可执行、可验证的长期维护。

7. **Report Governance Changes**
   - 汇报本次模式判断结果：是 `Incremental Update` 还是 `System Restructure`，以及做出该判断的依据。
   - 汇报实际执行的治理动作，而不只是列出修改过的文件，例如合并、拆分、迁移、`Retire` 和重写了什么。
   - 说明这次治理如何消除了重复、冲突、漂移或索引失真，并保留了哪些稳定规则。

## Abstraction Standard

- 不要把本次会话中的具体事件原样写成长期规则。
- 先识别可重复失败模式，再提炼为触发条件、动作和验证方式。
- 仅会话局部、不可迁移的偶发经验，不进入长期规则库；只有能抽象为可复用规则的会话经验，才应写入 `docs/rules`。

## Rule Writing Standard

- 优先写“原则 + 触发条件 + 执行动作 + 验证方式”。
- 主文件保持简洁：仅保留高频、稳定规则；细分规则放在 `docs/rules/*.md` 并在项目级提示词引用。
- 规则避免空话：避免“注意代码质量”这类不可验证表述。
- 语言简洁，避免同义反复。
- 若信息不足，先写最小可用规则，后续迭代补充。

## 规则文档模板（docs/rules/*.md）

```markdown
# <主题名称>

## Scope
- 该文件适用的任务范围与边界。

## Rules
1. 当 <触发条件> 时，必须/应当 <动作>。
   - Rationale: <为什么这样做>
   - Verification: <如何判断已满足>
2. ...

## Anti-Patterns
- <常见错误> -> <正确做法>

## Change Log
- YYYY-MM-DD: <新增/合并/冲突取舍摘要>
```

格式要求：
- 标题使用 `#` 一级标题；固定二级标题：`Scope`、`Rules`、`Anti-Patterns`、`Change Log`。
- `Rules` 必须编号；每条规则必须可验证。
- 禁止空泛表述（如“注意质量”“尽量优化”）。
- 文件名必须为 kebab-case，且与主题一致。

## 项目级提示词模板（最小可用）

当 `AGENTS.md` 或 `CLAUDE.md` 缺失时，创建包含以下最小结构：

```markdown
# Project Agent Guide

## Rules Index
- [docs/rules/<file>.md](docs/rules/<file>.md): <该规则文件约束范围的一句话说明>

## Usage
- 执行任务前，先读取与任务最相关的规则文件。
- 若新增 `docs/rules/*.md`，必须同步更新本文件的 `Rules Index`。
```

## 输出模板（回复用户时）

```markdown
## 规则沉淀结果

### 治理模式判断
1. 本次属于：增量更新 / 体系重整
2. 判断依据：<为何采用该模式，重点说明重复、冲突、漂移、索引失真或变更规模>

### 本次更新文件
1. docs/rules/xxx.md（新增/更新）
2. docs/rules/yyy.md（新增/更新）
3. AGENTS.md（新增/更新）
4. CLAUDE.md（新增/更新）

### 项目级提示词同步
1. 新增/更新引用：docs/rules/aaa.md -> <一句话摘要>
2. 新增/更新引用：docs/rules/bbb.md -> <一句话摘要>
3. 说明：<如有新增/调整 Rules Index 范围，写明同步原因与影响>

### 关键结构调整
1. 重写（Rewrite）：X -> X'（原因：<为何职责混杂、局部 patch 无法恢复结构或需要整体重整>）
2. 合并：A + B -> C（原因：<为何应合并为单一职责或单一决策面>）
3. 拆分：X -> X-part-1 / X-part-2（原因：<为何必须拆分，若触发 200 行分片策略，写明主文件与分片文件>）
4. 迁移：A -> B（原因：<为何主题归属更适合迁移后的文件>）
5. 废弃（Retire）：X -> Retire（原因：<为何旧规则已被更稳定的规则完全覆盖>）

### 治理结果
1. 消除：<本次消除了哪些重复、冲突、漂移或索引失真>
2. 保留：<本次保留了哪些稳定规则或稳定结构>

### 新增/强化的规则摘要
1. ...
2. ...
3. ...
```

## 边界与异常

- `docs/rules/` 不存在：先创建目录，再继续写入。
- `AGENTS.md` 或 `CLAUDE.md` 不存在：按“项目级提示词模板（最小可用）”创建。
- 历史规则格式混乱：先归一化结构，再分类重写。
- 主题不明确：先放入最接近主题，并在变更记录里标注“待后续重构”。