文档更新（Docs-as-Code）
归属：
docs/guides/sops/触发：新增/修改文档（guides、adr、prd、dev 等） 关联概念：CONTEXT.md术语、flow-review、VitePress 文档站
场景定义
对项目文档的独立新增或修改（不依附于某个功能 PR）。包括使用指南、配置、架构、术语、PRD、ADR、开发文档等。文档作为代码管理，走审查与合并。
目标与不做什么
- 目标：文档准确、与代码同步、术语一致，且可被审查与版本化。
- 不做：不把「随代码的文档」从这个 SOP 剥离开（涉及代码的文档应随代码 PR 同步更新，见
flow-code的文档同步约束）。
标准方法论（行业通行）
借鉴 Docs-as-Code 与知识库维护的通行做法：
- 文档即代码：文档进版本库、走 PR、经审查合并，与代码同等对待。
- 术语一致：领域术语以
CONTEXT.md为权威；新术语先写回CONTEXT.md，再在文档中引用，避免各文档各说各话。 - 与代码同步：文档变更应反映当前实现；代码变更涉及文档时，同 PR 更新。
- 单一事实来源：同一信息只维护一份（如阶段契约在
stage-contract.md），文档引用而非复制，避免漂移。 - 可核验：文档中的命令、路径、示例应可执行/可验证；CI 可加文档构建与链接校验。
本项目落地流程
- 明确文档归属：区分「独立文档更新」与「随代码的文档」（后者随对应功能 PR）。
- 术语检查：涉及新领域概念时，先写回根
CONTEXT.md（术语权威），再在目标文档引用。 - 单一来源：若内容已有权威源（如阶段契约、Profile、Release 规则），引用而非复制。
- 编写/修改：在独立分支
docs/<slug>/ worktree 内修改目标文档。 - 构建校验：涉及文档站时，跑
npm run docs:build验证构建与链接；sidebar 对docs/guides/等目录自动注册。 - 审查与合并：复用
flow-review；审查确认准确性、术语一致、无重复源；CI 绿后合并。
验证与门禁
- [ ] 术语与
CONTEXT.md一致（新术语已写回） - [ ] 无重复事实源（已引用权威源而非复制）
- [ ]
npm run docs:build通过（涉文档站时） - [ ] 审查确认准确 + CI 绿
产出物
- 文档更新 PR（
docs/<slug>）
复用与新增资产
- 复用：
flow-review（审查合并）、CONTEXT.md（术语权威）、VitePress 构建（验证）。 - 新增：
docs/<slug>分支约定（文档独立更新入口）。
反模式 / 注意事项
- 文档与代码脱节（改代码不更新文档）。
- 各文档重复维护同一信息（漂移）。
- 引入新术语却不写回
CONTEXT.md。 - 文档示例不可执行 / 命令过时。
- 把文档变更夹带进无关功能 PR（应随对应代码 PR 或独立文档 PR）。