| name | recording-knowledge |
| description | Use when developing any software project with AI assistance where key decisions, features, and lessons would otherwise be lost after the conversation ends |
Recording Knowledge
概览
AI 对话中的知识用过即忘。这个 Skill 教会 Agent 在开发过程中主动将完成的功能、做的决策、踩到的坑记录到项目本地的 docs/kb/，与代码同仓库、同版本、可检索。
知识库结构
docs/kb/
├── INDEX.md ← 主索引（自动维护）
├── TEMPLATE.md ← 记录模板
├── features/ (f-) ← 已开发特性
├── decisions/ (d-) ← 技术决策
├── pitfalls/ (p-) ← 踩坑记录
└── architecture/ (a-) ← 架构快照
记录类型
| 类型 | 前缀 | 目录 | 适用场景 |
|---|
| Feature | f- | features/ | 完成了一个可独立运行的功能 |
| Decision | d- | decisions/ | 做了技术选型或架构决策 |
| Pitfall | p- | pitfalls/ | 修复了隐蔽的 Bug 或踩坑 |
| Architecture | a- | architecture/ | 架构发生了有意义的演进 |
初始化
进入一个没有知识库的项目时，Agent 自动执行：
mkdir -p docs/kb/{features,decisions,pitfalls,architecture}
创建 docs/kb/INDEX.md：
# 知识库索引
## Architecture（架构快照）
_暂无_
## Decisions（技术决策）
_暂无_
## Features（特性记录）
_暂无_
## Pitfalls（踩坑记录）
_暂无_
创建 docs/kb/TEMPLATE.md（内容见本 Skill 附带的 TEMPLATE.md，或直接内联创建）。
初始化完成后告知用户："知识库骨架已创建，开发过程中说'记录一下'即可记录知识。"
触发记录
主动触发（Agent 识别）
以下场景出现时，Agent 应主动提议"这个值得记录到知识库"：
- 完成了一个可独立运行的功能 → 类型
Feature
- 做了一个技术选型或架构决策 → 类型
Decision
- 修复了一个隐蔽的 Bug 或踩坑 → 类型
Pitfall
- 架构发生了有意义的演进 → 类型
Architecture
提议话术："这个值得记录到知识库，要记录吗？" 用户同意后执行写入。
手动触发（用户指令）
用户说出以下关键词时，立即执行写入流程：
会话结束检查
每次 Agent 认为对话即将结束时，检查本会话中是否有值得记录但尚未记录的信息。如果有，主动询问用户是否需要记录。
写入流程
- 使用
docs/kb/TEMPLATE.md 模板创建新文件
- 文件命名：
{前缀}-{序号}-{简短英文描述}.md（全小写连字符）
- 写入
docs/kb/{类型}/ 目录
- 更新
docs/kb/INDEX.md：
- 在对应分类下追加一行（按时间倒序，最新的在最上面）
- 格式：
| YYYY-MM-DD | [文件名](路径) | 一句话说明 |
- 如果该分类从"暂无"变为有记录，替换
_暂无_ 行
记录标准
写什么
- 结论 — 最终选择了什么 / 做了什么 / 发生了什么
- 理由 — 为什么选这个不选那个 / 为什么出现这个问题
- 影响 — 对后续开发的约束或启发
不写什么
- 对话过程（"先试了 A 不行再试了 B"）
- 代码实现细节（代码本身在仓库里）
- 尚未确认的想法（知识库存储定稿，不是草稿箱）
翻阅规则
新会话启动时：
- 检查项目根目录是否存在
docs/kb/INDEX.md
- 如果存在，主动告知用户："这个项目有知识库记录（docs/kb/），需要读取背景知识吗？"
- 如果用户确认或需要回溯某类知识：
- 读 INDEX.md → 定位相关记录 → 读全文 → 给摘要
三层追问法（来自 p-001）
在开始任何设计或实现之前，Agent 必须先执行三层追问：
用户说："我想要一个 X 工具"
Step 1 — WHAT：你想要什么？
→ "你想要一个 X 工具，具体是什么样子的？"
Step 2 — WHY：你为什么想要这个？
→ "你觉得 X 工具能解决你的什么问题？"
Step 3 — ACTUAL NEED：没有 X，你的痛点是什么？
→ "如果没有 X，你现在感到最不方便的地方是什么？"
第三层才是应该被设计的。 不要把用户提出的方案直接当成需求。
何时执行
- 用户提出一个新的功能需求时
- 用户提出要引入一个新工具/框架时
- 用户描述了一个解决方案而不是问题时
识别信号（踩过坑的信号）
- 用户在讨论中多次表示不需要某些功能
- 架构中大量功能没有对应的真实使用场景
- Agent 发现自己正在设计"完整"而非"够用"的方案
常见错误
| 错误 | 正确做法 |
|---|
| 记录包含大量对话过程 | 只写结论、理由、影响三要素 |
| 为"未来可能有用"提前设计架构 | 先三层追问找到真实痛点，只解决已验证的问题 |
| 记录写完后不更新 INDEX.md | 每次写入后必须同步更新 INDEX |
| 认为知识只存在于 AI 的记忆中 | 当场写入 Markdown，与代码版本绑定 |
| 直接把用户说的方案当需求 | 执行三层追问：WHAT → WHY → ACTUAL NEED |
