# My Reflection

> 复盘存档：把一次学习 / 调试 / 探索的经历或一个项目，整理成一份可长期保存、日后复习的 Markdown 笔记，三种重量（速记 / 学习心得 / 项目档案）按提法自动选档，走哪档见正文。触发说法：『帮我复盘一下』『把这次的收获记下来』『整理成学习笔记/心得』『梳理一下我的理解』『总结一下这次的解决过程』『快速复盘』『简单说说』『记录一下』『先记个大概』『不用太详细』『整理项目』『写项目文档/项目介绍』『梳理这个项目』——即使用户没有说『复盘』二字。不要用于与本次会话无关的纯知识问答，或只要求执行不要求理解的任务。

- Skill: `ishenh/my-reflection` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add ishenh/my-reflection`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ishenh/my-reflection/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: IShenH (https://skillmd.com/u/ishenh)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ishenh/my-reflection

---


# 复盘存档（My Reflection）

## 这个 skill 做什么

一个入口，三种重量（速记 / 完整 / 深度）、两类产物。**先分轻重，再判断走哪条路，最后读对应的参考文件**——不要凭记忆直接套结构。

两条路的判据看**意图和触发词**——最常见的两个词族是：说『归档 / 项目』（让我做了很多事之后，记录发生了什么）→ B；说『学习笔记』（之前就某个问题、技术或概念讨论提问过）→ A。主题是不是技术、有没有代码都不决定归属：两者记录的东西不同，混用结构会两边都不合格：

| | 路径 A：学习心得记录 | 路径 B：项目档案 |
|---|---|---|
| 判据 | 重点是学习、理解、反思 | 重点是把一个项目本身讲清楚 |
| 对象 | 一个问题、一个概念、一段经历、一篇文章/一本书 | 一个项目整体（整个作品） |
| 回答 | 为什么是这样、我搞明白了什么 | 这个项目是什么、做成了什么 |
| 跨度 | 一次学习/调试/探索的经过 | 项目全生命周期，含版本演进 |
| 重心 | 深度：一个点挖到机制层 | 广度：概览、功能、成果、边界、叙事 |
| 读者 | 用户自己日后复习 | 他人（面试官、读者）+ 项目留档 |

## 第一步：先分轻重

轻量提法（『快速复盘』『简单说说』『简要记录』『记录一下』『先记个大概』『不用太详细』）→ 直接出**速记**，不要先纠结 A 还是 B，也不要读参考文件。只有需要完整文档时才往下走。

### 速记的样子（一张骨架，不分路径）

速记不做 A/B 区分，只用一张骨架，把两类对象该有的信息都收进来——对象是一个问题还是一个项目，都用它：

```
---
date: YYYY-MM-DD
type: 速记
tags: [reflection/quick-note, 关键词]
---

# 速记：{主题}

