recording-knowledge

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 认为对话即将结束时，检查本会话中是否有值得记录但尚未记录的信息。如果有，主动询问用户是否需要记录。

写入流程

1. 使用 docs/kb/TEMPLATE.md 模板创建新文件
2. 文件命名：{前缀}-{序号}-{简短英文描述}.md（全小写连字符）
3. 写入 docs/kb/{类型}/ 目录
4. 更新 docs/kb/INDEX.md：
   • 在对应分类下追加一行（按时间倒序，最新的在最上面）
   • 格式：| YYYY-MM-DD | [文件名](路径) | 一句话说明 |
   • 如果该分类从"暂无"变为有记录，替换 _暂无_ 行

记录标准

写什么

• 结论 — 最终选择了什么 / 做了什么 / 发生了什么
• 理由 — 为什么选这个不选那个 / 为什么出现这个问题
• 影响 — 对后续开发的约束或启发

不写什么

• 对话过程（"先试了 A 不行再试了 B"）
• 代码实现细节（代码本身在仓库里）
• 尚未确认的想法（知识库存储定稿，不是草稿箱）

翻阅规则

新会话启动时：

1. 检查项目根目录是否存在 docs/kb/INDEX.md
2. 如果存在，主动告知用户："这个项目有知识库记录（docs/kb/），需要读取背景知识吗？"
3. 如果用户确认或需要回溯某类知识：
   • 读 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