AI 编程项目工作流：知识库与需求文件夹全流程规范

工作流概述

这套工作流由三份规则文档组成，协同覆盖一个 AI 编程项目从立项到上线的全过程：

• 需求内容维护规则：六个 Phase 的执行流程与 Claude 操作规范
• 文件夹维护规则：文件命名、frontmatter 模板、目录结构约定
• 知识库内容维护规则：知识库分类结构与各阶段写入规则

三者配合使用，把 AI 的”对话记忆”外置到 Obsidian 文件系统，使每次新建会话都能通过读取文件恢复完整上下文。

---

如何激活工作流

每次新对话开始时，将以下内容粘贴给 Claude：

请读取以下工作流文档后进入工作模式：
- 需求内容维护规则：<1.4.7.1.1.2 文件夹路径>
- 知识库内容维护规则：<1.4.7.1.1.1 文件夹路径>（可选，有知识库时提供）

需求文件夹：<当前需求的绝对路径>
知识库文件夹：<知识库的绝对路径>（可选）
当前 Phase：<Phase 名称>（不填则 Claude 自动扫描 MOC 判断）

Claude 启动后将自动：

1. 读取工作流规则文档
2. 扫描需求文件夹下所有 MOC 文件的 taskStatus
3. 按以下逻辑判断当前 Phase：
   • 有且仅有一个 taskStatus=2 → 直接进入该 Phase
   • 有多个 taskStatus=2 → 按 Phase 编号取最小的，并告知用户
   • 没有 taskStatus=2，有 taskStatus=1 → 列出待投入的 Phase，询问用户从哪个启动
   • 全部为 0 或 4 → 提示用户说明当前阶段或从 Phase 1 重新开始
4. 输出当前状态摘要（进行中 Phase、已完成 Phase 数量、功能点列表），等待用户确认后进入执行

---

一、文件夹与文件规范

1.1 文件 frontmatter 模板

普通文件模板（所有新建文件默认使用，title 填文件名，layer_id 填所在位置编号）：

---
title: <文件名>
tags:
categories: []
creation_time: "{{date:YYYY-MM-DD HH:mm:ss}}"
updated: "{{date:YYYY-MM-DD HH:mm:ss}}"
date: "{{date:YYYY-MM-DD HH:mm:ss}}"
banner_img: https://obsidian-picture.oss-cn-shenzhen.aliyuncs.com/luoblog/202311131716524.jpg
excerpt: 摘要
hide: "true"
maintain: "true"
parent_id: <父级 layer_id>
layer_id: <本文件 layer_id>
sort_num:
taskStatus: "0"
---

外部素材文件模板（x.x.x.1.0/ 目录专用，用于 skills 产物或用户手动提供的原始文档）：

---
title: <文件名>
tags:
categories: []
creation_time: "{{date:YYYY-MM-DD HH:mm:ss}}"
updated: "{{date:YYYY-MM-DD HH:mm:ss}}"
date: "{{date:YYYY-MM-DD HH:mm:ss}}"
hide: "true"
maintain: "true"
parent_id: <父级 layer_id>
layer_id: <本文件 layer_id>
sort_num:
taskStatus: "0"
is_raw: "true"
source_url: <原始链接（若来自链接）>
source_type: sdoc / skill / axure / swagger / manual
fetched_at: "{{date:YYYY-MM-DD HH:mm:ss}}"
---

外部素材模板字段说明：

字段	说明
is_raw	固定为 "true"，标记该文件是原始素材而非工作流产出，便于 dataview/base 过滤
source_url	原始链接，便于后续重新抓取或核对最新版本；本地文件提供时留空
source_type	来源类型：sdoc（公司文档）/ skill（工具输出）/ axure（原型）/ swagger（接口文档）/ manual（用户手动提供）
fetched_at	抓取或接收时间，标记本地版本的时间点，提示内容可能已过期

---

1.2 文件夹核心规则

• 每篇笔记通过 frontmatter 的 layer_id（自身编号）和 parent_id（父级编号）构建虚拟树形结构
• 每个数字编号文件夹下有一个语义化命名的 MOC（Map of Content）入口文件，文件夹名与 MOC 文件名相互独立，两者通过 frontmatter 中的 layer_id 建立关联，MOC 文件通过双链串联子主题
• 数字编号文件夹用于定位层级，Claude 新建子文件夹时应按当前最大编号 +1 续号
• 阶段产出文件统一以需求名为前缀命名，格式：<需求名>-<文件用途>.md，避免不同需求间的同名文件在 Obsidian 双链中产生歧义

