Skip to content

Commit 324d5fb

Browse files
AparenciaAparencia
committed
docs(spec): 文档归档与技术债滚动治理机制设计
1 parent 336ee8a commit 324d5fb

1 file changed

Lines changed: 130 additions & 0 deletions

File tree

‎docs/superpowers/specs/2026-08-10-doc-archive-tech-debt-design.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# 设计：文档归档与技术债滚动治理机制
2+
3+
> 日期：2026-08-10
4+
> 状态：已批准（用户确认）
5+
> 关联：[文档编写规范](../../standards/documentation.md)、[技术债务管理](../../standards/tech-debt.md)、[归档机制说明](../../archive/README.md)
6+
7+
## 1. 背景与目标
8+
9+
项目文档体系（standards / templates / knowledge / adr / Foresight / product / versions）已成型，但缺少**日收工粒度的文档归档机制**：
10+
11+
- 已实施完成的文档没有统一的"生命终态"去向，活跃区不断堆积
12+
- 没有"归档前整理昨日技术债"的流程，债务分散在代码 TODO 与各文档中
13+
- 没有"技术债只认最新归档、旧归档只读"的权威约束
14+
15+
**目标**：建立按天归档 + 滚动技术债清单的机制，使文档生命周期闭环、债务可追溯且权威唯一。
16+
17+
## 2. 关键决策（已确认）
18+
19+
| 决策点 | 结论 |
20+
|--------|------|
21+
| 归档粒度 | 按天：`docs/archive/YYYY-MM-DD/` |
22+
| 归档内容 | 当天已实施完成的文档快照 |
23+
| 技术债去向 | 归档内滚动清单（`tech-debt.md`） |
24+
| 归档方式 | `git mv` 移动进归档（保留文件历史） |
25+
| 触发时机 | 日收工流程（每日，< 15 分钟） |
26+
| 缺失文档补齐 | A 机制文档（完整）+ B 已实施功能文档（简洁，每份 ≤ 1 页） |
27+
28+
## 3. 目录结构
29+
30+
```
31+
docs/
32+
├── archive/ # 归档根目录（独立、只读区）
33+
│ ├── README.md # 机制说明 + 全部归档日期索引（唯一权威入口）
34+
│ ├── 2026-08-10/ # 首个基线归档（机制启动日，无昨日债务可整理）
35+
│ │ ├── README.md # 当日索引：归档清单 + 债务摘要
36+
│ │ ├── tech-debt.md # 当日权威债务清单（滚动）
37+
│ │ └── ...已实施文档快照 # git mv 移入
38+
│ └── 2026-08-11/ # 归档前先整理 08-10 的债务
39+
│ ├── README.md
40+
│ ├── tech-debt.md # = 08-10 未偿债务(carried) + 今日新增(open)
41+
│ └── ...
42+
├── standards/ # 活跃规范（不归档）
43+
├── templates/ # 活跃模板（不归档，新增 archive-template.md）
44+
├── knowledge/ # 知识库（卡片验证后标 [ ] 已归档 并移入 archive）
45+
├── versions/ # 发布版本沉淀（按版本粒度，与 archive 并行不重叠）
46+
└── superpowers/specs/ # 设计与实施计划（实施完成后归档）
47+
```
48+
49+
**与 `versions/` 的边界**：`versions/` 按发布版本沉淀深度文档（发版计划/总结报告，人工撰写、版本回顾导向）；`archive/` 按天归档日常实施类文档的生命终态快照（git mv 移动、流程驱动）。两条机制并行，互不重复：version 文档不进 archive；archive 不沉淀发版级文档。
50+
51+
## 4. 归档对象判定标准
52+
53+
**可归档（生命终态）**：
54+
55+
| 类型 | 判定 |
56+
|------|------|
57+
| 方案/设计文档（brainstorm、plan、PRD） | 实施完成落地后 |
58+
| 实施文档（功能实现记录） | 功能验收通过后 |
59+
| 知识卡（bugs/solutions） | 修复验证、方案落地后，活跃索引标 `[ ] 已归档` 并移入 |
60+
| 被取代的 ADR | 新 ADR 生效后旧 ADR 移入 |
61+
| 已发布的版本规划文档 | 版本发布、对应总结沉淀至 versions/ 后 |
62+
| superpowers/specs 与 plans | 对应实施计划执行完成后 |
63+
64+
**不归档（持续活跃）**：standards/、templates/、knowledge/index.md、当前生效 ADR、CHANGELOG、README。
65+
66+
**判定核心**：文档描述的内容已实施完成、不再需要活跃维护 → 归档。归档时同步更新活跃区索引（链接改指归档路径 + 标 `[ ] 已归档`，复用现有生命周期标记标准）。
67+
68+
## 5. 日收工归档流程（SOP）
69+
70+
```
71+
收工归档（每个工作日，< 15 分钟）
72+
├─ 第 1 步 整理昨日债务
73+
│ 读 docs/archive/<昨日>/tech-debt.md
74+
│ 逐条核对（代码/提交验证）：已偿 → closed；未偿 → 继承为 carried
75+
├─ 第 2 步 识别今日新债务
76+
│ 扫描今日提交中的 TODO/FIXME/HACK、妥协方案 → 登记 open
77+
├─ 第 3 步 筛选今日已实施文档
78+
│ git log --since=<今日> 筛选 docs 变更 → 按 §4 判定 → git mv 移入今日归档夹
79+
├─ 第 4 步 写今日归档 README（索引 + 债务摘要 + 归档清单）
80+
├─ 第 5 步 更新活跃区索引（链接改指归档 + [ ] 已归档 标记）
81+
└─ 第 6 步 原子提交：docs(archive): archive YYYY-MM-DD
82+
```
83+
84+
**首次归档（基线，2026-08-10）**：无昨日归档 → 跳过第 1 步；将机制启动前近期（08-08 ~ 08-10）已实施文档一并纳入基线归档，并建立首个权威 `tech-debt.md`（含 B 项补齐文档时识别出的债务）。
85+
86+
## 6. 技术债滚动规则
87+
88+
- **格式**：沿用 [tech-debt.md](../../standards/tech-debt.md) 的 TD-XXX 编号与四类分类（有意/无意/环境变化/腐化），增加两个字段：
89+
- `来源归档`：识别该债务的归档日期
90+
- `状态`：`open`（今日新增）/ `carried`（继承昨日未偿）/ `closed`（今日已偿）
91+
- **继承折叠**：昨日未偿债务在今日清单中保留为 `carried`，只写 `TD-XXX | 一行摘要 | 来源归档`，不复制全文，控制清单膨胀；全文以首次登记日的归档为准
92+
- **唯一权威**：任何时刻，债务状态以**最新一日**归档的 `tech-debt.md` 为准；旧归档中的债务条目仅作历史追溯，不作为工作依据
93+
- **偿还闭环**：某日标 `closed` 的债务，后续归档中不再出现；`closed` 条目标注偿还动作对应的提交
94+
- **追加规则**：归档日无新增债务时，`tech-debt.md` 仍须存在（继承昨日清单），保证"最新归档必有权威清单"
95+
96+
## 7. 约束与只读保证
97+
98+
| 约束 | 保证方式 |
99+
|------|---------|
100+
| 技术债只认最新归档 | §6 唯一权威规则，写入 archive/README.md 与 tech-debt.md 标准 |
101+
| 旧归档仅可阅读已达成内容 | 归档与提交原子化（一次提交）；archive/README.md 声明"除最新一日外禁止修改"；git 历史可审计 |
102+
| 归档即快照 | `git mv` 保留文件历史；归档夹内文件不再被活跃流程引用 |
103+
| 时间戳命名 | `YYYY-MM-DD` 子文件夹；无归档日不建夹（空白日跳过） |
104+
105+
## 8. 缺失文档补齐范围
106+
107+
**A 机制文档（本轮交付）**：
108+
- `docs/archive/README.md` — 机制说明（判定标准、SOP、约束、与 versions/ 边界）
109+
- `docs/templates/archive-template.md` — 归档模板（与现有 11 个模板并列）
110+
- 更新 `docs/standards/documentation.md` — 新增"文档归档"章节
111+
- 更新 `docs/standards/tech-debt.md` — 新增"滚动归档"章节
112+
113+
**B 已实施功能文档（简洁，每份 ≤ 1 页）**：盘点近期（08-08 ~ 08-10）已实施无文档的功能并补齐，直接作为首次基线归档内容。候选（以实际提交为准）：
114+
- 性能优化批次：GPU 粒子 / WebGPU→WebGL 回退 / 渲染性能治理
115+
- 笔记创新 7 阶段（EchoDiscovery 等）
116+
- 生物发光色彩体系（令牌化改造）
117+
118+
## 9. 验证方式
119+
120+
- 机制文档齐全：archive/README.md、archive-template.md、两份标准更新到位
121+
- 首次基线归档存在：`docs/archive/2026-08-10/` 含 README.md、tech-debt.md、B 项实施文档
122+
- 活跃区索引一致性：被归档文档的旧位置已无残留（或已标 `[ ] 已归档` 指向归档路径）
123+
- 债务清单可追溯：首份 tech-debt.md 中每条债务含 `来源归档` 与 `状态`
124+
125+
## 10. 范围外（非目标）
126+
127+
- 不做归档自动化脚本（"已实施"判定需人工，脚本仅辅助筛选）
128+
- 不迁移 `versions/` 既有内容
129+
- 不回溯归档 08-08 之前的文档（历史文档保留现状，仅新机制生效后按 SOP 执行）
130+
- B 项补齐仅覆盖近 3 日提交，更早的缺口另立任务

0 commit comments

Comments
 (0)