Bepr4
be1a600fdc
- 移除旧清洗器、规则、测试和打包配置 - 增加 AGENTS.md 与 CLAUDE.md 同步协作规范 - 建立 research-wiki 文档生命周期和首个设计记录
106 lines
4.4 KiB
Markdown
106 lines
4.4 KiB
Markdown
# 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 只声明实际存在的能力和可运行检查；
|
||
- 没有访问或写入外部真实数据；
|
||
- 没有提交、推送或修改远端状态。
|