---

1.3 需求文件夹完整结构

以「需求-用户登录优化」为例：

x.x.x.1/                                  # 需求根文件夹（layer_id = x.x.x.1）
├── 需求-用户登录优化.md                    # 根 MOC（唯一，语义化命名）
│
├── x.x.x.1.0/                            # 素材/外部输入（.0 排在所有 Phase 之前）
│   └── 用户登录优化-技术方案初稿.md         # skills 产物或用户提供的原始文档（若有）
│
├── x.x.x.1.1/                            # Phase 1 — PRD评审和分析
│   └── 用户登录优化-PRD分析.md
│
├── x.x.x.1.2/                            # Phase 2 — 技术方案输出
│   ├── 用户登录优化-技术方案输出.md          # Phase 2 MOC
│   ├── 用户登录优化-技术方案初版.md
│   ├── 用户登录优化-技术方案汇总.md
│   ├── x.x.x.1.2.1/
│   │   └── 用户登录优化-feature-手机号登录.md
│   └── x.x.x.1.2.2/
│       └── 用户登录优化-feature-第三方登录.md
│
├── x.x.x.1.3/                            # Phase 3 — 开发阶段
│   ├── 用户登录优化-开发阶段.md             # Phase 3 MOC
│   └── 用户登录优化-开发记录.md
│
├── x.x.x.1.4/                            # Phase 4 — 联调自测
│   ├── 用户登录优化-联调自测.md             # Phase 4 MOC
│   ├── 用户登录优化-CodeReview.md
│   ├── 用户登录优化-自测清单.md
│   └── 用户登录优化-联调记录.md
│
├── x.x.x.1.5/                            # Phase 5 — 测试阶段
│   ├── 用户登录优化-测试阶段.md             # Phase 5 MOC
│   └── 用户登录优化-Bug跟踪.md
│
└── x.x.x.1.6/                            # Phase 6 — 验收上线
    ├── 用户登录优化-验收上线.md             # Phase 6 MOC
    ├── 用户登录优化-上线Checklist.md
    └── 用户登录优化-验收记录.md

层级说明：

层级	命名规则	用途
一级（根）	数字编号目录 + 语义化 MOC 文件	需求入口
二级（素材）	数字编号目录（根编号.0）	外部输入/skills 产物
二级（Phase）	数字编号目录（根编号.1~.6）+ 语义化 MOC 文件	阶段划分
三级（细分）	数字编号目录（Phase编号.1~.n）+ 语义化内容文件	功能点/模块拆分

---

1.4 MOC 入口文件内容示例

---
title: 需求-用户登录优化
taskStatus: "2"
layer_id: x.x.x
parent_id: x.x
---

## 当前状态
- 进行中 Phase：Phase 2 — 技术方案输出

## 外部资料
- 技术方案初稿（skill）：https://xxx.sheincorp.cn/doc/xxx

## 阶段产出

​```dataview
TABLE taskStatus AS 状态, title AS 文档
FROM "<当前需求文件夹的绝对路径>"
WHERE is_raw != "true" AND file.name != this.file.name
SORT file.path ASC
​```

## 外部素材

​```dataview
TABLE source_type AS 类型, source_url AS 来源, fetched_at AS 抓取时间
FROM "<当前需求文件夹的绝对路径>"
WHERE is_raw = "true"
SORT fetched_at DESC
​```

## 功能点列表
| 功能点 | 状态 | 复杂度 |
|-------|------|--------|
| 手机号登录 | 进行中 | 中 |
| 第三方登录 | 待投入 | 高 |

---

1.5 Claude 新建文件操作规范

1. 新建文件夹：在父目录下创建数字编号子目录（续当前最大编号 +1）
2. 新建文件：套用对应 frontmatter 模板（普通文件 / 外部素材），填写 layer_id 和 parent_id
3. 文件命名：阶段产出文件统一加需求名前缀，格式 <需求名>-<文件用途>.md
4. 外部素材：统一存入 x.x.x.1.0/ 并套用外部素材模板：
   • 用户提供链接 → Claude 直接抓取内容转为本地文件，source_url 填写链接，fetched_at 填写抓取时间
   • 用户直接放入文件夹 → Claude 扫描到后补全 frontmatter，source_url 留空，source_type 填 manual
