games-development-ai/docs/brainstorms/2026-06-17-文档体系重构-requirements.md

date, topic, title

date	topic	title
2026-06-17	文档体系重构	文档体系重构 —— 止血最小集(混合两层·阅读心法)

文档体系重构 —— 止血最小集(混合两层·阅读心法)

摘要

把文档体系的止血最小集做掉:① 改全局 prompt,退役"每任务 dated 双档"约定(流水与陈旧的发动机);② AGENTS.md 补全唯一前门索引 + 去重;③ 校准 §1–2 目标锚;④ 清死 store。两层(策展少而准 / 留痕放开检索)作为阅读心法映射到现有 canonical 结构,不新建目录/标签;蒸馏桥沿用现有 wave-close 步骤并补一条机器可检最低门。保留自研主干,不整体迁 CE。

---

问题背景

四病:散乱、更新不及时、过多(docs/agent-specs/ 276 文件)、初版目标不清晰。知识散在 .agents / docs/memorys / Claude 自动记忆 / 收口报告。今天(2026-06-17)的 canonical 重构已把 settled 子系统收成约 7 份活档,但只做了一半(生成域仍 dated 流水,另一 session 收敛中)。

根因(评审确认的最高杠杆点)= 流程提示词。 全局 ~/.claude/CLAUDE.md 的 large-task 协议仍要求每任务产 dated review.md + execution.md 双档(再加 master spec、分阶段 spec、两轮评审),这是"流水与陈旧"的发动机:产出已转 canonical,流程没改。改它 = 止血;存量整理是低杠杆慢性病,可分批。

CE 曾被议作整体替代:CE 确缺程序管理层(docs/mvp 闸门/进度账是这种硬日历闸门 MVP 的心跳,CE 把状态推给 git + 外部 tracker);但"CE 无蒸馏"不实——CE 的 solutions 层有 promote/refresh,真正不归档不蒸馏的只是它的 brainstorm/plan 每任务喂料。故结论 = 混合,不整体迁。

---

关键决策

• 止血优先(先关水龙头)。 改 prompt 是唯一阻止未来文档继续变烂的高杠杆动作;存量整理低杠杆、可分批、可等生成域 session 收敛。本次只做最小止血集。

• 两层是阅读心法,不是新结构。 策展层 = 现有 canonical/SoT;留痕层 = 现有 docs/brainstorms+plans+收口报告+_archive。映射到今天 canonical 重构已建的结构,不新建标签/目录,避免双命名 churn。

• 混合而非整体 CE(校准版)。 真因 = CE 缺程序管理层;"CE 无蒸馏"措辞已收窄(CE solutions 有 promote/refresh)。结论不变:保留主干,只借 CE 评审人格(试用)、brainstorm→plan 喂料、单锚模式。

• 全局 prompt 增量 deprecate,不硬替换。 本仓自己是该约定头号依赖方(276 文件 / _index / 记忆铁律),且其它项目无法盘点 → 旧双档标 deprecated/兼容,新任务走两层;改写与本仓约定 + 在飞 session 原子同步,避免 split-brain。

• 蒸馏要机制不要口号。 现有 wave-close 第 5/8 步已有蒸馏却没拦住陈旧 = 证据;补一条机器可检最低门(留痕新增 → 收口必须产"蒸馏 diff 或显式无可蒸馏 + 理由")。

flowchart TB
  ENTRY["AGENTS.md:唯一前门索引 + 顶层目标锚(§1-2)"]
  subgraph CURATED["策展层 · 少而准 · 人读即现行真相"]
    ABC["Doc A/B/C:产品·模块·映射"]
    PROG["MVP进度总账(含 §2 模块矩阵)"]
    CANON["各子系统 canonical 活档"]
    ADIR[".agents 能力库"]
  end
  subgraph TRACE["留痕/笔记层 · 放开累积 · 检索而非通读"]
    FEED["brainstorms / plans"]
    REP["收口报告 + _archive(含 census 快照)"]
  end
  ENTRY --> CURATED
  ENTRY -. "检索入口" .-> TRACE
  TRACE == "收口蒸馏(机器可检门)" ==> CURATED

---

需求

两层 = 阅读心法(不新建结构)

• R1. 两层映射现有结构,不新建目录/标签:策展层 = 现有 canonical/SoT(AGENTS.md 前门、Doc A/B/C、MVP进度总账含 §2 模块矩阵、各子系统 canonical、.agents);留痕层 = docs/brainstorms+docs/plans+收口报告+_archive(放开累积、检索)。
• R2. 判层规则(物理信号):_index 标 canonical 的 + AGENTS/docs/architecture/docs/mvp = 策展;docs/{brainstorms,plans} + agent-specs 非 canonical + _archive = 留痕。"孤儿"只针对策展层(策展 SoT 必须前门一跳可达);留痕前门不可达 = 设计如此。

① 改 prompt(止血)

