重置项目并建立文档治理基础架构
- 移除旧清洗器、规则、测试和打包配置 - 增加 AGENTS.md 与 CLAUDE.md 同步协作规范 - 建立 research-wiki 文档生命周期和首个设计记录
This commit is contained in:
@@ -0,0 +1,93 @@
|
||||
# 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. 写作与审查
|
||||
|
||||
- 面向没有参加过讨论、但具备相关技术背景的读者；
|
||||
- 从真实问题或读者可见现象开始，不先堆术语；
|
||||
- 结论写清理由、代价、适用边界和验证状态；
|
||||
- 参数、路径、命令、指标和当前阶段只维护一个权威版本；
|
||||
- 不把目标写成已完成，不泄露真实文档内容，不用文档替代测试；
|
||||
- 简单事实用短段落，只有比较关系确实更清楚时才使用表格或图。
|
||||
@@ -0,0 +1,105 @@
|
||||
# 0001：文档治理基础架构
|
||||
|
||||
## 状态
|
||||
|
||||
已批准。2026-08-20，项目负责人明确要求清除现有代码，并参考
|
||||
[`Bepr4/GovDoc-compare`](https://github.com/Bepr4/GovDoc-compare) 建立最基础的 Wiki 与 Agent 入口框架。
|
||||
|
||||
## 1. 问题
|
||||
|
||||
仓库此前已经包含一个可运行的 Python 清洗器、YAML 规则和测试，但尚未先建立研究问题、清洗边界、
|
||||
评估方法与决策记录。继续在实现上迭代会让“当前代码做了什么”和“我们为什么应该这样做”混在一起。
|
||||
|
||||
项目需要先回到可审查的治理基础：明确事实放在哪里、设计何时冻结、真实数据如何隔离，以及不同 Agent
|
||||
进入仓库时遵循哪一份规则。
|
||||
|
||||
## 2. 目标与非目标
|
||||
|
||||
目标：
|
||||
|
||||
- 清除既有应用代码和工程配置，避免把旧实现默认为新基线；
|
||||
- 为人类与编码 Agent 提供一致的仓库入口；
|
||||
- 区分冻结决策、当前说明、稳定事实、验证指南和临时草稿；
|
||||
- 明确外部真实文档的只读与不入库边界；
|
||||
- 只建立当前确实需要的最小文档骨架。
|
||||
|
||||
非目标：
|
||||
|
||||
- 本次不定义新的清洗算法、规则 schema 或评估指标；
|
||||
- 不创建源码、测试、实验或 CI 空壳；
|
||||
- 不保留旧实现作为默认兼容基线；
|
||||
- 不读取、复制、修改或清洗真实业务文档；
|
||||
- 不提交、不推送，也不修改参考仓库。
|
||||
|
||||
## 3. 方案比较
|
||||
|
||||
### 方案 A：文档优先的最小骨架（采用）
|
||||
|
||||
保留 Git 历史，删除现有实现，建立 README、同步 Agent 入口和五类 Wiki 目录。结构足以约束下一步研究，
|
||||
同时不会提前固定语言、依赖、接口和实验契约。
|
||||
|
||||
### 方案 B：保留旧代码并补 Wiki
|
||||
|
||||
迁移成本较低，但旧实现会继续被误解为已批准基线，与“清除所有代码”的明确要求冲突。
|
||||
|
||||
### 方案 C：同时创建完整工程空壳
|
||||
|
||||
可以提前提供 `src/`、`tests/`、配置和 CI，但这些选择尚无设计依据。空目录还容易让 README 把目标状态写成现状。
|
||||
|
||||
## 4. 决定
|
||||
|
||||
采用方案 A，并借鉴参考仓库的文档生命周期，而不是复制其算法、代码或与 GovDoc-SaaS 相关的具体约束。
|
||||
|
||||
```text
|
||||
govdoc-md-cleaner/
|
||||
├── AGENTS.md
|
||||
├── CLAUDE.md
|
||||
├── README.md
|
||||
└── research-wiki/
|
||||
├── README.md
|
||||
├── design/
|
||||
├── explanation/
|
||||
├── reference/
|
||||
├── guides/
|
||||
└── scratch/
|
||||
```
|
||||
|
||||
- 根 README 是当前阶段和完成进度的唯一权威；
|
||||
- `AGENTS.md` 与 `CLAUDE.md` 除首行标题外逐字一致；
|
||||
- `research-wiki/README.md` 定义文档分类和更新规则；
|
||||
- `design/` 批准后冻结，变化通过下一编号记录；
|
||||
- 当前不加入镜像检查脚本，因为用户要求清空代码；先使用 README 中的 shell 检查命令验证。
|
||||
|
||||
## 5. 数据与恢复边界
|
||||
|
||||
- `/home/lihaoze/gov_test_data` 视为外部只读材料；本次不访问其内容；
|
||||
- 原 Python 包、规则、测试和配置从工作树删除，但仍可从 Git 历史恢复；
|
||||
- `.git` 历史保留，不执行重写历史或远端操作；
|
||||
- 新实现只有在后续 design 明确范围并获批后才建立。
|
||||
|
||||
## 6. 风险与控制
|
||||
|
||||
- **文档镜像漂移：** 当前以 `diff` 命令人工检查；需要自动化时另建设计；
|
||||
- **空目录被视为能力：** README 明确当前没有实现，空分类只保存 `.gitkeep`；
|
||||
- **旧实现被无意恢复：** 后续设计需要重新说明需求和验收标准，不从历史代码推断契约；
|
||||
- **客户数据误入库：** Agent 规则和 `.gitignore` 同时声明边界，提交前仍需检查实际 diff；
|
||||
- **治理过重：** 本次只保留一个必要 design，不创建教程、API 文档或未来工程占位。
|
||||
|
||||
## 7. 实施与验收
|
||||
|
||||
实施内容：
|
||||
|
||||
1. 删除 `cleaner/`、`rules/`、`tests/`、旧 `docs/` 与 `pyproject.toml`；
|
||||
2. 重写根 README 和忽略规则；
|
||||
3. 创建正文镜像的 `AGENTS.md` 与 `CLAUDE.md`；
|
||||
4. 创建 Wiki 入口、首个 design 和五类目录；
|
||||
5. 检查目录中不存在应用代码，验证两份入口正文一致并审查 Git diff。
|
||||
|
||||
验收条件：
|
||||
|
||||
- 工作树中不存在原 Python、YAML 规则、测试或打包配置；
|
||||
- 两份 Agent 入口除首行外无差异；
|
||||
- Wiki 分类与维护方式有唯一说明；
|
||||
- README 只声明实际存在的能力和可运行检查；
|
||||
- 没有访问或写入外部真实数据；
|
||||
- 没有提交、推送或修改远端状态。
|
||||
Reference in New Issue
Block a user