5. 新建完成后：在父级 MOC 文件中追加双链引用
6. 阶段文档生成后：更新 MOC 中「当前状态」字段

---

二、需求内容维护规则

2.1 启动流程

Claude 收到需求文件夹路径后，执行以下步骤：

1. 读取需求文件夹下的 MOC 文件（文件名与文件夹名一致或唯一的 md 文件）
2. 扫描 MOC 中双链引用的所有子文件，找出 taskStatus: "2"（进行中）的条目
3. 根据 taskStatus 值判断当前所处 Phase（见下方映射表），若用户已明确说明 Phase 则直接使用
4. 输出当前状态摘要，询问用户确认后进入对应 Phase 执行流程

taskStatus 与 Phase 映射：

taskStatus	含义	对应 Phase
0	默认/未开始	等待用户指示
1	待投入	等待用户启动
2	进行中	按 Phase 文档执行
3	冻结中	提示用户当前已冻结
4	已归档	提示用户已归档

---

2.2 taskStatus 更新责任

Claude 在以下时机主动更新 taskStatus：

• 新 Phase 启动时：将当前 Phase 子文件夹 MOC 的 taskStatus 改为 "2"（进行中）
• Phase 结束时：将该 Phase 子文件夹 MOC 的 taskStatus 改为 "4"（已归档）
• 用户说「冻结」时：将当前 Phase 子文件夹 MOC 的 taskStatus 改为 "3"
• 需求根 MOC：整个需求进行中保持 "2"，仅在 Phase 6 验收上线完成后才改为 "4"

---

2.3 触发词速查

Phase	进入触发词	子步骤触发词
Phase 1	用户提供 PRD 内容	—
Phase 2	「开始技术方案」	「我们来看 <功能点>」/ 「汇总技术方案」
Phase 3	「开始开发」	「开始开发 <功能点>」
Phase 4	「开始联调自测」	「Review」/ 「自测」/ 用户描述联调问题
Phase 5	「提测」	用户反馈 Bug
Phase 6	「验收上线」	—

---

2.4 返工处理

当某个 Phase 已完成（taskStatus=4）但需要回头修改时：

轻微修改（不影响后续 Phase）：直接修改对应文件，在开发记录中注明变更，taskStatus 保持 "4" 不变

重大修改（影响后续 Phase 的内容）：

1. 将该 Phase MOC 的 taskStatus 改回 "2"（进行中）
2. 执行修改，同步更新受影响的后续 Phase 文件
3. 修改完成后重新归档（改回 "4"）
4. 在需求根 MOC「当前状态」中记录返工原因

---

2.5 知识库协作规则

若用户提供了知识库文件夹，各 Phase 按以下规则与知识库交互：

Phase	知识库操作	说明
Phase 1	查阅参考	优先查阅 概念/ 了解业务术语
Phase 2	查阅参考	查阅 架构决策/、模式沉淀/ 作为技术选型依据
Phase 3	不参考	严格按技术方案执行，不参考知识库，避免偏离方案
Phase 4	写入积累	Code Review 后识别可复用模式，写入 模式沉淀/
Phase 5	写入积累	Bug 根因分析完成后，询问是否写入 踩坑记录/
Phase 6	无操作	验收上线阶段无知识库操作

未提供知识库文件夹则跳过所有知识库相关步骤。

---

三、各 Phase 执行规则

Phase 1 — PRD 评审和分析

触发条件

用户提供 PRD 内容（文本粘贴 / 文件路径 / 口述描述均可）。

若用户尚未提供 PRD 内容，提示：

请提供 PRD 文档内容，可以直接粘贴文本、提供文件路径，或分段描述功能需求。

执行步骤

Step 1 — 功能点识别

• 从 PRD 中提取所有功能点，整理为列表
• 按「复杂度 × 依赖关系」排序（高复杂度、被依赖多的排前）

Step 2 — 功能点卡片输出

每个功能点输出一张卡片，格式如下：

### <功能点名称>
- 目标：<这个功能要解决什么问题>
- 边界：<明确不包含什么>
- 关键逻辑：<核心流程或规则>
- 风险点：<潜在技术难点或业务风险>
- 复杂度：高 / 中 / 低
- 依赖：<依赖哪些其他功能点或外部条件>

Step 3 — 领域概念识别

• 扫描 PRD 中出现的新领域概念（业务术语、专有名词）
• 列出发现的概念，询问用户：「以下概念是否需要写入知识库？」