- **是什么**：一句话说清这次记的对象（一个问题 / 一个项目 / 一件事）
- **经过**：2–3 句，按事情本身的顺序讲清发生了什么
- **根因 / 关键**：为什么会这样，一句话说透
- **怎么解决的 / 怎么做的**：关键改动或做法，一行
- **原理**：一句话给最核心的机制，不展开
- **下次注意 / 局限**：一行——下次怎么判断，或现在还差什么、没验证什么
```

写法上：

- **写成一段连贯的短讲解**，不要对着标签硬填——上面几行是『该讲到的信息』，不是必须出现的小标题；信息少时可以合并成两三句话。总长 20 行以内，一屏看完。
- **两类信息都兼有**：问题类重点在『根因 / 原理』，项目类重点在『做了什么 / 局限』，但都不要缺另一侧——项目速记也给一句原理（为什么这样做），问题速记也交代结果和边界。
- **口吻**：默认用户的视角（『遇到了……原以为……后来发现……』），主语『我』能省则省；但不必强求第一人称——事情的主角是 AI 或工具时，直接用中性的第三方叙述更准确（『排查时发现……』『让 AI 改了配置后……』）。详见 `references/learning-reflection.md` 的口吻一节。

速记的规则：

- **速记是索引，不是教材**：不贴长代码、不写七节结构、不做方案对比、不追求『不重走探索也能懂』（那是完整文档的标准）。
- 说了『快速讲讲』就**不要**输出完整文档；说了『讲透』『整理成完整笔记』也**不要**停在速记。
- **可升级**：用户随后说『展开第 N 点』『讲透原理』，就在这份速记的骨架上扩成完整文档（文件按保存去向归位），不要重头另起，也不要重新问一遍分类。
- 速记本身不做 A/B 区分——分类留到需要升级成完整文档时再判。轻量记录大多就是边界地带，不必在记录的时候把类别定死。

## 第二步：判断条件

（不走速记时）按顺序判断，命中即停：

1. **用户说『归档』『项目』（『归档一下』『整理项目』『写项目文档』『梳理这个项目』）→ 路径 B（项目档案）**。典型场景：让我做了一件事（写了个工具、搭了个功能、改了一堆东西），做完之后要把**发生了什么、做了什么**记录下来——对象是这件事/这个作品本身。
2. **用户说『学习笔记』『学习心得』（『整理成学习笔记』『记一下心得』）→ 路径 A（学习心得）**。典型场景：之前就某个问题、技术或概念跟 AI 讨论和提问过，要把**搞懂了什么、为什么是这样**记录下来——对象是理解和认知。
3. **其他说法时看内容**：这次重点是学习、理解、反思（搞懂一个报错/概念/技术点，读完一本书/一篇论文/一篇文章后的思考整理，把零散理解理顺）→ **路径 A**，与主题是不是技术无关；重点是把一个项目本身讲清楚（这个作品是什么、由什么组成、做出了什么，给别人看或留档）→ **路径 B**。
4. **用户在谈方案取舍**（两者唯一的实质重叠处）：
   - 问『为什么这样设计、trade-off 是什么、怎么在项目叙事里说』→ **路径 B**。
   - 问『这个方案为什么技术上行得通、切断了哪条因果链』→ **路径 A**。
5. **『复盘』二字本身不决定归属，看宾语**：『复盘这个项目』通常指 B；指项目里某个具体问题则 A。
6. **分不清时**，只问一句：「这次想留下的是学习/反思的心得，还是这个项目的档案？」不要一次抛多个问题。
7. **两条都要**（项目收尾时常见：项目档案 + 若干关键技术点心得）→ 先 B 后 A，各自独立成文，不要混在一份文档里。

## 第三步：读对应的参考文件

- 路径 A → 读 `references/learning-reflection.md`
- 路径 B → 读 `references/project-documentation.md`

读完再动笔。这两个文件各自带着完整的结构、质量标准与模板，是实际产出的依据。

## 两条路都适用的原则

- **不编造**：材料里没有的细节不补。推断要标注『推断 / 待验证』；项目效果没有数据就写『当前没有量化指标』，宁可留白也不要编数字。
- **区分信息状态**：事实（可验证的）／判断（对原因、动机、价值的解释）／待确认（材料不足的）——项目档案里尤其要随手标注。
- **为复习而写**：不出现『刚才』『上面那段代码』这类依赖会话现场的指代，涉及的东西直接用名字说清；开头交代背景（日期、项目、技术栈/环境）。
- **触发后直接产出**，不要反问『你想复盘什么』。信息不足时只针对缺失环节提问（优先问：当时的确切现象/报错是什么、已经做过哪些尝试）。

## 如果用户是要回看，不是要记录

用户想看的不是新的记录，而是旧的（『回顾一下我这段时间的速记』『把关于 Vite 的记录汇总一下』『我上次那个问题是怎么解决的』）时：去笔记根（见『保存与命名』）按关键词找相关文件读，然后串成一份回顾——按主题或时间线组织，指出反复出现的问题、哪些已经解决，不要凭空另写一份新记录。只有用户说要留档时才落盘。

## 保存与命名

产出都是 Markdown 文档，落盘后都要给出可点击的路径。

- **速记（轻量档）默认落盘**——用户要的就是『快速复盘或者记录』，所以直接存进笔记根，并告诉用户存到了哪；只有用户明确说『只是讲讲』『不用存』时才只在对话里给。
- **完整档（A / B）**：用户意图是留存（『把这次的收获记下来』『整理成笔记』『存档』）时落盘；用户只是在追问、没说要记（『这到底怎么回事』『为什么会这样』）时，先在对话里给文档，并提示可以存下来。

**保存位置**：先看 `references/paths.md` 是否存在（本地私有配置，不随仓库分发）——存在就完全按它执行；不存在则用下面的默认规则。

```
<笔记根>/
├── YYYY-MM-DD-主题.md       ← 速记（轻量）：直接放这一层
├── learning-notes\          ← 学习心得（A，完整 / 深度）
└── project-archives\        ← 项目档案（B）
```

- 笔记根默认是当前工作区的 `notes/`，没有就新建；用户指定过位置就用用户的。
- 想固定长期使用的位置（换机器、换工具都不用改正文），复制 `references/paths.md.example` 为 `references/paths.md` 填上即可。

| 产出 | 文件名 | 位置 |
|---|---|---|
| 速记（轻量） | `YYYY-MM-DD-主题.md` | 笔记根 |
| 学习心得（A） | 同名，`# 速记：` 改成 `# 学习心得：` | 笔记根\learning-notes\ |
| 项目档案（B） | `<项目名>.md`（如 `mcp-agent-project.md`），不带日期 | 笔记根\project-archives\ |

