Skip to content

README.md

Latest commit

 

History

History
149 lines (103 loc) · 4.82 KB

README.md

File metadata and controls

149 lines (103 loc) · 4.82 KB
Raw

Documentation Index

Type: general Updated: 2026-04-08 Summary: 将已废弃的 Feishu headless 手工恢复设计稿迁移到 docs/obsoleted 并刷新索引。

1. 适用范围

本规范强制适用于 docs/**/*.md。

这些文档承载的是：

  • 设计草案
  • 实施中方案
  • 已落地功能说明
  • 长期有效的架构/协议/流程文档
  • 已废弃但仍需保留的历史设计

像 README.md、QUICKSTART.md、deploy/**/README.md 这类与目录强绑定的共位说明文件，继续保留在原目录，不纳入生命周期归档目录；但后续如有重写，也建议补齐同样的元信息头。

2. 目录结构

docs/ 根目录只保留索引或共享模板，具体文档按生命周期进入子目录：

  • docs/draft/
    • 还在讨论，边界和结论都可能继续变化
  • docs/inprogress/
    • 方案已基本定稿，但尚未全部实现，或实现到一半
  • docs/implemented/
    • 功能已经落地，文档主要记录当前已实现行为和设计边界
  • docs/general/
    • 长期有效的架构、协议、流程、测试、部署类文档
  • docs/obsoleted/
    • 已不再作为当前实现依据，仅保留历史背景或设计理由

3. 必填头信息

每个 docs/**/*.md 文件都必须在标题下方紧跟一个可见元信息块：

# 文档标题

> Type: `draft`
> Updated: `2026-04-06`
> Summary: 一句话说明本次更新了什么。

要求：

  • Type 必须与所在目录一致
  • Updated 使用 YYYY-MM-DD
  • Summary 只写最近一次有效改动，不写长 changelog

对 obsoleted 文档，建议额外补一行：

> Superseded By: `docs/general/xxx.md`

4. 分类标准

4.1 draft

放这里的典型信号：

  • 还在和需求方讨论交互或边界
  • 关键抽象还可能重命名
  • 尚未承诺进入实现

4.2 inprogress

放这里的典型信号：

  • 方案已经决定做
  • 已经开始编码，或已实现一部分
  • 仍然存在明显未完成部分

4.3 implemented

放这里的典型信号：

  • 功能已经进入当前代码
  • 文档描述的是现有行为、取舍和已知边界
  • 它不是全局架构文档，但值得长期保留

4.4 general

放这里的典型信号：

  • 当前和未来一段时间都会持续有效
  • 是团队默认应遵循的架构/协议/流程基线
  • 不绑定单一 feature 的短期设计阶段

4.5 obsoleted

放这里的典型信号：

  • 当前实现已经不再按本文执行
  • 但历史决策背景仍有保留价值
  • 如果继续阅读，必须明确知道新的 source of truth 在哪里

5. 命名与移动规则

  • 文件名继续使用英文 kebab-case，避免中文文件名和空格
  • 文档状态变更时，直接移动到对应目录，不保留旧副本
  • 目录迁移后，必须同步修正 README 和其他文档中的相对链接
  • 新增文档时，优先先判断它属于哪种生命周期，再决定放到哪个目录

6. 当前索引

6.1 general

6.2 implemented

6.3 inprogress

6.4 draft

6.5 obsoleted