Step 4 — 生成 Phase 1 子文件夹和文件

1. 在需求根目录下新建数字编号子文件夹（根编号.1），例如 x.x.x.1.1/
2. 在该子文件夹下生成 <需求名>-PRD分析.md（功能点卡片汇总）
3. 在需求根 MOC 的「阶段文档」下追加双链：<需求名>-PRD分析

Step 5 — Phase 结束

1. 将 Phase 1 产出文件（<需求名>-PRD分析.md）的 taskStatus 更新为 "4"（已归档）
2. 更新需求根 MOC 的「当前状态」字段：

   当前状态：Phase 1 已完成，进入 Phase 2 — 技术方案输出
   功能点数量：<n> 个

3. 输出功能点列表摘要，提示用户：「可以说『开始技术方案』进入 Phase 2，或『我们来看 <功能点名称>』直接开始击穿」

---

Phase 2 — 技术方案输出

本阶段分三步：初版技术文档 → 功能点逐一击穿 → 汇总为完整技术方案。

灵活流程说明：根据需求规模可按需裁剪：

• 完整流程（推荐）：2.0 初版 → 2.1 功能点击穿 → 2.2 汇总
• 快速流程（简单需求）：跳过 2.0，直接 2.1 击穿 → 2.2 汇总
• 初版流程（外部已有完整方案）：2.0 初版 → 直接 2.2 汇总，跳过逐一击穿

Phase 2 启动

触发：用户说「开始技术方案」或从 Phase 1 切换进入

进入 Phase 2 时，第一步先建立 MOC，后续所有子步骤基于此 MOC 展开：

1. 在需求根目录下新建 Phase 2 子文件夹（根编号.2）
2. 在子文件夹下创建 <需求名>-技术方案输出.md 作为 Phase 2 MOC，taskStatus 设为 "2"
3. 在需求根 MOC 追加双链：<需求名>-技术方案输出，并更新「当前状态」字段

2.0 初版技术文档

触发：进入 Phase 2 时自动执行

本步骤有两种来源，优先使用用户提供的版本：

来源 A — 用户通过 skills 提供（优先）

用户通过外部 skill（如公司技术方案生成工具）生成了初版技术文档，以链接或本地文件形式提供：

• 链接：Claude 直接抓取内容读取，无需存文件；在根 MOC 的「外部资料」区块记录链接
• 本地文件：存入需求根目录下的 x.x.x.1.0/ 素材文件夹，文件名格式 <需求名>-技术方案初稿.md

Claude 读取后执行：

1. 对照 <需求名>-PRD分析.md 中的功能点卡片，检查文档是否覆盖所有功能点
2. 指出遗漏或不清晰的部分，询问用户是否需要补充
3. 以此为基础生成 <需求名>-技术方案初版.md，存入 Phase 2 子文件夹（x.x.x.1.2/）
4. 在 Phase 2 MOC（<需求名>-技术方案输出.md）中追加双链：<需求名>-技术方案初版

来源 B — Claude 自主生成

若用户未提供外部技术文档，Claude 基于以下内容自动生成初版：

• <需求名>-PRD分析.md 中的功能点卡片
• 项目相关代码上下文（架构、已有实现、接口规范）
• 知识库中 架构决策/、模式沉淀/ 的相关内容（若提供了知识库）

生成文档结构：

# 技术方案初版 — <需求名称>

## 背景与目标

## 整体设计思路

## 各功能点初步方案
（按 PRD 分析的功能点顺序列出，每点包含：初步实现思路、关键风险）

## 待确认事项
（需要用户或团队决策的问题清单）

保存为 <需求名>-技术方案初版.md，在 Phase 2 MOC 中追加双链：<需求名>-技术方案初版

初版完成后：

1. 在 Phase 2 MOC 中追加双链：<需求名>-技术方案初版
2. 更新需求根 MOC「当前状态」字段
3. 提示用户：「初版技术方案已就绪，可说『我们来看 <功能点名称>』逐一深化」

2.1 功能点击穿

触发：用户说「我们来看 <功能点名称>」

Step 1 — 调取功能点信息

• 读取 <需求名>-PRD分析.md 中该功能点的卡片（目标 / 边界 / 关键逻辑 / 风险点）
• 读取 <需求名>-技术方案初版.md 中该功能点的初步方案，作为深化的起点

Step 2 — 结合代码上下文输出技术方案

