架构文档重构 Playbook

一份"如何把一个项目的架构文档从 v1 重写为高质量、可演化、Agent 可消费的 v2"的可执行手册。

谁该用本 playbook：FinTec AI 生态内某个项目（Data Horizon / Trading Matrix / FinBayes / RLE / FEFM 等）的架构 / 工程负责人，需要把项目的工程化落地文档体系从早期版本重写为可被工程实施 Agent 消费的契约事实源。

新 Agent / 新会话快速理解：一次 Read 本文件即可获得方法论框架 + 决策矩阵 + 执行流程 + 模板指针。模板在 commons/playbooks/templates/architecture-document-rewrite/。

第一部分：什么时候用本 playbook

适用：

项目战略层（白皮书 / 产品定义）已稳定，但工程化落地文档（架构 / 实施 / 评估）跟不上 / 漂移 / 与战略脱节
工程实施 Agent（Codex / Claude Code / IDE Agent）面对当前文档读不进或实施不到位
架构有多个关键决策点尚未被独立记录，主文档变成方法论评分对比的大杂烩
业务对象 / 子系统 / 状态机 / 接口契约等概念在文档不同位置漂移
准备进入 walking skeleton 试点但缺一份 task-oriented 实施指南

不适用：

战略层尚未稳定（先稳上位再做下游）
单一 Agent / 单次会话即可完成的小重构（用普通 PR 流程）
纯文档润色（不涉及结构 / 决策变化）
工程实施仓的代码层任务（代码层用 OpenSpec task packet + 各项目自身工作流）

第二部分：方法论框架（选型矩阵）

架构文档不是一种范式能覆盖。本节给出主流方法论的适用边界 + 如何组合。

2.1 主流方法论对比

方法论	解决什么问题	优点	局限	颗粒度
arc42	架构文档分层骨架（12 部分模板）	经典 / 全面 / 治理可追溯	偏 enterprise / 对 AI Native / Agent-first 项目过重 / 全套展开会很长	文档体系
C4 Model（Brown）	架构图分层（Context → Container → Component → Code）	图清晰 / 避免"一图全部画死" / 与 arc42 互补	仅是绘图标准，不是文档结构 / Code 图很少需要	视图
ADR（Architecture Decision Records）	关键决策独立成档	决策可追溯 / 主文档不污染 / 变更管理	需要维护纪律（编号、状态、引用）	单决策
DDD（Domain-Driven Design）	业务建模 + bounded context	让架构与业务对齐 / 防术语漂移 / first-class business objects	需要领域专家 / 反复迭代	业务建模
Google Design Doc	单个设计提案与评审	聚焦决策 / 清晰流程	不是文档体系骨架 / 单文档颗粒度	单个设计
RFC / MADR	跨团队开放讨论 / Markdown 友好 ADR	协作友好	跨团队规模才需要	单决策
4+1 View Model（Kruchten）	4+1 视图（逻辑/开发/进程/物理/场景）	经典	现代 cloud-native 用 C4 更简洁	视图
12-Factor App	云原生应用 12 条原则	可操作	仅适合 SaaS / cloud-native 部署形态	部署
Schema-First Design	以数据 schema 为中心的设计	数据型项目天然契合	业务型项目过细	数据契约
OpenAPI / API Spec	API 接口契约	机器可读 / 工具链丰富	仅 API 层	接口
Event Storming	DDD 配套的事件风暴 workshop	业务建模 workshop	需要现场协同	业务建模

2.2 不能单用某一种 — 必须组合

任何严肃的架构文档至少需要 3 类方法论叠加：

一种文档骨架（arc42 或简化版 / Google Design Doc / 4+1）
一种视图标准（C4 推荐 / 4+1 经典）
一种决策记录（ADR / MADR / Google Design Doc）

复杂业务项目还需要：

一种业务建模（DDD / Event Storming）

数据 / 接口型项目还需要：

一种契约标准（Schema-First / OpenAPI）

2.3 项目特征 → 方法论组合的决策矩阵

项目特征	推荐组合
业务复杂 + 多关键决策 + Agent-first 消费	DDD（业务建模）+ arc42（精简版，仅留业务/系统/横向/质量/缺口/落地 6 部分）+ ADR（决策）+ C4（图）+ task-oriented 工程包（按里程碑切，给 Agent 消费）
数据管道 / 数据感知层	Schema-First + ADR + arc42 简化（业务/系统/接口/质量 4 部分）+ C4 容器图
执行 / 交易型	arc42 + ADR + 合规追溯文档（regulatory traceability matrix）+ C4
ML / 学习引擎 / 基础模型	arc42 + ADR + 实验设计模板（每实验一份）+ 模型卡（Model Card）+ C4 容器图
内部工具 / 小项目	Google Design Doc + ADR
公开 API 项目	OpenAPI + ADR + arc42 极简
多团队协作 / 跨组织提案	RFC + ADR + 项目特征对应的其他组合