• R3. 通盘改写全局 ~/.claude/CLAUDE.md 的 large-task 协议块(非只挖两词):退役"每任务必产 dated review+execution 双档 + master + 分阶段 spec + 两轮评审",改为两层原理(WHAT/HOW 临时喂料 → 收口蒸馏进策展正典 → 喂料留痕)。
• R4. 增量 deprecate:旧双档路径标 deprecated/兼容保留,新任务走两层;写法项目无关,本项目特定路径留本仓 AGENTS.md。
• R5. 前置原子条件:改全局前先同步本仓 engineering-conventions §10 + _index 规范 + wave-needs-review-and-execution-spec-pair 记忆,并与在飞 session owner 确认不再产新双档;同一原子批次。

② AGENTS 补索引 + 去重

• R6. AGENTS.md 唯一前门:完整覆盖策展层(逐项指向唯一 SoT)+ 留痕层给单一检索入口(不逐条挂);不新建 master 文档。
• R7. 去重:同一概念在策展层只有一个 SoT,其余处改一句话 + 指针。

③ 校准 §1–2 目标锚

• R8. 不新建锚(§1–2 已是锚):认领唯一目标 SoT,其余目标源(docs/mvp/goals.md、总账 §0、mvp-scope-and-milestones、战略与合规)各归位为一句话 + 指针。
• R9. 消双 roadmap 二义:日常默认 = 执行版(10 人 3 周),投资人版仅对外;"MVP 现行目标"一句话可答。

④ 清死 store + 知识归位

• R10. docs/memorys 判死(只读/归档,不再新增;新留痕走 docs/brainstorms+plans)。
• R11. Claude 自动记忆划界外:引擎托管、仓外、不可纳管;定位 = 个人会话加速,仓内为权威源,有复用价值须蒸馏回 .agents 才算数。
• R12. 真正收敛只 .agents(策展)+ 收口报告(留痕);不新增第 5 个 store;.agents 维持策展纪律(一主题一档、查重、过时即删)。

蒸馏与检索(治"更新不及时"的真机制)

• R13. 蒸馏沿用现有 wave-close 第 5/6/8 步(核对微调,不新增门);补机器可检最低门:本波产生留痕 → 收口须产"蒸馏 diff 或显式无可蒸馏 + 理由"(对齐 §10 第 8 步既有模式)。
• R14. 留痕检索最低约定:新留痕文件强制 frontmatter 最小字段(date/topic/status/superseded-by);存量不全量回填(doc-organizer 巡检按需补);ce-learnings-researcher 接入待后议。

事实归位(修自相矛盾)

• R15. census(docs/agent-specs/2026-06-17-产品功能与技术模块-完成度与优先级总账.md)判为一次性留痕快照(留 agent-specs、dated 合理),不进策展前门;模块完成度策展 SoT = MVP进度总账 §2(census 是其功能粒度快照,可被指针引用)。
• R16. 模块进度唯一家 = MVP进度总账 §2;子系统 canonical 的"现状"段只写该子系统设计决策落地状态(并声明"模块真实度见 §2");不依赖不存在的"各模块 .agent"。

---

成功标准

• 改 prompt 后,新任务不再产 dated review/execution 双档(止血生效)。
• 前门一跳可达任一策展 SoT;策展层无孤儿、无重复 SoT;判层规则可操作。
• "MVP 现行目标"一句话可答,§1–2 与总账 §0 / Doc A 一致、双 roadmap 主从明确。
• docs/memorys 不再新增;无第 5 个仓内 store;Claude 自动记忆明确划界外。
• 留痕新增时,收口产出"蒸馏 diff 或显式无可蒸馏 + 理由"(蒸馏门可检)。

---

范围边界

砍(本次不做):

• 两层作为新目录/标签体系(只作阅读心法)。
• 新增收口门(改为核对微调现有 wave-close 第 5/6/8 步)。
• CE 评审舰队"正式替代"现有评审(本次只借用试跑;是否替代另开独立决策,不 supersede review-prefer-codex-xhigh / impl-review-one-opus-round)。

推迟:

• 全部文档逐项归两层 + 知识大迁移 → 交 doc-organizer 巡检分批,等生成域 session 收敛。
• census 是否提升为策展层;存量 141 档 frontmatter 回填范围;ce-learnings-researcher 接入。

拒绝(不变): 不外迁 GitHub Issues、不退役自研主干、不整体迁 CE。

---

依赖与假设

• 多 session 枢纽协调: AGENTS.md / .agents/README / _index / wave-close-checklist 是双 session 共享枢纽 → 改动串行 / 最小 diff / 落地前同步在飞 session 进度(对齐"独占资源串行")。
• 全局 prompt 是显式承担的已知风险(非已消除):其它项目无法盘点 → 增量 deprecate 兜底。
• Claude 自动记忆仓外不可纳管(见 R11)。
• 本文档 = 留痕喂料: 收口时其决策蒸馏进 harness(AGENTS.md / .agents)+ 全局 prompt;此为一次性元任务,区别于常规收口蒸馏(常规只进 canonical/.agents,不含全局 prompt)。

---

待定问题

可留到规划阶段:

• 全局 large-task 协议块的具体改写文本(与第 55–69 行咬合的两轮评审/master spec 段一并通盘改)。
• census 最终去留(留痕快照 vs 提升策展)。
• 存量 frontmatter 回填范围与 ce-learnings-researcher 是否接入。