• 读取项目相关代码，确认当前架构与约定
• 若提供了知识库，查阅 架构决策/、模式沉淀/、工具使用/ 作为参考
• 给出针对项目规范的技术实现方案

Step 3 — 架构决策（有需要时）

若存在多个可行方案，提供对比表格并给出推荐理由，用户确认后记录决策结论。

Step 4 — 生成功能点子文件夹和文件

1. 在 Phase 2 子文件夹下新建功能点三级子文件夹（根编号.2.n，按已有功能点数量续号）
2. 在三级子文件夹下生成 <需求名>-feature-<功能点名称>.md，文档结构：
   • 功能背景（来自 PRD 卡片）
   • 技术方案（实现思路、接口设计、数据结构）
   • 架构决策（若有）
   • 边界与排除项
   • 风险与注意事项

Step 5 — 更新 MOC

在 Phase 2 MOC 中追加双链：<需求名>-feature-<功能点名称>

提示下一步：「可继续『我们来看 <下一个功能点>』，或说『汇总技术方案』」

2.2 技术方案汇总

触发：用户说「汇总技术方案」，或所有功能点均已完成击穿

Step 1 — 收集所有功能点文档

• 读取 Phase 2 子文件夹下所有 feature-xxx.md
• 检查是否有 PRD 中的功能点尚未击穿，若有则提示用户

Step 2 — 生成 <需求名>-技术方案汇总.md

文档结构：

# 技术方案 — <需求名称>

## 背景

## 整体设计

## 各功能点方案（附双链）

## 数据库变更

## 接口变更

## 风险与注意事项

## 架构决策记录

若体量较大，可在 Phase 2 子文件夹下按模块新建三级子文件夹，在 技术方案汇总.md 中通过双链引用。

Step 3 — 更新 MOC

在 Phase 2 MOC 中追加双链：<需求名>-技术方案汇总

Step 4 — 自动写入知识库（若提供了知识库）

从「架构决策记录」提取决策内容，自动写入知识库 架构决策/，文件名：ADR-<需求名>-<决策主题>.md

Step 5 — Phase 结束

将 Phase 2 MOC 的 taskStatus 更新为 "4"（已归档），提示：「技术方案已生成，可说『开始开发』进入 Phase 3 — 开发阶段」

---

Phase 3 — 开发阶段

触发条件

用户说「开始开发 <功能点>」

执行步骤

Step 1 — 回顾方案

• 读取该功能点的 <需求名>-feature-<名称>.md
• 简要输出：实现要点 / 关键接口 / 注意事项

Step 2 — 代码对照检查

用户提交代码后（粘贴代码片段 / 提交 diff / 描述实现），对照 feature 文档逐项核查：

• 接口名称、参数、返回值与技术方案一致
• 数据结构字段与技术方案一致
• 边界条件处理（空值、越界、异常场景）
• 错误码定义与技术方案一致
• 权限控制与技术方案一致
• 风险点中标注的注意事项已处理

发现实现偏差时，区分根因并按以下流程处理：

偏差类型	处理方式
代码理解错误	指出问题，给出修正建议，修复后记录偏差原因到开发记录
技术方案描述不清	与用户确认正确实现方式，更新 feature 文档，记录修改理由
影响其他功能点	同步更新技术方案汇总相关章节，并提示用户

Step 3 — 踩坑识别

两种情况分开处理：

• 实现偏差：代码与 feature 文档不一致 → 记录到开发记录，Step 5 自动写入知识库
• 非显然实现：代码与方案一致但用了特殊手段 → 询问：「这个处理方式值得写入知识库踩坑记录吗？」

Step 4 — 更新开发记录

若 Phase 3 子文件夹（根编号.3）不存在，先新建，并在其中创建：

• <需求名>-开发阶段.md 作为 Phase 3 MOC（在需求根 MOC 追加双链：<需求名>-开发阶段）
• <需求名>-开发记录.md 用于记录开发过程（在 Phase 3 MOC 追加双链：<需求名>-开发记录）

将以下内容追加到 <需求名>-开发记录.md：

## <功能点名称> — <日期>
- 实现摘要：
- 偏差记录：（若有，属于「实现偏差」类）
- 踩坑记录：（若有，属于「非显然实现」类）

Step 5 — 自动写入知识库（若提供了知识库）

• 实现偏差（与技术方案不一致）：自动写入知识库 踩坑记录/，无需询问
• 非显然实现（特殊手段、绕过限制）：询问用户后写入 踩坑记录/

