设计文档变更日志

记录文档体系的每次修订，便于追溯决策演变。

格式约定：

• 每次修订记录日期、变更内容、变更原因
• 变更类型：新增 / 修改 / 删除 / 拆分 / 合并

---

2026-03-15 — 三级进度追踪体系

设计动机

Plans 文档为静态方案，无进度语义；HANDOFF.md 只有瞬时快照，无全局进度视角。跨多个会话的大任务缺乏"做到哪了"的追踪能力。

核心变更

• 建立三级进度链：features.md（项目级）→ plans/（方案级）→ HANDOFF.md（会话级）
• Plans 模板增加 Progress: n/m 字段和 - [x]/- [ ] 任务清单
• HANDOFF.md 增加 Active Plan 引用和 Session Tasks 复选框清单
• 临时任务→正式 plan 升级规则：未完成项 > 5 且需跨会话时建议升级

文件变更

• 修改 doc-06 §4.3 Plans 模板 — 增加 Progress、Feature、任务清单字段
• 修改 doc-06 §5 /checkpoint 流程 — 增加进度更新步骤
• 修改 doc-19 §4 Handoff 模板 — 从 6 段结构 + docs/handoff/ 归档制统一为 4 段 + 根目录覆写制
• 修改 /plan Skill — 持久化时生成任务清单 + Progress: 0/N
• 修改 /checkpoint Skill — 新增 Step 2 进度更新（勾选完成任务、更新 Progress、完成判定）
• 修改 /handoff Skill — 恢复时展示活跃 plan 进度

---

2026-03-15 — doc-06 文档体系重设计：从目录分类到 AI 知识模型

来源：xiaoxi 真实项目文档产出分析（49 个文件的类型/频率/演变模式）+ 行业调研（Thoughtworks SDD、Addy Osmani LLM Workflow、AWS ADR、Atlassian KB）+ 对话讨论。

核心变更

doc-06 从"按团队惯例分类的目录结构"重设计为"按 AI 知识消费场景组织的三层知识模型"：

• 契约层（spec/prd/product-spec/design-spec）— 定义"建什么、怎么建"
• 状态层（features/approved-deps）— 反映项目当前状态
• 知识层（plans/adr/research/troubleshooting/api）— 持续累积的知识资产

重写

• 重写 06-文档体系.md — 新增知识模型（7 种 AI 场景→文档来源→加载策略）；目录结构从 9 个子目录精简为 5 个；新增格式契约（ADR/Troubleshooting/Plans/Research 四套模板）；新增文件→目录升级制；新增知识沉淀机制（/checkpoint 统一路由）；新增交叉引用指导；新增生命周期表
• 重写 /checkpoint Skill — 从"只写 HANDOFF.md"升级为"知识路由 + HANDOFF 覆写"：Step 1 知识提取→Step 2 归档→Step 3 HANDOFF 覆写→Step 4 统一提交

删除的结构

• docs/prd/（4 文件结构）→ 单文件 docs/prd.md（真实项目验证无人拆分）
• docs/architecture/（overview + tech-stack + adr/）→ 拆为独立 docs/plans/ + docs/adr/
• docs/data/ → 删除（属于 prd 的一部分）
• docs/references/ → 打散到 docs/ 根目录

新增的结构

• docs/plans/ — 技术方案 + 阶段计划（xiaoxi 验证：第二大文档类型，占 25%）
• docs/adr/ — 架构决策记录（从 architecture/ 下提升为一等公民）
• docs/troubleshooting/ — 踩坑知识库（从 issues/ 升级，从事件日志→可复用知识库）

Skill 修改

• 修改 /plan Skill — 新增 Step 5 持久化：方案确认后写入 docs/plans/{slug}.md + 更新索引
• 修改 /debug Skill — 产出路径 docs/issues/ → docs/troubleshooting/，模板调整为症状→根因→解法→防御
• 修改 /takeover Skill — approved-deps 路径 docs/references/ → docs/approved-deps.md

文档更新

• 修改 22-项目知识沉淀机制.md — 沉淀出口从分散收敛到 /checkpoint 统一路由；路径从 issues/ → troubleshooting/、architecture/adr/ → adr/
• 修改 01-CLAUDE-md设计.md — 模板中文档路径对齐新结构（adr/、approved-deps.md、plans/）
• 修改 CLAUDE.md — 架构描述新增三层知识模型引用

核心转变：文档体系的设计视角从"团队文档管理惯例"转向"AI 知识消费场景"。三层理念：Context Engineering（文档为 AI 上下文优化）→ Spec-Driven（先定义再实现）→ Knowledge Accumulation（知识持续沉淀）。参考来源：Thoughtworks SDD | Addy Osmani LLM Workflow | AWS ADR | Atlassian KB

---

2026-03-15 — 新增产品设计阶段：补全生命周期链路断层

来源：系统性诊断发现体系在产品侧→UI 侧的交界面存在 5 个结构性断层：spec → ui-page 之间无页面规格、无权限矩阵、无用户旅程图、无 Design Token 定义、埋点规格完全缺失。两个已有的项目级模板（design-spec-template.md + product-spec-template.md）恰好填补这些缺口，但需要从系统层面整合而非碎片化修补。

新增

• 新增 docs/design/23-产品设计契约.md — 产品设计阶段在生命周期中的定位：阶段位置（spec 之后、plan 之前）、两份文件的协同方式（product-spec 先行→design-spec 跟进→共享词汇表桥接）、与上下游 6 个环节的输入输出关系、项目文件约定、模板内容概览、与 Figma MCP 的关系
• 新增 docs/templates/product-spec-template.md（688 行）— 产品结构契约模板：产品定义、信息架构（站点地图/导航/路由/内容模型）、用户旅程（首次体验/核心循环/转化/支线）、页面注册与职责（状态矩阵/数据流）、用户状态与权限（状态机/权限矩阵）、通知体系、异常旅程（降级/数据边界）、数据分析（埋点漏斗/事件规范）、走查清单、国际化
• 新增 docs/templates/design-spec-template.md（~800 行）— 设计规范契约模板：AI 行为契约（5 项检查）、Design Token 系统（色彩/字体/间距/阴影/圆角/动效）、布局系统、组件规范（全量状态）、交互模式（表单/加载/错误/空态/手势）、组合模式（页面级布局）、图标图片、文案规范、设计走查
• 新增 .claude/skills/product-design/SKILL.md — 产品设计契约 Skill，4 步流程：搜集上下文→生成 product-spec.md（结构先行）→生成 design-spec.md（视觉跟进）→双走查清单验证。红线：product-spec 先于 design-spec、共享词汇表一致、页面双重登记、状态矩阵按类型覆盖

增强

• 增强 .claude/skills/ui-page/SKILL.md — Step 1 前新增 Step 0：读取 product-spec.md 和 design-spec.md，获取页面规格（路由/数据流/状态矩阵）和设计规范（Token/组件），不再盲飞；无文件时回退到原有流程
• 增强 .claude/skills/spec/SKILL.md — §9 UI/UX Notes 从 2 行占位符扩展，新增指引：有 UI 的功能后续用 /product-design 生成完整契约

文档更新

• 修改 00-总体架构.md — §7 项目目录结构新增 product-spec.md、design-spec.md、docs/templates/ 三个位置；关联文档补 doc-23
• 修改 02-Skills技能体系.md — 新增 §4.5 product-design Skill 描述；Skills 总数 21→22；完整清单新增"产品设计"分组；典型工作流新增"有 UI"路径；§4.6-§4.10 编号顺延
• 修改 07-人的操作手册.md — §3.5 全流程总览新增产品设计阶段（/product-design → product-spec + design-spec）；阶段操作表新增产品设计行；阶段跳过规则新增"有 UI + 多页面"行；阶段衔接补充 /product-design 节点
• 修改 11-UI开发策略.md — §4 第三阶段美化：新增 design-spec.md 引用路径（有/无两种提示词模板）；§8 子系统关系新增产品设计契约联动
• 修改 README.md — 索引表新增 doc-23；体系描述 23→24 篇；doc-02 描述更新为 22 个 Skills
• 修改 CLAUDE.md — 架构描述更新：23→24 篇、新增 docs/templates/ 说明

