zizi-al/games-development-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
games-development-ai/docs/plans/2026-06-17-文档体系重构-plan.md
zizi 15efff4dee docs(harness): 文档体系重构(止血最小集)——两层模型+机器可检蒸馏门 
全局 ~/.claude/CLAUDE.md(仓外)退役「每任务 dated review+execution 双档」→两层喂料(WHAT/HOW)+收口蒸馏,增量 deprecate(旧档兼容)。本仓:engineering-conventions §10.6(两层心法/判层/蒸馏门/留痕 frontmatter);wave-close 第5/8步机器可检蒸馏门;AGENTS §2 目标锚去双 roadmap 二义 + §3.3 两层前门索引(模块进度 SoT=总账§2 / 自动记忆界外 / memorys 判死)。

评审 CE 5 人格(coherence/feasibility/scope/product/design)压缩至止血最小集,砍两层新目录/新收口门/评审舰队正式替换。WHAT=docs/brainstorms/2026-06-17-文档体系重构-requirements.md;决策记忆 docs-system-hybrid-two-layer(仓外)。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-17 16:33:21 +00:00

6.1 KiB
Raw Blame History

date, topic, type, status, origin, title
date topic type status origin title
2026-06-17 文档体系重构 execution shipped docs/brainstorms/2026-06-17-文档体系重构-requirements.md 文档体系重构(止血最小集)执行计划

文档体系重构(止血最小集)执行计划

WHAT 见 origin 需求文档。本文件是 HOW:执行序、改哪些文件、验证、回滚。 本计划本身是留痕喂料(两层模型留痕层);收口时蒸馏入 harness 后留痕。

目标与范围

落地需求文档的 4 个动作(① 改全局 prompt ② AGENTS 补索引去重 ③ 校准 §1-2 锚 ④ 清死 store)+ 评审高置信修正。不做:两层新目录/标签、新收口门、评审舰队正式替换、全量文档归两层(推迟给 doc-organizer)。

涉及文件

文件 动作 层
~/.claude/CLAUDE.md(全局,第 ~55–69 行 large-task 协议块) 通盘改写为两层 + 增量 deprecate 跨项目契约
AGENTS.md §1–2 / §3–5 锚校准 + 前门索引去重 策展枢纽
.agents/rules/engineering-conventions.md §10 退役双档规则 + 落两层/判层/frontmatter/蒸馏门 策展枢纽
.agents/skills/wave-close-checklist.md 第 5/6/8 步 核对微调 + 留痕归位 + 机器可检蒸馏门 策展枢纽
docs/agent-specs/_index.md census 标留痕快照 + 留痕检索入口登记 策展枢纽
docs/mvp/MVP进度总账.md §2 / 各子系统 canonical「现状」段 措辞对齐(模块进度唯一 SoT=§2) 策展
docs/memorys/ 判死标注(只读) 留痕
记忆 wave-needs-review-and-execution-spec-pair 改两层喂料口径 仓外记忆

⚠️ AGENTS.md / .agents/README / _index.md / wave-close-checklist.md 是双 session 共享枢纽——见 Phase 0。

执行序

Phase 0 — 协调与前置(不改文件)

  • P0-1. 与在飞 session owner 确认:(a) 改上述枢纽文件的时间窗(串行,避免 push 撞车);(b) 其生成域设计链不再产新 dated 双档(否则全局改后 split-brain)。
  • P0-2. 草拟全局 prompt 新「large-task 协议块」文本(覆盖 R3/R4:两层原理 + 旧双档标 deprecated/兼容),先交创始人过目;未获 OK 不进 Phase 2。

