bestpractice_architecture_doc_design

道-方法 · 道层 skill 全文

本页是 <code>rules/skills/drafts/bestpractice_architecture_doc_design.md</code> 的逐字投影（仅隐私清洗，零改写）。

架构文档设计方法论

1. 背景

NightCode 是一个多模型 AI Agent 编排平台。在经历多次实现尝试失败后，发现核心问题在于文档散落、版本混乱、缺乏统一的实现计划。

文档散落现状：

• .kiro/specs/ — Kiro 规范文件（unified-system-description, system-flow-diagrams）
• docs/v4.5-architecture/ — 旧版架构文档（结构可参考但内容过时）
• Modification Plans (Theme 3-10) — 最新的设计决策（分散在多个文件中）
• 源代码 src/ — 实际模块组织

核心问题：没有一个"唯一真实来源"，每次实现都要重新拼凑信息。

2. 设计过程

2.1 调研阶段

方法：并行多源调研 + 对比分析

同时调研 4 个信息源，重点找出信息之间的不匹配：

关键发现：

• V4.5 的 Agent 分组太笼统，没有区分 Brain / Working / Advisory
• Task Splitter 应从 Prometheus 中独立
• Atlas 已废弃，Agent Builder 是函数不是 Agent
• Permission 系统和 Anti-hallucination 是 Theme 4/5 的核心但 V4.5 中完全缺失
• Recovery 应独立成章，不应嵌在 Orchestration 下

2.2 框架设计原则

经过讨论确定 4 条设计原则：

1. Follow the data flow — 按请求流转顺序组织章节（入口 → 规划 → 执行 → 基础设施），而非按技术层级编号（L0/L1/L2）。读者沿着数据流自然理解系统。

1. Agent-centric grouping — 将 Agent 按角色分为 3 类，各成一章：
• Brain Agent（规划/审核/分析）
• Working Agent（代码执行）
• Advisory Agent（信息收集，只读）

1. Three-tier progressive disclosure — 三层渐进式披露：
• INDEX.md → 系统全貌，1 分钟理解
• 章节 README.md → 某个子系统概览，5 分钟理解
• Detail Doc → 某个组件的完整规范，按需深入

1. "Where to look" as first-class — GUIDE.md 是核心导航文档，回答"我想做 X，应该从哪开始？"

2.3 交叉引用协议（核心创新）

问题：跨层概念（如 Process Documentation）同时涉及 5+ 个章节。如果每处都完整描述 → 重复，必然失去同步。如果只写一处 → 读者要跳 5 个文档才能理解。

解决方案 — 三层协议：

层 1: Canonical Source（权威源）

每个概念有且仅有一个权威文档，所有实现细节、格式规范、状态机图都只在这一处完整描述。

在 INDEX.md 末尾维护"权威源映射表"：

| 概念 | 权威文档 | 涉及章节 |
|------|---------|---------|
| Process Documentation | 06-infrastructure/process-doc-system.md | 02, 03, 04, 07 |
| Context Pressure States | 06-infrastructure/context-manager.md | 03, 04, 07 |

这张表本身就是"更新时去哪同步"的查找表。

层 2: Contract Block（契约块）

在非权威文档中，用标准化的契约块描述"本层对该概念的义务"：

### → Process Documentation

**本层义务**: Working Agent 必须在任务结束前输出 `[PROCESS_SUMMARY]`，
包含 status、filesModified、decisions 三个必填字段。

**本层限制**: Worker 不得修改其他 Agent 的 Process Doc 文件。