2.4 本 playbook 推荐的默认基线（生态内多数项目适用）

默认基线 = arc42 精简版 + C4 + ADR + DDD + task-oriented 工程包

arc42 精简版（不是 12 部分全做）：业务架构 / 系统全景 / 系统运行 / 部署与基础设施 / 横向贯穿关注点 / 质量与验收 / 缺口与决策 / 落地映射
C4：Context（外部世界）+ Container（容器拓扑）+ Component（子系统组件）+ State Machine（业务对象生命周期）+ Sequence（关键场景流转）。不画 Code 图。
ADR：M0 启动前的关键接口决策必须 accepted；中优先级 ADR 可 M1+ 实施期补；每条 ADR 含 Context / Decision / Rationale / Consequences / Status / Related，≤80 行
DDD：业务架构部分识别 first-class business objects + bounded context；用 ubiquitous language 锚定术语
task-oriented 工程包：按里程碑切片，每个 milestone 一份 engineering-packs/m{N}-*.md，含具体 Pydantic / DDL / CLI / Mock fixture / CI 模板

各项目根据自身特征在此基线上增减：

数据型项目：加 Schema-First 章节
执行/合规型项目：加 合规追溯矩阵 章节
ML 项目：加 实验设计模板 + 模型卡
公开 API：加 OpenAPI spec

第三部分：五条核心范式（生态内通用）

下列范式独立于具体方法论选择，是"长链路、多步骤的架构文档重构"的结构性约束。

范式 1：工作流外化（Workflow Externalization）

问题：长链路文档重构跨多次会话 / 多个 Agent，单一会话 context 易爆，心智模型易漂移。

解法：把工作流状态、决策、草稿、Review 都外化到独立目录，会话只是"加工现场"。

最小目录结构：

governance/workstreams/<workstream-id>/
├── status.md                          # 节点时间线 + 当前状态 + 续接协议
├── decisions/                         # ADR-NNN-*.md 独立成档
├── drafts/                            # CHAP-NN-*.md 章节草稿
├── reviews/                           # 多 Agent Review 报告（按轮次组织）
└── <date>-retrospective.md            # 工作流收尾时的复盘

关键约定：

status.md 节点编号严格递增 + 每节点描述：时间戳 / 完成的事 / 当前阻塞
续接协议在 status.md 头部固定：读这份 → 查 ADR → 看草稿 → 不要回看对话历史
决策（ADR）与草稿（CHAP）互相独立
重要约定（稳定 ID 规则 / 写作纪律 / 战略不变量）固化到 status.md 末尾

模板：见 templates/architecture-document-rewrite/workstream-status.md

范式 2：主架构 + 工程包双轨（Dual-Track）

问题：单一架构文档随完整性提升必然膨胀；工程实施 Agent 一次性 load 时 context 占用过高，多文件操作或调试时易爆。

解法：

A 轨治理事实源（主架构）：战略 → 业务 → 系统 → 横向贯穿 → 质量 → 缺口 → 落地的完整契约定义
C 轨 task-oriented 工程包（engineering-packs/）：按里程碑切，每个 milestone 一份自包含工程材料

双轨契约：

维度	主架构（A 轨）	engineering-packs（C 轨）
战略不变量	定义	引用主架构 §N
业务对象	定义（含跨层映射表）	引用主架构 + 给 M{N} 数据模型
接口子集	抽象定义	具体 implement/stub/skip 表
数据模型 schema	引用工程包	完整代码
DDL	抽象总览	完整 SQL
CLI 规格	抽象	命令字符串 + 退出码
Mock fixture	概念	目录结构 + hash 算法
CI 模板	概念	完整 yaml
Bootstrap	不写	包管理 + 工具链选定

projects/<project-id>/engineering/
├── architecture.md                    # A 轨：治理事实源（典型 5000-7000 行）
└── engineering-packs/                 # C 轨：Agent 消费包
    ├── m0-<slug>.md                   # 走通骨架（典型 1500-3000 行）
    ├── m1-<slug>.md                   # 下一里程碑（按需起草）
    └── ...

约定：

每个 milestone 一个工程包文件
文件命名 m{N}-<slug>.md
主架构对应章节缩为简短指针段（≤80 行）
横向贯穿关注点（边界 / 可观测 / 演化）留主架构，被各工程包引用

何时该拆分：

主架构 ≥ 6000 行
工程实施 Agent 单次 load 主架构占 context ≥ 60%
已经经过 ≥ 1 轮多 Agent review（不要早拆，否则草稿期就分裂）

范式 3：多 Agent 跨视角三角验证（Cross-Agent Triangulation）