核心转变：这不是"吸收两个模板文件"，而是补全生命周期中缺失的产品设计阶段。补全后，有 UI 的功能从 spec 到美化的完整链路为：spec.md（做什么）→ product-spec.md + design-spec.md（怎么组织 + 怎么看）→ plan（怎么建）→ /ui-page（有规范输入）→ 美化（有 Token 约束）。

---

2026-03-14 — 补充 Prompt Caching 机制、Auto Memory 治理和指令故障排除

来源：对照 Claude Code 官方文档"存储指令和记忆"及外部最佳实践文章，识别出体系在三个点的覆盖缺口。

文档更新

• 修改 13-上下文管理策略.md — 新增 §8 Prompt Caching 章节：缓存机制要点、常见破坏行为、对 MCP/Skill/模型切换设计取舍的底层解释；原 §8/§9 顺延为 §9/§10
• 修改 01-CLAUDE-md设计.md — §6 Auto Memory 从边界表扩充为完整小节：工作机制（MEMORY.md 200 行限制、主题文件按需读取、存储结构）、治理建议；新增 §7 故障排除（指令不被遵循的 5 步排查 + InstructionsLoaded Hook）

设计原则：不搬运配置语法（链接官方文档），只补判断层——解释"为什么这么设计"和"出问题怎么排查"。

---

2026-03-12 — 代码质量管线统一：消除 review 重叠

来源：发现三个"review"工具（内置已废弃的 /review、自定义 /review skill、捆绑 /simplify）职责边界模糊。经调研 Claude Code 内置能力现状和行业分层质量管线最佳实践，统一为三阶段管线。

文档更新

• 修改 02-Skills技能体系.md — §1 内置技能表新增 /security-review；新增"三阶段代码质量管线"和"/simplify 安全使用指南"两个小节
• 修改 10-可靠性保障体系.md — §9 完整流程图"写完了"阶段加入 /simplify → /review → /security-review 管线
• 修改 .claude/skills/review/SKILL.md — 描述明确与 /simplify、/security-review 的分界；安全性维度从 Must Check 降为 Light Check
• 删除 meituan-collector/.claude/commands/review.md — 弱化重复，项目审查规则通过 CLAUDE.md 定制

设计原则：一个阶段一个工具，利用内置能力不自建，自定义 Skill 只做内置做不好的事。

---

2026-03-11 — 补充"执行韧性"原则

来源：Claude Code 使用洞察报告（358 会话/月的实测数据）揭示体系在三个接缝处漏气——会话边界摩擦高、批量操作中途失败无恢复、首轮对齐偏差率 ~1/3。这些不是设计缺陷，而是判断层缺少"韧性"维度。

文档更新

• 修改 00-总体架构.md — §5 新增 5.3"执行韧性"原则（轻量交接 / 渐进执行 / 约束前置），原 5.3→5.4、5.4→5.5
• 修改 .claude/skills/handoff/SKILL.md — 精简恢复流程：6 步→4 步，砍掉验证清单和预读文件步骤，交接字段从 6 个压缩为 4 个（已完成/下一步/关键文件/待决策）
• 修改 ~/.claude/CLAUDE.md（全局）— 外部服务预检新增批量操作渐进验证规则

三处改动遵循"一个原则，两处落地"策略。不新建文档，不新增 Skill，只在判断层补充韧性维度并磨薄现有流程。

---

2026-03-11 — 体系维护范式升级：判断写死，清单写活

来源：对比 Claude Code 2026-03 最新能力（18 个 Hook 事件、Agent Teams 正式化、Plugin 系统、JSON Hook 输出模式等），发现体系的维护痛点不在内容缺失，而在稳定判断与易变清单混杂导致的更新耦合。

核心决策

引入维护原则"判断写死，清单写活"：体系的价值在决策判断（什么时候该用什么），不在信息搬运（事件列表、配置语法、定价数据）。判断层只有范式级变化才更新，参考层标注时效和来源、链接官方文档。

文档更新

• 修改 CLAUDE.md — 新增"文档维护原则"章节，写入判断层/参考层/单一数据源三条规则
• 修改 00-总体架构.md — 新增 §3"人机协作契约"（人的职责/AI 的职责/协作节奏）；新增 §11"文档维护原则"；章节编号顺延（原 §3→§4 ... 原 §9→§10）
• 修改 04-Hooks体系.md — §2 事件表从"按事件类型罗列"重构为"按防线目的组织"（安全/质量/上下文/生命周期），补全 PostToolUseFailure、InstructionsLoaded、ConfigChange、WorktreeCreate/Remove 等新事件，链接官方参考；§3 新增 JSON 结构化输出模式（推荐）；安全防火墙脚本升级为 JSON 输出；修复 §7 子章节编号错误
• 修改 13-上下文管理策略.md — §7 删除硬编码定价表和月度成本表，改为引用 doc-03 §10（单一数据源原则）
• 修改 05-MCP服务体系.md — §2 新增安全基线：enableAllProjectMcpServers: false，防止恶意仓库通过 .mcp.json 注入 MCP 服务器

本次不追求补全所有 Claude Code 新功能。新功能（/loop、Voice Mode 等）待实测验证后再决定是否纳入判断层。体系的韧性来自"不追着功能列表补文档"，而来自"只在范式变化时更新判断"。

---

2026-03-05 — doc-07 新增阶段级路线图

文档更新

• 修改 07-人的操作手册.md — §3.5 新增"阶段级路线图"章节：五阶段全流程（需求定义→工程规格→方案设计→编码实现→验证交付），对齐体系 Skill 设计（/spec→/prd→/plan→§4 循环→/review+/test），/tech-research 定位为可选旁路而非固定阶段

补充宏观路线图，与 §4 日常操作循环形成"宏观阶段→微观操作"的递进结构。

---

2026-03-05 — Skill 微调：/spec 边界探查维度

Skill 更新

• 修改 .claude/skills/spec/SKILL.md — Step 2 维度探查从 6 维度扩展为 7 维度，新增第 6 条"边界"维度（"这次明确不做什么？"），原第 6 条"元问题"顺延为第 7 条

来源：外部项目协作模板借鉴。/spec 输出模板已有 Anti-Goals 和 Out of Scope 字段，但提问流程中缺少显式的边界探查，导致这些字段容易空置。

---

2026-03-05 — 吸收外部方法论提示词模板

来源：《人机协作编程方法论 — What & How 双轮驱动框架》评估后，吸收有操作价值的内容。

文档更新

• 修改 21-面向AI的知识工程方法论.md — §0.2 新增"认知资源管理"底层机制说明（冷区/热区已在前次融入，本次补充角色生效机制）
• 修改 docs/prompts/09-进阶技巧.md — 新增食谱 7"多代理协作"：子代理检查点自查模板（提交前契约兼容性验证）+ 合并验证模板（Lead/Judge 跨模块对齐检查）；组合技巧新增组合 5（多模型 + 多代理）

核心判断：该方法论与体系高度重叠，仅两个提示词模板具备增量价值——子代理自查和合并验证填补了 doc-03 在操作层面的具体模板缺失。

---

2026-03-04 — 融入外部方法论借鉴点

来源：深度分析《人机协作编程方法论 v5》，提取借鉴点融入体系。

文档更新（1 篇设计文档 + 1 个 Skill）

• 修改 21-面向AI的知识工程方法论.md：
  • 导论新增"冷区/热区分离"核心心智模型
  • §1.2 末尾新增"自回归生成惯性（写飞）"底层机制说明
  • 新增 §0"建立正确预期"：§0.1 能力边界（任务规模×类型矩阵 + 10 秒决策法）、§0.2 人的角色定位（项目经理模型 + 三种错位）、§0.3 介入信号（5 个运行时监控信号）
• 修改 .claude/skills/plan/SKILL.md — Step 1 新增"改动性质判断"（兼容型/破坏型分流）；Step 3 新增破坏型改动的接口变更清单模板