Phase 1 — 本仓策展层与规范(枢纽文件,与在飞 session 串行,单批次)

  • P1-1. engineering-conventions §10:退役「每任务 dated review+execution 双档」规则;落两层原理 + 判层规则(R2)+ 留痕最低 frontmatter date/topic/status/superseded-by(R14)+ 机器可检蒸馏门(R13)。
  • P1-2. wave-close-checklist 第 5/6/8 步:核对微调,补「留痕归位」+「收口须产蒸馏 diff 或显式『无可蒸馏+理由』」(R13);不新增步。
  • P1-3. AGENTS.md §1–2:认领唯一目标 SoT,goals.md/总账§0/mvp-scope/战略与合规 各归位为一句 + 指针;消双 roadmap 二义(日常默认=执行版)(R8/R9)。
  • P1-4. AGENTS.md §3–5:补唯一前门索引——策展层逐项指向 SoT + 留痕层单一检索入口(不逐条挂)+ 判层规则(R6/R7)。
  • P1-5. docs/memorys 判死(只读,前门给检索入口,R10);AGENTS/.agents 注明 Claude 自动记忆界外、仓内权威(R11)。
  • P1-6. census 归位:_index/前门标其为留痕快照(R15);MVP进度总账 §2 定为模块进度唯一 SoT,子系统 canonical「现状」段措辞改为「只写本子系统设计落地状态,模块真实度见 §2」(R16);删任何「各模块 .agent 记进度」表述。
  • P1-7. 更新记忆 wave-needs-review-and-execution-spec-pair 为两层喂料口径。

Phase 2 — 全局 prompt(原子,Phase 1 同批次收尾)

  • P2-1. 创始人 OK 后,改全局 ~/.claude/CLAUDE.md large-task 协议块(通盘,含与之咬合的两轮评审/master/分阶段段)为两层 + 增量 deprecate。

Phase 3 — 验证(对成功标准)

  • 模拟一个新任务流:确认不再要求产 dated 双档(止血生效)。
  • 前门一跳可达性自检:策展 SoT 无孤儿、无重复。
  • 「MVP 现行目标」一句话可答,§1–2 与总账§0/Doc A 一致。
  • docs/memorys 无新增;无第 5 个仓内 store;自动记忆界外声明在位。
  • 蒸馏门:造一个留痕新增场景,确认收口要求「蒸馏 diff 或显式无可蒸馏+理由」。

Phase 4 — 收口蒸馏 + 留痕归档

  • 本 brainstorm + 本 plan 作留痕喂料;蒸馏已入 harness;_index/前门登记其留痕检索入口;决策记忆已落 docs-system-hybrid-two-layer.md。

边界失败路径

  • 在飞 session 拒绝串行/时间窗冲突 → Phase 1 推迟,先单独做 Phase 2 的草拟(不落盘)。
  • 创始人不批全局新文本 → Phase 2 挂起,Phase 1 本仓改动仍可独立完成(本仓 AGENTS 优先级高于全局)。

验证方法

每 Phase 后:git diff 自检 + 上述成功标准逐条勾。本仓 harness 改动不涉编译;若触及构建相关另按 staging-ops 冒烟门(本次预计不涉)。

完成条件

4 动作落地 + 成功标准全过 + 留痕归档 + 决策记忆在位。

回滚策略

  • 每 Phase 独立 commit;全局 prompt 改动单独 commit便于单独 revert。
  • 增量 deprecate ⇒ 旧约定兼容保留,回滚=把旧段恢复为推荐路径,无破坏性。
  • 多 session:push 前按 [[multi-session-shared-tree-push-conflict]] 配方处理撞车(find 挪走别人 untracked,再 rebase+push)。

收口（2026-06-17 · SHIPPED）

止血最小集已落工作树并验证绿:

  • 全局 ~/.claude/CLAUDE.md 退役 dated 双档 → 两层喂料(增量 deprecate,旧档兼容)。
  • 本仓:engineering-conventions §10.6(两层心法/判层/蒸馏门/frontmatter)、wave-close 第 5/8 步机器可检蒸馏门、AGENTS §2 目标锚去双 roadmap 二义 + §3.3 两层前门索引(模块进度 SoT=总账§2 / 自动记忆界外 / memorys 判死)。
  • 决策蒸馏入记忆 docs-system-hybrid-two-layer。
  • 验证:全局旧双档段 0 残留 + 两层段在;本仓三件 grep 全中。

待选择性提交:仅 stage 本任务 5 处(conventions/wave-close/AGENTS + 新 brainstorm/plan),排除另一 session 在飞的生成域「固定游戏架构-SAA」档。推迟项(全量归两层 / census 提升 / frontmatter 回填 / ce-learnings-researcher 接入)交 doc-organizer 巡检分批。