问题：单一 Agent / 单一视角 review 有盲点。

解法：按个人/团队的 Agent 路由表分工 + 多维度并行 + 跨 Agent 互不引用。

Reviewer 维度切片（默认 4-7 个）：

维度	看什么	推荐 Reviewer 来源
跨章内部一致性	业务对象 / 子系统 / 状态机在不同章节是否一致；§N 引用是否真指向被引内容	Claude Code sub-agent / Codex
上位文档对齐	主架构 vs 战略白皮书 vs 产品定义是否一致；上位有无需反向更新	Claude Code sub-agent
工程可实施性	接口签名是否够清晰让 Agent 实施；缺什么"工程包"；M0 完成度估算	Claude Code sub-agent / Codex
可读性 + mental model（R2 加）	新人按白皮书→产品→架构路径读，多久能开工	Claude Code sub-agent
落地 Agent 100% 严格（R2 加）	CI 拦截能力 / 偏离类型 / 自动化程度	Claude Code sub-agent / Codex
战略保真度 + 综合（每轮）	跨维度综合发现 + 跨 Agent 独立验证	Codex（不同模型形成多样性）

关键纪律：

互不引用：Reviewer 之间不引用对方报告，避免群体思维偏移
覆盖不同维度：每个 reviewer 视角任务清晰，不重复
混合 Agent 模型：至少包含 ≥ 2 个不同 LLM 厂商的 Agent（如 Claude + GPT），形成跨模型三角
统一输出 schema：P0 / P1 / P2 + 抽查问题 + 强项 + 独立发现五段式
核心文档主笔不外包：重要单文件文档（战略白皮书 / 产品定义 / 架构主稿）由主控亲笔撰写 / 编辑 / 合并；Codex 与子 Agent 仅用于独立评审，不主笔、不代为合并核心文档（避免核心叙事外包）

调度模式：

Claude Code sub-agent 内调度（Agent 工具 + run_in_background=true）
Codex worker-dispatch（codex exec --skip-git-repo-check < prompt.md > output.md）
混合：主控 Claude Code + Codex worker + 多 sub-agent

模板：见 templates/architecture-document-rewrite/review-task-packet.md

范式 4：草稿到合并的 merge-script 模式

问题：多章独立草稿如何合并为单一主文档？修订时如何避免主文档与草稿分叉？

解法：草稿是事实源 → merge 脚本是机械产物。

核心流程：

drafts 是修订入口：永远回 drafts/CHAP-NN-*.md 修改，不直接编辑合并后的主文档
prologue 在主文档：主文档顶部（frontmatter + 目录 + 配套资产指针）直接编辑
合并标记：主文档用  HTML 注释划分 prologue 与章节正文
机械合并：脚本读 drafts + 截取 prologue + 拼正文 + heading shift + 跨章引用替换

Merge script 接口（伪代码）：

def main():
    chapter_files = sorted(DRAFTS.glob("CHAP-*.md"))
    existing = TARGET.read_text()
    marker = "<!-- 以下为"
    prologue = existing[:existing.index(marker)+...]  # 截取 prologue
    parts = [prologue.rstrip() + "\n\n"]
    for f in chapter_files:
        body = strip_frontmatter(f.read_text())
        body = shift_headings(body, num, title)  # # 第N节 → ## N. 标题，其他下移
        parts.append(body.rstrip() + "\n")
    TARGET.write_text("".join(parts))

合并后处理：

CHAP-NN → §N 跨章引用替换（一次性 sed / Python 正则）
跑 verify-kb / 站点构建校验

模板：见 templates/architecture-document-rewrite/merge-script.py

范式 5：战略保真度 + 写作纪律双轨

问题：长文档容易掺入战略层被否决的概念 / 防御型清单 / 方法论冗余。

解法：双轨约束。

5.1 战略保真度（机械 + 人工双层）

机械层：verify-kb / CI 跑 grep 禁词清单（项目特定的被否决概念）
人工层：PR Review 必备一位非作者人员复核，识别同义改写（如禁词"X"被改写为"X倾向 / X指向"等）

Goodhart's law 防护：禁词 grep 命中数不作为质量指标，仅作为反例提醒。真正的合格判定是"人工实质语义核查 + 机械 grep"双层。

5.2 写作纪律

纪律	描述
内容 > 形式	每节 / 段落 / 表格服务实施者疑问，不为模板齐整堆砌
建设型而非防御型	重点说"做什么 / 怎么做"，不变成"不许什么 / 不是什么"清单
不解释方法论	方法论选择放 ADR；主文档只引结论
抽象 vs 具体	优先用项目实际场景说明，少用"系统应该"
图配三段说明	图表达什么 / 图特意不表达什么 / 怎么读这张图
专有名词第一次出现给一句话解释	强制
成熟态视野（L1 / 愿景类文档）	战略 / 愿景文档面向完整成熟态，第一阶段 / P0-P1 只是路径起点，勿把愿景降维到当前已实现范围
评审落到真稿	Review 对象必须是真源 / 真稿，不能是框架表 / 有损中间表达——后者会放大其实已在真源解决的 gap