Step 6 — 提示下一步

输出：「『<功能点>』开发完成。可继续『开始开发 <下一个功能点>』，或说『联调自测』进入 Phase 4」

所有功能点开发完毕后，将 Phase 3 MOC 的 taskStatus 更新为 "4"（已归档）。

---

Phase 4 — 联调自测

本阶段包含：Code Review → 自测 → 联调记录，可按实际顺序灵活触发。

Phase 4 启动

触发：用户说「开始联调自测」或从 Phase 3 切换进入

进入 Phase 4 时，第一步先建立 MOC：

1. 在需求根目录下新建 Phase 4 子文件夹（根编号.4）
2. 在子文件夹下创建 <需求名>-联调自测.md 作为 Phase 4 MOC，taskStatus 设为 "2"
3. 在需求根 MOC 追加双链：<需求名>-联调自测，并更新「当前状态」字段

4.1 Code Review

触发：用户说「Review」或「帮我看一下代码」

Step 1 — 建立 Code Review 文档

• 在 Phase 4 子文件夹下新建 <需求名>-CodeReview.md
• 在 Phase 4 MOC 中追加双链：<需求名>-CodeReview

Step 2 — 读取 diff 并逐文件检查

读取当前分支 git diff，对照 <需求名>-技术方案汇总.md 逐文件检查：

• 实现是否符合技术方案设计
• 是否存在安全隐患（SQL 注入、XSS、越权等）
• 是否有未处理的异常或边界情况
• 代码可读性与命名规范

输出格式：

### <文件路径>
- [必改/建议/优化] <问题描述>（第 X 行）
  建议：<修改建议>

Step 3 — 模式沉淀识别

归纳 Review 中发现的可复用模式，询问用户是否写入知识库 模式沉淀/。

4.2 自测

触发：用户说「自测」或「生成自测清单」

Step 1 — 生成自测清单

• 在 Phase 4 子文件夹下生成 <需求名>-自测清单.md
• 在 Phase 4 MOC 中追加双链：<需求名>-自测清单

## 自测清单 — <需求名称>

### 功能验证
- [ ] <功能点> 正向流程通过
- [ ] <功能点> 边界条件处理正确

### 异常场景
- [ ] 网络异常处理
- [ ] 参数校验覆盖
- [ ] 权限控制验证

### 回归检查
- [ ] 关联功能未受影响

4.3 联调记录

触发：用户描述联调过程或联调发现的问题

• 在 Phase 4 子文件夹下新建或追加 <需求名>-联调记录.md
• 在 Phase 4 MOC 中追加双链（首次）：<需求名>-联调记录
• 记录内容：联调对象（前端/其他服务）、发现的问题及解决方案、遗留事项

Phase 4 结束

将 Phase 4 MOC 的 taskStatus 更新为 "4"（已归档），提示：「可说『提测』进入 Phase 5 — 测试阶段」

---

Phase 5 — 测试阶段

触发条件

用户说「提测」或「测试阶段」

Phase 5 启动

进入 Phase 5 时，第一步先建立 MOC：

1. 在需求根目录下新建 Phase 5 子文件夹（根编号.5）
2. 在子文件夹下创建 <需求名>-测试阶段.md 作为 Phase 5 MOC，taskStatus 设为 "2"
3. 在需求根 MOC 追加双链：<需求名>-测试阶段，并更新「当前状态」字段

执行步骤

Step 1 — 建立 Bug 跟踪文档

• 在 Phase 5 子文件夹下新建 <需求名>-Bug跟踪.md
• 在 Phase 5 MOC 中追加双链：<需求名>-Bug跟踪

Step 2 — Bug 跟踪记录

用户反馈测试发现的 Bug 时，追加到 <需求名>-Bug跟踪.md：

## Bug 列表

| # | 描述 | 严重度 | 状态 | 修复说明 |
|---|------|-------|------|---------|
| 1 | <Bug描述> | 高/中/低 | 待修复/已修复 | |

Step 3 — 协助 Bug 分析

• 用户提交 Bug 时，Claude 协助：定位原因、对照技术方案分析根因、给出修复建议
• 若 Bug 根因涉及设计问题，标记并更新 <需求名>-技术方案汇总.md 对应章节

Step 4 — 踩坑沉淀

Bug 修复后，询问用户是否将根因分析写入知识库 踩坑记录/。

Phase 5 结束

