文档-代码同步规范 v1.0
文档-代码同步规范 v1.0
摘要
本规范定义 Xisound 文档体系与代码仓库如何保持同步的政策。 核心理念：分层治理（不同文档层用不同同步策略）· 漂移容忍（架构层接受短期不一致）· CI 强制（实现层必须 1:1 mirror）· 四级校验（PR / Sprint / 季度 / Release）。 适用于所有 Xisound 文档作者、代码工程师、QA 与项目经理。
v1.0 生效
本规范于 2026-05-06 基于《技术开发文档体系方案 v1.0》（O3/O6 拍板）固化生效。 所有新写的文档和代码变更必须遵守本规范。历史文档按 §6 渐进式对齐。
1. 背景与动机
1.1 为什么需要本规范
初创期 / 快速迭代期的 Xisound 普遍存在以下痛点：
| 痛点 | 表现 |
|---|---|
| 文档追不上代码变化 | 代码每天改，文档只在 PR 时才改 |
| 不知道"改代码要不要改文档" | 工程师凭感觉决定，标准不一致 |
| 不知道"哪些文档是准的" | 找到一份文档，不知是最新还是过时 |
| 新人 onboarding 混乱 | 文档和代码讲的不是同一个系统 |
| 被 review 时反复返工 | Reviewer 说"文档没同步"，已经合并又拆 |
根本原因：所有文档被"一刀切"对待（要么强制同步要么全不管），没有分层治理。
1.2 本规范的目标
四大目标
- 按层分治：不同文档层（D0-D6）用不同策略，避免一刀切
- 明确契约：每个工程师 / 作者清楚"什么时候必须改文档"
- 漂移容忍：承认架构层短期会漂移，但有定期校准机制
- CI 强制底线：实现层（D4）偏差必须被 CI 拒绝合并
2. 三种同步模式（公司实践）
不同文档层的本质是选择不同的"真源"：
2.1 三模式对比
| 模式 | 真源 | 变更方向 | 代表行业 | 代表公司 |
|---|---|---|---|---|
| A · Code-First | 代码 | 代码变 → 文档跟着变 | 互联网 / SaaS（80%） | FAANG · Stripe · Linear · Vercel |
| B · Docs-First | 文档 | 文档变 → 代码跟着变 | 安全关键（汽车 / 航空 / 医疗） | Bosch · Tesla · 宁德 · 波音 |
| C · Contract-First | 接口契约（OpenAPI / Proto） | 契约变 → 代码 + 文档双向生成 | 中台 / API 平台 | AWS · Google Cloud · 阿里云 |
2.2 Xisound 采用的模式
分层混合（与业内字节 / 阿里 / 华为类似）：
flowchart TB
S[文档层] --> D0[D0 战略/品牌/融资<br/>Docs-First · 年度]
S --> D1[D1 中心章程<br/>Docs-First · 季度]
S --> D2[D2 产品 PRD/Spec<br/>Docs-First · Release 级]
S --> D3[D3 架构级<br/>Docs-First（初稿）+ 漂移容忍]
S --> D4[D4 实现级<br/>Code-First · PR 级 CI 强同步]
S --> D5[D5 执行模板<br/>静态]
S --> D6[D6 测试运维<br/>Code-First]
S --> EXT[external 对外<br/>Docs-First · 法务 review]
classDef docs fill:#6B3FA0,stroke:#6B3FA0,color:#fff
classDef code fill:#DFA66D,stroke:#DFA66D,color:#fff
classDef hybrid fill:#A83F88,stroke:#A83F88,color:#fff
class D0,D1,D2,EXT docs
class D4,D6 code
class D3 hybrid3. Xisound 七层治理策略（按层细则）
3.1 总表 · 每层策略一览
| 层 | 策略 | 同步频率 | 谁负责 | CI 强制？ |
|---|---|---|---|---|
| D0 · 公司级 | Docs-First | 年度 review | CEO / CFO / HR / 法务 | ❌ |
| D1 · 中心级 | Docs-First | 季度 review | 各中心负责人 | ❌ |
| D2 · 产品级 | Docs-First（PRD/Spec）+ Code-First（tech-arch/api） | Release 级（大版本） | 产品经理 + 研发 owner | 部分（API 文档） |
| D3 · 架构级 | Docs-First（初稿）+ 漂移容忍 | 季度架构评审 | 架构组 | ❌（但有漂移检查） |
| D4 · 实现级 | Code-First | PR 级 | 代码 owner | ✅ 强制 |
| D5 · 执行级 | 静态模板 · 无需同步 | 年度 | 文档工程 | ❌ |
| D6 · 测试运维 | Code-First | PR 级 | QA / SRE | ✅ 强制 |
| external · 对外 | Docs-First + 法务 review | Release 级 | 市场 + 法务 | ❌（但有公开性审查） |
3.2 D0 · 公司级（Docs-First · 年度）
定义：战略 / 品牌 / 融资 / 制度 / 跨中心规范
同步规则： - 战略 / 愿景 → 年度 review（每年 Q4 review 下一年规划） - 品牌 / 色彩 → 重大改版时（如 v1.0 → v2.0） - 融资材料 → 每轮融资前 CFO 更新 - 合同模板 → 法规变更时 法务更新
判断文档过时： - ❌ 不需要看代码 - ✅ 看外部环境变化（法规 / 市场 / 融资轮次）
3.3 D1 · 中心级（Docs-First · 季度）
定义：各中心章程 + 职责边界 + 内部规范
同步规则： - 每季度末各中心负责人 review 本中心文档 - 组织架构变更时立即更新 - 规范细则（如 sw-dev-spec）：代码实践验证过的规则才能更新规范
3.4 D2 · 产品级（混合）
定义：每产品 12 份模板文档（P1-P10 × 12 = 120 份）
同步规则（按模板类型差异化）：
| 模板 | 策略 | 触发 |
|---|---|---|
| overview / prd / spec | Docs-First | 产品里程碑（M1/M2/M3） |
| tech-arch | 混合 | 架构大改时 · 配合 D3 |
| api | Code-First | 代码 API 签名变化立即同步 |
| user-manual | Docs-First | Release 级 |
| one-pager / pricing / competitor | Docs-First | 营销活动 / 季度 review |
| changelog | Code-First | 每次 Release 自动生成 |
| faq | Docs-First | 客户反馈累积后 |
| training | Docs-First | 员工培训需求 |
3.5 D3 · 架构级（Docs-First 初稿 + 漂移容忍）⭐ 重点
定义：System / Backend / Frontend / DSPAlgo / Data-Model / Protocol / Deployment Topology
核心理念：架构文档是"北极星"，指导代码怎么写；但承认代码执行中会漂移。
同步规则：
| 阶段 | 动作 | 频率 |
|---|---|---|
| 初稿 | 架构组先写 D3 文档 · 定义"理想架构" | 项目启动 |
| 实施 | 代码按 D3 实现 · 如需偏离必须开 ADR（Architecture Decision Record）记录 | 持续 |
| 漂移识别 | 每季度架构评审对比 D3 与实际代码 | 季度 |
| 对齐 | 发现偏差 → 决定是改文档迁就代码还是改代码迁就文档 | 季度末 |
| 重大改版 | D3 文档升 v2.0 · 触发代码重构 | 年度 |
漂移容忍窗口： - ≤ 1 个月：正常 · 不 block - 1-3 个月：标 "⚠️ 已知漂移" - > 3 个月：必须季度评审对齐
3.6 D4 · 实现级（Code-First · CI 强制）⭐ 重点
定义：与 04_development/ / 03_algorithms/ / 07_web/xisound-website/ 代码仓库 1:1 mirror
同步规则：
CI 强制规则
任何 PR 修改代码目录（如 04_development/backend_csharp/Controllers/*.cs）→ 必须同步修改对应的 D4 文档（D4-implementation/backend-csharp/controllers/*.md）。
未同步的 PR 将被 CI job docs-sync-check 自动阻断合并。
对应规则：
代码路径 ↔ 文档路径
04_development/backend_csharp/**/*.cs D4-implementation/backend-csharp/**/*.md
04_development/frontend_vue3/src/**/*.ts D4-implementation/frontend-vue3/**/*.md
04_development/dsp_algo/**/*.c D4-implementation/dsp-algo/**/*.md
04_development/pysidecar/**/*.py D4-implementation/pysidecar/**/*.md
03_algorithms/**/*.{m,py,c} D4-implementation/algorithms/**/*.md
07_web/xisound-website/src/**/*.astro D4-implementation/web-astro/**/*.md
豁免清单（不触发 CI 检查）：
- 测试文件变化（**/*.spec.* / **/tests/**）
- 注释 only 修改
- 格式化 only 修改（prettier / dotnet format）
- 依赖版本升级（package-lock.json / *.csproj.lock.json）
3.7 D6 · 测试与运维（Code-First）
定义：unit / integration / e2e / hil / cicd / ops/monitoring / ops/release / ops/incident
同步规则：
- 新增测试类型 → 同步更新 D6 规范
- CI 流水线变更 → 同步更新 D6-testing-ops/cicd/
- 线上事故 → 7 天内 必须写 Postmortem
3.8 external · 对外（Docs-First + 法务 review）
定义：面向客户 / 公开发布的产品主页 / 技术支持 / 下载 / Demo
同步规则： - 所有对外文档必须 法务 + 市场双签 才能发布 - 任何与产品能力相关的描述必须有 D2/D3 内部文档作为来源引用（防止吹牛） - 变更 → 先改内部 → 再决定是否暴露到对外 → 法务 review → 发布
4. 四级检查时点
4.1 PR 级（最高频 · 实时）
触发：每个 Pull Request 提交
检查项：
- ✅ CI job docs-sync-check 扫描代码改动路径，对比文档是否同步
- ✅ reviewer 人工 check：D4/D6 文档是否一致
- ✅ 新增功能必须有 D3 架构章节 ref 或 ADR
违规处置：CI 拒绝 · PR 无法合并
4.2 Sprint 级（2 周）
触发：每个 sprint 结束前一天
检查项： - 本 sprint 所有 PR 是否都同步了文档？ - 有没有"临时豁免"的 PR 没补回来？ - 本 sprint 产生的 ADR 是否归档？
违规处置：开 issue 指派给 owner 补
4.3 季度级（3 个月）
触发：每季度第一周
检查项： - D3 架构评审：对比文档与实际代码，识别漂移，决定对齐方向 - D1 中心规范是否仍适用？ - D5 模板是否需要更新？ - external 对外材料是否过期？
产出： - 《Qx 文档-代码同步审查报告》（D5 模板） - 本季度漂移修正 backlog
4.4 Release 级（大版本）
触发：发布 v1.0 / v2.0 / 车规 Tapeout / ASPICE 认证
检查项： - 全体系文档 snapshot - D2 产品文档完整 review - external 对外发布材料法务 review - 溯源矩阵（需求 → 设计 → 实现 → 测试）检查（车规专属）
5. 角色与职责（RACI）
| 动作 | 工程师 | Doc Owner | Tech Lead | Architect | QA | Doc Engineer |
|---|---|---|---|---|---|---|
| PR 同步 D4 文档 | R | A | C | I | I | I |
| 创建 ADR | R | C | A | C | I | I |
| D3 季度评审 | C | C | C | R/A | I | C |
| D4 CI job 维护 | R | I | C | C | I | A |
| Release 文档 snapshot | I | C | C | C | C | R/A |
| D0/D1 规范更新 | I | I | C | C | I | R/A |
R = Responsible（执行）· A = Accountable（负责）· C = Consulted（咨询）· I = Informed（知会）
6. 历史文档渐进式对齐策略
对于 规范生效前的历史文档（如 old-arch-doc/ 33 份），采用渐进式对齐：
6.1 分类处理
| 文档状态 | 处置 |
|---|---|
| 历史定稿 · 内容稳定（如 System Architecture v7） | 迁入 D3 + 标注 as of 2026-05 · 代码迭代中 |
| 多版本草稿（如 DSPAlgo v5/v6） | 归档 _legacy_arch_drafts/ · 仅保留最终版 |
| 与代码严重偏离（> 6 个月） | 标 🔴 deprecated · 等待季度评审决定重写或删除 |
| 内容仍有价值但过时 | 保留 · 加 ⚠️ 历史参考 · 内容待更新 横幅 |
6.2 对齐节奏
- 批 1：骨架建立（本规范生效即完成）
- 批 2：历史定稿原样迁移 + 标注
- 批 3：草稿归档
- 批 4-5：D4 实现级 AI 辅助生成（基于当前代码）
- 批 6：季度评审后，根据漂移情况决定是否重写 D3 主文档
7. 工具链与自动化
7.1 CI Job 设计（O6=C 拍板 · 规划 2026 Q2 落地）
job 名称：docs-sync-check
执行逻辑：
# .github/workflows/docs-sync-check.yml
name: docs-sync-check
on: pull_request
jobs:
check:
steps:
- 获取 PR diff
- 识别修改的代码文件路径
- 按 §3.6 映射表找对应文档路径
- 若代码改了但文档没改 → 失败
- 识别豁免清单（§3.6 末）→ 跳过
- 输出报告到 PR comment
7.2 AI 辅助（O8=C 拍板）
场景： - AI 每周扫描代码变更 vs 文档，生成"偏差热力图"issue - AI 根据代码自动生成 D4 文档草稿（由工程师校对） - AI 识别文档里的 "TODO" / "待补充" 标记并提 issue
工具：Claude / Copilot / Cursor
7.3 漂移可视化（规划）
- MkDocs 插件：在每页顶部自动显示 "最后同步代码: 3 天前"
- 超过 90 天自动打
🟡 可能过时横幅 - 超过 180 天自动打
🔴 已过时 · 请 review
8. 常见问题 FAQ
Q1：我是个新工程师，不知道一个 PR 要改哪些文档怎么办？
A： 1. 先看 §3.6 代码-文档映射表 2. 如果不在表内（如新功能） · 创建对应 D4 文档 · 或升级 D3 架构文档 3. 不确定 → 找 Tech Lead 或 Doc Engineer 咨询
Q2：CI 卡我合并，但这个修改确实不需要改文档（如修 typo）
A：豁免清单（§3.6 末）已覆盖大部分情况。若确实被误拦：
1. 在 PR 描述里加 [skip-docs-sync] 标签
2. 需要 Tech Lead + Doc Engineer 双 approve
3. 事后在 ADR 记录该特例
Q3：架构已经偏离文档很久了，文档还是改吗？
A：看偏离性质： - 代码错了 → 改代码迁就文档（保持文档作为"北极星"） - 文档过时 → 升级文档 · 标 v2.0 · 触发一轮 "清理运动" - 双方都错 → 架构评审重新设计 → 同步更新
Q4：对外文档和内部文档不一致怎么办？
A：外部是"脱敏 subset"，内部是"完整版"。不一致是正常的（对外隐藏细节）。但： - 对外宣称的能力 必须有 内部文档支撑 - 对外发布前必须双签（法务 + 市场） - 定期比对"对外承诺 vs 内部现状"
Q5：D3 文档和 D4 文档讲的是同一件事，怎么区分？
A： - D3 架构级：为什么这么设计（decisions / trade-offs / diagrams） - D4 实现级：实际代码长什么样（API 签名 / 文件结构 / build 命令） - 一份文档不要同时讲两种（混淆只会更难维护）
Q6：AI 生成的文档能直接 merge 吗？
A：不能。AI 生成的永远是 v1.0-draft · status: draft。必须：
1. 对应代码栈的 owner 工程师审阅
2. 确认技术准确性 + 补充隐性知识
3. 升级 status: published 才能合并
9. 例外与特殊情况
9.1 Hotfix / 生产事故
规则：允许先改代码救火（不改文档），但必须： - 48 小时内补文档 - 写 Postmortem 进 D6 - 下个 sprint 复盘
9.2 Research / Spike
规则：探索性代码（spike/* / research/* / experimental/* 分支）不强制文档同步。但：
- 代码必须在对应分支 · 不合入 main
- 合入 main 时必须补齐文档
9.3 车规 / 安全关键场景
规则：反向（Docs-First 强制 · 覆盖本规范其他条款）： - 必须先有设计文档（D3） 才能写代码 - 必须有需求 → 设计 → 实现 → 测试的溯源矩阵 - 任何变更必须经 CAB（Change Advisory Board）审批
这是 ISO 26262 / IATF 16949 / ASPICE 的强制要求，不可妥协。
9.4 外部开发者贡献（XiVST 插件等）
规则：外部贡献必须附文档，没有文档的 PR 直接拒。这比内部工程师要求更严（因为缺少 onboarding 保障）。
10. 规范的演进
本规范也是一份文档，本身也适用本规范：
- 策略：Docs-First
- 同步频率：季度 review（每季度第一周）
- 升级门槛：v1.x 小改 Tech Lead 批 · v2.0 大改需跨中心联席会议
- 反馈渠道：GitHub issue / 文档末尾"反馈"链接
11. 相关文档
12. 快速记忆卡（工程师速查）
一张图记住
改了代码？看这张表：
| 改了什么 | 必须同步吗？ | 哪里改？ |
|---|---|---|
| Controller / Service / Component 业务逻辑 | ✅ 必须 | D4-implementation/ |
| 公开 API 签名 | ✅ 必须 | D4 + D2 产品 api.md |
| 配置文件 schema | ✅ 必须 | D4-implementation/.../config.md |
| 依赖版本 | ✅ 必须 | D4-implementation/.../dependencies.md |
| 注释 / 格式化 | ❌ 豁免 | - |
| 测试文件 | ❌ 豁免 | - |
| 新功能 / 大改 | ✅ 必须 + 开 ADR | D3 + D4 + ADR |
| 架构重构 | ✅ 必须 + 季度评审 | D3 |
不确定？问 Tech Lead 或 Doc Engineer。别合并。
版本历史
| 版本 | 日期 | 变更 |
|---|---|---|
| v1.0 | 2026-05-06 | 首次发布 · 基于 tech-docs-framework v1.0 拍板（O3/O6/O8）固化生效 |
文档-代码同步规范 · v1.0 · 2026-05-06 · © Xisound Inc.
反馈
对本规范有意见？请提 PR 或联系 docs@xisound.com。