第四部分：11 Phase 启动到收尾执行流程

下列流程可直接作为工作流维护者的 checklist。每 Phase 完成后跑 verify + 在 status.md 记节点。

Phase 0：启动前置（治理）

- [ ] 上位事实源齐备（战略白皮书 + 产品定义文档）
- [ ] 上位文档已对齐（任务清单 / 业务对象 / 边界 / 未决问题）
- [ ] 工程范式确定（参考本 playbook 默认基线）
- [ ] 工程协作模式确定（哪些 Agent / 工具 / Review 链路）
- [ ] 评估本项目的特征 → 用本 playbook §2.3 决策矩阵选定方法论组合

Phase 1：工作流初始化

- [ ] 建 `governance/workstreams/<workstream-id>/` 目录
- [ ] 起 status.md（节点 1：工作流初始化）—— 复制 `templates/workstream-status.md`
- [ ] 起 ADR-001 工程范式 / ADR-002 文档结构 / ADR-003 工程协作（继承生态范式或起草自己的）
- [ ] 在 status.md 末尾固化「写作纪律」「战略不变量」段

Phase 2：章节追踪表 + 草稿起草

- [ ] 决定章节数量与结构（参考本 playbook 默认基线 + §2.3 决策矩阵）
- [ ] 起章节追踪表（在 status.md）：每章 ID / 标题 / 状态 / 草稿文件 / 阻塞
- [ ] 按章节分批起草，每批 3-5 章为一个节点
- [ ] 每批完成时跑：战略保真度 grep + verify-kb + 在 status.md 记节点
- [ ] 业务架构章节（first-class objects + 场景 + 价值流转）必须先做（后续所有章节依赖）
- [ ] 横向贯穿章节（边界与安全 / 可观测性 / 演化与版本）必须在 ADR 之前做

Phase 3：合并为主文档

- [ ] 准备 merge script（复制 `templates/merge-script.py` 并改 TARGET 路径）
- [ ] 起主文档 prologue（frontmatter + 目录 + 配套资产指针）
- [ ] 跑 merge + CHAP-NN → §N 替换 + verify-kb
- [ ] 旧版主文档归档到 `_archive/projects/<project-id>/<date>-architecture-v1-rewrite/`（加 archived frontmatter + 归档说明）

Phase 4：多 Agent Review R1

- [ ] 启动 3-4 个 Claude Code sub-agent 并行（维度按 §3 范式 3 切片）
- [ ] 启动 Codex worker-dispatch（综合 + 独立验证）
- [ ] 持久化 4 份 review report 到 reviews/
- [ ] 起 R1 综合行动方案（合并 P0/P1/P2）

Phase 5：修订（按 R1 行动方案）

- [ ] P0 修订（必须，阻断 M0 启动）
- [ ] P1 修订（建议，影响落地质量）
- [ ] 重新跑 merge + verify-kb
- [ ] 在 status.md 记节点

Phase 6：双轨拆分（如主架构 ≥ 6000 行 / Agent context 占用 ≥ 60%）

- [ ] 评估是否真的需要拆分（早拆 = 草稿期就分裂，不可逆）
- [ ] 建 engineering-packs/ 目录
- [ ] 拆出 m0-<slug>.md（含 Pydantic + DDL + CLI + Mock fixture + CI 模板等）
- [ ] 主文档对应章节缩为指针段（≤80 行）
- [ ] 扩展派生脚本（如本仓有 derive-agent-pack.mjs）加 engineering-packs/ 路由
- [ ] 重新 merge + verify

Phase 7：多 Agent Review R2（视角切换）

- [ ] 启动 R2 reviewer，视角从「文档结构 / 内部一致性」切换到「实施新人 mental model」+「落地 Agent 100% 严格」+「Codex 综合独立验证」
- [ ] 持久化 R2 reports + 综合行动方案
- [ ] **诚实评估** M{N} 实施完成度（典型 60-85%，剩余靠 review gate + 评估闭环）

Phase 8：修订（按 R2 行动方案）

- [ ] 按 R2 P0/P1 修订
- [ ] 重新 merge + verify
- [ ] 在 status.md 记节点

Phase 9：上下游对齐

