Documentation as Infrastructure

让 5–6 万行的项目
可被精准、丝滑地持续升级

这套分层文档体系解决一个核心问题:「想知道某件事,去哪查?」——一跳直达、不被过时文档误导、决策有迹可循。下面用看板把它讲清楚,并教你日后怎么用、怎么维护。

三套代码库 · 共用一套后端 已上线 175 公测 阶段一 + 二 已落地 + 已提交

· 以前 ·

  • 文档全是 PRD / 方案 / 旧审计,没有「现状」
  • 旧文档冒充现役(写 Next15,实为 Next16)
  • 每次都要重新翻代码核验,不敢信文档
  • 「为什么这么设计」散落在脑子和 commit 里

· 现在 ·

  • 分 6 类,每类只有一个权威源
  • 每篇文档顶部挂时效徽章,可信度一眼可见
  • 现状 = 真相,直接用,不重复核验
  • 不可逆决策进 ADR 日志,永久可追溯
The Map · 分层结构

一张图看懂:文档分几层、各管什么

最上面是唯一入口;下面分两大支柱——git 文档装「耐久真相」(是什么 / 为什么),memory 装「易变状态」(现在怎样)。点任意卡片展开说明。

📍 docs/README.md —— 文档地图 · 唯一入口 想查任何事,先看这里的「权威规则表」,一跳直达
git 文档 —— 耐久真相(可评审 / 可追溯)是什么 · 为什么
docs/reference/
当前架构 · 现状真相
架构总览 · 领域规则 · 数据模型(49 表) · API索引(223 端点·脚本生成)。四篇全 ✅CURRENT,技术栈/表/端点以这里为准。
docs/decisions/
为什么这么做 · ADR
不可逆决策日志:先审后发权限模型、账号合并三铁律、技术栈选型…… 只增不改,防止后人把刻意设计当 bug 改掉。
子库 CLAUDE.md
这个库怎么干活
进 booking / miniapp / camp-web 目录自动加载:各自的铁律 + 代码地图,少走弯路。
docs/plans/
未来意图 · PRD/方案
是「想做成什么」,不一定等于现状。每篇顶部有状态徽章,以 README 状态表为准。
部署运维手册 + runbooks/
运维 · 部署步骤
175 部署的唯一标准;runbooks 只做指针,不复制正文,避免双源不一致。
docs/archive/
历史快照
6 月初的旧审计等,git mv 迁入、history 保留,仅供回顾、不再当现状。
memory现在怎样
MEMORY.md 索引
易变状态
随会话更新
当前部署到哪台机、某开关激活没、踩了什么坑、待办进度。git 外,专管「现在」。
边界:同一事实别两边各写。
git 写「是什么 / 为什么」,
memory 写「现在处于什么状态」。
How to Use · 怎么用

场景导航器:你想做什么?

这是日后最常用的入口。选一个你要做的事,它告诉你该读哪些文档、为什么,上面的分层图会同步高亮。

Single Source of Truth · 权威规则表

想知道 X → 唯一去这里

这张表是整套体系的「裁判」。任何时候不确定该信哪个,以它为准——它就写在 docs/README.md 和根 CLAUDE.md 里。

想知道什么单一真相源
当前架构 / 数据流 / 技术栈现状docs/reference/
为什么这么做(不可逆决策 / 不变量来由)docs/decisions/ (ADR)
某个子库怎么干活该子库 CLAUDE.md / AGENTS.md
未来意图 / PRD / 方案docs/plans/(以状态表为准)
运维 / 部署步骤部署运维手册.md + runbooks/
易变的部署态 / 进度 / 联调坑memory(MEMORY.md 索引)
历史快照docs/archive/
全局导航 / 编码约定根 CLAUDE.md
Keep It Alive · 怎么维护

四条纪律,让体系自己保持常新

文档体系最大的敌人是「建完就烂」。这四条已写进根 CLAUDE.md,每次开发自然触发——不是额外负担,是顺手的事。

1

架构变了 → 更新 reference

动了数据流 / 技术栈 / 模块结构,顺手改 docs/reference/ 对应文档,而不只写 memory。

2

做了不可逆决定 → 追加 ADR

docs/decisions/ 新增一条,编号递增、只增不改。决定变了就写新的、旧的标「已被 NNNN 取代」。

3

收尾 /wrap → 检查同步

会话收尾时,除更新 memory 外,回头看 reference / ADR 是否需要跟着改。

4

写新 PRD → 挂状态徽章

新方案顶部加徽章;实现后回 docs/README.md 状态表把它标成「已实现」。

◆ 什么进 git 文档

架构、不可逆决策、领域不变量等耐久真相。可评审、可追溯、不随 memory 丢失。

例:「营地为什么先审后发」→ ADR 0001

◆ 什么留 memory

当前部署到哪、哪个开关激活没、踩了什么坑、待办进度等易变状态

例:「175 当前是否已开 JSAPI」→ memory

每篇 reference / plans 顶部一行时效徽章,可信度一眼可见:
✅ CURRENT — 与现状一致,直接信 ⚠️ SUPERSEDED→x — 过时,去 x 看现状 📦 ARCHIVED — 历史快照,仅溯源
Roadmap · 路线图

分阶段推进,不一次性堆满

骨架规则(阶段一)与现状参考层(阶段二)均已落地、已提交;剩下是按需的增量维护。这套分阶段做法避免过度设计——每填一个域就标 CURRENT。

✓ 阶段一 · 已完成

骨架 + 清理 + 规则

  • docs/README 文档地图 + 权威规则表
  • reference / decisions / runbooks 三层
  • 4 条种子 ADR + 三库 orientation
  • 9 个旧审计件归档 · 过时件挂徽章
  • 维护纪律写进根 CLAUDE.md
✓ 阶段二 · 已完成

reference 全部填满并标 CURRENT

  • API 索引:脚本自动生成 223 端点
  • 数据模型:两库 49 表 + 核心表详解
  • 领域规则:积分 + 三模式计价深化
  • 架构总览 / 领域规则全 ✅CURRENT
◆ 现状已被量化 —— reference 层成果速览
223
API 端点
已编入索引
49
数据表已建模
主库 28 + 预约 21
4/4
reference 文档
全部 ✅CURRENT
⚙️
API 索引脚本生成
路由变即重跑
223 个端点的鉴权分布 —— 一眼看清后端权限版图
user 86 admin 54 public 53 内部 20
🔑 user 需登录 · 86 🔒 admin · 54 🌐 public · 53 🔒 internal · 20 🔓 可选 3 · owner 4 · partner 3
⚙️

亮点:API 索引由脚本自动生成,从此「文档不再过时」

scripts/gen-api-index.mjs 扫描两库路由、方法级推断鉴权,产出 223 端点全表。路由有增删,跑一次 node scripts/gen-api-index.mjs 即同步;幂等——代码不变则输出不变、git 无噪音 diff。这正是系统化文档管理降低长期维护负担的核心。

The Payoff · 最终达成

稳健升级迭代的闭环

当这套体系运转起来,每一次升级都站在可信、可追溯的基础上——这就是从「能改」到「敢快改、改不错」的关键。

信任不重复核验文档
精准一跳定位到位
不踩雷决策可追溯
自更新纪律保鲜
稳健迭代敢快改·改不错