AI 辅助编程全生命周期

主题

22 - 项目知识沉淀机制 ​

1. 定位 ​

三个断点 ​

项目开发中有三种知识会在会话结束后丢失：

  1. 调研结论 — 花了一小时对比三个方案，选完就忘了为什么不选另外两个
  2. 踩坑经验 — 花了半天定位一个 Bug，修完就过了，下次同类问题从零开始
  3. 决策上下文 — 为什么用方案 A 而不是方案 B，三个月后只记得结论不记得理由

这三种知识的共同特点：产出时有完整上下文，但不主动记录就会随会话消散。

与体系的三角关系 ​

doc-08 维护 ─────── 体系自身的健康检查、规则老化、版本管理
     │                 ↑ 进化触发
     │                 │
doc-20 引入 ─────── 外部知识的评估、吸收、融合
     │                 ↑ 知识来源
     │                 │
doc-22 留存 ─────── 项目过程中产生的知识的记录与检索（本文档）
  • doc-08（维护）：向内看，确保体系本身健康
  • doc-20（引入）：向外看，从外部世界吸收养分
  • doc-22（留存）：向下看，捕获项目实践中产生的知识

三者互补：留存的踩坑经验可能触发维护更新，引入的外部知识可能沉淀为调研记录。

核心理念：沉淀点 ​

沉淀点（Retention Point）：在现有 Skill 工作流的关键时刻植入一个轻量判断 —— "这条知识值得留下吗？"

如果值得，用最小格式存入约定位置。不新建知识管理系统，不新增 Skill，不引入复杂规范。

与 Claude Code Auto Memory 的分工 ​

