3-Layer · workflow

frontend-api-cli-parity

04-frontend-api-cli-parity.md

🔗

P1 source: claude-sessions created: 2026-06-13

◉

WHAT IS THIS

定位

Frontend、API、CLI 三层架构对齐审计。它适合持续扩展 API 包、CLI 命令、前端 action 的项目，每新增一批能力就跑一次。

⚡

TRIGGERS

触发场景

▸API 新增了 endpoint，但 CLI 或 frontend 没接。

▸CLI 里有 command，后端没有对应 action。

▸Frontend 常量 URL 手写，和 API route 不一致。

▸生成目录和手写目录并存，出现 orphan 文件。

▸三层命名接近但不完全一致，比如 candidateSearch、searchCandidates、candidate.search。

↹

INPUT & OUTPUT

输入 / 产出

↘ INPUT

Frontend exports，比如 src/index.ts、actions/、routes/。
API routes、controller、OpenAPI、DTO。
CLI generated/actions/commands。
URL constants、schema files、docs reference。

↗ OUTPUT

三层能力矩阵。
orphan 文件清单。
命名冲突清单。
缺失接入 patch。
生成规则或 contract 更新建议。

🪜

STEPS

编排步骤

1
扫 frontend export
提取公开 action、hook、client method、URL 常量。
2
扫 API surface
提取 route、method、request DTO、response DTO、错误 envelope。
3
扫 CLI surface
提取 command、action、generated client、schema resolver。
4
建 capability matrix
每行一个 capability，每列是 frontend、API、CLI、docs、tests。
5
找 orphan
标记只存在一层的文件或能力。
6
找命名漂移
标记同一能力不同命名，给 canonical name。
7
修复或降级
能直接补的补上；需要 contract 决策的转入 →#01。

⚙

AGENT ROLES

Agent 分工

⚙

Frontend Agent

负责 exports、URL、UI action。

⚙

API Agent

负责 routes、DTO、schema。

⚙

CLI Agent

负责 command、generated client、formatter。

⚙

Matrix Agent

合并三层矩阵。

⚙

Verifier Agent

跑类型检查、CLI smoke、API tests。

✓

ACCEPTANCE GATE

验收 gate

✓每个 public API 都有对应 docs 或明确内部标记。
✓每个 CLI command 能追到 API route 或本地实现理由。
✓Frontend URL 常量都能解析。
✓没有 orphan generated 文件。
✓canonical naming table 更新。
✓相关 tests、typecheck、build 通过。

⊘

FAILURE HANDLING

失败处理

⊘

如果三层对不上是因为 contract 不清楚，停止本 workflow，先跑 contract alignment。

⊘

如果 generated 文件无法人工修改，修 generator，不修产物。

⊘

如果 API 已废弃，删除或标 deprecated，不保留沉默 orphan。

⌘

TEMPLATE

capability matrix 模板

TEMPLATE

| Capability | Frontend | API | CLI | Docs | Tests | Status |
| --- | --- | --- | --- | --- | --- | --- |