- [ ] 战略白皮书反向修订（如 review 发现遗漏 / 漂移）
- [ ] 产品定义文档反向修订（如发现遗漏 / 漂移 / 7 处 stub 指针）
- [ ] 同位 v1 文档归档（被新架构吸收的部分）—— 加 archived frontmatter + 顶部归档说明
- [ ] inbox 中相关 proposal 转 accepted + 加 acceptance_note 指向本工作流
- [ ] 项目级 README + 仓库根 CLAUDE.md 中过期的 hint 更新

下推（上游 → 下游）专项守则（L1→L2 下推实战教训）：

下推 ≠ 重述：保留上游分层坐标，不为「精简」重新分组。 把上游的层级 / 重要度 / 三维坐标往下压成更少层时，极易无意改写排序（实例：L1「突发事件 + 私域职业信号同列第一层」被下推压成「私域职业信号降第三层、结构化行情升第二层之上」）。行可重排，层不可改；必须改层级时显式标注「偏离上游 + 理由」并回写上游或落 ADR。
评审固定加一条「上游真源逐层比对」维度，专查下推是否悄悄改了排序 / 重要度（本次 CC + Codex 双路独立都把此项列为头号 blocking）。
新增任务包 / 编号前先核既有号段： grep "WP-" 全量，避免撞号（实例：拟用 WP-P2-02 撞既有 → 改 WP-P2-04）；任何被引用的 WP-ID 必须有定义（避免 WP-COVER-01 式失锚）；矩阵列出但未进「第一批」清单的任务包，须显式声明「首批子集」。
节号顺延连带核对： 新增章节前 grep "第.节" 与跨文档引用，顺延后复跑一次。

Phase 10：ADR 关键决策起草

- [ ] M0 启动前必锁的接口决策起 ADR（典型 3-5 条「高优先级 ADR」）
- [ ] 中优先级 ADR 留 M1+ 实施初期补
- [ ] 更新主架构的 ADR 索引章节（已 accepted vs 待写）

Phase 11：工作流收尾

- [ ] v1 实施类文档（goal-execution 类）加 deprecation banner
- [ ] status.md 节点收尾 + 工作流状态 active → stable
- [ ] 起复盘文档（复制 `templates/retrospective.md`）—— 工作流维护者必做
- [ ] 评估本次工作流的方法论实战检验，写回本 playbook（如发现新范式）

第五部分：项目特化适配指南

下表给出生态内项目类型的特化建议。各项目按自身特征在 §2.4 默认基线上增减。

5.1 数据感知 / 数据管道型项目

特征：偏数据型 first-class objects（事件 / 实体 / 时间线 / 数据点 / 数据源）；不直接 LLM 应用；下游消费方多。

特化建议：

加 Schema-First Design 章节（数据 schema 设计 + 演化策略 + lineage 追踪）
C4 Container 图为主（不需要复杂 Component 图）
engineering-packs 按数据源 / pipeline 阶段切（不按 LLM-milestone 切）
ADR 重点：数据 source 接入 / schema 演化 / 数据质量门禁 / lineage 实现
Review 维度增加：数据源契约对齐 / 数据质量保证 / 与下游消费方接口契合
横向贯穿章节：数据质量指标体系（freshness / completeness / accuracy / lineage）必加
加 感知版图 / 信息范围 方法（DH 2026-06 复用产出）：按「重要度设计（脱离现状，按市场 × 信息类型 × 结构化度 + 影响力 / 时效 / 风险 / 下游需求 / 差异化驱动）→ 映射当前实践覆盖 → 高重要度且未覆盖 = 优先工程化任务」三步建立；它同时是战略内容与改造 backlog 的桥
差异化优先于商品化：数据感知层优先做"别处难自助获取"的差异化资产（私域 / 事件合成 / 跨源印证 / 非标资产化）；第三方 API 可自助的商品化数据（标准行情）按需纳入、不优先重复路由

5.2 执行 / 交易型项目

特征：持凭证 + 受治理执行；合规约束远比认知型严格；多步骤交易签名。

特化建议：

加 合规追溯矩阵 章节（每条合规要求 → 文档 / 代码 / 审计 trail 落地）
加 凭证管理 ADR（与"不收不存"型项目的凭证不变量正交但不冲突）
engineering-packs 按执行场景切（市价 / 限价 / 网格 / 等）
ADR 重点：凭证存储 / 多签 / 执行回报与对账 / 监管审计可见性
Review 维度增加：合规边界审计 + 执行可靠性（含恢复路径）
横向贯穿章节：合规追溯 + 审计 trail 完整性（不可妥协）

5.3 ML 学习引擎 / 基础模型项目

特征：偏数据型 first-class objects（轨迹 / 奖励 / 模型版本 / 实验）；训练管道 + 模型服务双轨。

特化建议：

