@pzy560117/codex-harness 0.1.0 → 0.1.1

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/superpowers-codex-solo-builder-playbook.md

@@ -0,0 +1,676 @@
+# Superpowers + Codex 单人全流程研发实战手册
+
+**日期**: 2026-04-22  
+**定位**: 补足 `AI_Codex_pipeline_v1_2_deep_audit.md` 偏方法论、偏理想化的问题。  
+**目标**: 回答一个更实际的问题: 在上下文有限、只有 1 个人主导、AI 全程辅助的前提下，怎么把 `需求 -> 文档 -> UI 设计 -> 设计转前端 -> 后端 -> 联调 -> 测试` 跑通，并且让每一阶段都有明确输入、输出、闸门和可替换工具。
+
+## 1. 先说结论
+
+### 1.1 真正可落地的模式
+
+在今天这个阶段，最稳的不是“AI 一口气从一句话做完整个项目”，而是:
+
+1. 人负责定义阶段闸门和最终判断。
+2. AI 负责在每个阶段内批量产出候选方案、文档、代码和测试。
+3. 仓库负责把这些候选物变成可验证产物。
+
+如果没有结构化文档、状态矩阵、设计 token、接口 contract、自动验证链路，那么 AI 只是在高速输出草稿，不是在交付工程。
+
+### 1.2 你现在这套链路里，Superpowers 和 Codex 分别应该做什么
+
+- `Superpowers` 负责流程纪律: 需求澄清、设计、计划、代码审查、验证前置、子代理分工。
+- `Codex` 负责仓库内落地: 读文档、改文件、生成代码、跑验证、回写文档。
+- `AI 生图` 只负责探索视觉方向，不能直接作为生产级前端输入真相源。
+- `Figma / 设计 token / screen states / component map` 才是 1:1 还原代码的真相源。
+
+### 1.3 最关键的一条判断
+
+**纯“图片 -> 前端代码”路径，适合原型，不适合直接进生产。**  
+真正能接近 1:1 的路径是:
+
+```text
+需求文档
+  -> 验收示例 + 追溯矩阵 + 测试数据 / 回归范围
+  -> 页面/状态矩阵
+  -> 设计 token + component map + screen states
+  -> Figma / Code Connect / Storybook
+  -> Codex 实现组件和页面
+  -> visual regression / e2e 回归
+```
+
+### 1.4 这份手册现在按 `vb4.md` 的完整流程重排
+
+`vb4.md` 给出的不是普通“研发阶段列表”，而是一套完整的 Agent Harness:
+
+- 8 个前馈 Skill
+- 4 类执行 Sub-Agent
+- 6 类反馈 Hook / Sensor
+- 两阶段 Code Review
+- 反馈沉淀和规则进化
+
+所以你后面看这份手册时，不要把它理解成单纯的“项目流程建议”，而要理解成:
+
+```text
+Guides: 先定义怎么做
+  -> Builders: 再让 AI 去做
+  -> Sensors: 做完马上检查
+  -> Steering Loop: 把反复出现的问题升级成规则
+```
+
+## 2. GitHub 实践取样结论
+
+这次只取对你目标最有用的 6 类 GitHub 实践，不做泛搜。
+
+| 仓库 | 看的重点 | 对你的启发 |
+| --- | --- | --- |
+| `OpenHands/software-agent-sdk` | agent 可以跑在本地工作区，也可以跑在 ephemeral workspace；仓库里直接给了 GitHub workflow 示例 | AI 自动化不要只停在聊天。低风险、重复性高的任务可以直接变成 workflow |
+| `Aider-AI/aider` | repo map 不是口号，而是压缩全仓库上下文的核心手段 | 大仓库里必须有 `repo-map`/`feature-pack` 这类中间上下文文件 |
+| `figma/code-connect` | 把 Figma Dev Mode 里的代码片段替换成真实生产代码 | 设计转代码不该靠截图猜，而要靠设计组件与代码组件绑定 |
+| `figma/sds` | Figma Variables、Styles、Components、Code Connect、Storybook、tokens 脚本放在同一仓库 | 真正可持续的 1:1 还原，依赖 token、组件、stories、设计文件一起维护 |
+| `orval-labs/orval` + `stoplightio/prism` | OpenAPI 生成类型安全 client / mocks；mock server + validation proxy | 前后端并行开发前，先把 contract 固化，再生成 client 和 mock |
+| `UiPath/apollo-ui` | 设计系统仓库里有 design tokens、Storybook、测试、Copilot instructions、visual regression 规则 | UI 的真相源不是一张图，而是组件库、tokens、stories、tests、instructions |
+
+另一个必须单独说的仓库是 `abi/screenshot-to-code`:
+
+- 它证明了“截图 / mockup / Figma -> 代码”这条路确实能跑。
+- 它也反向证明了这条路天然更适合**原型和首稿**，因为生成结果仍然需要再走组件化、状态补齐、测试和重构。
+
+## 3. 先把 `vb4` 的完整 Harness 映射成 `Superpowers + Codex` 版本
+
+### 3.1 八个 Skill 的对应关系
+
+| `vb4` 阶段 Skill | `vb4` 的职责 | 当前推荐实现 | 必须落盘的真相源 |
+| --- | --- | --- | --- |
+| `product-spec-builder` | 通过多轮追问把模糊想法收敛成 Product Spec | `Superpowers: brainstorming` + `docs/product/*` 模板 | `prd-lite.md`、`page-inventory.md`、`state-matrix.yaml`、`acceptance-criteria.md`、`ACCEPTANCE_EXAMPLES.md`、`TRACEABILITY_MATRIX.md` |
+| `design-brief-builder` | 把“深色、极简”这种口头偏好量化成设计标准 | 设计 brief 文档 + 设计问题清单 | `design-brief.md`、视觉原则、交互原则 |
+| `design-maker` | 直接在设计工具中产出页面原型图 | Figma MCP / 设计工具 + AI 生图做方向探索 | Figma 页面、关键组件、页面状态图 |
+| `dev-planner` | 先调研技术栈，再拆 Phase 和 Task | `Superpowers: writing-plans` + feature plan | `DEV-PLAN.md`、`feature-pack.md`、`repo-map.md` |
+| `dev-builder` | 按 Task 逐项编码，每项先编译验证再推进 | Codex + `tools/harness/codex-loop.ps1` / 任务队列 | task 文档、代码、测试、trace |
+| `bug-fixer` | 四阶段系统调试，不猜不试 | `systematic-debugging` 思路 + bug fix workflow | 证据、假设、验证记录、修复说明 |
+| `code-review` | 两阶段审查: 先 Spec 合规，再代码质量 | reviewer 会话 / code-review skill / PR 审查 | 审查记录、风险列表、缺口列表 |
+| `release-builder` | 构建、打包、发布、回写发布信息 | verify + release checklist + workflow | 发布清单、回滚说明、验收报告 |
+
+### 3.2 这 8 个 Skill 里，哪些是你当前最该补的
+
+如果按 `vb4` 的完整顺序看，你当前 `.agents` 里已经比较强的是:
+
+- `dev-planner`
+- `dev-builder`
+- `code-review`
+- `部分 release / verification`
+
+真正还不够落地的是前半段:
+
+- `product-spec-builder`
+- `design-brief-builder`
+- `design-maker`
+
+也就是说，你现在不是“后端或测试不够”，而是**需求与设计的前馈控制还不够重**。这正是用户前面感觉“还是太理想化”的根因。
+
+## 4. `vb4` 最有价值的不是阶段，而是控制环
+
+### 4.1 两阶段 Code Review 必须保留
+
+`vb4` 里最值得直接继承的是“两阶段审查”:
+
+1. Stage 1: 功能完整性
+2. Stage 2: 代码质量
+
+在你的链路里，建议固定成:
+
+```text
+Stage 1:
+- 对照 Product Spec / Design Brief / 设计稿 / DEV-PLAN
+- 看有没有漏功能、少状态、多实现、错优先级
+
+Stage 2:
+- 看命名、类型、安全、结构、测试缺口、回归风险
+```
+
+这两阶段不要合并。  
+因为很多 AI 产物最先出的问题不是“代码丑”，而是“实现的东西根本不是 Spec 要的”。
+
+### 4.2 Hook / Sensor 在 Codex 侧的对应实现
+
+`vb4` 基于 Claude hooks，但你当前仓库主要跑在 Codex / PowerShell / `.agents` 上，所以要做等价映射，而不是照搬名字。
+
+| `vb4` Sensor | 在 Codex / Hermes 侧的等价物 |
+| --- | --- |
+| `pre-commit-check` | `tools/harness/verify.ps1`、`test_command`、`git diff --check`、driver commit 前检查 |
+| `auto-push` | GitHub Actions / 发布 workflow / 可选的推送脚本，不建议默认本地无脑自动 push |
+| `stop-gate` | completion gate: 有代码变更但没审查、没验证，不允许结束 |
+| `detect-feedback-signal` | 在 `feedback/` 或回顾文档里记录“用户反复纠正”的信号 |
+| `mark-review-needed` | 代码文件变更后自动进入“待审查”状态；可由 task/progress/PR 检查承接 |
+| `check-evolution` | session 开始时检查历史反馈、回归规则和待升级约束 |
+
+结论不是“你一定要把 Hook 名字做出来”，而是**这些传感器背后的检查语义必须存在**。
+
+### 4.3 Review -> Fix 闭环要自动，而不是靠人记
+
+`vb4` 最对的一点是：  
+不是“写完代码 -> 人想起来再去 review”，而是:
+
+```text
+实现
+  -> Stage 1 review
+  -> 不过就修
+  -> Stage 2 review
+  -> 不过就修
+  -> verify
+  -> 才允许完成 / 提交 / 发布
+```
+
+如果这条闭环不能自动推进，后面还是会退回到“AI 写一堆，人手动盯每一步”的老路。
+
+### 4.4 Sub-Agent 隔离必须保留
+
+`vb4` 里另一条很关键的规则是: **每个 Task 用全新实例，不继承前一任务的执行历史。**
+
+这个在你当前 Codex 体系里同样成立:
+
+- 一个 feature 可以有长期 DEV-PLAN
+- 但每个 task 实现和审查，最好是 fresh session
+- 允许共享的是结构化上下文
+- 不允许共享的是上一轮的错误假设和聊天噪音
+
+共享的应该是:
+
+- Product Spec
+- Design Brief
+- 设计稿 / 组件映射
+- DEV-PLAN
+- 当前 task 的 `context_files`
+
+不该共享的应该是:
+
+- 上一轮失败的长聊天
+- 大量无关 trace
+- 与当前 task 无关的猜测过程
+
+### 4.5 `vb4` 的设计优先级必须保留
+
+`vb4` 有一条非常值钱的原则:
+
+```text
+设计稿 > Design Brief > Product Spec
+```
+
+也就是:
+
+- 功能逻辑以 Product Spec 为准
+- 视觉与交互优先级以设计稿为准
+- Design Brief 是设计稿没写清时的补充标准
+
+这条规则会直接影响 review:
+
+- 如果设计稿里没有这个交互，代码加了，必须解释为什么
+- 如果 Product Spec 改了 UI，设计稿没更新，应该阻断进入后续实现
+
+### 4.6 `DEV-PLAN` 不是附属文档，而是跨 session 锚点
+
+`vb4` 对 DEV-PLAN 的定位很准: 它不是普通计划，而是跨 session 继续开发的锚点。
+
+对于 Codex 来说，这意味着:
+
+- 新 session 不该从头猜项目状态
+- Phase 开始时应该重新读 `DEV-PLAN`
+- Task 开始时应该重新读当前 phase 的目标、交付物和限制
+
+所以后面你如果继续沉淀模板，`DEV-PLAN` 应该成为一级入口，而不是“可有可无”。
+
+## 5. 各阶段痛点与推荐打法
+
+### 5.1 总览表
+
+| 阶段 | AI 自动化可行性 | 最大痛点 | 推荐主模型 / 工具 | 必须落盘的文档/文件 | 进入下一阶段的闸门 |
+| --- | --- | --- | --- | --- | --- |
+| 需求分析 | 高 | 需求模糊、范围漂移 | `gpt-5.4`，`Superpowers: brainstorming` | `prd-lite.md`、`page-inventory.md`、`acceptance-criteria.md`、`state-matrix.yaml`、`ACCEPTANCE_EXAMPLES.md`、`TRACEABILITY_MATRIX.md` | 页面、角色、状态、验收标准和追溯入口不再口头化 |
+| 需求到实施计划 | 高 | 任务切分粗，AI 一次吞太多 | `gpt-5.4` 或 `gpt-5.4-mini`，`Superpowers: writing-plans` | `feature-pack.md`、`repo-map.md`、feature plan、任务清单 | 每个 task 都能单会话完成 |
+| AI 生图探索 UI | 中 | 只有正常态，没有异常态和结构 | `gpt-image-1.5` 或其他图像模型 | moodboard、风格参考、页面清单补充 | 只把图当参考，不把图当最终规范 |
+| 设计规范化 | 高 | 从视觉稿到代码缺中间层 | Figma、Code Connect、SDS 思路、`gpt-5.4` 做设计 QA | `information-architecture.md`、`screen-states.md`、`component-map.md`、`design-tokens.json` | 每个页面的 default / empty / loading / error / disabled / mobile 都补齐 |
+| 设计转前端代码 | 中到高 | 纯图片转代码不稳定；状态缺失；交互缺失 | Codex、`gpt-5.2-codex` 思路、Storybook、Code Connect | stories、组件实现、页面实现、视觉验收清单 | stories、typecheck、build、交互验收通过 |
+| 后端设计与实现 | 高 | 接口漂移、错误码不一致、权限漏掉 | `gpt-5.4`、OpenAPI、Orval、Prism | `contracts/openapi.yaml`、错误码规范、DTO/Schema | client / mock / contract 三方一致 |
+| 前后端联调 | 中到高 | 双方各写一份类型；本地环境不一致 | generated client、mock server、devtools MCP | 联调记录、异常态清单、真实接口映射 | 主要业务流和异常流跑通 |
+| 测试与回归 | 高 | AI 不会主动补全测试矩阵 | Playwright、Storybook、Vitest、visual regression | `verify-matrix.md`、affected tests、P0/P1 regression、e2e-plan、unit/integration/e2e、visual baseline | 不是“能用”，而是 fresh evidence 和回归通过 |
+
+## 6. 每一阶段到底怎么做
+
+### 6.1 阶段 A: 需求分析与边界收敛
+
+#### 主要痛点
+
+- 用户需求会混着业务目标、页面想法、实现偏好、验收标准一起说。
+- 如果这一阶段不强制结构化，后面每个 agent 都会自己脑补。
+- 1 个人最容易在这里被 AI 带着越做越大。
+
+#### 推荐打法
+
+- 用 `Superpowers: brainstorming` 先把需求拆成单功能 spec，而不是直接让 Codex 写代码。
+- 用高推理模型先做范围收敛，再用 Codex 只负责回写文档。
+- 这一步不要急着画 UI，也不要急着写 API。
+- 参考 `vb4`，这一步结束时应该有**面向 AI 的 Product Spec**，不是只给人看的需求摘要。
+
+#### 推荐模型
+
+- 主模型: `gpt-5.4`  
+  OpenAI 当前模型总览建议默认从 `gpt-5.4` 开始，定位是复杂推理和编码的旗舰模型。
+- 成本优化: `gpt-5.4-mini`  
+  适合需求改写、文档补全、子任务拆分这类高频但较稳定的工作。
+
+#### 最低输出物
+
+- `docs/product/prd-lite.md`
+- `docs/product/page-inventory.md`
+- `docs/product/acceptance-criteria.md`
+- `docs/product/state-matrix.yaml`
+- `docs/testing/ACCEPTANCE_CRITERIA.md`
+- `docs/testing/ACCEPTANCE_EXAMPLES.md`
+- `docs/testing/TRACEABILITY_MATRIX.md`
+- `docs/testing/TEST_DATA_MATRIX.md`
+- `docs/testing/test-matrix.md`
+
+#### 这一阶段的实操示例
+
+```text
+输入: “做一个企业工单后台，支持筛选、保存视图、批量分派、审计日志”
+
+AI 第一轮输出不应该是代码，而应该是:
+- 角色: 客服、主管、管理员
+- 页面: 列表页、详情页、保存视图弹窗、批量操作抽屉
+- 状态: 默认/空/加载/错误/无权限/长列表/移动端折叠
+- 验收: 保存视图后刷新仍在；无权限用户看不到批量分派
+```
+
+如果这些验收示例、Requirement IDs 和追溯矩阵还没落盘，就不该进入 Design Brief、任务拆分或正式实现阶段。
+
+### 6.2 阶段 B: AI 生图与设计探索
+
+#### 主要痛点
+
+- AI 生图只擅长“风格感”，不擅长精确布局、组件复用和状态全覆盖。
+- 一张图里通常只有 happy path，没有 error / empty / disabled / responsive。
+- 文本渲染、对齐、表格密度、业务组件一致性都容易失真。
+
+#### 推荐打法
+
+- 把 AI 生图定位为**视觉方向探索**，不是直接给前端开发的生产资产。
+- 输出不应该只有图片，还要有“页面清单 + 状态缺口清单”。
+- 每轮出图后，必须追问: 缺了哪些界面？缺了哪些状态？哪些元素必须组件化？
+- 参考 `vb4`，这里应该先经过 `design-brief-builder`，再进入 `design-maker`，而不是直接从需求跳到出图。
+
+#### 推荐模型
+
+- 探索视觉方向: `gpt-image-1.5`
+- 多轮修改: 用 Responses API 里的图像工具做迭代编辑，而不是每次全量重画
+
+#### 必须补的文档
+
+- `docs/design/information-architecture.md`
+- `docs/design/screen-states.md`
+- `docs/design/component-map.md`
+
+#### 关键判断
+
+如果你手上只有 AI 生成的 JPG/PNG，没有 token、没有状态矩阵、没有组件映射，那么这还不能进“前端实现”阶段。
+
+### 6.3 阶段 C: 把视觉稿变成可编码设计规范
+
+#### 主要痛点
+
+- 开发拿到图，不知道哪些是组件、哪些是一次性布局。
+- 设计稿里颜色、字号、间距、断点没有结构化表示。
+- 同一个组件在多个页面上表现不一致，AI 容易越写越散。
+
+#### 推荐打法
+
+- 借鉴 `figma/sds` 的方式，把这一步拆成 4 份资产:
+  - `design-tokens.json`
+  - `component-map.md`
+  - `screen-states.md`
+  - Figma 与代码组件绑定
+- 借鉴 `figma/code-connect` 的做法，让设计稿里看到的不是“自动生成 HTML”，而是真实的生产组件代码片段。
+
+#### 最低输出物
+
+- `docs/design/design-tokens.json`
+- `docs/design/component-map.md`
+- `docs/design/screen-states.md`
+- `figma.config.json` 或等价的 Figma 到代码映射配置
+
+#### 什么时候这一步算完成
+
+- 每个页面都知道由哪些组件组成。
+- 每个组件都知道有哪些状态。
+- token 可被前端直接消费，而不是还要人工再翻译一次。
+- 设计和代码之间存在“引用关系”，不是两套平行宇宙。
+
+### 6.4 阶段 D: 设计稿 1:1 还原为前端代码
+
+#### 三条路线的可行性判断
+
+| 路线 | 可行性 | 适用场景 | 不适合什么 |
+| --- | --- | --- | --- |
+| 纯截图 / 纯图片 -> 代码 | 低到中 | 原型、首稿、探索版 demo | 生产级后台、复杂状态、多页面一致性 |
+| Figma / 设计稿 -> 代码首稿 | 中 | 页面骨架、静态布局、首版组件 | 缺 stories、缺 tokens、缺交互定义时 |
+| 设计 token + component map + screen states + Code Connect -> 代码 | 高 | 生产级、长期维护、多人协作 | 前期没有做结构化设计时 |
+
+#### 实际推荐
+
+1. 可以用 `screenshot-to-code` 这类工具先出第一版页面骨架。
+2. 但第二步必须立刻把它拆回组件库、stories、tokens、状态矩阵。
+3. 真正交给 Codex 实现时，输入应该是规范化设计，不是单张图片。
+4. 真正发生冲突时，遵循 `vb4` 的优先级: 设计稿 > Design Brief > Product Spec。
+
+#### 推荐模型 / 工具
+
+- in-repo 实现: Codex
+- 编码模型: `gpt-5.2-codex` 思路适合长链路 agentic coding；如果直接走 OpenAI 当前主线，也可以用 `gpt-5.4` / `gpt-5.4-mini`
+- UI 组件真相源: Storybook + design tokens + component map
+- 视觉绑定: Figma Code Connect
+
+#### 前端阶段最低交付物
+
+- `packages/ui/*` 或等价组件目录
+- `stories/*.stories.tsx`
+- 页面代码
+- `docs/design/component-map.md` 回写
+- 视觉验收 checklist
+
+#### 这一阶段最常见的错误
+
+- 只看默认态，不补 empty/loading/error
+- 直接从图生成整页，不先抽组件
+- 没有 stories，后续无法视觉回归
+- 文本、表格、列表、弹窗全部硬编码
+
+### 6.5 阶段 E: 后端与 contract-first
+
+#### 主要痛点
+
+- AI 同时写前后端时，最容易出现 contract 漂移。
+- 错误码、分页、枚举、权限边界经常前后不一致。
+- 联调阶段才发现字段名、类型、空值语义对不上。
+
+#### 推荐打法
+
+- 先让 AI 生成 `OpenAPI`，再生成 client、types、mock。
+- 借鉴 `orval` 生成前端 client、hooks、mocks。
+- 借鉴 `prism` 做 mock server 和 validation proxy。
+
+#### 推荐模型
+
+- 复杂 schema / error model 设计: `gpt-5.4`
+- 大量 DTO/测试补全: `gpt-5.4-mini`
+
+#### 最低输出物
+
+- `contracts/openapi.yaml`
+- `packages/api-client/*` 或等价 generated client
+- `mocks/` 或 `prism` 配置
+- 错误码 / 权限矩阵
+
+#### 判断是否可以进联调
+
+- 前端和后端都只围绕同一份 contract 工作。
+- mock 场景可以覆盖正常、空态、异常、超时、无权限。
+- generated client 已替代手写 API 调用。
+
+### 6.6 阶段 F: 联调
+
+#### 主要痛点
+
+- 本地环境不一致。
+- 前端还在调样式，后端还在调字段。
+- 联调时才第一次跑完整业务流。
+
+#### 推荐打法
+
+- 先跑 mock 联调，再切真实后端。
+- 生成 client 后，前端禁止再手写一套 request schema。
+- 联调用 devtools MCP 或真实浏览器，不靠“代码看起来没问题”。
+
+#### 最低交付物
+
+- 联调清单
+- 异常流清单
+- 真实接口切换记录
+- 与 contract 不一致的问题列表
+
+### 6.7 阶段 G: 测试与回归
+
+#### 主要痛点
+
+- AI 生成代码后，很少主动补齐完整测试矩阵。
+- 视觉回归最容易被省掉，结果“1:1”无法证明。
+- 单元测得过，但真实页面交互仍然可能坏。
+
+#### 推荐打法
+
+- 组件层: stories + component tests
+- 前端层: typecheck + build + Playwright
+- 后端层: unit + integration + auth/permission tests
+- 联调层: contract validation + e2e
+- 视觉层: visual regression
+- 参考 `vb4`，这一阶段不只是一轮“跑测试”，而是 `Review -> Fix -> Review -> Verify` 的闭环。
+- Stage 17 / 最终 verify 只负责 fresh evidence、affected tests、P0/P1 regression 和契约/视觉确认，不负责第一次定义测试范围。
+
+#### 最低输出物
+
+- `docs/testing/verify-matrix.md`
+- `docs/testing/RISK_BASED_TEST_PLAN.md`
+- `docs/testing/REGRESSION_PLAN.md`
+- `docs/testing/EVIDENCE_PROTOCOL.md`
+- affected tests 清单和对应执行证据
+- failure findings / repair 记录
+
+#### 借鉴的 GitHub 实践
+
+- `UiPath/apollo-ui` 的 `.github/copilot-instructions.md` 明确写了: library code 需要单测和 visual regression，demo 代码不需要。
+- 这类做法非常适合你: 把“什么必须测、什么可以不测”写进仓库，让 AI 按仓库规则工作。
+
+## 7. Superpowers 在这条链路里怎么用
+
+### 7.1 推荐映射
+
+| 阶段 | 推荐 Superpowers / 技能 |
+| --- | --- |
+| 需求澄清 | `brainstorming` |
+| Design Brief 收敛 | 继续走 `brainstorming`，但输出转向视觉规则而不是业务规则 |
+| 设计冻结后转实施 | `writing-plans` |
+| 任务并行拆分 | `subagent-driven-development` |
+| Bug 修复 | `systematic-debugging` |
+| 实现后代码审查 | `requesting-code-review` |
+| 收到评审意见后 | `receiving-code-review` |
+| 验证交付前 | `verification-before-completion` |
+
+### 7.2 正确使用姿势
+
+- Superpowers 不应该替代产品文档、设计文档、contract 文档。
+- 它负责的是“流程 discipline”，不是“业务真相源”。
+- 真相源必须落在仓库文件里，并且被 Codex 读取。
+- 如果要贴近 `vb4`，可以把它理解成: Superpowers 更接近 `Guides`，而 `.agents` driver / review / CI 更接近 `Sensors`。
+
+## 8. 用 Codex 跑一个真实功能的示例
+
+这里用“工单列表筛选与保存视图”举例。
+
+### Step 1: 需求与状态
+
+产出:
+
+- `docs/product/prd-lite.md`
+- `docs/product/page-inventory.md`
+- `docs/product/state-matrix.yaml`
+- `docs/product/acceptance-criteria.md`
+
+最低要求:
+
+- 页面: 列表、筛选条、保存视图弹窗
+- 状态: default / empty / loading / error / dirty / permission denied
+
+### Step 2: Design Brief + 设计规范
+
+产出:
+
+- `docs/design/design-brief.md`
+- `docs/design/component-map.md`
+- `docs/design/screen-states.md`
+- `docs/design/design-tokens.json`
+
+最低要求:
+
+- 筛选条拆成可复用组件
+- 表格列密度、按钮层级、筛选标签状态都被定义
+- 保存视图弹窗的校验态明确
+
+### Step 2.5: DEV-PLAN
+
+产出:
+
+- `plans/features/ticket-filter.dev-plan.md`
+
+最低要求:
+
+- Phase 划分明确
+- 每个 Task 都能在 fresh session 中完成
+- 明确哪些文件是上下文真相源
+
+### Step 3: 前端施工
+
+Codex 输入不应该是“按这张图做一个工单页”，而应该是:
+
+```text
+阅读:
+- docs/product/prd-lite.md
+- docs/product/state-matrix.yaml
+- docs/testing/ACCEPTANCE_EXAMPLES.md
+- docs/testing/TRACEABILITY_MATRIX.md
+- docs/design/component-map.md
+- docs/design/screen-states.md
+- packages/ui/*
+
+只实现:
+- 列表页筛选条
+- 保存视图弹窗
+
+必须补:
+- 对应 Requirement IDs 的测试映射
+- 对应 stories
+- typecheck / build / e2e 验证
+```
+
+### Step 4: 后端与 contract
+
+产出:
+
+- `contracts/openapi.yaml`
+- generated client
+- mock server 配置
+
+接口至少包括:
+
+- `GET /ticket-views`
+- `POST /ticket-views`
+- `GET /tickets`
+
+### Step 5: 联调与回归
+
+最低验证:
+
+- `typecheck`
+- `lint`
+- `build`
+- 组件 stories
+- e2e: 创建视图、应用视图、无权限失败
+- visual: 列表页、空态、弹窗
+
+还要补一条 `vb4` 风格的闭环:
+
+```text
+实现完成
+  -> Stage 1: 对照 Product Spec / 设计稿审查
+  -> 修复偏差
+  -> Stage 2: 对照代码质量 / 测试缺口审查
+  -> 修复问题
+  -> affected tests + verify + fresh evidence
+```
+
+## 9. 这一套方案的可行性边界
+
+### 9.1 高可行
+
+- 后台系统
+- SaaS 管理端
+- 表单流
+- 审批流
+- 数据看板
+- 标准 CRUD
+
+### 9.2 中可行
+
+- 复杂交互的专业工具
+- 图形编辑器
+- 带大量自定义画布的应用
+
+### 9.3 低可行
+
+- 只靠 AI 生图，直接做高精度生产前端
+- 没有设计系统、没有状态矩阵、没有 contract，就要求 AI 一次做完整工程
+
+## 10. 对你当前仓库最有价值的落地动作
+
+下面这些基础模板已经补进 `templates/`：
+
+- `templates/design/design-brief.md`
+- `templates/context/dev-plan.md`
+- `templates/docs/spec-to-ui-to-code-workflow.md`
+- `templates/testing/ACCEPTANCE_EXAMPLES.md`
+- `templates/testing/TRACEABILITY_MATRIX.md`
+- `templates/testing/verify-matrix.md`
+- `templates/contracts/openapi.yaml`
+- `templates/contracts/orval.config.ts`
+- `templates/contracts/prism-usage.md`
+- `templates/prompts/review-stage1-spec.md`
+- `templates/prompts/review-stage2-quality.md`
+- `templates/governance/feedback-evolution-loop.md`
+
+在这个基础上，如果你现在要继续沉淀到 `hermes/.agents`，下一步最值得补的是:
+
+1. 把 `templates/product/*`、`templates/design/*`、`templates/context/*` 串成一个标准前置阶段工作流。
+2. 新增 UI 交付检查表，强制页面状态和 visual regression 成为闸门。
+3. 让 driver / CI 真正消费 Stage 1 / Stage 2 review 模板，而不是只把模板放在仓库里。
+4. 把 feedback / evolution loop 接到实际 session 启动检查或回顾流程里。
+5. 把 `spec-to-ui-to-code` 与 `contracts/*` 模板进一步接进具体示例项目，而不是只停留在模板层。
+
+## 11. 推荐默认选型
+
+基于 OpenAI 当前公开模型页和你这个单人项目场景，推荐默认配置如下:
+
+| 用途 | 推荐 |
+| --- | --- |
+| 复杂需求分析 / 方案评审 | `gpt-5.4` |
+| 高频文档改写 / 子任务拆分 / 批量补测试 | `gpt-5.4-mini` |
+| Codex 式长链路编码 | Codex + `gpt-5.2-codex` 思路，或直接使用当前 Codex 默认编码模型 |
+| UI 视觉探索 | `gpt-image-1.5` |
+| UI 代码首稿 | Codex + 结构化设计输入，不建议纯图片直转生产代码 |
+
+## 12. 参考链接
+
+### OpenAI 官方
+
+- Models overview: https://developers.openai.com/api/docs/models
+- GPT-5.4: https://developers.openai.com/api/docs/models/gpt-5.4
+- GPT-5.4 mini: https://developers.openai.com/api/docs/models/gpt-5.4-mini
+- GPT-5.2-Codex: https://developers.openai.com/api/docs/models/gpt-5.2-codex
+- Image generation guide: https://developers.openai.com/api/docs/guides/image-generation
+
+### GitHub 实践
+
+- OpenHands SDK: https://github.com/OpenHands/software-agent-sdk
+- Aider: https://github.com/Aider-AI/aider
+- Figma Code Connect: https://github.com/figma/code-connect
+- Figma SDS: https://github.com/figma/sds
+- screenshot-to-code: https://github.com/abi/screenshot-to-code
+- Orval: https://github.com/orval-labs/orval
+- Prism: https://github.com/stoplightio/prism
+- UiPath Apollo UI: https://github.com/UiPath/apollo-ui