# 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. 写作与审查（非常重要！！！务必遵守！！！）

- 面向没有参加过讨论、但具备相关技术背景的读者，要用人话讲解！别创造黑话，别堆积信息密度极大的长难句！
- 尽量多使用表格和图，让读者更容易看懂。
- 从真实问题或读者可见现象开始，不先堆术语；
- 结论写清理由、代价、适用边界和验证状态；
- 参数、路径、命令、指标和当前阶段只维护一个权威版本；
- 不把目标写成已完成，不泄露真实文档内容，不用文档替代测试；