可能需要三轨：A 治理事实源 + B 实验包 + C 模型部署包
加 Model Card（模型卡）章节 —— 每个模型版本的能力 / 训练数据 / 评估 / 风险
加 实验设计模板（每实验一份，含 hypothesis / setup / evaluation / outcome）
ADR 重点：预训练数据 / 微调策略 / 量化推理 / 部署形态 / 评估 baseline
Review 维度增加：数据采集合规 / 实验设计严谨度 / 模型评估方法
横向贯穿章节：模型版本化与回滚 + 训练数据合规 + 实验可重现性

5.4 AI Native / Agent-first 应用型项目

特征：自然语言入口 + LLM Function Calling + 多 Provider 降级 + 状态化协作。

特化建议：

加 意图识别策略 ADR（LLM Function Calling 主导 vs 规则路径 vs 混合 — 默认推荐 LLM Function Calling 主导）
加 Provider 降级链 ADR（多层降级保证 LLM 不可用时仍可用）
加 凭证不变量章节（不收 / 不存 / 不训练金融执行凭证等业务边界）
加 评估闭环章节（LLM 输出无确定预期，需统计指标 + 数据集驱动）
engineering-packs 按里程碑切（Walking Skeleton + 状态化 + 任务扩展 + 入口扩展 + 评估闭环 + 演化）
Review 维度：意图识别准确率 / 综合输出契约（反方 / 失效条件 / 信息缺口）/ 凭证端到端阻断

5.5 内部工具 / 小项目

特征：单一团队 / 单一目标 / 短链路。

特化建议：

不需要完整 arc42 / DDD —— 直接 Google Design Doc + ADR 即可
不需要双轨拆分
Review 1 轮即可
模板：本 playbook 不强推；项目自决

5.6 公开 API 项目

特征：暴露外部 API；客户端多样；契约稳定性要求高。

特化建议：

OpenAPI / API Spec 作为契约事实源（机器可读）
ADR 重点：版本化策略 / 错误码 / 限流 / 鉴权
engineering-packs 按 API endpoint group 切
Review 维度增加：客户端兼容性 / 契约稳定性 / 错误码语义

第六部分：可复用模板指针

模板都在 templates/architecture-document-rewrite/ 子目录。

模板	用途	何时复制
`workstream-status.md`	status.md 模板（含续接协议 + 节点表头 + 章节追踪表骨架）	Phase 1 启动时
`adr.md`	ADR 模板（Context / Decision / Rationale / Consequences / Status / Related，≤80 行）	每条 ADR 起草时
`chapter-draft.md`	章节草稿模板（frontmatter + "这一节回答" 首句 + 内容骨架 + "与其他章节的关系"段）	每章起草时
`review-task-packet.md`	Review 任务包模板（含 Reviewer 视角 / 维度切片 / 输出格式要求 / 关键约束）	每轮 Review 启动时
`merge-script.py`	Merge 脚本模板（drafts/ → 主文档 + heading shift + prologue 截取）	Phase 3 / 每次重新 merge 时复制并改 TARGET
`retrospective.md`	复盘文档模板（量化产出 + 五范式实战检验 + 项目特化记录）	Phase 11 收尾时

第七部分：方法论的边界（诚实声明）

7.1 本 playbook 不能保证的事

局限	说明
依赖人工裁决	多 Agent review 找出 P0/P1，但最终修订决策仍需主控人裁决（Agent 不能自主推进战略层修订）
依赖工具链	merge-script / verify / Multi-Agent Review 调度等工具 —— 缺失需找替代方案
依赖工作流维护者的纪律	节点编号 / frontmatter 规范 / 战略保真度自检 —— 这些是人为纪律不是机械约束
质量上限有结构性约束	M{N} 阶段 CI 拦截率上限 ~50-55%（语义层 10-15%），要拉到 95%+ 需评估闭环上线 + LLM-as-judge —— 这是结构性约束不是方法论问题
不替代领域专业知识	本 playbook 是方法论 / 流程 / 模板。领域内容（金融认知 / 数据感知 / 交易执行等）由项目自身知识承载
并发共享工作区的提交	多会话共用一个 git 工作区时，`checkout -b` 切 HEAD 会打断活跃会话；应不切分支 + 选择性 `git add` 仅本工作流文件 + 贴仓库"直提 main"惯例
过程稿的相对链接陷阱	drafts/ 下的整合 / 过程稿若带原文相对链接（`./assets`、`../../`）会成断链、被 verify-kb 挡下；提交前清理一次性过程稿，或放在不被扫描的位置
工具 / 外部评审转储的入库友好性	`codex exec` 等工具的原始会话转储常带个人绝对路径 + 断裂相对链接 + 无 frontmatter，被 verify-kb（content-hygiene + links）挡下。入库前提炼为「带 frontmatter（含 `scope`/`maturity`）、去私有绝对路径、无悬空链接」的干净稿；原始转储留工作区 / `.agent-state`，不入治理库。工作流内每个 md 起手即补全 frontmatter 必填项
现行代码事实须逐文件核对、勿信 stale 文档	当 L3 / 架构文档引用现行代码事实（job / agent / 表 / 字段 / 路径 / 重试 / 监控 / 配置）时，必须以实际代码 + system-fact-map 为准核对，不采信 `CLAUDE.md`/`AGENTS.md`/README——这些 prose 文档极易漂移（DH L3 实战连续揪出：`dn_event_news_std` 停写却被述为活跃、`agent_job.go`/`news_std_agent.go` 不存在、MonitorJob 被误标价格监控、`retry_count<3` 是死代码、「配置驱动」实为硬编码、`etc/*.yaml` 明文凭证）。评审子 Agent 与 Codex 都应被要求逐文件核对；漂移登记入「风险 / 代码仓映射」节，不冻结错误现实。真实安全发现（明文凭证等）派生独立任务。
外部评审工具的大上下文限制	`codex exec` 评审整份大文档（数千行）+ 代码易触发 remote-compaction、丢失最终结论。把受审小节抽到临时文件、只附该段给外部工具（DH L3 自第五部分起改窄范围后连续多部无 compaction）。CC 子 Agent 可用全上下文，外部工具窄化。

