跳到主要内容

文档工程与治理共识

为解决跨仓协作中的进度失真、历史纠缠和规范不统一问题，SayClaw 团队采用“三区隔离”与“跨仓集中 Worklog”策略。 所有内部开发者（人类及 AI 幕僚）在编写、阅读文档时，必须遵循以下共识。

1. 物理结构：三区分离​

文档库 (sayclaw-docs) 顶层严格分为三个区：

1.1 planning/（计划区）​

  • 定位：给团队与 AI 提供目标的输入源（Epic、Roadmap）。
  • 红线：禁止维护进度状态。不允许在此出现 [x]、✅、进行中 等标记。计划即目标，它只代表“当时我们决定要什么”，绝不能代替“现在做到了什么”。

1.2 execution/（执行区）​

  • 定位：项目真正的心跳与时间线。包含流水账与关键决策。
  • 内容：
    • worklog-YYYY-MM.md：当月的执行流水账。
    • adr/：架构决策记录 (Architecture Decision Records)，记录不可逆的工程决断。

1.3 reference/（手册区）​

  • 定位：系统的真实倒影（手册即代码）。
  • 红线：不讲未来，只讲现状。这里的内容必须永远与 main 分支的线上代码保持一致，旧的架构必须直接删除或标为过期，绝不允许“规划中”的画饼混入其中。

2. 跨仓集中 Worklog 登记法则（重要）​

对于多仓项目，AI 或研发在业务仓操作后，必须统一回 sayclaw-docs 进行登记。

操作标准（SOP）：

  1. 在具体业务仓（如 sayclaw-backend）完成开发、测试。
  2. 提交代码并创建 Merge Request (MR)。
  3. 关键一步：紧接着切换到 sayclaw-docs 仓库的 wangcai 或对应特性分支，打开 docs/execution/worklog-当前月.md。
  4. 追加一条记录，格式如下： - YYYY-MM-DD [角色/作者] 做了什么简述。涉及仓库的 MR 链接。

3. 月度归档与提炼​

worklog 是沟通工具，不是终极文档。 每月底（或大版本发布前），团队/AI 需扫描当月 worklog。如果其中包含了对架构、数据结构、部署流程的长效变更，必须将其整理、提炼并更新到 reference/ 或 execution/adr/ 中。随后，该月 worklog 封存，不再修改。