database-documentation

database-documentation

完整、准确地记录数据库，使文档能够证明就是数据库的真实结构，而不是看似合理的猜测。半对不对的结构文档比没有文档更糟：人们会相信它，然后写出有问题的代码。

唯一原则：有据可依且经过验证

输出中的每条陈述都必须：

• 有据可依——可追溯到具体来源，优先采用实时数据库（对系统目录进行内省）。ORM 模型、迁移、生成的类型和种子数据只是对数据库的描述，并非数据库本身；实际运行的才是系统目录。
• 经过验证——通过重新对实时数据库进行内省，并与生成的文档进行差异比较来确认，直到差异为空，或每项剩余差异都有明确说明。绝不要写“文档已完整”——而应让差异归零并展示结果。

如果任由前沿模型自行处理，它会读取 ORM，写出自信满满的说明，最终交付一份不完整且部分内容为幻觉的结构文档（漏掉检查约束枚举、写错 ON DELETE、遗漏旧表、虚构列）。这项技能正是为了彻底杜绝这种情况。它通过两种机制做到这一点：(1) 以实时数据库为准；(2) 判断绝不由单个 Agent 独自做出——让相互独立的质疑者找出单轮检查遗漏的问题。

范围（v1）：仅限关系型数据库/SQL

目标包括 PostgreSQL、MySQL、SQL Server、SQLite。如果检测到文档数据库（MongoDB）或图数据库，请说明并停止处理该数据库——不要为其生成关系型文档（默默记录错误是最糟糕的结果）。请注明这超出范围，而不是进行猜测。

工作流

按顺序执行以下阶段。每个阶段都注明其退出产物。将所有临时文件（中间提取结果、工作中的 CSM）放在单个 .database-documentation/ 临时目录或平台临时空间中——唯一需要持久保存的交付物是文档和 schema.json。

阶段 0 — 发现（只读）

