25 - 文档体系演化机制
1. 定位
文档体系不是静态规范，而是经实战磨砺持续演化的活体系统。本文档承载五类演化机制，回答一个核心问题：
当方法论的字面规则在某个项目语境跑不通时，该怎么办？
借鉴来源：prompt-hub 项目实战盲区文件（11 条已识别盲区，3 条已落 v1.2 patch）+ 产品文档体系方法论 v1.3。
与 06-文档体系的分工
- 06 定义体系的静态结构（三层 + 格式契约 + 生命周期）
- 25 定义体系的动态演化（怎么活下去、怎么长出来、怎么自我修正）
两者必须配合阅读。
2. 章节 N/A 规范（共享规则）
2.1 触发条件
当某章节在本项目语境合理不适用时（不是"懒得写"），必须保留章节占位 + 合规标注。区分"合理 N/A"和"偷懒"的判据：
- ✅ 合理 N/A：受 constitution / tech-stack 禁令约束（如 LLM-free 项目无 Eval 集）
- ✅ 合理 N/A：受项目形态约束（如桌面应用无 URL 路由）
- ❌ 不算 N/A：因为还没想清楚 / 因为现在没时间写 / 因为觉得不重要
后两类属"待补"或"不写"，应明示状态而非 N/A。
2.2 合规标注五要素
## §X 章节名（N/A — 触发条件：<一句话>）
**N/A 声明**：本章节在 prompt-hub 项目语境不适用。
**理由**：根据 [[02-constitution#D1]] 禁用 LLM SDK，工具无非确定性 AI 输出。
**替代方案**：如有替代实现（如用规则引擎替代 LLM），在此说明；无则写"无替代"。
**升级条件**：当 [触发事件] 发生时，本章节升级为完整规范。
例如：违反 D1 引入 LLM SDK 须先开 ADR，ADR Accepted 后本节展开。
**反向链**：登记到 [[methodology-gaps.md]] 第 N 条，避免审计反复发现同问题。2.3 禁止事项
| 反模式 | 后果 |
|---|---|
| 直接删除章节 | 审计判"缺章节" |
| 写「(略)」「同上」 | 无法判断是"不适用"还是"未写完" |
| 章节标题保留但内容空白 | AI 召回时获得无意义片段 |
| N/A 但不给升级条件 | 永久搁置，体系腐烂 |
2.4 好例子
prompt-hub docs/design/11-test-spec.md §6 LLM Eval 集 是规范 N/A 的样板：明示 N/A、理由链回 constitution、给违反禁令时的升级触发、反向链方法论盲区。
3. pre-code 阶段降级规范
3.1 pre-code 状态定义
项目处于以下任一状态时，标记为 status: pre-code：
- 0 LOC（未建仓 / 仅有设计文档）
- 已建仓但未通过 M0 技术验证（spike 未跑通）
- 关键技术决策（核心 ADR）仍 Proposed 未 Accepted
pre-code 阶段，部分文档字面要求不可达。强行满足会写出违反"手写而非自动生成"原则的伪规则。
3.2 各文档类型的合法降级形态
tech-stack.md（pending-adr stub）
status: pending-adr必含降级内容：
- 物理约束清单：从 constitution 推论的硬约束（如「桌面原生 only」→ 排除 Web 框架）
- 待决策矩阵：每个未拍板的技术领域列候选 + 触发 ADR 编号
- 升 v1.0 触发条件：「所有候选 ADR Accepted 后」
CLAUDE.md 关键命令（TBD 占位）
## §2 关键命令
> 建仓后必含；当前 pre-code 阶段为 TBD 占位。
> 回填时机：M0 技术验证通过 + `pnpm install` 走通后。
```bash
# pnpm install # 待 ADR-004 包管理器决议后填
# pnpm dev # 待 Tauri 模板生成后填
#### prd / ops-spec / test-spec 中的数字
所有性能基线 / 阈值 / SLO 数字标 🎯 目标态（见 §4 数字来源标注）。
#### CLAUDE.md 失败案例驱动
新项目 cold-start 阶段允许 ≥30% 规则来自约束推论（必须显式标 `[推论自 constitution#X]`），但每月 review 必须迁移至少 1 条到 [事故沉淀]。
### 3.3 升 v1.0 的触发条件
| 文档 | 升级触发 |
|---|---|
| tech-stack pending-adr → v1.0 | 所有核心 ADR Accepted |
| CLAUDE.md 关键命令 TBD → 实命令 | 首次 `pnpm install` 走通 |
| 性能数字 🎯 → 📊 | 首次实测 |
| pre-code → active | 第一个功能完成端到端验证 |
升级时必须 bump 文档版本（patch / minor，按 §7 规则）。
## 4. 数字来源标注（🎯/📊/⚠️）
### 4.1 三标定义
| 符号 | 含义 | 说明 |
|---|---|---|
| 🎯 | 目标 target | 设计期望，未实测 |
| 📊 | 基线 baseline | 首次实测值，作为 regression 基准 |
| ⚠️ | 临界 threshold | 违反触发处理的红线值 |
三者可同行并列，例：主形态唤起 P95：🎯 200ms / 📊 未测 / ⚠️ 250ms block PR
### 4.2 强制场景
以下场景所有数字必须标注来源：
- ops-spec 性能预算 / SLO
- test-spec 性能基准
- prd NFR 中的数字指标
- constitution 中的硬约束数字（如「200ms 唤起死线」）
### 4.3 不强制场景
以下场景可不标注：
- 字段长度上限（如「name ≤ 64 字符」）—— 这是契约不是测量
- 配置默认值（如「重试次数 3」）—— 这是常量不是 SLO
- 枚举值数量（如「四值枚举」）—— 这是定义不是观察
判断口诀：**该数字会因为代码变化而需要更新吗？**会 → 必须标。
### 4.4 升级路径🎯 200ms（pre-code 设计期望） ↓ M0 spike 实测 📊 10.49ms（首次实测，commit f753219 测量） ↓ regression test 引入 📊 10.49ms 基线 + ⚠️ 100ms PR block 红线
每次升级必须 commit message 标注（如 `perf(measure): hotkey-wake P95 baseline 10.49ms`）。
## 5. 实战盲区追踪机制
### 5.1 盲区登记文件
项目根 `docs/methodology-gaps.md` 独立维护（不嵌入 06 或 25 文档内）。这是文档体系的「自身 changelog」，记录"哪些字面规则在本项目跑不通"。
新建项目时不必立即建，第一次发现盲区时再建。
### 5.2 盲区记录格式
每条盲区独立小节：
```markdown
## 盲区 ⑨ — 章节 N/A 合法性缺失（解决日期：2026-05-19 v1.2）
- **方法论原文**：§5 各节定义了「必含章节」，但未规定"合理 N/A 时如何合规标注"
- **现实困境**：3 处「合理 N/A」（LLM Eval / 部署拓扑 / dashboard），作者各自发明格式不统一
- **当前处理**：test-spec §6 写得最规范（明示 + 理由 + 替代 + 升级 + 反向链）
- **修订建议**：§5 开头增加「§5.0 N/A 章节规范」共享规则
- **优先级**：P0（跨文档通用 + 高频触发 + 现有解决方案发散）
- **落地状态**：✅ v1.2 已落5.3 三阶段流转
阶段 1：登记 ← 任何 AI 或人在工作中发现"规则跑不通"，立刻登记
阶段 2：bump 候选 ← 月度复盘汇总，按 P0/P1/P2 排序，给出 patch 草案
阶段 3：落地登记 ← 上游方法论 bump 后，标 ✅ 已落 / ⏳ 推延 / 🤔 待评估5.4 优先级判定
基于三个维度：
| 优先级 | 跨文档通用性 | 频繁触发性 | 现有解的发散度 |
|---|---|---|---|
| P0 必修 | 高（≥3 文档受影响） | 每个项目都遇到 | 各项目各自发明 |
| P1 建议 | 中（1-2 文档） | 多数项目遇到 | 有零散先例 |
| P2 可选 | 低（单文档场景） | 偶发 | 已有约定俗成解 |
5.5 与 §7 八步流程的衔接
盲区追踪是 §7 变更管理的触发源：
盲区登记累积 ≥3 条 P0 → 触发上游方法论 bump 评估 → 走 §7 八步不强制每条盲区立即触发 bump（避免抖动）。
6. 独立审计环节
6.1 写作单线 + 评价 Agent 分工原则
| 任务类型 | 推荐方式 | 理由 |
|---|---|---|
| 创作型 + 短文档（≤200 行） | 单线顺序 | 共享上下文，一致性高 |
| 评价 / 审计 / 一致性检查 | 独立 Agent | 客观度高，避免自审盲点 |
为什么不混用：自己写的文档自己审，会习惯性合理化已有判断。独立 Agent 没有作者的"沉没成本"，能发现真盲点。
实战证据：prompt-hub W1 阶段独立 Agent 审计 4 份文档产出 5 个真盲区，这是单线自审难以达到的客观度。
6.2 审计触发条件
| 触发条件 | 审计范围 |
|---|---|
| bump major 前 | 受影响的全部下游文档 |
| 阶段交付前（如 M0 验证通过） | 当阶段所有契约文档 |
| 月度复盘 | 抽样 3-5 份高频变更文档 |
| 用户主动触发 | 任意 |
6.3 审计 Agent 输入与产出
输入：
- 待审文档全文
- 上游方法论 v1.X 规范
- 既有 methodology-gaps.md（避免重复发现）
产出：
- 评分（每文档 0-10 分，跨维度）
- 盲区清单（新发现 N 条，可加入 methodology-gaps）
- bump 候选建议
6.4 与 §7 八步流程的关系
独立审计是 §7 的 §7.bis 环节，插入位置：
1. 锁定 diff
2. 影响半径分析
3. 上游一致性检查
3.bis ← 独立审计（如触发条件满足）
4. 选择 bump 类型
...bis 标识表示条件触发：只在 §6.2 列出的条件满足时执行。
7. 演化机制在七层项目全貌中的位置
文档体系不是项目全貌。完整项目需要七层共存：
| 层 | 载体 | 文档能否替代 |
|---|---|---|
| 设计层 | 13 份核心文档 + 25 演化机制 | ✅ 文档主场 |
| 实现层 | 代码 | ❌ 代码是唯一事实源 |
| 验证层 | 测试 + CI | ⚠️ test-spec 定规则，跑通靠代码 |
| 运行时层 | 监控 / 日志 / APM | ❌ 性能、bug 只能运行时观察 |
| 用户层 | 反馈 / analytics / 访谈 | ❌ PMF、留存只能从真实用户来 |
| 反思层 | 复盘 / incident / checkpoint | ❌ 默契、共识、教训 |
| 演化层 | 外部学习 / 调研 / RSS | ❌ 行业变化、新技术 |
本机制（25）位于反思层和演化层之间的传导带：
- 从反思层吸收原料（盲区登记、审计报告、N/A 实证）
- 向演化层产出动作（bump 候选、N/A 共享规则升级）
- 反向回流设计层（升级 06 文档体系自身）
警示：不要把 13 份文档当成项目全部——文档说功能可用 ≠ 用户用得动 ≠ 真实跑得动。
反哺来源
本文档承载的五类机制全部反哺自 prompt-hub 项目实战：
| 节 | 反哺来源 |
|---|---|
| §2 N/A 章节规范 | 盲区 ⑨（v1.2 §5.0 已落） |
| §3 pre-code 降级 | 盲区 ① ② ③ ⑩（v1.3 推延） |
| §4 数字来源标注 | 盲区 ⑩ |
| §5 盲区追踪机制 | prompt-hub 产品文档体系方法论-实战盲区.md 整体范式 |
| §6 独立审计 | W1 观察 2-3 |
详见 ~/Vault/知识库/方案模板/产品文档体系方法论-实战盲区.md。
关联文档：06-文档体系 | 22-项目知识沉淀机制 | 上游方法论：~/Vault/知识库/方案模板/产品文档体系方法论.md v1.3