20 - 体系外部进化机制
1. 定位
补全 doc-08 缺失的外部进化能力。
08-运维与持续进化 已建立完善的内部进化闭环：
/retro 会话回顾 → 进化触发器 → 规则老化清理 → 健康检查但整个闭环基于项目内部积累，缺少从外部世界吸收养分的标准化通道。当工具链更新、社区出现新的最佳实践、或用户在其他项目中获得新经验时，没有规范的方式将这些外部知识融入体系文档。
内部闭环 vs 外部闭环
内部闭环 (doc-08) 外部闭环 (doc-20)
/retro 会话回顾 /absorb 外部吸收
进化触发器 定期搜索
规则老化清理 项目实战反哺
月度/季度健康检查 竞品对标 + 版本追踪
│ │
└──────── 融合 ────────────┘
│
体系文档更新 → CHANGELOG 标注来源 → /docaudit 验证三原则
- 输入有标准 — 不是看到什么就往里塞，每条外部知识经过结构化评估
- 吸收有流程 — 从评估到融合有明确的阶段和操作规范
- 融合有验证 — 融入后必须通过 /docaudit 和站点构建验证
互补关系
| 机制 | 职责 | 知识来源 | 输出方向 |
|---|---|---|---|
/retro | 会话级经验沉淀 | 本项目本次会话 | CLAUDE.md 规则 |
/tech-research | 编码前技术选型 | Web 搜索 | docs/research/ |
/absorb | 外部知识融入体系 | 文章、更新、竞品 | 体系文档（design/prompts/skills） |
| doc-08 健康检查 | 体系内部维护 | 项目内积累 | 清理过时条目 |
2. 标准化吸收流程（四阶段）
所有外部知识输入都走同一个标准流程：
外部知识 → §2.1 评估（五问法）→ 不通过 → 归档备查
│ 通过
▼
§2.2 定位 → §2.3 融合 → §2.4 验证2.1 评估：五问评估法
对每条外部知识，依次回答五个问题：
| # | 问题 | 评估标准 | 不通过则 |
|---|---|---|---|
| 1 | 可靠性 — 来源可信吗？ | 官方文档 > 知名博客 > 社区帖子 > 个人观点 | 标注低可靠性，降级参考 |
| 2 | 时效性 — 信息新鲜吗？ | 6 个月内优先，超过 1 年需交叉验证 | 搜索更新版本 |
| 3 | 关联性 — 与体系相关吗？ | 直接影响体系文档的技术栈、工作流或原则 | 跳过，不浪费时间 |
| 4 | 增量性 — 体系里有了吗？ | 对比现有文档，确认是新知识而非重复 | 跳过或仅微调措辞 |
| 5 | 实操性 — 能落地吗？ | 有具体配置、命令或模式，而非纯理论 | 降级为"待观察" |
五问全部通过 → 进入定位阶段。 3-4 个通过 → 视情况决定（标注保留理由）。 不足 3 个通过 → 归档备查，不融入。
2.2 定位：更新目标决策树
通过评估后，确定知识应该更新到体系的哪个位置：
这条知识是关于...
├── 工具用法 / 配置方法 / 架构模式
│ └── → docs/design/ 对应文档
│
├── Prompt 写法 / 提示词模板
│ └── → docs/prompts/ 对应食谱
│
├── CLAUDE.md 规则 / 项目约束
│ └── → CLAUDE.md 或全局 ~/.claude/CLAUDE.md
│
├── Skill 流程优化
│ └── → .claude/skills/对应Skill/SKILL.md
│
├── 新的 Skill 或工具能力
│ └── → 新建 Skill + 更新 doc-02 清单
│
└── 跨多个文件
└── → 列出所有受影响文件，评估变更范围2.3 融合：操作规范
执行文档修改时遵守以下规范：
- 最小改动原则 — 只修改需要修改的部分，不趁机"顺手重构"
- 交叉引用更新 — 新增内容如果引用了其他文档，检查双向引用是否完整
- CHANGELOG 标注来源 — 每次融合在 CHANGELOG.md 中记录：来源类型包括：
来源：[来源类型] 来源描述文章吸收、版本追踪、竞品对标、项目反哺、定期搜索 - 行数控制 — 新增内容后检查目标文件是否超过 500 行，超过则先拆分再融合
2.4 验证
融合完成后执行三项验证：
bash
# 1. 文档体系审计
/docaudit
# 2. 行数检查（修改过的文件）
wc -l docs/design/修改过的文件.md # 确认 ≤ 500 行
# 3. 站点构建验证
cd site && npm run build全部通过后，提交变更并在 CHANGELOG 中标注来源。
3. 输入源一：用户喂文章（/absorb Skill）
最常见的场景：用户在浏览网页、阅读邮件或看到推荐文章时，想让体系吸收其中的有价值内容。
SOP
- 获取内容（WebFetch 或直接读取）
- 结构化提取（核心要点、技术细节、最佳实践）
- 五问评估（§2.1）
- 定位影响范围（§2.2）
- 输出评估报告 → 等待用户确认
- 用户确认后执行融合（§2.3）
- 验证（§2.4）
评估报告模板
markdown
## 外部知识评估报告
### 来源信息
- **标题**: {文章标题}
- **来源**: {URL 或来源描述}
- **日期**: {发布日期}
- **可靠性等级**: 高 / 中 / 低
### 核心要点提取
1. {要点 1 — 一句话概括}
2. {要点 2}
3. {要点 3}
### 五问评估
| 维度 | 评估 | 通过 |
|------|------|------|
| 可靠性 | {评估说明} | ✓/✗ |
| 时效性 | {评估说明} | ✓/✗ |
| 关联性 | {评估说明} | ✓/✗ |
| 增量性 | {评估说明} | ✓/✗ |
| 实操性 | {评估说明} | ✓/✗ |
### 影响评估
| 受影响文件 | 变更类型 | 变更内容摘要 |
|-----------|---------|------------|
| {文件路径} | 新增/修改 | {简述} |
### 建议操作
- [ ] {具体操作 1}
- [ ] {具体操作 2}
### 风险提示
- {如有与现有内容冲突，明确指出}注意事项
- /absorb 不自行决定采纳 — 评估报告输出后必须等待用户确认
- 冲突优先提示 — 如果新知识与现有文档内容矛盾，必须在报告中明确标注
- 部分采纳 — 一篇文章可能只有部分内容值得吸收，在报告中标明哪些采纳、哪些跳过
4. 输入源二：定期搜索
主动搜索而非被动等待，定期检查工具链和技术栈的最新进展。
SOP
- 确定本次搜索主题（从推荐清单或自定义）
- 使用 /tech-research 执行搜索（context:fork 隔离）
- 筛选有价值的发现
- 对每条发现走 /absorb 评估流程
- 批量融合通过评估的内容
推荐搜索清单
| 主题 | 搜索关键词示例 | 频率 | 关注重点 |
|---|---|---|---|
| Claude Code | "Claude Code" changelog {year} | 月度 | 新功能、breaking changes、新命令 |
| Next.js | "Next.js" blog {year} | 月度 | 新版本特性、迁移指南、性能改进 |
| Prisma | "Prisma" release {year} | 季度 | Schema 变化、新 adapter、性能改进 |
| TypeScript | "TypeScript" release {year} | 季度 | 新类型特性、编译器改进 |
| AI 编码实践 | "AI coding" best practices {year} | 月度 | 新的协作模式、Prompt 技巧、工具更新 |
| React | "React" blog {year} | 季度 | 新 API、模式变化、生态更新 |
| Tailwind CSS | "Tailwind CSS" changelog {year} | 季度 | 新工具类、breaking changes |
执行方式：/tech-research + /absorb 联动
典型流程：/tech-research → 调研报告（docs/research/）→ 用户筛选 → /absorb → 体系文档更新。
关键区别：/tech-research 产出调研报告（留存），/absorb 产出体系文档更新（直接修改 design/prompts）。二者是上下游关系。
除月度计划驱动的定期搜索外，也可随时使用"进化触发提示词库"（§9）即时触发单次搜索与吸收。
5. 输入源三：项目实战反哺
在实际项目中积累的经验，筛选出具有普适性的部分反哺到体系文档。
与 /retro 的区别
| 维度 | /retro | 项目实战反哺 |
|---|---|---|
| 粒度 | 会话级（本次对话的经验） | 体系级（可跨项目复用的模式） |
| 输出 | CLAUDE.md 规则 | 设计文档 / Prompt 食谱 / Skill |
| 频率 | 每次重要会话结束 | 积累后批量处理 |
| 判断标准 | "这个错下次要避免" | "这个模式其他项目也能用" |
SOP
- /retro 识别泛化信号（见下表）
- 记录到"待吸收清单"（CLAUDE.md 临时区域或独立文件）
- 积累 3-5 条后批量处理
- 对每条走标准吸收流程（§2）
- 清理待吸收清单中已处理的条目
泛化信号判断表
| 信号 | 说明 | 泛化方向 |
|---|---|---|
| 同一个 Prompt 模式在 2+ 项目中有效 | 不是项目特有的，是通用模式 | → docs/prompts/ |
| 某个 Skill 的流程需要调整 | 原流程有盲区或低效步骤 | → .claude/skills/ |
| 发现了新的 Hook 拦截场景 | 不是项目特有的安全/质量风险 | → docs/design/04 |
| 某个架构模式反复出现 | 可以抽象为通用指导 | → docs/design/ 对应文档 |
| AI 在多个项目中犯同一个错 | 是模型通病而非项目问题 | → CLAUDE.md 全局规则 |
| 某个调试技巧解决了类别问题 | 不只是修了一个 bug | → docs/prompts/05 调试排错 |
待吸收清单格式
在 CLAUDE.md 或独立文件中维护：
markdown
## 待吸收清单（体系反哺）
- [ ] Prisma 嵌套事务的正确写法 → design/17 或 prompts/02
- [ ] 大文件拆分的通用判断标准 → design/06
- [ ] shadcn/ui 组件定制的最佳流程 → prompts/02 或 design/116. 输入源四：竞品对标
关注同类体系（AI 辅助编程框架、编码规范体系）的设计理念，借鉴有价值的模式。
SOP
- 发现竞品 — GitHub 搜索 "AI coding workflow"、关注 awesome 列表和社区讨论
- 结构化对比 — 解决什么问题？与本体系重叠/不重叠部分各自怎么做的？
- 借鉴有价值的模式 — 提取具体配置、流程或模板（不照搬），走标准吸收流程（§2）
对比维度
| 维度 | 关注点 |
|---|---|
| 体系结构 | 分层方式、模块划分、文档组织 |
| Skill/命令设计 | 命名、参数、流程步骤 |
| 自动化程度 | Hooks 覆盖范围、CI 集成 |
| 进化机制 | 如何保持体系鲜活 |
| 上手成本 | 渐进式采用路径设计 |
注意事项
- 关注理念不照搬配置 — 每个体系有自己的上下文，直接复制配置几乎不会适用
- 警惕"功能羡慕" — 竞品有的功能不一定是我们需要的，对照 §2.1 五问评估
- 体系一致性优先 — 借鉴的模式必须与现有体系的设计原则兼容（实操优先、个人场景精简）
7. 输入源五：版本追踪
追踪核心工具链的版本更新，及时响应 breaking changes 和重要新特性。
SOP
- 检查 changelog — Claude Code releases、Next.js blog、Prisma releases、
npm outdated - 筛选相关变更 — 新功能影响工作流？废弃项体系中引用了？Breaking changes？
- 走标准吸收流程（§2）— 普通更新正常流程，Breaking change 走紧急响应（见下）
Breaking Change 紧急响应流程
当核心工具链发生 breaking change 时：
- 评估影响范围 — 搜索体系文档中所有引用；评估 CLI 模板和 Skills 是否受影响
- 标记紧急程度：
- P0 — 体系核心功能不可用（立即处理）
- P1 — 部分功能受影响（本周处理）
- P2 — 仅文档描述过时（下次月度更新处理）
- 执行更新 — 按 §2 标准流程，CHANGELOG 标注 "Breaking Change 响应"
- 验证 — /docaudit 全量检查 +
cd site && npm run build
版本追踪清单
| 工具 | 追踪方式 | 频率 | 关注重点 |
|---|---|---|---|
| Claude Code | GitHub releases + 官方博客 | 每次使用前快速扫一眼 | 新命令、新配置项、行为变更 |
| Next.js | 官方博客 + GitHub releases | 月度 | 新 API、构建优化、安全修复 |
| Prisma | GitHub releases | 季度 | Schema 语法变化、性能改进 |
| TypeScript | 官方博客 | 季度 | 新类型特性、strictness 变化 |
| Node.js | 官方博客 | 半年 | LTS 版本切换、API 废弃 |
| npm 生态 | npm outdated + npm audit | 月度 | 安全漏洞、主版本升级 |
8. 执行节奏与工作量
五种输入源总览
| 输入源 | 频率 | 预估时间 | 触发方式 |
|---|---|---|---|
| 用户喂文章 | 随时 | 15-30 分钟/篇 | 用户主动 /absorb |
| 定期搜索 | 月度 | 30-45 分钟 | 月度检查时执行 |
| 项目实战反哺 | 积累后批量 | 20-30 分钟/批 | /retro 识别后积累 |
| 竞品对标 | 季度 | 30-60 分钟 | 季度检查时执行 |
| 版本追踪 | 月度 | 15-30 分钟 | 月度检查时执行 |
与 doc-08 月度/季度节奏整合
月度检查追加项（~45 分钟）：
□ 外部知识吸收
- 运行版本追踪（§7）：核心工具链有无重要更新？
- 执行定期搜索（§4）：本月重点关注 1-2 个主题
- 处理待吸收清单：项目实战中积累的泛化经验季度检查追加项（~30 分钟）：
□ 竞品对标
- 扫描同类体系的最新动态
- 评估是否有值得借鉴的新模式
□ 吸收效果回顾
- 过去一季度吸收了哪些外部知识？
- 吸收的内容是否真的有用？（用了几次？）
- 有没有吸收后反而增加了复杂度的内容？→ 考虑回退月度总投入
| 活动 | 时间 |
|---|---|
| doc-08 原有月度检查 | ~40 分钟 |
| 版本追踪 + 定期搜索 | ~45 分钟 |
| 待吸收清单处理 | ~15 分钟 |
| 月度总计 | ~1.5-2 小时 |
降级策略
当时间紧张时，按优先级降级：
P0（必做）：Breaking Change 紧急响应
P1（推荐）：版本追踪 + 用户喂文章
P2（可延期）：定期搜索 + 项目实战反哺
P3（可跳过）：竞品对标跳过 P2/P3 不会导致体系退化，只是减缓外部知识的输入速度。内部闭环（doc-08）始终保持运行。
进化触发提示词库（§9）是定期搜索的灵活补充：定期搜索保证节奏，提示词库支持随时按需触发，二者互补。
9. 进化触发提示词库
将"触发体系迭代"的动作模板化。以下提示词可随时使用，驱动 AI 执行对应的搜索与吸收流程。
工具链追踪类
调研 {工具名} 最新的最佳实践和 changelog，评估对体系的影响，按 /absorb 流程执行融合阅读 {官方文档URL} 最新内容，与我们的 {doc-XX} 逐项对比，列出需要更新的条目生态扩展类
调研 {工具名} 与 Claude Code 的集成方案（MCP/Plugin），评估是否融入 doc-05 MCP 体系搜索 {领域} 的社区最佳实践，评估对体系 {具体模块} 的赋能价值体系自检类
对比 Claude Code 官方文档（code.claude.com/docs/en/）与我们的设计文档体系，找出所有差距检查体系中的 {doc-XX} 是否与当前工具链版本一致，列出过时内容批量进化类
针对体系中所有涉及 {主题} 的文档，统一检查并更新到最新实践使用说明
- 花括号
{}内为占位符，使用时替换为实际值 - 每条提示词隐含标准吸收流程（§2），AI 应自动执行五问评估 → 定位 → 融合 → 验证
- 可与
/absorb或/tech-research组合使用，也可直接在会话中发给 AI
10. 与现有体系的集成
doc-08 需新增的条目
进化触发表（§4）新增行：
| 信号 | 进化动作 |
|---|---|
| 核心工具链发布新版本 | 走版本追踪流程（doc-20 §7） |
| 看到有价值的外部文章/教程 | 走 /absorb 吸收流程（doc-20 §3） |
| /retro 中发现可泛化的经验 | 记录到待吸收清单（doc-20 §5） |
月度检查新增条目：
□ 外部知识吸收（详见 doc-20 §8）
- 版本追踪：核心工具链更新
- 定期搜索：本月重点主题
- 待吸收清单处理CHANGELOG 来源标注格式
所有通过外部吸收流程的变更，在 CHANGELOG 中标注来源类型：
markdown
来源：[文章吸收] {文章标题}（{URL}）
来源：[版本追踪] Claude Code v1.x → v2.x changelog
来源：[竞品对标] {竞品名称} 体系分析
来源：[项目反哺] {项目名称} 实战经验泛化
来源：[定期搜索] {搜索主题} 月度扫描吸收结果的更新路径
| 知识类型 | 更新目标 | 示例 |
|---|---|---|
| 工具用法 / 配置方法 | docs/design/ 对应文档 | Claude Code 新命令 → doc-02 或 doc-08 |
| Prompt 模式 / 模板 | docs/prompts/ 对应食谱 | 新的调试提示词 → prompts/05 |
| 编码规范 / 最佳实践 | docs/design/ 或 CLAUDE.md | TypeScript 新模式 → doc-12 或 CLAUDE.md |
| Skill 流程优化 | .claude/skills/ 对应 Skill | review 流程改进 → skills/review/ |
| 新 Skill | 新建 + 更新 doc-02 | 发现新的可固化流程 → 新 Skill |
| 架构模式 | docs/design/ 对应文档 | 新的测试策略 → doc-10 |
| 安全实践 | docs/design/04 或 CLAUDE.md | 新的安全风险 → Hooks 或规则 |
与 /docaudit 的配合
每次外部知识融合后，/docaudit 的检查项全部适用：
- 索引一致性（新增文档后 README 更新了吗）
- 编号连续性（有没有跳号）
- CHANGELOG 时效性（本次变更记录了吗）
- 行数限制（修改后的文件超 500 行了吗）
- 交叉引用（新增内容的内部链接有效吗）
11. 关联文档
- 08-运维与持续进化 — 内部进化闭环，本文档补全外部进化
- 02-Skills 技能体系 — /absorb Skill 在体系中的位置
- 00-总体架构 — 体系演进方向
/tech-research— 定期搜索的执行工具/retro— 项目实战反哺的信号入口/docaudit— 融合后的验证工具- CHANGELOG — 来源标注格式
本文档定位为外部进化的 SOP 手册。具体的吸收操作通过 /absorb Skill 执行，体系内部维护仍由 doc-08 负责。