Recording knowledge

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