---
title: schema 目录下的架构决策 .md 是事实源，调研类 fork 必须显式扫描
date: 2026-04-30
type: process
tags: [research-fork, schema, architecture-decision, prompt-pattern]
---

## 现象

调研 fork 在审批+表单引擎联合审视时，把"FormDefinition 没有 regionId 但文档当作有"判定为 P0 数据模型 drift，建议加 regionId 列。实际上 `backend/prisma/schema/FORM_ORGANIZATION_ARCHITECTURE.md` 是 v2.0 架构清理的已落地决策，明文规定"彻底去除 FormDefinition 的 regionId / regionScope / allowedRegions"，把这些字段刻意删掉了。fork 没读这份文档，只读了 `docs/modules/form-management/07-api.md` 的旧段落，所以做了反向建议。

## 根因

研究类 fork 的 prompt 默认列了 `docs/modules/{module}/` 下的标准文档（PRD/数据模型/API/状态机），但**没强制让它扫 `backend/prisma/schema/` 下的非 `.prisma` 文件**。这种目录里常常躺着"已落地但没被提升到 docs/standards 级别"的架构决策（README、ARCHITECTURE、DECISIONS、MIGRATION、CHANGELOG），它们的权威性其实**高于** `docs/modules/` 里的 API/数据模型文档（后者经常滞后）。

文档优先级真实排序：
1. **schema 本身**（`*.prisma`）— 代码即事实
2. **schema 目录下的 .md**（架构清理记录、v2.0 决策、迁移说明）— 已落地的工程决策
3. `docs/standards/` — 项目级规则
4. `docs/modules/{module}/` — 模块文档（容易和 schema 漂移）

## 解法

**调研类 fork 的 prompt 必须显式包含**：

> 读完模块文档后，**必须扫一遍 `backend/prisma/schema/` 目录下的所有非 `.prisma` 文件**（`*.md`、`README*`、`ARCHITECTURE*`、`DECISIONS*`、`MIGRATION*`）。这些是已落地的架构决策，权威性高于 `docs/modules/` 的 API/数据模型文档。
>
> 当 schema 实际状态与 `docs/modules/{module}/` 文档冲突时：
> - 先在 `prisma/schema/` 找有没有解释这次"删除/重构"的 .md
> - 找到 → 按"文档过时" 处置，**不要建议改 schema 反向回滚**
> - 找不到 → 才升级为契约 drift 让用户决策

## 适用范围

- 所有"对比文档↔代码现状"类调研任务
- 所有跨模块架构审视任务
- 写在 `.agents/skills/plan-review`、`code-review`、调研类 skill 的检查清单里

## 后续动作

- [ ] 把这条规则写入 `.agents/skills/code-review` 或新建 `research-fork-checklist` skill 的标准检查项
- [ ] 在 `docs/standards/06-documentation-system.md` 补一句"schema 目录下的 .md 是事实源之一，权威性介于代码和 docs/standards 之间"