7.2 真实的工作量预估

项目类型	章节数估算	工作流时长估算（连续投入）
数据型项目	20-25 章	25-35 小时
业务复杂型项目	25-30 章	30-40 小时
合规重型项目	25-30 章	35-45 小时
ML 型项目	22-28 章	30-40 小时
内部工具	5-10 章	5-10 小时（不走完整 11 Phase）

前提：上位事实源已稳定，主控人能投入连续时间（不是碎片化）。

7.3 方法论本身需要与项目共同演化

每次复用本 playbook，请把以下问题作为复盘核心写回：

这套方法在本项目上是否仍然适用？哪些步骤需要调整？
多 Agent review 的"维度切片"在本项目上需要怎样的新维度？
双轨是否需要变成三轨（如 ML 项目）？
战略保真度纪律的禁词清单在本项目上是什么？

每一次复用都是对方法论的实战检验。本 playbook 不是终极方案，是会演化的生态资产。

第八部分：Agent / 新会话快速启动

新 Agent / 新会话第一次接触本 playbook 时的标准动作：

Read commons/playbooks/architecture-document-rewrite.md（本文件）
查 §2.3 决策矩阵 → 决定本项目用什么方法论组合
跑 Phase 0 启动前置 checklist
复制 templates/workstream-status.md 起本项目 status.md
进入 Phase 1

每个 Phase 完成后回到本 playbook 对照下一 Phase checklist，跑完 11 Phase。

复盘文档复制 templates/retrospective.md，工作流收尾时填写。

第九部分：本 playbook 的来源与反馈

起源：FinBayes 项目（认知型 AI Native 应用）2026-05-26 至 2026-05-27 完成的架构文档从 v1 到 v2 的重写工作流，过程见 governance/workstreams/finbayes-arch-rewrite/，包含全程 21 个工作流节点的 status.md 时间线 + 6 份 accepted ADR + 9 份多 Agent Review 报告 + 复盘原始版本。

反馈机制：

每次复用本 playbook 的项目在收尾时写复盘，识别新范式 / 调整建议
调整建议如有共识，通过 governance/change-protocol.md 流程回写本 playbook
本 playbook 跨项目的实战检验越多，质量越高

当前版本：v1.3（2026-06-01）—— 在 FinBayes 架构重写基线上，吸收 Data Horizon L1 矫正、L1→L2 下推、L2→L3 全新撰写三个工作流的复盘反馈（注：DH L3 是首次用本 playbook 从零撰写一份对标 29 节的 L3 架构文档，验证了范式与纪律可覆盖 L1 矫正 / L2 下推 / L3 新撰三类操作）

目标演化路径：

v1.0 → v1.1（2026-06-01，已应用）：DH 战略白皮书矫正工作流复用，新增——写作纪律「成熟态视野」「评审落真稿」、范式 3「核心文档主笔不外包」、§5.1 感知版图方法与差异化优先、§7.1 并发工作区提交与过程稿链接陷阱（来源：governance/workstreams/data-horizon-whitepaper-refine/2026-06-01-retrospective.md）
v1.1 → v1.2（2026-06-01，已应用）：DH L1→L2 下推工作流复用，新增——Phase 9「下推专项守则」（下推≠重述·保层级、评审加上游逐层比对维度、WP-ID 号段核对与索引闭合、节号顺延连带核对）、§7.1「工具 / 外部评审转储入库友好性」（来源：governance/workstreams/data-horizon-l2-downstream-sync/2026-06-01-retrospective.md）
v1.2 → v1.3（2026-06-01，已应用）：DH L2→L3 全新撰写工作流复用，新增——§7.1「现行代码事实须逐文件核对、勿信 stale 文档」（CLAUDE.md 漂移连环教训）、「外部评审工具大上下文限制 → 受审小节窄化规避 compaction」；并验证「分部主笔（约 3 节/部）+ 逐部双路评审（CC 代码核对 + Codex）+ 用户每部过目」对 29 节大文档的可控性（来源：governance/workstreams/data-horizon-l3-architecture/2026-06-01-retrospective.md）
v1.3 → v1.4：TM（交易执行）项目复用后的调整（预计新增合规追溯矩阵细化）
v1.3 → v2.0：4+ 个项目复用后形成稳定通用基线

