Skip to content

documentation-framework-guide.md

Latest commit

 

History

History
203 lines (138 loc) · 7.85 KB

documentation-framework-guide.md

File metadata and controls

203 lines (138 loc) · 7.85 KB
Raw

文档框架

本文记录本仓库的文档治理方法。重点不是复制目录名称，而是持续回答：当前是什么、正在做什么、已经验证了什么、还有什么问题。

一句话框架

用一个默认入口控制阅读上下文，用稳定设计、任务计划、完成日志、问题单和精选归档分离不同职责，用文件移动表达生命周期，用当前代码、配置和实际结果约束事实结论。

最值得遵守的规则

  1. 只设一个默认入口，让入口负责导航而不是堆积正文。
  2. 把长期规则、当前计划、完成事实、未决问题和历史证据放在不同文档中。
  3. 用目录和移动文件表达状态，不靠文件名后缀或复制多个版本。
  4. 把 skipped 视为上下文排除和停止决定，不把它当成普通 Backlog。
  5. 让代码、配置和测试承载机器事实，文档负责解释和链接。
  6. 严格分开静态配置、离线验证、真实模型调用、桌面验收和业务验收。
  7. 任务结束时同时闭合稳定文档、计划、日志、Issue 和索引；未满足验收就保留未完成状态。
  8. 普通旧版本交给 Git，只有具有独立审计、决策或回滚价值的证据才进入归档。

推荐目录

docs/
├── README.md                 # 唯一默认入口
├── design/                   # 长期稳定规范
├── plan/
│   ├── README.md             # 计划状态索引
│   ├── in-progress/          # 正在执行
│   ├── pending/              # 已纳入考虑，尚未实施
│   ├── skipped/              # 暂时跳过，默认不进入上下文
│   └── completed/            # 目标和约定验证已经完成
├── logs/YYYYMM/              # 日期化完成记录
├── issues/
│   ├── open/                 # 尚未解决
│   ├── skipped/              # 暂时不跟进
│   └── closed/               # 已满足关闭条件
└── archive/                  # 精选历史证据

根目录的 README.md 面向使用者；AGENTS.md 面向 Agent 和维护者。两者可以互相链接，但不复制正文。

各类文档的职责

默认入口 docs/README.md 是阅读路由。它应让读者在一分钟内找到当前工作、稳定设计、机器权威和历史入口，不应长期复制测试数量、密钥、单次上游输出或完整历史清单。

稳定设计回答系统长期应该怎样工作，适合记录产品范围、架构、配置和文档规则。设计变化时原地更新同一主题文件。

计划回答准备做什么、为什么做、如何判断完成、允许做到哪一步。只有需要持续跟踪、跨多个步骤、涉及公共契约或需要明确授权边界的任务才需要计划。

计划索引完整列出进行中、待进行和暂时跳过项，并只展示最多 5 项最近完成。完整历史通过 completed/ 和日志查找。

完成日志回答这次实际上做了什么，必须绑定日期、范围、验证命令和未执行项。日志中的结论不得直接外推为当前能力。

Issue 回答哪里存在尚未闭环的问题。关闭时移动原文件，并保留修复前现象、原关闭条件和完成日志指针。

归档只保留 Git 历史不够方便使用的精选证据。归档默认不进入当前上下文。

默认读取路径

docs/README.md
    ↓
当前进行中计划
    ↓
与任务直接相关的稳定设计和机器权威
    ↓
当前代码、配置、测试或当次结果
    ↓
仅在需要时读取待进行计划、开放 Issue、完成日志或精选归档

没有进行中计划且需要选择下一项工作时，才查看 pending/。skipped/ 默认不打开正文。

权威映射

问题 优先权威 文档的作用
环境变量叫什么、默认值是什么？ .env.example 与 config.py 解释语义和禁止项
结果状态和字段是什么？ core/models.py 与对应测试 解释空结果和 partial 边界
系统长期应遵守什么架构？ 当前稳定设计与架构测试 记录不变量和变更门禁
当前团队正在做什么？ in-progress/ 计划及索引 记录目标、进度和停止边界
某次工作做了什么？ 日期化完成日志和对应 revision 记录当时事实与未执行项

如果设计文档与当前代码冲突，先核对当前实现和测试，确认是实现偏离设计还是设计已经过期，再同步修正。

状态流转

pending ──开始执行──> in-progress ──达到验收──> completed
   │                         │
   └────暂时不做─────────────┴──> skipped

skipped ──负责人明确恢复──> pending

Issue：

open ──满足关闭条件──> closed
 │
 └──暂时不跟进──> skipped ──负责人明确恢复──> open

状态变化通过移动原文件表达，不复制并存。部分完成或阻塞时仍留在活动状态，并写明已完成、剩余工作、停止原因和需要的决策。

证据分层

层级 能证明什么 不能替代什么
静态配置 环境变量名存在、就绪条件可计算 上游可调用、译文正确
契约与离线测试 当前代码在 Fake 或 HTTP mock 下通过 真实模型、截屏或桌面交互
真实模型调用 某个精确请求在某时某环境得到结果 其它文本、其它图片、桌面验收
桌面/业务验收 约定场景由使用者确认满足目标 未来持续正确或未覆盖场景正确

必须避免：config-check 成功不等于模型可用；离线测试通过不等于已经划词或 OCR；一次真实翻译成功不等于 OCR 可用；已提交不等于使用者已经验收。

任务闭环

任务开始时先读默认入口和当前计划，检查 Git 状态，再判断是否需要建计划。执行中只更新原计划，不创建“新版计划”。任务结束时回读 diff，运行与风险匹配的验证，更新计划、Issue、日志和索引，并明确未执行的提交、推送或真实调用。

命名和排版

任务型文档使用 YYYY-MM-DD-<task-slug>.md，日期采用 Asia/Shanghai。README.md 和按主题长期维护的稳定设计保留稳定名称。状态由目录表达，不在文件名中写 done 或 wip。

Markdown 采用“一个逻辑段落一行”，不按固定列宽硬换行；标题、段落、列表、表格、引用和 fenced code block 之间保留一个空行。每份 Markdown 只有一个一级标题。

可复用模板

任务计划

# <任务>计划

> 状态：进行中
>
> 创建日期：YYYY-MM-DD（Asia/Shanghai）

## 目标

……

## 当前依据

- 当前代码、配置或运行证据：……
- 已知未知项：……

## 范围与非目标

- 范围：……
- 非目标：……

## 执行步骤

1. ……

## 验收条件

- ……

## 授权与停止边界

- 允许：……
- 需要额外授权：……
- 出现……时停止。

完成日志

# <任务完成记录>

> 完成日期：YYYY-MM-DD（Asia/Shanghai）
>
> 计划：[<计划名称>](../../plan/completed/<file>.md)

## 任务边界

……

## 完成内容

- ……

## 验证结果

- `<实际命令>`：……

## 限制与未执行项

- 未验证：……
- 未执行：真实模型调用、推送等。

验证清单

  • 每份 Markdown 只有一个一级标题。
  • 所有内部相对链接存在。
  • 每个活动计划都进入计划索引，且只存在于一个状态目录。
  • 最近完成数量不超过 5 项。
  • skipped 正文没有被默认入口当作当前工作引用。
  • 当前事实来自当前代码、配置或当次实际结果；历史数字带有日期和 revision。
  • 计划目标没有被写成已完成事实。
  • 文档没有泄漏密钥或未脱敏上游响应。