97 lines
4.8 KiB
Markdown
97 lines
4.8 KiB
Markdown
# 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`，编号四位递增，英文短名只用于稳定引用。建议结构如下：
|
||
|
||
1. 状态；
|
||
2. 问题与可观察现象；
|
||
3. 目标与非目标；
|
||
4. 候选方案；
|
||
5. 决定与理由；
|
||
6. 施工范围目录；
|
||
7. 实施与验收。
|
||
|
||
草稿可以在评审期间修改。批准后冻结；如果决策改变，新文档必须写明 `supersedes: NNNN`，并保留旧文档。
|
||
|
||
## 4. explanation：解释当前为什么这样工作
|
||
|
||
这里解释已经生效的算法流程、数据流、边界、适用条件和代价。第一节从实际问题、失败案例或总览开始。
|
||
|
||
未批准或未实现的机制必须明确标注为候选方案，并链接到对应 design，不能通过 explanation 绕过确认门。
|
||
|
||
## 5. reference：准确查询事实
|
||
|
||
这里保存需要稳定查询、但未来代码和测试不能完整表达的事实，例如外部格式约束、共享字段语义、
|
||
经验证的第三方行为或数据集的脱敏统计。
|
||
|
||
函数签名、默认参数和数据结构如果已由代码或测试表达，不在这里维护第二份副本。
|
||
|
||
## 6. guides：完成一项已验证操作
|
||
|
||
guide 必须来自实际运行，至少包含前置条件、准确命令、预期结果、验证日期和失败后的判断方式。
|
||
尚不存在的脚本或预想中的流程不能写成指南。
|
||
|
||
## 7. scratch：容纳尚未收敛的材料
|
||
|
||
调研摘记、比较表、执行计划和 design 草稿可以放在 `scratch/`。它们可以支持连续协作，
|
||
但不能作为当前机制或已批准决定引用。Agent 不自动删除 scratch 内容。
|
||
|
||
## 8. 数据与实验材料
|
||
|
||
- 客户原文、审核文件、历史大结果和软链接不属于 Wiki；
|
||
- 外部真实数据默认只读，不因研究需要复制进仓库；
|
||
- 实验产出只有在目录和脱敏规则获批后才可保存；
|
||
- 小型汇总进入 Git 前必须确认无法还原客户内容；
|
||
- 每个实验应能追溯输入范围、版本、参数、环境、指标和输出位置。
|
||
|
||
## 9. 写作与审查（非常重要！！！务必遵守！！！）
|
||
|
||
- 面向没有参加过讨论、但具备相关技术背景的读者，要用人话讲解！别创造黑话，别堆积信息密度极大的长难句！
|
||
- 尽量多使用表格和图，让读者更容易看懂。
|
||
- 从真实问题或读者可见现象开始，不先堆术语；
|
||
- 结论写清理由、代价、适用边界和验证状态；
|
||
- 参数、路径、命令、指标和当前阶段只维护一个权威版本；
|
||
- 不把目标写成已完成，不泄露真实文档内容，不用文档替代测试；
|
||
|