所有 Bug 修复完毕、测试通过后：

• 将 Phase 5 MOC 的 taskStatus 更新为 "4"（已归档）
• 提示：「可说『验收上线』进入 Phase 6」

---

Phase 6 — 验收上线

触发条件

用户说「验收上线」或「准备上线」

Phase 6 启动

进入 Phase 6 时，第一步先建立 MOC：

1. 在需求根目录下新建 Phase 6 子文件夹（根编号.6）
2. 在子文件夹下创建 <需求名>-验收上线.md 作为 Phase 6 MOC，taskStatus 设为 "2"
3. 在需求根 MOC 追加双链：<需求名>-验收上线，并更新「当前状态」字段

执行步骤

Step 1 — 生成上线 Checklist

• 在 Phase 6 子文件夹下生成 <需求名>-上线Checklist.md
• 在 Phase 6 MOC 中追加双链：<需求名>-上线Checklist

基于技术方案和开发记录，生成上线前确认清单：

## 上线 Checklist — <需求名称>

### 代码准备
- [ ] 所有功能点开发完毕
- [ ] Code Review 问题已全部处理
- [ ] 测试阶段 Bug 已全部修复

### 配置与环境
- [ ] 数据库变更脚本已准备（如有）
- [ ] 配置项变更已同步（如有）
- [ ] 依赖服务已确认就绪

### 上线操作
- [ ] 灰度/分批发布策略已确认（如有）
- [ ] 回滚方案已准备

### 上线后观察
- [ ] 核心监控指标正常
- [ ] 错误日志无异常
- [ ] 关键业务流程验证通过

Step 2 — 验收记录

用户验收完成后，在 Phase 6 子文件夹下新建 <需求名>-验收记录.md，在 Phase 6 MOC 中追加双链：<需求名>-验收记录，记录：

• 验收时间
• 验收结论
• 遗留事项（若有）

Phase 6 结束 — 需求归档

• 将 Phase 6 MOC 的 taskStatus 更新为 "4"（已归档）
• 将需求根 MOC 的 taskStatus 更新为 "4"（已归档）
• 提示：「需求『<需求名称>』已完成，建议将需求文件夹归档」

---

四、知识库内容维护规则

4.1 知识库分类结构

知识库文件夹下应包含以下一级分类子目录：

分类目录	收录内容
概念/	领域概念、名词解释、业务术语
架构决策/	架构选型理由、技术方案关键决策（ADR 格式）
踩坑记录/	具体错误现象 + 根因分析 + 解法
模式沉淀/	可复用的代码模式、设计模式、最佳实践
工具使用/	框架、库、工具的使用技巧与注意事项

---

4.2 知识库更新规则

自动写入（无需询问用户）：

• Phase 2 技术方案汇总完成后：将架构决策自动写入 架构决策/，文件名格式：ADR-<需求名>-<决策主题>.md
• Phase 3 结束后：若开发记录中存在实现偏差（代码与技术方案不一致，如接口调整、数据结构变更、边界处理差异），自动追加到 踩坑记录/

询问后写入：

• 新领域概念（Phase 1 发现）→ 写入 概念/
• 非显然实现（Phase 3 发现）：特殊技巧、绕过框架限制、非常规处理方式 → 询问后写入 踩坑记录/
• Bug 根因（Phase 5 发现）：测试暴露的缺陷根因，尤其是设计层面的问题 → 询问后写入 踩坑记录/
• 模式沉淀（Phase 4 Code Review 后归纳）→ 写入 模式沉淀/

踩坑记录三类边界：

类型	写入方式	定义
实现偏差	自动	做了但做偏了，代码与方案文档不一致
非显然实现	询问	做到了但用了特殊手段，别人不一定知道怎么做
Bug 根因	询问	测试才暴露，属于方案或实现的漏洞

不写入知识库的内容：

• 需求过程性文档（PRD 分析、开发记录等）
• 代码本身能直接表达的内容
• 临时性的实现细节

---

4.3 知识库文件模板

写入知识库的文件统一使用以下 frontmatter：

---
title: <标题>
tags: [<所属分类>]
categories: []
creation_time: "{{date:YYYY-MM-DD HH:mm:ss}}"
updated: "{{date:YYYY-MM-DD HH:mm:ss}}"
date: "{{date:YYYY-MM-DD HH:mm:ss}}"
hide: "true"
maintain: "true"
source_req: <来源需求名称>（可选）
---