Spec-First

App 一致性审查 ​

spec-app-consistency-audit 是移动 App 的静态优先审查入口，用于在模拟器、真机、打包或 QA 前比较产品意图、设计状态、本地源码、页面路由、KMP / Clean Architecture、组件复用、埋点、i18n、工程质量和行业规则。

它提升 review 输入质量，但不替代运行时验证、自动化测试、QA 或真机验证。

入口 ​

宿主入口
Claude Code/spec:app-consistency-audit prd:<path> figma-context:<path> source:<path>
Codex$spec-app-consistency-audit prd:<path> figma-context:<path> source:<path>

常用参数：

参数说明
source:<path>App source root，默认当前仓库根目录
prd:<path>本地 PRD 或产品输入
figma-context:<path>本地 materialized Figma JSON evidence
figma-ref:<id-or-url>仅作为 reference，不等同于可抽取证据
base:<ref>diff base，headless 或 code-review 调用时应显式传入
mode:headless父流程使用的程序化模式，返回 compact envelope
mode:report-only只读模式，不写 run artifacts
depth:deep聚焦深挖标记，不是互斥 mode

执行逻辑图 ​

text
用户运行 /spec:app-consistency-audit 或 $spec-app-consistency-audit
  |
  v
读取 prd:<path>、figma-context:<path>、source:<path>、base:<ref>
  |
  v
执行 preflight：确认输入存在、diff base、source root、Figma evidence 可抽取
  |
  +-- 输入缺失或不可抽取
  |     |
  |     v
  |   记录 degraded coverage，不把 reference 当 evidence
  |
  +-- 输入可用
        |
        v
      聚合 PRD / Figma / source / route / architecture / analytics / i18n facts
        |
        v
      LLM 专家审查跨来源一致性和行业规则风险
        |
        v
      deterministic evidence gate 过滤无证据 finding
        |
        v
      输出 app-consistency-audit.md、issues.json、audit-report.json
        |
        v
      作为 code review、QA、真机验证前的静态风险输入

适合使用 ​

  • PRD、Figma context 或本地 source 已存在，且跨来源一致性重要。
  • Android / iOS 行为、导航、页面状态或弱网状态可能漂移。
  • KMP shared logic、Clean Architecture 边界、页面路由或组件复用需要审查。
  • 埋点、i18n、accessibility 或行业规则风险需要在 QA 前暴露。

不适合使用 ​

  • 用户只想跑测试、lint、build、模拟器或真机检查。
  • 没有 PRD、Figma context 或 source input 可审查。
  • 任务只是格式化或机械重构。
  • 用户希望该 workflow 直接修改产品代码或项目规范。

产物边界 ​

默认和 mode:headless 会写入 run-scoped artifacts：

text
.spec-first/app-audit/runs/<run-id>/

常见产物包括：

文件作用
metadata.jsonrun id、scope、head sha、diff hash、worktree fingerprint 和审查模式
artifact-manifest.json本次 run 写出的 artifact 清单和 hash
preflight.json输入可用性和 degraded modes
impact-facts.jsonsource、diff、route、interaction 和候选影响面机器事实
app-audit-context.jsonLLM 专家使用的聚合上下文
issues.json通过 deterministic evidence gate 的结构化 issue
audit-report.json机器可读审查报告
app-consistency-audit.md面向用户的静态一致性审查报告

.spec-first/app-audit/ 是 gitignored 执行产物，不是 source truth。需要共享时，优先摘录结论或另存为团队约定的 durable doc。

Figma 证据规则 ​

figma-context:<path> 才是可抽取 evidence；figma-ref:<id-or-url> 只是 reference。Figma MCP 是宿主可选能力，用于在默认交互模式下 materialize 本地 JSON，不属于 spec-mcp-setup 的 required baseline。

在 mode:headless 和 mode:report-only 下，不应远程 materialize Figma context。缺少本地 context 时，应记录 degraded coverage，而不是把 reference 当作证据。

与 code review 的关系 ​

spec-code-review 可以把 App 一致性审查作为补充输入，特别是移动 App 改动在运行时 QA 前需要先确认 PRD / Figma / source 是否一致时。最终合并判断仍应结合真实测试、运行时验证和 reviewer 对当前 diff 的风险判断。