02
PRD Align · workflow

prd-cross-consistency

02-prd-cross-consistency.md
📚
P0 source: claude-and-codex-sessions created: 2026-06-13
◉

WHAT IS THIS

定位

PRD、ADR、CONTEXT、Plan、README 的一致性体检。目标不是润色文档，而是找出状态错位、术语漂移、架构承诺不一致、pending 决策未落地。

⚡

TRIGGERS

触发场景
▸同一 capability 在多份 PRD 里含义不同。
▸PRD 写了 approved，ADR 里仍是 pending。
▸Plan 标记 completed，但代码、测试、frontmatter 不支持这个状态。
▸新增 agent/runtime/event 后，旧文档还保留旧状态机。
▸读文档时需要靠人脑猜“到底哪份为准”。
↹

INPUT & OUTPUT

输入 / 产出
↘ INPUT
  • docs/prds/*.md
  • docs/adrs/*.md
  • CONTEXT.md
  • README.md
  • docs/plans/*.md
  • capability 名称或模块范围，可选。
↗ OUTPUT
  • 一份 conflict report。
  • 一份 canonical terminology table。
  • 需要新增或更新的 ADR 列表。
  • 可直接提交的文档 patch。
🪜

STEPS

编排步骤
  1. 1
    文档清单
    扫描所有候选 Markdown，记录标题、frontmatter、状态字段、最后更新时间。
  2. 2
    决策点抽取
    按 capability、状态机、数据模型、agent event、权限边界、部署边界抽取决策点。
  3. 3
    多文档交叉比对
    每个决策点检查所有文档里的表述，标记 canonical、conflict、missing、stale。
  4. 4
    反驳轮
    专门找“看起来一致但实际不一致”的地方，比如名称一样但状态含义不同。
  5. 5
    ADR 落点检查
    pending 决策必须有 ADR 或明确不需要 ADR 的理由。approved/locked 状态必须能追到 ADR 或代码证据。
  6. 6
    修改文档
    更新 canonical 文档，删除过期重复段落，把实现细节下沉到 Plan。
  7. 7
    链接和 frontmatter 检查
    跑 link check、git diff --check，确认状态字段一致。
⚙

AGENT ROLES

Agent 分工
⚙
Extractor Agents
每个 agent 负责一类决策点。
⚙
Contradiction Agents
只找冲突，不做修复。
⚙
ADR Agent
判断哪些 pending 需要 ADR。
⚙
Editor Agent
统一术语和状态。
⚙
Verifier Agent
跑链接、锚点、frontmatter、diff check。
·

冲突类型

冲突类型
  • 名称冲突：同一 capability 多个名字。
  • 语义冲突：名字一样，行为不同。
  • 状态冲突：draft、approved、locked、completed 不一致。
  • 时间冲突：旧文档覆盖新决策。
  • 边界冲突：PRD 写产品目标，Plan 写实现细节，两者互相污染。
  • 来源冲突：文档承诺和代码实际不一致。
✓

ACCEPTANCE GATE

验收 gate
⊘

FAILURE HANDLING

失败处理
⊘
如果冲突无法自动裁决，输出一组最小问题给用户，不继续批量改。
⤳
如果发现 PRD 过度承载实现细节，转入 →#17。
⤳
如果文档状态和 git 状态冲突，转入 →#06。
⌘

TEMPLATE

最小报告模板
TEMPLATE
## PRD Consistency Report

### Canonical Decisions

| Decision | Canonical source | Status | Evidence |
| --- | --- | --- | --- |

### Conflicts

| Topic | File A | File B | Resolution |
| --- | --- | --- | --- |

### ADR Actions

| Decision | Action | Owner | Reason |
| --- | --- | --- | --- |