Claude Code 内置 Auto Memory 机制（~/.claude/projects/*/memory/），会自动记录操作性经验（构建命令、调试模式、代码风格偏好）。

两套机制的分工：

维度Auto Memory（自动）结构化沉淀（本机制）
写入方式Claude 自动判断人决策，AI 辅助执行
内容类型操作性知识（怎么做）决策性知识（为什么这样做）
版本管理不进 git，机器本地进 git，可追溯可协作
检索方式每次会话自动加载grep tags/title 主动检索
典型内容"这个项目用 cd site && npm run build 构建""选 Vite 不选 Webpack 的完整评估"

原则：Auto Memory 管"肌肉记忆"，结构化沉淀管"认知资产"。

沉淀点的判断标准不变（§2.4），但可以额外排除一条：如果知识纯属操作性（构建命令、环境配置），Auto Memory 已自动捕获，无需手动归档。

2. 沉淀点设计 ​

什么是沉淀点 ​

沉淀点是 Skill 执行末尾的一个提示性步骤，不是强制门禁。它在工作流自然完成后提醒一句："要不要存下来？"

沉淀出口 ​

沉淀方式触发时机产出位置
/checkpoint 统一路由会话结束或阶段完成时adr/、research/、troubleshooting/、plans/ 等
/tech-research 即时归档调研完成后docs/research/
/debug 即时归档问题修复后docs/troubleshooting/

/checkpoint 是主要的知识沉淀出口，负责捕获自由对话中产生的知识。/tech-research 和 /debug 在执行过程中即时归档。两者互补，同一内容不重复归档。

设计原则 ​

  1. 提示性而非强制性 — 不用 Gate 卡流程，用户说"不需要"就跳过
  2. 最小格式 — 只要求 3 个 frontmatter 字段（title/date/tags），正文格式不限
  3. 复用现有输出 — 调研报告直接存，问题记录从修复方案裁剪，不重复写
  4. AI 辅助判断 — 由 AI 根据标准建议是否归档，人类做最终决定

沉淀判断标准 ​

不是所有产出都值得记录。沉淀的核心问题是：未来还会用到吗？

  • 调研：结论会影响后续决策的 → 存；一次性快速验证的 → 不存
  • 问题：花了 30+ 分钟才定位的 → 存；一眼看出的笔误 → 不存
  • 决策：影响跨模块架构的 → ADR；单模块内部的 → 调研 Recommendations 就够

3. 调研记录 ​

存放位置 ​

docs/research/
├── README.md                        # 索引表
└── {YYYY-MM-DD}-{slug}.md           # 调研记录文件

与 docs/prd/、docs/api/ 等平级，是 docs/ 的标准子目录。

文件格式 ​

直接复用 /tech-research 现有输出格式，只需在头部添加最小 frontmatter：

markdown
---
title: CRDT 实时同步方案调研
date: 2026-03-01
tags: [crdt, real-time, sync]
---

# Research: CRDT Real-time Sync

> **Goal:** 选择实时协作编辑的同步方案
> **Date:** 2026-03-01
> **Depth:** Deep dive
> **Dimensions:** Open-Source, Best Practices, Performance

## TL;DR
...（/tech-research 标准输出格式，无需改动）

frontmatter 三个字段说明：

字段用途格式
title索引显示标题中文，一句话
date调研日期YYYY-MM-DD
tags检索标签小写英文数组，2-5 个

索引表 ​

docs/research/README.md：

markdown
# 调研记录

| 日期 | 主题 | 标签 |
|------|------|------|
| 2026-03-01 | [CRDT 实时同步方案调研](./2026-03-01-crdt-sync.md) | crdt, real-time, sync |

新增记录时在表尾追加一行，按日期倒序排列（最新在上）。

调研 → ADR 衔接 ​

当调研结论直接支撑了技术选型决策时：

  1. 调研记录照常存入 docs/research/
  2. 提示用户：如果这是跨模块决策，建议用 Prompt 食谱 10 — 食谱 3 转化为 ADR
  3. ADR 的"上下文"章节中添加调研记录的链接，建立追溯链

这是提示性检查，不强制。日常调研不需要都产出 ADR。

/tech-research Skill 修改 ​

Step 5（等待确认）之后新增 Step 6：

Step 6: 沉淀
调研报告经用户确认后：
1. 保存到 docs/research/{YYYY-MM-DD}-{slug}.md，添加 frontmatter（title/date/tags）
2. 更新 docs/research/README.md 索引表
3. 提示：如果调研支撑了技术选型，建议用食谱 10-食谱 3 转化为 ADR

4. 问题记录 ​

筛选三问法 ​

不是每个 Bug 都值得记录。修复完成后，问三个问题：

  1. 花了超过 30 分钟才定位？ — 说明问题不直观，下次可能同样费时
  2. 根因不在报错的直接指向？ — 间接因果链，说明调试路径有陷阱
  3. 同类问题可能在其他场景复发？ — 不是孤立事件

任一为是 → 建议归档。三个都否 → 不需要记录。

存放位置 ​

docs/troubleshooting/
├── README.md                        # 索引表
└── {YYYY-MM-DD}-{slug}.md           # 问题记录文件

记录模板 ​

5 个极短章节，每个 1-3 句话：

markdown
---
title: Prisma 多对多关系查询返回空数组
date: 2026-03-01
tags: [prisma, relation, query]
---

# Prisma 多对多关系查询返回空数组

## 症状
用户标签查询始终返回空数组，但数据库中确实有关联数据。

## 根因
Prisma 的 `include` 不会自动穿透中间表。需要显式指定
`include: { tags: { include: { tag: true } } }` 两层嵌套。

## 解法
将查询从单层 include 改为嵌套 include，涉及 3 个 API handler。

## 防御
在 Prisma 查询的 code-standards 规则中添加：
"多对多关系必须使用嵌套 include"。

## 经验
> Prisma 的多对多不像 ActiveRecord 那样透明，
> 中间表是显式存在的，查询时必须手动穿透。

"经验"字段是核心 — AI 检索时最先阅读这一行。用一句话总结这次踩坑的本质洞察。

索引表 ​

docs/troubleshooting/README.md：

markdown
# 问题记录

| 日期 | 问题 | 标签 |
|------|------|------|
| 2026-03-01 | [Prisma 多对多关系查询返回空数组](./2026-03-01-prisma-m2m-include.md) | prisma, relation, query |

/debug Skill 修改 ​

Step 5（等待确认后执行修复）之后新增 Step 6：

Step 6: 归档检查
修复完成后，三问法评估：
1. 花了超过 30 分钟才定位？
2. 根因不在报错的直接指向？
3. 同类问题可能在其他场景复发？

任一为是 → 提示用户归档。确认后：
- 生成 docs/troubleshooting/{YYYY-MM-DD}-{slug}.md（5 章节模板）
- 更新 docs/troubleshooting/README.md 索引表

5. 决策记录增强 ​

复用已有 ADR 机制 ​

不新建决策记录机制。doc-06 §4 已定义了 ADR 模板和使用场景，本节只做两处增强：

增强 1：ADR "上下文"章节添加调研链接 ​

在 ADR 模板的"上下文"章节中，增加可选的调研参考字段：

markdown
## 上下文
[描述面临的问题和背景，2-3 句话]

**调研参考：** [CRDT 实时同步方案调研](../research/2026-03-01-crdt-sync.md)

建立从决策到调研的追溯链。这是可选字段，有调研就加，没有就省略。

增强 2：轻量决策分级 ​

不是所有决策都需要 ADR：

决策范围记录方式示例
跨模块架构决策ADR（docs/adr/）从 REST 迁移到 GraphQL
单模块技术选型调研记录的 Recommendations 章节选择 date-fns 而非 dayjs
日常编码决策commit message变量命名、代码组织

这与 doc-06 §4 的指导一致，只是用分级表格让判断更明确。

6. 检索与维护 ​

检索协议 ​

在采用本机制的项目 CLAUDE.md 中写入：

markdown
## 知识检索规则
- 技术调研前先搜索 docs/research/（避免重复调研）
- 调试问题前先搜索 docs/troubleshooting/（避免重复踩坑）
- 检索方式：grep tags 或 title 关键词

AI 天然擅长 grep 和文件搜索，不需要额外的检索工具或索引系统。

索引维护 ​

索引维护并入 /docaudit Skill，新增第 6 项检查：

6. 知识沉淀检查（如目录存在）
   - docs/research/ 和 docs/troubleshooting/ 下的文件是否都在对应 README.md 索引中
   - 文件 frontmatter 是否包含 title、date、tags 三个必填字段

"如目录存在"是关键条件 — 这是可选机制，未采用的项目不会被检查报错。

/retro 会话回顾增强 ​

在 Q3 之后追加 Q4，引导会话结束时检查是否有知识遗漏：

Q4: 有值得归档的知识吗？
- 本次有费时定位的问题？→ 建议 issue 归档
- 有调研成果未保存？→ 检查 docs/research/
- 有技术决策未记录？→ 建议补充 ADR

规模控制 ​

沉淀机制不应成为负担。两个限制：

  • 每个目录不超过 50 个文件 — 超过时考虑按年份归档子目录
  • 单个记录不超过 200 行 — 超过说明内容应该拆分或简化

7. 与体系的关系 ​

三角互补 ​

    doc-08 维护
   ╱ 体系健康 ╲
  ╱             ╲
doc-20 引入 ─── doc-22 留存
  外部知识         项目知识
  • 留存 → 维护：踩坑经验可能暴露体系规则缺陷，触发 doc-08 的进化流程
  • 引入 → 留存：外部知识吸收后的调研记录存入 docs/research/
  • 维护 → 留存：健康检查发现知识目录索引不一致时，触发修复

doc-06 目录更新 ​

本机制在 doc-06 §2 的 docs/ 统一结构中新增两个目录：

子目录用途维护方式
docs/research/调研记录（/tech-research 产出）调研完成后自动提示归档
docs/troubleshooting/问题记录（/debug 产出）问题修复后三问法评估归档

关联文档 ​

关联文档：06-文档体系 | 08-运维与持续进化 | 20-体系外部进化机制 | 02-Skills 技能体系

面向个人开发者的 AI 辅助编程工程化方案

基于 Claude Code 构建