1. 识别数据库引擎 + 版本以及 ORM：查找 schema.prisma、*.entity.ts + 数据源、drizzle.config.*、knexfile.* + migrations/、Django models.py、Rails schema.rb、原始 SQL DDL。通过数据源/提供程序、docker-compose.yml 镜像标签以及 .env* 中的连接 URL，查明数据库引擎 + 版本。
2. 查找实时数据库的可达路径，按以下顺序尝试，遇到第一个可用路径即停止：已连接的 DB MCP 服务 → 通过 docker compose exec / docker exec 进入数据库容器（从 compose 环境变量中读取凭据）→ 使用主机：端口来自 .env 的本地数据库 CLI（psql/mysql/sqlcmd/sqlite3）。继续前，先用一条简单查询（SELECT 1、列出表）证明连接可用。如果数据库已停止但 compose 文件中有定义，请提出启动它。绝不要打印凭据：将从 .env/compose 读取的密码/DSN 视为机密——只在执行的命令中使用，并在展示或写入文档的内容中将其脱敏（password=***）。
3. 盘点所有其他来源：迁移目录（+数量）、生成的客户端/*.d.ts、种子数据/测试固件，以及对应用代码中原始 SQL/查询构建器调用的 grep 搜索。检查是否已有 docs/db/——如果存在，这次就是一次更新：加载它以比较变更，并遵循现有的文档风格。
4. 宣布达到的层级（参见降级阶梯），让读者了解可信度。

退出产物：简短的发现说明——数据库引擎、ORM、可达层级、已验证的实时数据库命令，以及来源路径。

阶段 1 — 提取所有表层（尽可能并行）

将每个可用表层独立提取为规范架构模型（Canonical Schema Model，CSM）结构 （参见 references/csm-contract.md）。在支持子 Agent 的平台上，为每个表层并行运行一个提取器， 不要让它们看到彼此的输出——独立达成一致才是真正的证据；共享上下文只会导致群体思维。

对象类别检查清单——提取每个类别；漏掉任何一个是最常见的失败原因。 复制此清单， 并确认每一项都已在 schema.json 中列出，且有实际计数：

• 表 · [ ] 列（类型 + 是否可空 + 默认值 + 注释）· [ ] 主键 · [ ] 外键（+ ON DELETE/UPDATE）
• 唯一约束 · [ ] 检查约束 · [ ] 索引（+ 部分索引/表达式索引）· [ ] 枚举（+ 取值）
• 序列 · [ ] 触发器 · [ ] 视图（+ 定义）· [ ] 例程（函数/过程）

序列、触发器和例程常被遗忘，因为它们不是列——请明确提取它们。 完整、逐字地捕获视图/触发器/例程的主体内容——绝不要缩写、总结或用 ... 省略；定义被截断就意味着文档不完整（也就是错误）。 schema.json.enums = 仅限数据库原生枚举类型。 带有 CHECK (col IN (...)) 的字符串列应归入 对应表的 check_constraints（而非 enums）；仅在应用层定义的取值集合应写在列描述中， 并标注“由应用强制执行”。将非原生枚举放入 enums，就是对线上架构的臆造。

• 线上内省（权威依据）。 读取完整目录。有关确切的 Postgres 查询（以及 MySQL/MSSQL/SQLite 对应查询），请参见 references/introspection-postgres.md；这些查询涵盖表、列 （类型及长度/精度、是否可空、默认值、标识列、生成列、排序规则、注释）、主键、外键及其 ON DELETE/ON UPDATE、唯一约束及检查约束、索引（包括部分索引谓词和表达式列）、枚举、域、序列、视图/物化视图、触发器、例程。不要调用任何基准测试/预言机脚本——请自行编写并运行内省查询。
• ORM 模型 → CSM（意图 + 描述；各 ORM 的说明见 references/）。
• 迁移 → 按时间戳顺序合并，以重建最终状态（不要凭目测检查 200 个文件）。
• 生成的类型 / 种子数据 / 应用查询 → 用于交叉验证；应用查询扫描可发现 ORM 中不存在但应用使用的表/列 （遗留表）。

退出条件：每个表层都有一份部分 CSM。

阶段 2 — 协调为一份 CSM（优先级 + 漂移）

合并为主 CSM，并按物理数据库名称为表建立键。优先级：

1. 存在线上数据库 → 以它为准，不容置疑。 任何表层与之不一致，都应产生漂移发现项（记录在 issues/ 中），绝不能悄悄修改文档。文档描述的是线上数据库。
2. 不存在线上数据库 → 综合迁移 ⊕ ORM 得出共识（迁移决定结构，ORM 决定意图）；标记冲突。

为每个对象标注 confidence：verified（经线上数据确认）/ consensus / single-source / conflict。 如果有线上数据库，请通过两种方法交叉核对它（例如 information_schema 与 pg_catalog）——在推翻其他表层之前，预言机必须先与自身达成一致。

退出条件：主 CSM + discrepancies 列表。

阶段 3 — 生成文档 + schema.json

将所有输出写入一个专用文档目录，绝不要将文件散放在仓库各处。默认使用 docs/db/；如果阶段 0 发现已有数据库文档目录（例如 docs/db/、docs/database/、 docs/schema/，或仓库现有的其他存放目录），则写入该目录，以符合项目惯例。若目录不存在，请创建。 将 CSM（它是数据库的纯函数）渲染到该目录中，遵循 references/output-template.md 中的模板，并根据架构大小选择文档结构：

• ≤ 约 15 张表 → 单个 docs/db/DATABASE.md（统计信息标题、一个 mermaid ERD、各表章节、Issues 章节）。
• 更多表 → 在 docs/db/ 下创建：README.md（索引 + 统计信息）+ ONBOARDING.md + 每个领域一个 diagrams/<domain>.md（使用 mermaid erDiagram，包含所有列及类型 + 关系连线，随后为各表添加章节）+ diagrams/full-erd.md（仅表级关系，以确保可以渲染）+ tables/entity-reference.md + issues/README.md。

在同一目录中生成 schema.json（docs/db/schema.json）。

各表章节：用 1–2 句话撰写基于证据的描述、一个 Column | Type | Nullable | Default | Description 表格，然后列出 Indexes: 和 Foreign Keys:（含 ON DELETE）。领域划分顺序为 ORM 模块/文件夹 → 名称前缀 → FK 聚类，并设置 Legacy/Misc 兜底类别。 schema.json 遵循 references/csm-contract.md 中定义的结构。

阶段 4 — 证明一致性（经过验证的部分）

此步骤并非可选，也不能凭感觉判断。声称“看起来完整”毫无价值。能力较弱的模型尤其容易声称已实现一致性，实际却并非如此；不要相信这种说法，请实际核对数据。

1. 数量门槛（早期预警）。 对每种对象，在实时数据库中计数，并与 schema.json 中的数量进行比较。计数查询必须选取与你的提取过程和 CSM 定义完全相同的对象集合，否则正确的文档也会无法通过门槛，你还可能“修复”它并凭空编造内容。两条适用于所有真实数据库的规则：索引不包括 PK/唯一约束的支持索引；例程/对象不包括扩展所拥有的对象（pg_depend.deptype='e'）。请使用 references/introspection-postgres.md 中与对象集合匹配的计数查询（“Count-gate queries”），不要使用朴素的 count(*)，也不要使用有损视图（例如 information_schema.check_constraints 会混入 NOT NULL 行；reltuples 可能为 -1）。 打印 class | live | documented | match? 表格。若数量不匹配，请调查原因——可能确实有遗漏，也可能是计数查询选择了错误的对象集合。数量匹配是必要条件，但并非充分条件（数量相同也可能掩盖类型互换或 ON DELETE 错误）。
2. 标识差异比对（实际证明）。 重新进行一次全新内省，并对所有对象类别比对标识和属性，而不只是数量：表、列（名称/类型/可空性/默认值）、PK、FK（+on_delete）、唯一约束、检查约束、索引（+部分索引/表达式）、枚举（+值）、视图、触发器、例程、序列。
3. 对于每处差异：修正文档，或说明理由（例如“仅实时数据库存在的对象已列在 Drift 下”）。
4. 重复以上步骤，直到数量表匹配，且标识差异比对为空或所有差异均有充分说明。
5. 撰写一致性报告（位于 README.md 或 issues/ 中）：包含各对象类别的数量表，并明确写出“0 个未记录对象，0 个虚构对象”。只有在标识差异比对（步骤 2）为空时，才能写“已验证”，仅数量匹配不够。若没有实时数据库，请针对共识 CSM 运行差异比对，并在每个输出文件中标注“共识一致性（未针对实时数据库验证）”。

阶段 5 — 对抗性审查（≥3 个独立审查者，绝不能只有 1 个）

由于负责判定的 Agent 本身也是前沿模型，与撰写文档的 Agent 有相同的盲点，单次审查只会走过场。召集 ≥3 个上下文隔离的对抗性审查者，让他们分别在独立会话中工作，必须找出问题，并采用不同视角：

• 遗漏猎手 — 抽查实时表：每张表是否都已列出所有列？是否记录了旧版表、每个枚举值/CHECK、每个索引和外键？
• 幻觉猎手 — 每个已记录的对象/类型/默认值/ON DELETE/描述是否都能追溯到真实来源？标记任何虚构内容。
• 正确性猎手 — 类型、可空性和外键基数是否与实时数据库完全一致？

他们的审查结果共同用于下一轮生成。凡是需要判断的地方，都由评审小组作出决定。

降级阶梯（声明你的等级）

等级	条件	置信度
T1	实时数据库 + 并行子 Agent + 对抗性审查者	已验证，可证明
T2	实时数据库，单个 Agent	已验证，顺序执行
T3	无实时数据库，子 Agent	有共识，未验证
T4	无实时数据库，单个 Agent	有共识，未验证
T5	只有一个静态表面	低——醒目显示“未验证——无实时数据库”横幅

子 Agent、MCP 和 docker 都是优化手段，绝非必要条件——没有它们时，同样的阶段也可以在当前流程中直接执行。 绝不捏造无法读取的数据：缺失内容应标记出来，而不是猜测。

参考资料

• references/csm-contract.md — schema.json 的结构（可验证的输出契约）。
• references/introspection-postgres.md — 各引擎对应的精确目录查询。
• references/output-template.md — 要复现的人类可读文档结构。
• references/hard-cases.md — 枚举（原生/CHECK/应用层）、JSON 列、多态关系、软删除、复合键、部分索引/表达式索引、视图、多模式、citext/排序规则、旧版表。