第一部分：什么时候用本 playbook​

第二部分：方法论框架（选型矩阵）​

2.1 主流方法论对比​

2.2 不能单用某一种 — 必须组合​

2.3 项目特征 → 方法论组合的决策矩阵​

2.4 本 playbook 推荐的默认基线（生态内多数项目适用）​

第三部分：五条核心范式（生态内通用）​

范式 1：工作流外化（Workflow Externalization）​

范式 2：主架构 + 工程包双轨（Dual-Track）​

范式 3：多 Agent 跨视角三角验证（Cross-Agent Triangulation）​

范式 4：草稿到合并的 merge-script 模式​

范式 5：战略保真度 + 写作纪律双轨​

5.1 战略保真度（机械 + 人工双层）​

5.2 写作纪律​

第四部分：11 Phase 启动到收尾执行流程​

Phase 0：启动前置（治理）​

Phase 1：工作流初始化​

Phase 2：章节追踪表 + 草稿起草​

Phase 3：合并为主文档​

Phase 4：多 Agent Review R1​

Phase 5：修订（按 R1 行动方案）​

Phase 6：双轨拆分（如主架构 ≥ 6000 行 / Agent context 占用 ≥ 60%）​

Phase 7：多 Agent Review R2（视角切换）​

Phase 8：修订（按 R2 行动方案）​

Phase 9：上下游对齐​

Phase 10：ADR 关键决策起草​

Phase 11：工作流收尾​

第五部分：项目特化适配指南​

5.1 数据感知 / 数据管道型项目​

5.2 执行 / 交易型项目​

5.3 ML 学习引擎 / 基础模型项目​

5.4 AI Native / Agent-first 应用型项目​

5.5 内部工具 / 小项目​

5.6 公开 API 项目​

第六部分：可复用模板指针​

第七部分：方法论的边界（诚实声明）​

7.1 本 playbook 不能保证的事​

7.2 真实的工作量预估​

7.3 方法论本身需要与项目共同演化​

第八部分：Agent / 新会话快速启动​

第九部分：本 playbook 的来源与反馈​

第一部分：什么时候用本 playbook

第二部分：方法论框架（选型矩阵）

2.1 主流方法论对比

2.2 不能单用某一种 — 必须组合

2.3 项目特征 → 方法论组合的决策矩阵

2.4 本 playbook 推荐的默认基线（生态内多数项目适用）

第三部分：五条核心范式（生态内通用）

范式 1：工作流外化（Workflow Externalization）

范式 2：主架构 + 工程包双轨（Dual-Track）

范式 3：多 Agent 跨视角三角验证（Cross-Agent Triangulation）

范式 4：草稿到合并的 merge-script 模式

范式 5：战略保真度 + 写作纪律双轨

5.1 战略保真度（机械 + 人工双层）

5.2 写作纪律

第四部分：11 Phase 启动到收尾执行流程

Phase 0：启动前置（治理）

Phase 1：工作流初始化

Phase 2：章节追踪表 + 草稿起草

Phase 3：合并为主文档

Phase 4：多 Agent Review R1

Phase 5：修订（按 R1 行动方案）

Phase 6：双轨拆分（如主架构 ≥ 6000 行 / Agent context 占用 ≥ 60%）

Phase 7：多 Agent Review R2（视角切换）

Phase 8：修订（按 R2 行动方案）

Phase 9：上下游对齐

Phase 10：ADR 关键决策起草

Phase 11：工作流收尾

第五部分：项目特化适配指南

5.1 数据感知 / 数据管道型项目

5.2 执行 / 交易型项目

5.3 ML 学习引擎 / 基础模型项目

5.4 AI Native / Agent-first 应用型项目

5.5 内部工具 / 小项目

5.6 公开 API 项目

第六部分：可复用模板指针

第七部分：方法论的边界（诚实声明）

7.1 本 playbook 不能保证的事

7.2 真实的工作量预估

7.3 方法论本身需要与项目共同演化

第八部分：Agent / 新会话快速启动

第九部分：本 playbook 的来源与反馈