4.8 KiB
research-wiki 文档治理说明
更新触发点： 新增、删除或改变 Wiki 分类，修改 design 冻结方式、事实权威或数据边界时， 必须在同一变更中更新本文件。
清洗研究会同时产生不同寿命的材料：某次方案选择需要保留当时的判断，当前机制需要随实现更新， 运行步骤需要反复验证，探索笔记则可能很快失效。它们不能使用同一种维护方式。
1. 目录与生命周期
| 内容 | 目录 | 维护方式 |
|---|---|---|
| 动工前的方案比较、选择和代价 | design/ |
批准后冻结；改变时新增下一编号 |
| 当前有效的机制、数据流和原因 | explanation/ |
事实变化时同步更新 |
| 代码无法完整表达的稳定查询事实 | reference/ |
权威事实变化时更新 |
| 可复现运行、验证与排障步骤 | guides/ |
操作变化时更新并重新验证 |
| 调研笔记、计划和未收敛草稿 | scratch/ |
不作为当前事实；由项目负责人决定去留 |
| 当前阶段和已完成工作 | 根目录 README.md |
阶段变化时更新 |
根目录 AGENTS.md 与 CLAUDE.md 是协作者入口，不放入 Wiki。
空分类使用 .gitkeep 保留，不创建只写未来设想的占位文档。
2. 常青层与记录层
explanation/、reference/、guides/ 属于常青层：现实改变后直接更新原文，使其继续描述当前事实。
design/ 属于记录层：它保存决策发生时的问题、方案、理由和代价。批准后即使结论后来被替代，
也保留原文并新增一份 design。
判断文档去向时可以问：三个月后发现它不再正确，是应该改掉原文，还是保留原判断并记录新决定？
前者进入常青层，后者进入 design/。
3. design：先记录选择，再实施
以下事项需要 design：
- 清洗语义、保真边界、规则顺序或冲突处理方式；
- 输入输出契约、评估指标、标注方法或实验方案；
- 重要依赖、公共接口、源码结构或数据目录；
- 事实权威、数据安全和跨仓职责的改变；
- 一旦选错会造成大面积返工或使实验作废的决策。
文件使用 NNNN-short-title.md，编号四位递增，英文短名只用于稳定引用。建议结构如下：
- 状态；
- 问题与可观察现象；
- 目标与非目标；
- 候选方案；
- 决定与理由；
- 施工范围目录；
- 实施与验收。
草稿可以在评审期间修改。批准后冻结；如果决策改变，新文档必须写明 supersedes: NNNN，并保留旧文档。
4. explanation：解释当前为什么这样工作
这里解释已经生效的算法流程、数据流、边界、适用条件和代价。第一节从实际问题、失败案例或总览开始。
未批准或未实现的机制必须明确标注为候选方案，并链接到对应 design，不能通过 explanation 绕过确认门。
5. reference：准确查询事实
这里保存需要稳定查询、但未来代码和测试不能完整表达的事实，例如外部格式约束、共享字段语义、 经验证的第三方行为或数据集的脱敏统计。
函数签名、默认参数和数据结构如果已由代码或测试表达，不在这里维护第二份副本。
6. guides：完成一项已验证操作
guide 必须来自实际运行，至少包含前置条件、准确命令、预期结果、验证日期和失败后的判断方式。 尚不存在的脚本或预想中的流程不能写成指南。
7. scratch：容纳尚未收敛的材料
调研摘记、比较表、执行计划和 design 草稿可以放在 scratch/。它们可以支持连续协作，
但不能作为当前机制或已批准决定引用。Agent 不自动删除 scratch 内容。
8. 数据与实验材料
- 客户原文、审核文件、历史大结果和软链接不属于 Wiki；
- 外部真实数据默认只读，不因研究需要复制进仓库；
- 实验产出只有在目录和脱敏规则获批后才可保存；
- 小型汇总进入 Git 前必须确认无法还原客户内容；
- 每个实验应能追溯输入范围、版本、参数、环境、指标和输出位置。
9. 写作与审查（非常重要！！！务必遵守！！！）
- 面向没有参加过讨论、但具备相关技术背景的读者，要用人话讲解！别创造黑话，别堆积信息密度极大的长难句！
- 尽量多使用表格和图，让读者更容易看懂。
- 从真实问题或读者可见现象开始，不先堆术语；
- 结论写清理由、代价、适用边界和验证状态；
- 参数、路径、命令、指标和当前阶段只维护一个权威版本；
- 不把目标写成已完成，不泄露真实文档内容，不用文档替代测试；