核心结论：外部方法论在原则层与体系 100% 重合，但提供了高认知传递效率的表达方式。§0 是全新内容——帮助用户在学习任务设计之前先建立正确的协作预期。

---

2026-03-04 — 适配 Claude Code Auto Memory 机制

来源：评估 Claude Code 内置 Auto Memory 机制对体系的影响，明确 Auto Memory（操作性知识）与结构化沉淀（决策性知识）的分工边界。

文档更新（3 篇）

• 修改 22-项目知识沉淀机制.md — §1 新增"与 Claude Code Auto Memory 的分工"小节：对比表（写入方式/内容类型/版本管理/检索方式/典型内容）、分工原则（Auto Memory 管肌肉记忆，结构化沉淀管认知资产）、沉淀判断补充排除条件
• 修改 01-CLAUDE-md设计.md — §6 末尾新增"与 Auto Memory 的边界"小节：五类信息归属表（规则→CLAUDE.md / 纠正点→常见陷阱 / 操作偏好→Auto Memory / 构建命令→Auto Memory / 架构认知→Auto Memory）、三条判断原则
• 修改 08-运维与持续进化.md — §2 gitignore 列表更新 Memory 条目（旧 .claude/memory.jsonl → 新 ~/.claude/projects/*/memory/）；§4 进化触发条件表新增"Auto Memory 同一模式出现 3+ 次 → 提升为 CLAUDE.md 正式规则"

核心结论：Auto Memory 与体系互补而非冲突。Auto Memory 自动处理低价值高频率的操作经验，体系继续管理高价值低频率的决策知识。体系定位"人机认知对齐的契约层"不受影响。

---

2026-03-03 — 新增 doc-22 项目知识沉淀机制

来源：体系自身评估 — doc-08 管维护、doc-20 管引入，但项目过程中产生的知识（调研结论、踩坑经验、决策上下文）缺少标准化的留存机制。

新增文档

• 新增 22-项目知识沉淀机制.md（~340 行）— 沉淀点设计（在 Skill 工作流关键时刻植入"值得留下吗？"判断）、调研记录（docs/research/）、问题记录（docs/issues/，三问法筛选）、决策记录增强（ADR 上下文加调研链接）、检索协议、与 doc-08/doc-20 三角互补关系

Skills 修改（4 个）

• 修改 /tech-research — Step 5 后 +Step 6 沉淀（保存调研记录 + 更新索引 + ADR 转化提示）
• 修改 /debug — Step 5 后 +Step 6 归档检查（三问法评估 + 生成问题记录 + 更新索引）
• 修改 /retro — Q3 后 +Q4 知识归档引导（issue 归档 / 调研检查 / ADR 补充）
• 修改 /docaudit — +第 6 项检查：知识目录索引一致性 + frontmatter 完整性

同步更新

• 修改 06-文档体系.md — §2 目录结构表追加 research/ 和 issues/ 两个子目录
• 修改 README.md — 索引表追加 doc-22，体系描述 22→23 篇
• 修改 CLAUDE.md — 架构描述 22→23 篇

核心理念：不新建知识管理系统，不新增 Skill，不引入复杂规范。只做三件事：约定两个存放位置、在三个现有 Skill 中植入沉淀触发、给 AI 一条检索规则。

---

2026-03-02 — 批量对齐官方文档 + Figma MCP 深度集成

来源：[定期搜索] Claude Code 官方文档 (code.claude.com/docs/en/) 全面对比 来源：[定期搜索] Figma MCP Server 官方文档 + 社区最佳实践

7 篇设计文档更新（子代理并行执行）

• doc-01：新增 .claude/rules/ 路径范围规则、@path 导入语法、claudeMdExcludes、行数调整为 50-200、五层放置层级、强调语法官方确认
• doc-02：新增官方内置技能（/simplify /batch /debug）、上下文预算数据、Plugin 生态 + Marketplace、动态注入增强
• doc-03：新增子代理持久记忆（memory: user/project/local）、maxTurns、worktree 隔离、Agent(type) 语法、Teams Hooks
• doc-04：新增 HTTP Hooks、SessionEnd/TeammateIdle/TaskCompleted/PermissionRequest 事件、exit code 2 "阻断并反馈"语义、Skill 范围 Hooks
• doc-05：新增 Tool Search 延迟发现（节省 85% token）、Figma 安装/工具/限速全面更新、作用域优先级、静默断开处理
• doc-11：新增 Figma 双向工作流（Code→Figma）、Code Connect 组件映射、组件优先渐进策略、大文件处理、CLAUDE.md Figma 规则
• doc-20：新增 §9 进化触发提示词库（4 类 7 个模板）、§4/§8 增加互补引用

README 索引更新

• doc-01 描述更新（50-200 行、rules/、@path）
• doc-20 描述更新（新增进化触发提示词库）

---

2026-03-02 — 集成 Figma MCP 工作流

来源：调研 Figma 官方 MCP Server + Claude Code 最佳实践

设计文档更新

• doc-05：§4.2 P1 新增 Figma MCP 条目（配置方法、核心工具表、使用场景、注意事项）
• doc-11：§4.3 新增 Figma MCP Design-to-Code 工作流；§5 MCP 配置新增 Figma

---

2026-03-02 — 对齐 Claude Code 最新 Skills/Hooks 特性

来源：对比 code.claude.com 官方文档

Skills Frontmatter 升级（8 个 SKILL.md）

• review / docaudit / health-report / impact：添加 context: fork + agent: Explore + allowed-tools（只读分析类隔离运行）
• checkpoint / commit / retro：添加 disable-model-invocation: true（禁止模型自动触发）
• code-standards：添加 user-invocable: false（背景知识，非用户调用）

设计文档更新

• doc-01：§4 新增 .claude/rules/ 路径关联规则小节
• doc-02：§3 关键字段列表升级为完整 Frontmatter 参考表，补全 6 个缺失字段
• doc-04：§2 事件表新增 SubagentStart / Prompt 事件；末尾新增 §9 Hook 类型扩展（HTTP Hooks、Prompt Hooks、SubagentStart 事件、Skills 内嵌 Hooks）

---

2026-03-02

冻结 CLI 工具 ai-dev-cli

原因：CLI 的三个命令（init/check/takeover）已被对应的 Skills 完全覆盖，且 Skills 版能理解代码语义，效果更好。继续维护 CLI 意味着双重维护（2,320 行代码 + 40 个模板），收益不对称。

• 修改 cli/README.md — 添加冻结状态标注，推荐直接使用 Skills
• 修改 docs/design/README.md — 快速开始改为推荐 Skills，CLI 标注为冻结
• 修改 docs/design/09-脚手架设计.md — 添加冻结状态说明

---

2026-03-01

修改 /prd Skill — 两轮实测驱动的重构

来源：用 agent-growth 风控模块实测 /prd 流程，两轮迭代。

• 修改 .claude/skills/prd/SKILL.md（372→269 行，减 28%）：
  • 第一轮（流程改进）：新增 Step 0 上下文搜集、多输入源支持、Step 3/4 互换（状态机先于数据模型）、新增跨模块合约
  • 第二轮（密度提升）：压缩模板示例（我每次都会重新生成，不需要完整 JSON 示例）、新增范围控制规则（≤5 实体 / ≤20 端点）、新增设计启发（JSON vs 正规化、状态 vs 独立实体、枚举粒度）、每个 Step 加回退信号

修改 README 索引 — 更新 doc-21 描述

• 修改 README.md — doc-21 索引描述从旧版（信息论：三力量、价值密度、双版本架构）更新为当前控制论内容（质量方程、失败模式、任务分解、控制单元、反馈校准）

---

修改 doc-21 全文重写：从"AI 指令写作理论"到"AI 任务设计方法论"

来源：深度讨论 — 实践发现 token 不是瓶颈，清晰度才是；信息价值密度不能替代约束强度；粒度正确性是被忽视的关键因子。

重写内容

• 重写 21-面向AI的知识工程方法论.md（444→377 行），核心问题重新定义为"怎么设计一个任务让 AI 能可靠完成"：
  • 新 §1 质量方程（目标 × 约束 × 粒度，乘法关系）+ 三个真实失败模式（context 漂移、隐式假设填充、完美主义扩散）+ 控制论视角
  • 新 §2 任务分解方法论（旧版完全缺失）：在决策边界拆任务、三维度分解（纵向/横向/维度切面）、粒度校准信号、输入-输出链
  • 新 §3 控制单元七要素（目标/输入/约束/流程/模板/退出条件/交接物）+ Skill 实例化结构
  • 新 §4 三层反馈（单元内/单元间/跨周期）+ 偏差诊断表（9 种症状→根因→修复）
  • 新 §5 设计速查（检查清单 + 写作原则 + 反模式，合并压缩旧版三章内容）
  • 新 §6 体系定位（双版本原则简述 + 知识老化，从独立章节降为附录）
• 删除内容：Token 经济学、价值密度分级、编排即创新哲学、10 条展开式设计原则（压缩为速查表）
• 修改 CHANGELOG.md — 记录本次变更

本次重写的核心转变：doc-21 不再试图回答"怎么给 AI 写好文档"（信息编码问题），而是回答"怎么设计任务让 AI 可靠完成"（行为控制问题）。新增的任务分解方法论（§2）是最大增量 — 这是旧版完全没有触及的关键环节。

---

2026-02-28

新增 doc-21 面向 AI Agent 的知识工程方法论

来源：深度讨论 — 评估外部项目的调研方法论和 PRD 工程规范文档时，发现需要一套元方法论来指导"如何为 AI 编写有效的驱动指令"。

新增文档

• 新增 21-面向AI的知识工程方法论.md（444 行）— 体系元方法论：AI 行为驱动的三种力量（硬约束/结构模板/流程序列）+ 约束力度校准（MUST/SHOULD/MAY 光谱）+ 负面示例机制、价值密度三级分类 + Token 经济学（ROI 分析）、双版本架构 + 多文档优先级与冲突解决、编排即创新 + 知识老化与模型演进、AI 视角 8 条设计原则、6 种反模式、实施指南含反馈闭环（偏差信号诊断表）

同步更新

• 修改 README.md — 索引表新增 doc-21 行，体系描述更新为 22 篇

定位：指导所有其他文档、Skills、Prompt Cookbook 的设计与维护。核心洞察来自 AI 自身视角 — "什么样的写法真正改变我的输出质量"。

---

2026-02-27 (3)

新增 doc-20 体系外部进化机制 + /absorb Skill

来源：体系自身评估 — doc-08 已有完善的内部进化闭环，但缺少外部知识输入的标准化流程。

新增文档

• 新增 20-体系外部进化机制.md（445 行）— 补全外部进化缺口：标准化吸收流程（评估→定位→融合→验证）、五问评估法、五种输入源 SOP（用户喂文章、定期搜索、项目实战反哺、竞品对标、版本追踪）、执行节奏与降级策略、Breaking Change 紧急响应流程

新增 Skills

• 新增 .claude/skills/absorb/SKILL.md — 外部知识吸收技能，7 步流程：获取内容→结构化提取→五问评估→定位影响范围→输出评估报告→等待确认→执行融合

同步更新

• 修改 README.md — 索引表新增 doc-20 行，doc-02 描述更新为 21 个 Skills
• 修改 CLAUDE.md — 设计文档 20→21 篇，Skills 20→21 个
• 修改 02-Skills技能体系.md — Skills 总数 20→21，清单新增 /absorb
• 修改 08-运维与持续进化.md — §4 进化触发表新增外部知识行；月度检查新增外部知识吸收条目；关联文档补 doc-20
• 修改 00-总体架构.md — §9 体系演进方向补充外部进化引用
• 修改 site/sync.mjs — DESIGN_SLUG_MAP 新增 20 映射；skillCategories 新增 absorb；首页数字更新
• 修改 site/.vitepress/config.mts — sidebar 新增 doc-20 和 /absorb 入口

补全从"外部世界吸收养分"的标准化流程。内部闭环（/retro→触发器→老化→健康检查）+ 外部闭环（/absorb→定期搜索→反哺→对标→版本追踪）= 完整持续进化体系。

---

2026-02-27 (2)

P0 更新：对齐 2026 最新实践

来源：体系全面评估 + Anthropic 2026 Agentic Coding Trends Report + 社区最佳实践研究。

重写

• 重写 01-CLAUDE-md设计.md — §2 指令数从 150 行下调至 50-100 行 + 文件引用；新增 WHAT/WHY/HOW 框架、渐进式披露、规则标记粒度指南（NEVER/MUST/IMPORTANT 分级表）；§4 扩充模块层指导；新增 §5 与 Skills/Hooks 优先级关系

增强

• 增强 03-子代理体系.md — §3 压缩冗余示例；§8 Agent Teams 从 39 行扩充至 ~95 行：Planner-Worker-Judge 架构、Tasks DAG 依赖管理、Worktree 隔离、通信机制、五项风险缓解
• 增强 14-技术栈选型指南.md — §5.2 新增"Claude Tool Use 首选"定位，降低对外部编排框架的依赖建议；§6 引入 OpenTelemetry 趋势、修正免费额度引用；§7 修正 Cloudflare 国内访问评估

P0 更新聚焦三个与 2026 现实脱节的关键点。核心转变：CLAUDE.md 从"综合手册"转向"精简纠正点"，Agent Teams 从"实验性"升级为"特定场景推荐"，技术栈评估回归"原生能力优先"。

---

2026-02-27

新增 Codex MCP 异构审查集成

来源：Claude Code + Codex MCP 协作方案 评估整合。

增强

• 增强 05-MCP服务体系.md — §4.3 P2 区新增 Codex MCP 条目：配置命令、门禁触发原则、三节点调用模板、风险缓解表；§8 新增 Codex 与 /review 的协作关系
• 修改 09-进阶技巧.md — 食谱 3 Claude 增强新增异构审查交叉引用
• 修改 04-代码审查.md — 食谱 6 三会话隔离新增 Codex MCP 异构复审引用

定位：P2 可选、门禁触发、不常驻。核心价值在跨模型族反证视角，补足同模型体系的确认偏差。

---

2026-02-24

新增 Git 工作流 + 上下文管理执行手册 + /checkpoint + /resume Skills

来源：ruoyi 项目实战经验泛化回馈。

新增文档

• 新增 18-Git工作流.md（310 行）— 原子提交原则、Conventional Commits 格式（Type/Scope/Subject）、暂存区纪律（禁止 git add .）、分支策略（个人项目简化版）、WIP Commit 四段式模板、绿色基线 Tag、Git 调试（bisect/blame/show）、提交前检查清单
• 新增 19-上下文管理执行手册.md（249 行）— 与 doc-13 互补（策略层 vs 执行层）；五阶段 SOP（Start→Build→Checkpoint→Resume→Close）、WIP Commit 模板、Handoff 六段结构模板、会话切换 Checklist（Outgoing/Incoming）、CLAUDE.md 规则模板、四场景决策树

新增 Skills

• 新增 .claude/skills/checkpoint/SKILL.md — 会话检查点，5 步流程：收集状态→暂存文件→WIP commit→创建 handoff→Outgoing checklist
• 新增 .claude/skills/resume/SKILL.md — 恢复会话上下文，6 步流程：定位 handoff→读取展示→审查 commit→运行验证→Incoming checklist→兜底流程

增强

• 增强 10-可靠性保障体系.md（404→479 行）— §4.1 新增 L0-L4 五层测试分级表；§4.2 新增 AI 生成代码验收标准和 PR 体积控制；新增 §4.4 Flaky 测试处置流程（P1/P2/P3 分级+排障步骤+反模式）；§5 新增 CI 门禁建议；§10 新增 doc-18 引用

同步更新

• 修改 README.md — 索引表新增 doc-18、doc-19，doc-02 描述更新为 20 个 Skills
• 修改 CLAUDE.md — 设计文档 18→20 篇，Skills 18→20 个
• 修改 02-Skills技能体系.md — Skills 总数 18→20，清单新增"会话管理：/checkpoint → /resume"，典型工作流新增会话切换
• 修改 13-上下文管理策略.md — §4.3 检查点模式末尾新增 doc-19 交叉引用；§9 新增 doc-19、/checkpoint、/resume 引用
• 修改 .claude/skills/commit/SKILL.md — 末尾新增 doc-18 引用
• 修改 site/sync.mjs — DESIGN_SLUG_MAP 新增 18/19 映射，skillCategories 新增会话管理分组，首页 features 数字 18→20
• 修改 site/.vitepress/config.mts — sidebar 新增 doc-18/19 入口，Skills 新增会话管理分组

泛化要点：删除 ruoyi 项目的具体案例和脚本依赖，改为通用模板和 CLAUDE.md 规则；命令从 pnpm/turbo 改为通用 npm run；分支策略简化为个人开发者友好版。

---

2026-02-20 (8)

新增 doc-17 API 接口维护体系

• 新增 17-API接口维护体系.md — Schema as Single Source of Truth 工作流：Zod .openapi() 元数据增强、按域路由注册、apiHandler 包装器（28 行→9 行样板消除）、OpenAPI JSON 生成脚本、CI 一致性检查、VitePress + Scalar 渲染集成
• 更新 README.md 索引表 — 新增 doc-17 条目，文档总数 17→18 篇

来源：实际项目中 API 文档与代码脱节的痛点总结。将散落在 doc-01（Zod 约定）、食谱 01 §3（API 契约）、食谱 02 §3（新增 API）中的 API 相关指导，提升为独立的接口维护子系统设计。

---

Skills 资源导航 + review 改进

• 新增 02-Skills技能体系.md §8「Skills 资源导航」— 官方资源（4 项）、社区市场（5 项）、功能增强套件（2 项）、快速安装命令
• 改进 .claude/skills/review/SKILL.md — 借鉴官方 code-review 插件，新增置信度标注、新旧问题区分、假阳性过滤清单
• 精简 02-Skills技能体系.md §4.6 review — 从 60 行内联代码块转为摘要格式（文档内嵌版本已过时），指向实际 SKILL.md

来源：对比 anthropics/claude-code 官方 code-review 插件与本地 /review skill，吸收多 Agent 验证的核心理念（置信度评分、假阳性过滤、git blame 上下文），保留本地优势（5 维度审查、规格对照、零 GitHub 依赖）。

---

2026-02-19 (6)

文档体系去重精简 + Prompt 增强 + 快速上手合并

• 新增 docs/prompts/10-技术调研.md — 技术选型对比、开源评估、调研成果转化（ADR链路）、任务拆解（依赖+并行标注）、行业标准梳理
• 增强 docs/prompts/04-代码审查.md — 安全审查食谱扩展 OWASP 7-9（依赖漏洞、日志泄露、加密合规）
• 增强 docs/prompts/06-重构优化.md — 性能优化食谱新增 Profiling 驱动诊断工具箱
• 精简 15-Prompt工程实战.md — 从 241→156 行，删除与 Prompt Cookbook 重复的 §3 高频库（8个表格）和 §4 完整反模式表格，重新定位为"理论框架+进阶技巧+个人积累区"
• 精简 07-人的操作手册.md §5 — 提示词速查从 3 个完整表格精简为四要素表+5条高频提示词，链接 Prompt Cookbook
• 精简 12-效率最佳实践.md §5 — 反模式从 2 个完整表格精简为 6 条速查，链接 doc-15
• 精简 02-Skills技能体系.md — 从 509→487 行，压缩 §7.5 参数传递示例
• 合并 QUICKSTART.md + WALKTHROUGH.md → 统一快速上手指南（310 行），Part1 基础循环 + Part2 进阶实战 + Part3 体系导航
• 删除 WALKTHROUGH.md — 内容已合并入 QUICKSTART.md
• 更新 prompts/README.md 索引表 — 新增 10-技术调研条目

来源：评估 claude-code-prompts-v2.md 后，吸收有价值增量（调研转化链路、任务拆解、Profiling 驱动、OWASP 扩展），同时精简 4 处文档间内容重复。

---

2026-02-19 (5)

提交粒度与审查粒度指导

• 修改 .claude/skills/commit/SKILL.md — 新增「提交粒度：小步频繁提交」章节，区分立即 commit 与积累后 commit 的场景
• 修改 .claude/skills/review/SKILL.md — 新增「审查粒度」章节，明确 review 在 PR/MR 级别进行
• 修改 07-人的操作手册.md — §4 日常操作循环"收尾"改为"提交（按逻辑单元）"；新增 §11 提交与审查的粒度；原 §11 每日检查清单改为 §12
• 修改 02-Skills技能体系.md — §4.8 commit 新增提交粒度说明；§4.6 review 新增审查粒度说明

核心原则：按逻辑单元提交，按功能单元 review。

---

2026-02-19 (4)

docs/ 目录统一完整结构

• 修改 06-文档体系.md — 定位从"最小化但不缺失"改为"所有项目统一完整结构"；去掉三级分类（必须/推荐/不需要），改为统一目录树 + 各子目录说明表；docs/approved-deps.md 路径改为 docs/references/approved-deps.md；ADR 路径改为 docs/architecture/adr/；文档自动化规则示例路径同步更新
• 修改 00-总体架构.md — §6 项目目录结构从 adr/ + approved-deps.md 替换为完整 docs/ 子目录树（13 个文件）
• 修改 09-脚手架设计.md — Level 0 追加完整 docs/ 结构的 13 个文件；Level 1 移除 docs/features.md（已在 Level 0）；Level 3 移除 docs/approved-deps.md 和 docs/adr/（已在 Level 0）；§4.1 模板目录描述同步更新
• 修改 cli/src/commands/init.ts — initLevel0() 追加 13 个 docs 文件生成；initLevel1() 移除 features.md 生成代码；initLevel3() 移除 approved-deps.md 和 adr/.gitkeep 生成代码
• 修改 cli/src/commands/takeover.ts — approved-deps.md 路径全部改为 docs/references/approved-deps.md，目录创建改为 docs/references
• 移动 cli/templates/level-1/docs/features.md.tpl → cli/templates/level-0/docs/features.md.tpl
• 移动 cli/templates/level-3/approved-deps.md → cli/templates/level-0/docs/references/approved-deps.md
• 新增 11 个模板文件（cli/templates/level-0/docs/ 下）— README.md、prd/（4 文件）、architecture/（3 文件含 adr/001-template.md）、api/api-spec.md、data/data-spec.md、references/resources.md
• 修改 16 个文件批量路径更新 — docs/approved-deps.md → docs/references/approved-deps.md，docs/adr/ → docs/architecture/adr/（涉及 Skills、CLI 模板、设计文档、Prompt 食谱）
• 修改 site/.vitepress/config.mts — approved-deps 链接从 Level 3 移至 Level 0

Breaking Change：所有项目 docs/ 目录在 Level 0 即全量生成完整结构。approved-deps.md 新路径为 docs/references/approved-deps.md，adr/ 新路径为 docs/architecture/adr/。已安装 pre-bash-dep-guard.sh Hook 的项目需要更新脚本中的白名单路径。

---

2026-02-19 (3)

新增 Prompt Cookbook — 提示词食谱（10 篇）

• 新增 docs/prompts/ 目录 — 一级目录，10 篇 Prompt Cookbook 食谱 + README 索引
• 新增 docs/prompts/README.md — Cookbook 索引页，按生命周期阶段分 4 组导航
• 新增 docs/prompts/00-需求分析.md — 模糊想法→结构化需求、用户故事、竞品分析、可行性评估、MVP 定义（6 个食谱）
• 新增 docs/prompts/01-架构设计.md — 技术选型对比、系统架构、API 契约、数据模型、模块划分、ADR（6 个食谱）
• 新增 docs/prompts/02-代码实现.md — 锚定文件、契约先行、API/组件/DB 迁移、小步迭代、三方集成（7 个食谱）
• 新增 docs/prompts/03-测试验证.md — 单元测试、集成测试、边界条件、Mock 构造、回归测试、E2E（6 个食谱）
• 新增 docs/prompts/04-代码审查.md — Diff 审查、安全审查、性能审查、对抗测试、方案对比、三会话隔离（6 个食谱）
• 新增 docs/prompts/05-调试排错.md — 根因定位、回归测试先行、影响分析、日志注入、性能瓶颈、依赖冲突（6 个食谱）
• 新增 docs/prompts/06-重构优化.md — 模块拆分、类型增强、性能优化、代码异味、依赖升级、遗留代码（6 个食谱）
• 新增 docs/prompts/07-文档写作.md — README、API 文档、CHANGELOG、ADR、内联注释、用户文档（6 个食谱）
• 新增 docs/prompts/08-运维部署.md — CI/CD、Dockerfile、环境配置、部署脚本、监控告警、故障恢复（6 个食谱）
• 新增 docs/prompts/09-进阶技巧.md — Prompt 链、上下文管理、多模型协作、会话分治、元提示词、个人库构建（6 个食谱）
• 修改 site/sync.mjs — 新增 PROMPTS_SLUG_MAP 映射表、rewritePromptsLinks() 函数、Step 5 Prompt Cookbook 同步逻辑、首页新增食谱卡片
• 修改 site/.vitepress/config.mts — nav 新增 "Prompt 食谱" 入口，sidebar 新增 /prompts/ 四组分类
• 修改 CLAUDE.md — 架构说明新增 /docs/prompts/ 描述

Prompt Cookbook 定位为通用深度食谱（场景级），与 doc-15 Prompt 工程实战（概念级）和 Skills（工具级）形成三层互补。每篇 5-8 个食谱，统一格式：场景描述 → 核心模板（）→ 变量说明 → 好坏对比 → 实战案例 → Claude 增强。

---

2026-02-19 (2)

新增 16-功能清单体系 + /features Skill

• 新增 16-功能清单体系.md — 功能全景视图、开发进度跟踪、测试覆盖关联三大能力；定义 docs/features.md 的 Markdown 格式规范（5 种状态、7 列字段、模块分组）；维护纪律与规模控制
• 新增 .claude/skills/features/SKILL.md — /features Skill，三个子命令：add（添加功能条目）、update（批量更新状态和测试覆盖）、report（输出进度统计报告）
• 新增 cli/templates/level-1/docs/features.md.tpl — Level 1 初始化时自动生成功能清单模板
• 修改 cli/src/commands/init.ts — Level 1 新增 features.md.tpl 生成逻辑
• 修改 cli/src/commands/check.ts — 新增 checkFeaturesDoc() WARN 级别检查（存在性、表头格式、ID 唯一性、状态合规性）
• 修改 site/sync.mjs — DESIGN_SLUG_MAP 新增 16 号文档映射
• 修改 02-Skills技能体系.md — Skills 总数从 17 更新为 18，新增 /features
• 修改 06-文档体系.md — "推荐有"分类新增功能清单条目
• 修改 10-可靠性保障体系.md — 功能级测试覆盖视角联动
• 修改 README.md — 索引表新增 16 号文档，doc-02 描述更新为 18 个 Skills
• 修改 CLAUDE.md — Skills 数量从 17 更新为 18，设计文档从 16 篇更新为 17 篇

功能清单定位为"推荐有"（中大项目），不强制要求。CLI Level 1 自动生成模板，/features Skill 封装所有维护操作。与 /plan、/test、/health-report 联动形成闭环。

---

2026-02-19

新增 /tech-research Skill — 技术调研

• 新增 .claude/skills/tech-research/SKILL.md — 技术调研技能，5 步流程：界定调研范围 → 执行调研（Web Search） → 综合整理 → 输出建议 → 等待确认。覆盖 5 个维度（标准与规范、开源生态、最佳实践、竞品分析、性能参考），使用 context: fork 隔离执行
• 新增 cli/templates/level-3/tech-research.md — 脚手架模板，Level 3 初始化时自动生成
• 修改 cli/src/commands/init.ts — Level 3 新增 tech-research Skill 生成
• 修改 02-Skills技能体系.md — Skills 总数从 16 更新为 17，新增 §4.2 tech-research，子节编号顺移，§7.3 示例压缩
• 修改 README.md — doc-02 描述中 Skills 数量从 16 更新为 17
• 修改 CLAUDE.md — Skills 数量从 16 更新为 17
• 修改 site/.vitepress/config.mts — Skills 侧边栏"需求与规划"新增 /tech-research 链接
• 修改 site/sync.mjs — skillCategories 新增 tech-research，首页特性数量更新为 17

典型工作流：技术选型 → /tech-research → /spec → /plan → 编码。context:fork 隔离执行避免大量 web search 占用主会话上下文。

---

2026-02-18 (7)

新增 /docs-site Skill — VitePress 文档站搭建

• 新增 .claude/skills/docs-site/SKILL.md — VitePress 文档站搭建技能，5 步流程：确认需求 → 初始化 VitePress → 生成文档模板 → 配置 Cloudflare Pages 部署 → 验证构建
• 新增 cli/templates/level-3/docs-site.md — 脚手架模板，Level 3 初始化时自动生成
• 修改 cli/src/commands/init.ts — Level 3 新增 docs-site Skill 生成
• 修改 02-Skills技能体系.md — Skills 总数从 15 更新为 16，新增"脚手架"分组（/ui-page + /docs-site）
• 修改 README.md — doc-02 描述中 Skills 数量从 15 更新为 16
• 修改 site/.vitepress/config.mts — Skills 侧边栏新增 /docs-site 链接，"UI 与项目接管"拆分为"脚手架"和"项目接管"两组

通用型文档站搭建技能，归入 Level 3 脚手架类，与 /ui-page、/takeover 并列。

---

2026-02-18 (6)

模型定价与成本策略更新

• 修改 03-子代理体系.md §10 — 模型分级策略从旧款 Opus 4 定价（$15/$75）更新为 Opus 4.6（$5/$25）；成本比例从"Sonnet 约为 Opus 的 1/5"修正为"~0.6x"，Haiku 从"1/30"修正为"~0.2x"；新增定价对比表和 SWE-bench 基准测试参考；"何时值得用 Opus 子代理"补充复杂调试和纠错成本考量
• 修改 12-效率最佳实践.md §11.5 — 定价表更新为 Opus 4.6/Sonnet 4.6/Haiku 4.5 三款当前模型；费用估算表按新定价重算（Opus 列从旧 5x 降为 ~1.67x）；模型选择策略新增 Haiku 4.5 适用场景；月度成本预期按新定价下调

Opus 4.6 定价较旧款 Opus 4 大幅下降（$15→$5 输入，$75→$25 输出），Sonnet 4.6 编码能力接近 Opus（SWE-bench 79.6% vs 80.8%），成本策略从"尽量用 Sonnet 省钱"调整为"按推理深度需求选择，成本差距已不大"。

---

2026-02-18 (5)

CLI Skills 全量迁移 + 权限规则修复

• 修改 09-脚手架设计.md — Level 1 从 .claude/commands/ 迁移至 .claude/skills/ 格式；Level 2 补全遗漏的 2 个 Hook 脚本（post-write-size-guard / pre-bash-dep-guard）；Level 3 从 2 个 Skills + 2 个 Commands 扩展为完整 12 个 Skills；§4.1 目录结构和 §4.2 init 说明同步更新；--fix 描述对齐实际行为
• 修改 cli/src/commands/init.ts — initLevel1 从生成 commands 改为生成 skills；initLevel3 从 commands+skills 混合改为全部 skills（12 个）；选项标签和级别描述改为中文；VERSION 同步为 2.0.2
• 修改 cli/templates/level-0/settings.json.tpl — 修复 deny 规则 :* 语法错误（Bash(curl:*|*sh) → Bash(curl *|*sh)），避免 Claude Code 解析报错
• 修改 cli/templates/level-1/*.md — 3 个模板从 commands 格式转为 skills YAML frontmatter，内容从简化英文版替换为完整中文版
• 修改 cli/templates/level-3/debug.md + doc.md — 同上，commands → skills 格式
• 修改 cli/templates/level-3/code-standards.md + spec.md — 英文内容替换为中文完整版
• 新增 cli/templates/level-3/ 下 8 个 Skill 模板 — check / test / impact / retro / health-report / docaudit / takeover / ui-page

CLI 全量迁移至 Skills 体系：Level 1 生成 3 个核心 Skills，Level 3 累计 16 个 Skills，与项目 .claude/skills/ 完全对齐。修复 settings.json deny 规则语法兼容性问题。

---

2026-02-18 (4)

一致性修复 — 文档与脚手架对齐

• 修改 cli/src/commands/check.ts — 新增 checkAnyType() 和 checkDefaultExport() 两个检查函数，补全 doc-09 承诺的 any 类型和 default export 粗筛检查；检查函数总数从 8 增至 10
• 修改 09-脚手架设计.md — §4.1 和 §7 检查函数表更新为 10 个，新增 checkAnyType 和 checkDefaultExport 行
• 修改 02-Skills技能体系.md — §1 补充 doc-15 交叉引用；§4.5 debug 和 §4.7 doc 的 SKILL.md 示例补充 allowed-tools 声明，与 CLI 模板对齐
• 修改 00-总体架构.md — 末尾补充关联文档引用（含 doc-15）
• 修改 CHANGELOG.md — 修正 2026-02-18 (2) 条目计数表述歧义（"15 篇（含 CHANGELOG）" → "15 篇（00-14）"）

一致性审计修复：补全 CLI 未实现的文档承诺、对齐文档与代码的 allowed-tools 声明、完善 doc-15 交叉引用网络。

---

2026-02-18 (3)

文档结构优化 + 新增 15-Prompt 工程实战

• 新增 15-Prompt工程实战.md（~250 行）— 整合 07/12 分散的 Prompt 内容，提供 8 类场景高频库（任务启动/代码实现/验证测试/代码审查/调试修复/重构优化/会话管理/知识沉淀）、反模式（致命 + 低效）、5 种进阶技巧（锚定文件/约束注入/分步引导/角色切换/精确纠错），以及个人积累区（§6 持续更新）
• 修改 08-运维与持续进化.md — 合并 §4「月度体检」和 §7「文档体系健康检查清单」为统一的「§7 健康检查清单（月度+季度）」，消除内部重叠；§4 保留进化触发条件和规则老化机制，新增指向 §7 的指针
• 修改 07-人的操作手册.md — §5 末尾新增 Doc 15 交叉引用
• 修改 12-效率最佳实践.md — §5 末尾新增 Doc 15 交叉引用
• 修改 README.md — 新增 15 篇索引行，更新 08 篇描述
• 修改 CLAUDE.md — 15 篇（00-14） → 16 篇（00-15）

新增第 15 篇，体系文档总数升至 16 篇。Prompt 知识从两处分散段落升级为独立可维护文档，Doc 08 检查清单合并为更清晰的两级结构。

---

2026-02-18 (2)

新增 14-技术栈选型指南

• 新增 14-技术栈选型指南.md（382 行）— 融合 AI-First-Tech-Stack-Guide.docx 原始素材与 2025-2026 在线最新实践；核心补充：LLMOps 可观测性层（Langfuse / LangSmith / AgentOps）、Vercel AI SDK、CrewAI / OpenAI Agents SDK、Cloudflare Workers AI 边缘部署方案、S/A/B/C 四级 AI 友好度分级表、快速决策树

新增第 14 篇，设计文档总数升至 15 篇（00-14）

---

2026-02-18

文档体系迭代 v2 — 对齐 Claude Code 官方最佳实践

Stage A: 创建

• 重写 03-子代理体系.md（151→433 行）— 新增自定义子代理（§3，文件格式/frontmatter/实战示例）、权限模式（§4，六种模式决策表）、子代理记忆与技能注入（§5）、Agent Teams 实验性功能（§8）、选择指南决策树（§9）
• 新增 13-上下文管理策略.md（~350 行）— 上下文窗口基础、会话管理命令速查（/clear/compact/rewind/continue/resume/rename）、主动控制策略（一任务一会话/检查点模式/两次纠错规则）、子代理保护上下文、退化识别与应对、成本视角、四大反模式
• 修改 00-总体架构.md — .claude/agents/ 描述更新，不再说"不需要自定义 agent 文件"

Stage B: 增强

• 修改 07-人的操作手册.md（260→~325 行）— 新增 §4.5 验证优先工作流（三层验证体系/提示词模板/验证节奏/CLAUDE.md 规则模板）；§8 末尾增加 13 篇交叉引用
• 修改 02-Skills技能体系.md（493→~478 行）— 压缩 §4.2 /spec 和 §5.3 /takeover 内嵌代码块为摘要+链接；扩充 §7 进阶（context:fork 隔离执行、!command 动态注入、$ARGUMENTS[N] 参数传递）
• 修改 08-运维与持续进化.md（295→~330 行）— 新增 §6.5 新兴生态：插件与分发（Plugins 概念/结构/评估原则/保守策略）
• 修改 10-可靠性保障体系.md（540→~400 行）— /impact、/test、/health-report 三个 Skill 完整 YAML 块替换为摘要表格+链接引用，修复超 500 行问题
• 修改 12-效率最佳实践.md（537→~500 行）— 精简 §8 @引用策略、§9 检查点提交模式、§11.5 成本表格

Stage C: 同步

• 修改 README.md — 新增 13 篇索引行，更新 03 篇描述
• 修改 CHANGELOG.md — 新增本次迭代条目
• 修改 CLAUDE.md — "13 篇" → "14 篇"
• 修改 site/sync.mjs — 新增 13 篇 slug 映射，首页 feature "13 篇" → "14 篇"
• 修改 site/.vitepress/config.mts — sidebar 新增 13 篇入口
• 新增 docs/WALKTHROUGH.md — 进阶演练（以个人知识库 API 为例的完整开发循环）

涉及 15 个文件，对齐 Claude Code 官方最佳实践中的自定义子代理、权限模式、上下文管理、验证优先、插件生态等重要主题。

---

2026-02-17 (8)

新增 /spec Skill — 需求分析与产品定义

• 新增 .claude/skills/spec/SKILL.md — 需求分析与产品定义技能，合并需求收集（苏格拉底提问、清晰度评分）与产品定义（策略探索、用户故事/验收标准、特性分解、数据模型、API 概要），产出单文件 spec.md
• 新增 cli/templates/level-3/spec.md — 脚手架模板，Level 3 初始化时自动生成
• 修改 cli/src/commands/init.ts — Level 3 新增 spec Skill 生成
• 修改 02-Skills技能体系.md — 新增 §4.2 spec，子节编号 4.2→4.7 顺移，Skills 总数从 14 更新为 15，新增典型工作流说明
• 修改 CLAUDE.md — Skills 数量从 14 更新为 15
• 修改 cli/README.md — 生成文件清单补充 spec Skill，Level 3 描述更新

典型工作流：小功能 → /plan → 编码；中大功能 → /spec → /plan → 编码；接手项目 → /takeover → /spec → /plan → 编码。

---

2026-02-17 (7)

清理 09-脚手架设计.md 过时 bash 代码

• 修改 09-脚手架设计.md（1001→301 行）— 移除约 770 行旧版 bash 实现代码，替换为当前 TypeScript CLI 架构描述
  • §4：init.sh 完整设计（486 行 bash）→ CLI 实现架构（源码目录结构 + 关键模块说明）
  • §6：safe_write 函数 → safeWrite()/appendGitignore()/mergeJsonFile() TypeScript 描述
  • §7：check 模式核心实现（118 行 bash）→ 8 个检查函数列表及 --fix/--ci 行为说明
  • §8：takeover 模式核心实现（113 行 bash）→ 检测逻辑和输出物描述
  • §9：主入口重构（53 行 bash）→ 删除，内容已被 §4 架构描述覆盖
  • §11：后续扩展 更新为 TypeScript 模块化扩展方式
  • 章节编号从 11 个压缩为 10 个（§9 CI 集成、§10 后续扩展）

里程碑：设计文档与 TypeScript CLI 实现完全对齐，无残留 bash/jq 引用。

---

2026-02-17 (6)

CLI 发布到 npm

• 修改 cli/package.json — 新增 repository、homepage、keywords 字段
• 新增 cli/README.md — npm 包页面说明（Quick Start、Init Levels、Usage、生成文件清单）
• 修改 CLAUDE.md — 架构描述补充 npm 包信息
• 修改 09-脚手架设计.md — 所有命令示例从 ./ai-dev.sh 更新为 npx ai-dev-cli，使用方式改为 npm 安装，CI 集成更新
• 修改 README.md — "下一步"章节更新为已完成状态
• 修改 QUICKSTART.md — 初始化命令从 ./scripts/ai-dev.sh init 0 更新为 npx ai-dev-cli init --level 0

里程碑：ai-dev-cli@2.0.0 发布到 npm，用户一行 npx ai-dev-cli init 即可初始化。

---

2026-02-17 (5)

UI 开发策略增加设计参考资源

• 修改 11-UI开发策略.md — 新增"设计参考资源"章节：可出代码的组件库（Magic UI、Aceternity UI、Tailwind UI）、AI 编程专用工具（v0.dev、21st.dev、Realtime Colors）、截图参考来源（Mobbin、Godly、Dribbble、Figma Community）、美化阶段推荐工作流
• 修改 README.md — 更新 11 文档描述

核心原则：选有现成代码的设计系统作基础，用截图参考指导风格，AI 还原度最高。

---

2026-02-17 (4)

Init 命令增加数据库方案选择

• 修改 cli/src/utils/prompt.ts — 新增 select() 交互式列表选择函数
• 修改 cli/src/types.ts — 新增 DatabaseOption 类型，InitOptions 增加 database 字段
• 修改 cli/src/commands/init.ts — 新增数据库方案选择交互步骤，4 种方案的模板变量映射
• 修改 cli/src/index.ts — 新增 --database CLI 选项
• 修改 cli/templates/level-0/CLAUDE.md.tpl — 硬编码技术栈替换为 6 个模板变量
• 修改 cli/templates/level-3/approved-deps.md — 数据库依赖替换为 模板变量
• 修改 09-脚手架设计.md — init 执行流程新增数据库方案选择步骤

4 种数据库方案：prisma-sqlite（默认）、prisma-pg、supabase-cloud、supabase-cn。

---

2026-02-17 (3)

脚手架 Node.js CLI 重写

• 新增 cli/ 目录 — Node.js CLI 工具 ai-dev-cli（TypeScript + commander）
  • src/ — 源码（index.ts 入口 + init/check/takeover 三命令 + utils 工具模块）
  • templates/ — 独立模板文件（从 bash heredoc 提取，level-0 到 level-3 + takeover）
  • package.json — 可发布到 npm，npx ai-dev-cli init 即可使用
• 删除 scripts/ai-dev.sh（1098 行）+ scripts/README.md（371 行）— 功能已由 CLI 完全替代
• 依赖精简：仅 commander 一个运行时依赖，零外部工具依赖（不再需要 jq）
• 跨平台支持：macOS / Linux / Windows

里程碑：脚手架从 1098 行 bash 脚本升级为可测试、可发布的 TypeScript CLI 工具。

---

2026-02-17 (2)

体系实现与增强

• 新增 docs/QUICKSTART.md（~160 行）— 快速上手指南，以 Todo API 为例的端到端开发循环演示
• 新增 13 个 SKILL.md 实现文件（.claude/skills/ 目录下）：
  • 日常开发：code-standards、plan、review、debug、commit、doc
  • 持续合规：check、takeover
  • 可靠性：impact、test、health-report
  • UI 开发：ui-page
  • 进化闭环：retro（新增 Skill，会话回顾）
• 修改 02-Skills技能体系.md — Skills 总数从 12 更新为 14（新增 /retro 和 /ui-page）
• 修改 11-UI开发策略.md — 新增 Taro 移动端方案（方案四）、推荐技术栈总览、Taro CLAUDE.md 规则模板
• 修改 12-效率最佳实践.md — 新增 §11.5 成本意识（API 成本量级参考、优化策略、模型选择、月度预期）；/retro 加入使用频率预判
• 修改 README.md — 更新技术栈描述、新增 QUICKSTART 指引、更新 02/11/12 文档描述
• 删除 files1/、files2/ — 参考材料精华已融入体系，原始文件不再保留

里程碑：14 个 Skills 全部从设计文档落地为可执行的 SKILL.md 文件。

---

2026-02-17

集成 Dev Workflow Skills 精华

来源：files1/（项目审计技能包）、files2/（6 阶段开发工作流技能包），选择性提取有价值的内容融入现有体系。

• 修改 06-文档体系.md（152→167 行）— 将轻量 PRD 从"不需要的"调整为"推荐有的"，新增 PRD 使用条件和 5 个核心章节说明
• 修改 02-Skills技能体系.md（519→490 行）— 精简路由表/配合/check 等章节（-49 行）；增强 /plan Skill 加入按规模分路径的需求结构化和精简 PRD 产出；增强 /takeover Skill 加入文档盘点、逆向架构快照和置信度标注；增强 /review Skill 加入规格对照审查维度
• 修改 12-效率最佳实践.md（454→481 行）— 新增 §3.5 按规模选择开发模式（小/中/大功能分级流程 + 大功能实现顺序模式）

决策：不引入独立的 6 阶段流水线或 Orchestrator，保持 Skills 独立可调用的设计原则。

---

2026-02-15 (4)

新增脚手架使用说明文档

• 新增 scripts/README.md（371 行）— ai-dev.sh 面向用户的完整使用手册，涵盖三种模式（init/check/takeover）的命令参考、生成文件速查表、Hooks 说明、CI 集成示例和 FAQ

---

2026-02-15 (3)

融入四维协同架构洞见

来源：四维协同架构框架（Tactics / Connectivity / Strategy / Philosophy），筛选对个人开发者有实操价值的内容融入现有文档。

• 修改 00-总体架构.md（175→225 行）— 新增 §9 体系演进方向（成熟度信号、跨项目知识迁移、战术 vs 战略优先级）
• 修改 07-人的操作手册.md（217→259 行）— 新增 §10 认知管理（信任校准、认知负载预算、跨会话学习）
• 修改 08-运维与持续进化.md（267→295 行）— 新增战略级触发器 + 规则老化机制
• 修改 12-效率最佳实践.md（450→454 行）— 新增架构决策会话类型 + 军规例外说明
• 修改 10-可靠性保障体系.md（528→540 行）— 新增审查者自身可靠性章节

⚠ 10-可靠性保障体系.md 超过 500 行限制（540 行），需要后续拆分。

---

2026-02-15 (2)

落实 Insights 报告建议

• 新增 ~/.claude/CLAUDE.md — 全局工作流偏好（中文交流、英文注释、Conventional Commits、文档工作流、项目分析流程、会话管理）
• 新增 ai-dev-lifecycle/CLAUDE.md — 项目级规则（架构描述、CHANGELOG 同步、README 索引更新、500 行上限、配置示例规范）
• 新增 .claude/skills/docaudit/SKILL.md — 文档体系审计技能（索引一致性、编号连续性、CHANGELOG 时效性、行数检查、交叉引用检查）
• 修改 02-Skills技能体系.md — 新增 §5.2 docaudit 技能，Skills 总数从 11 更新为 12
• 修改 README.md — 更新 02 文档的描述，反映 docaudit 新增

---

2026-02-15

体系初始化

• 新增 初始化 Git 仓库，添加 .gitignore
• 新增 本变更日志（CHANGELOG.md）
• 修改 08-运维与持续进化.md — 补充"文档体系健康检查清单"章节（第 7 节），涵盖每月检查和每季度检查两个维度

初始文档清单（v1.0）

编号	文档	行数
00	总体架构	175
01	CLAUDE.md 设计	161
02	Skills 技能体系	477
03	子代理体系	151
04	Hooks 体系	359
05	MCP 服务体系	234
06	文档体系	152
07	人的操作手册	217
08	运维与持续进化	208 → 260（新增健康检查清单）
09	脚手架设计	981
10	可靠性保障体系	527
11	UI 开发策略	346
12	效率最佳实践	449