**权威规范**: [Process Doc System](../06-infrastructure/process-doc-system.md#output-format)

关键规则：

• → 前缀标识交叉引用
• 只描述本层义务和限制，不解释概念本身的设计原理
• 必须包含指向权威文档的链接

层 3: Dependency Header（依赖头）

每个 detail 文档在 YAML frontmatter 中声明依赖关系：

---
canonical-for:
  - process-doc-output-format    # 本文档是这些概念的权威源
depends-on:
  - 06-infrastructure/context-manager.md  # 本文档引用了这些权威源
touched-by:
  - 03-brain-layer/README.md     # 修改本文档时需检查的其他文档
---

2.4 更新协议（5-Phase + Git + 审查）

修改任何文档时的标准流程（UPDATE-SEQUENCE.md 定义了完整版）：

Git Commit（如有未提交变更）
  ↓
Phase 1: 意图锚定 — 先更新 USER-REQUIREMENTS.md，固定"为什么改"
  ↓
Phase 2: 权威源修改 — 只改一个文件，记下 touched-by 列表
  ↓
Phase 3: 契约传播 — 更新 touched-by 中的契约块
  ↓
Phase 4: 结构同步 — 仅在文件增删时触发，更新 INDEX/README
  ↓
Phase 5: 变更记录 — CHANGELOG.md 追加语义记录
  ↓
Git Commit（必须）
  ↓
Phase 6: 文档审查 — spawn doc-validator，按 R1~R5 审查

核心原则：每个环节做完就立刻更新，不攒批；按依赖顺序执行，避免加载不需要的文件（防 context 污染）。

配套机制：

• 各场景最小更新路径（6 种典型场景，含场景 F「从设计文档写入」）
• 反模式列表（8 种不要做的事）
• Git 版本控制包裹（写入前后 commit）

2.5 用户需求文档（后续补充的核心环节）

在首次创建框架后，发现一个关键缺失：设计文档中没有记录用户的原始需求和裁定。这导致：

• 填充具体内容时无法追溯某个设计选择的来源
• 冲突裁定的结果没有持久化，下次对话可能重复讨论
• 不同文档之间的取舍缺乏统一依据

解决方案：在框架根目录添加 USER-REQUIREMENTS.md：

• 地位：优先级最高，高于所有其他设计文档
• 内容：每条需求包含用户原文（引用块）+ 背景 + 影响
• 更新规则：随用户交流实时更新
• 冲突裁定：当两个源文档冲突时，用户的裁定记录在此
• 待裁定追踪：已知冲突但未获裁定的事项也记录在此

这是整套方法论中最重要的补充——文档框架的权威性来自用户需求，不来自任何技术文档。

2.6 设计变更记录（语义层面的版本控制）

Git commit 记录文件变更，但不记录设计意图的演进。例如一个 commit 可能修改了 3 个文件，但无法说明"为什么这个设计选择从 A 改成了 B"。

解决方案：在框架根目录添加 CHANGELOG.md：

• 记录维度：触发来源、涉及文档（精确到文件 + 具体修改内容）、设计意图
• 记录标准：简短但全面，高精细度。纯格式调整不记录，仅记录有意义的设计变更
• 与 Git 的关系：CHANGELOG 记录"为什么"，Git 记录"什么变了"。两者互补
• 集成到更新协议：修改文档标准流程中新增 Step 5（记录设计变更）

记录格式：

### YYYY-MM-DD — [变更摘要]
**触发来源**: [用户裁定 / 冲突分析 / 实现反馈 / 重构]
**涉及文档**:
- `路径/文件.md` — 具体做了什么修改
**设计意图**: 一句话说明为什么做这个变更

2.7 编写规范：叙述与代码分离

设计文档的核心目的是传达"是什么"和"为什么"，而非"怎么写代码"。如果代码实现细节混在叙述中，会导致：

• 读者被实现细节干扰，无法快速理解设计意图
• 代码一旦变更，文档中的代码片段就过时
• 难以区分"必须遵守的设计约束"和"可以灵活实现的参考"

解决方案：WRITING-STANDARDS.md 定义了文档结构规范：

1. 文字叙述占文档前 80%：需求与本质（必须放最前）、设计、职责边界、行为描述，全部用自然语言
2. 代码设计统一放在文档末尾（附录）：只保留最关键的协议、接口、数据结构
3. V1 版本声明：附录中的代码设计标注为"V1 草案，仅供参考"，实际开发时应采取更缜密的方式
4. 不放的内容：内部实现逻辑、工具函数、配置格式、测试用例
5. 内容单一性：每个设计内容只在权威源完整描述，非权威文档通过契约块引用，零冗余

2.8 文档审查机制（LLM 驱动）

文档写完后，如何确保质量？人工审查不现实（文档数量多），脚本检查又无法做语义判断。

解决方案：用 LLM agent 自动审查，CHANGELOG 驱动确定审查范围：

• 审查规则：VALIDATION-RULES.md 定义 5 类检查（R1 结构、R2 需求质量、R3 可追溯性、R4 内容规范、R5 冲突检测）
• 审查 agent：.claude/agents/doc-validator.md，只读操作，不修改文档
• 触发方式：文档修改 + Git Commit 后，主 agent 自动 spawn doc-validator
• 审查范围：读取 CHANGELOG 最新条目，只审查本次涉及的文档
• 结果持久化：审查状态表在 VALIDATION-RULES.md 中逐文档追踪
• 严重性分级：❌（违反硬性规则，必须修复）、⚠️（质量不足，建议修复）、✅（通过）
• 修复流程：审查发现的问题作为新一轮更新（从 Phase 1 开始），不在审查中直接修复

3. 最终产出物

框架结构（10 个章节 + 7 个入口文件）

docs/architecture/
├── USER-REQUIREMENTS.md        # 用户需求文档（最高优先级）
├── CHANGELOG.md                # 设计变更记录（语义层版本控制）
├── UPDATE-SEQUENCE.md          # 更新次序规范（5-Phase 流程）
├── WRITING-STANDARDS.md        # 编写规范（叙述与代码分离）
├── VALIDATION-RULES.md         # 审查规则（R1~R5）+ 审查状态追踪
├── INDEX.md                    # 全局入口 + 权威源映射表
├── GUIDE.md                    # 操作指南 + 更新协议
├── 01-system-overview/         # 架构总览、设计原则、执行模式、数据流
├── 02-orchestrator/            # Sisyphus 入口 + 指挥
├── 03-brain-layer/             # 规划流水线
├── 04-working-agents/          # 执行层 + 共享协议
├── 05-advisory-agents/         # 信息收集层
├── 06-infrastructure/          # Hook、Signal、Context、ProcessDoc、Injector
├── 07-recovery/                # Tier 0-3 恢复
├── 08-monitoring/              # Health Monitor + Model Selector
├── 09-permissions/             # Permission Templates + Anti-hallucination
└── 10-cross-cutting/           # 信息重要度、并发模型、已知问题

与 V4.5 的关键区别

4. 可复用的设计方法（适用于任何复杂系统）

1. 多源调研 + 对比分析 — 先广泛收集所有信息源，重点找出信息之间的不匹配
2. 按数据流而非技术分层组织 — 读者沿着请求生命周期自然理解系统
3. 渐进式披露 — INDEX → README → Detail，3 层深度，读者按需深入
4. 交叉引用协议 — 权威源 + 契约块 + 依赖头，解决跨模块概念同步问题
5. 操作指南优先 — GUIDE.md 回答"我想做 X，去哪找"
6. 更新协议内置 — 不只写文档，还要写"如何更新文档"
7. Agent-centric 分类 — 按角色（Brain/Working/Advisory）而非按技术特征分组
8. 用户需求文档优先 — USER-REQUIREMENTS.md 是最高优先级，所有设计可追溯到用户原文
9. 语义变更记录 — CHANGELOG.md 记录设计意图演进，与 Git 互补（Git 记录"什么变了"，CHANGELOG 记录"为什么"）
10. 叙述与代码分离 — 文字叙述占前 80%，代码设计放末尾附录，标注 V1 仅供参考
11. 更新次序规范 — 5-Phase 严格次序（意图锚定 → 权威源 → 契约传播 → 结构同步 → 变更记录），防止 context 污染和遗忘
12. 内容单一性 — 写入设计内容时完全拆分到权威位置，零冗余。非权威文档只用契约块引用，不复制内容。与交叉引用协议互补（协议管读取导航，单一性管写入约束）
13. Git 版本控制包裹 — 每次文档更新前后都有 Git 提交。写入前提交保证可回滚基线（已干净则跳过），写入后提交保证变更持久化。与 CHANGELOG 互补（Git 管文件快照，CHANGELOG 管语义意图）
14. 需求按模块归属 — 需求嵌入模块文档，不集中存放。每个模块以"需求与本质"开篇（需求是什么 → 模块本质 → 为什么重要），然后是具体设计。USER-REQUIREMENTS.md 转为用户决策登记处 + 归属索引。跨模块需求指定一个归属模块（完整分析）+ 若干影响模块（描述本地影响），复用交叉引用协议的权威源 + 契约块机制
15. LLM 驱动的文档审查 — 每次文档修改后自动触发 LLM agent 审查。CHANGELOG 驱动确定审查范围，按 5 类规则检查（结构、需求质量、设计可追溯性、内容规范、冲突检测）。审查状态逐文档追踪，持久化在审查规则文件中。全 LLM 方案，无脚本依赖
16. 需求贯穿渐进式披露 — "需求与本质"不只出现在最细粒度的模块文档中，而是贯穿每一层：INDEX（系统使命）→ 章节 README（子系统整体需求 + 本质定位）→ Detail Doc（单模块需求 → 本质 → 设计）。每一层自然衔接，读者在任何深度都能理解"为什么需要这个"
17. 写入协议（内容归属判定 + 渐进式读取 + 写入场景） — 解决"给定设计文档如何写入架构"的完整路径。GUIDE.md 新增「内容归属判定」：Step 0 渐进式读取（读取范围随流程推进逐步扩大：归属判定只读框架文件 → 写入准备读目标文件 → 契约传播读 touched-by）+ Step 1-5 内容路由（概念拆解 → 查映射表 → 章节路由 → 权威源确定 → 内容拆分）。UPDATE-SEQUENCE 新增场景 F（从设计文档写入架构文档的 Phase 0→5 流程）。读取策略不放在 WRITING-STANDARDS（它只管输出格式），而是作为内容归属判定的前置步骤

5. 适用场景判断