- 速记升级成学习心得时，把文件**移**到 `learning-notes\` 并就地扩写，不要在两处各留一份。
- 项目档案不带日期：它要长期反复更新，已有档案就在其上更新，不从零重写。
- 同一件事第二次记录（同一个问题又犯了、接着上次继续）→ 先按主题关键词找已有文件名（`ls *关键词*.md`，根层和两个子文件夹都看），找到就扩写，不要新建日期文件。同一件事只有一个文件。
- 路径可能含空格或中文，按原样写入（shell 里整个路径要加引号），不要截断、转义或改写。
- 文件名里的主题：空格换成短横线，去掉 `\ / : * ? " < > |` 这些平台非法字符，控制在 40 字以内。
- 目录不存在就创建；若笔记根所在位置不可用（换了机器、盘符不存在），先问用户一句，不要静默改存到别处。用户当场指定了别的位置时，从其指定。
- 目录里已有索引文件时才顺手补一条；没有就不必为单次产出新建索引。

## 笔记头部（frontmatter）

每份笔记的第一行就是 frontmatter，三行，不要省——笔记工具（Obsidian、Logseq）靠它按日期、类型、标签把笔记捞出来，纯文本检索也一样受益：

```yaml
---
date: 2026-09-16
type: 速记 | 学习心得 | 项目档案
tags: [reflection/quick-note, 关键词]
---
```

- `type` 与实际产出一致：速记 / 学习心得 / 项目档案。
- 标签用层级标签，固定第一个：速记 `reflection/quick-note`、学习心得 `reflection/learning`、项目档案 `reflection/project`；再补一到三个主题关键词（如 `vite`、`proxy`）。前缀要换别的，在 `references/paths.md` 里改。
- 日期只写在这里，H1 里不再重复（文件名已带日期）。
- **相关笔记互相链接**：同一主题已有别的笔记时，在正文末尾加一行——按 `references/paths.md` 里配的 `链接写法` 写（例如 `[[笔记名]]` 这种可点击的库内双链，或中性的 `相关笔记：笔记名`），没配就写 `相关笔记：笔记名`。升级是移动文件，所以不要让它链回自己。

## 交付前自检

- 完整档：至少有一处写到机制层（哪个函数、哪个配置项、哪条调用链）、至少一条可迁移经验、没有编造材料里不存在的东西。
- 速记：20 行以内；问题类不缺结果与边界，项目类不缺一句原理。
- 落盘：路径、文件名、H1 三者与『保存与命名』一致；速记升级时是**移动**文件，不是复制。
- 头部：frontmatter 三行（date / type / tags）齐全，`type` 与实际产出一致，`tags` 里带主题关键词。