# Speckit

> Codex 版规范驱动开发（SDD）工作流。Use when the user mentions `speckit`, `Spec-Kit`, `Specify`, `/speckit.start`, `/speckit.requirement`, `/speckit.constitution`, `/speckit.reqdoc`, `/speckit.ui`, `/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, `/speckit.implement`, `/speckit.version`, `/speckit.iterate`, or asks to create/update versioned spec artifacts under `.spec/`.

- Skill: `zengfanling/speckit` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add zengfanling/speckit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zengfanling/speckit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ZengFanling (https://skillmd.com/u/zengfanling)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zengfanling/speckit

---


# Speckit for Codex

这个 skill 把 Spec-Kit 的规范驱动开发流程改写成 Codex 可直接执行的版本。

目标是让 Codex 围绕 `.spec/` 目录完成一整套闭环：

`项目宪章 -> 需求分析 -> 需求方案 -> UI 方案 -> 功能规范 -> 技术方案 -> 任务拆解 -> 代码实现 -> 版本迭代`

## Codex 版原则

1. 不依赖 CodeBuddy 专属 agent、MCP 或 slash 命令执行器。
2. 通过 Codex 自己的阅读、编辑、实现、测试、浏览器验证能力完成工作。
3. 不假装“自动双向同步”。如果 `reqdoc` 或 `ui` 有变更，Codex 要在同一轮里主动同步另一份文档。
4. 默认把产物写入工作区 `.spec/`。只有当用户明确说“先别落盘”或“先给我草稿”时，才只在对话里展示。
5. 如果要生成 Vue 代码，先读取同目录下的 [基于vue3前端开发规范.md](./基于vue3前端开发规范.md)，并严格遵循其中约定。
6. 如果仓库已有实现，优先贴合现有代码结构、设计系统和测试方式，不要强行套模板。

## 目录约定

使用以下结构：

```text
.spec/
├── manifest.json
├── changelog.md
├── v1/
│   ├── requirement.md
│   ├── constitution.md
│   ├── reqdoc.html
│   ├── ui.md
│   ├── ui-assets/
│   │   ├── manifest.md
│   │   └── ...
│   ├── specification.md
│   ├── plan.md
│   ├── tasks.md
│   └── manifest.json
└── v2/
    └── ...
```

约定：

- 根目录 `manifest.json` 记录当前版本和版本列表。
- 每个版本目录下的 `manifest.json` 记录该版本已有的产物、状态、时间戳。
- `changelog.md` 记录版本变化摘要。
- `ui` 阶段的产物统一使用 `ui.md`，不要依赖外部私有平台格式。
- `ui-assets/` 用于存放 UI 阶段从效果图中拆分出来的控件切图与说明。

## 命令映射

用户提到以下任一入口时，按对应阶段执行：

- `/speckit.start`：检查现有材料，自动判断下一步。
- `/speckit.constitution`：项目宪章。
- `/speckit.requirement`：需求分析。
- `/speckit.reqdoc`：需求方案文档。
- `/speckit.ui`：UI 方案文档。
- `/speckit.specify`：功能规范。
- `/speckit.plan`：技术方案。
- `/speckit.tasks`：任务拆解。
- `/speckit.implement`：代码实现。
- `/speckit.version`：查看当前版本状态。
- `/speckit.iterate`：基于当前版本开启下一轮迭代。

如果用户没有写 slash 命令，但明确说“用 speckit 做”“按 spec-kit 流程做”“把需求走成一套 spec”，同样触发本 skill。

## 执行总流程

### 1. `/speckit.start`

先检查：

- 工作区是否已有 `.spec/`
- 是否已有 PRD、需求文档、设计稿、截图、原型、已有代码
- 当前是新项目、增量需求，还是已有版本迭代

然后先做入口分型，至少判断两个维度：

- **需求类型**：传统需求，还是 AI 需求
- **演进方式**：`0 到 1`，还是 `1 到 N`

入口判断规则与 `/speckit.requirement` 保持一致：

- 如果核心价值来自固定流程、规则编排、表单、审批、展示、查询、交易、配置等确定性能力，判定为 **传统需求**
- 如果核心价值依赖模型推理、生成、检索、分类、总结、对话、推荐、自动化决策辅助等能力，判定为 **AI 需求**
- 如果当前业务流程、产品结构、页面或代码基本不存在，判定为 **`0 到 1`**
- 如果当前系统、角色、页面、流程或代码已经存在，判定为 **`1 到 N`**

如果入口判断为 `1 到 N`，在决定走哪一步之前，先补做一轮 **现有流程扫描**：

- 优先读取代码中的真实用户操作链路
- 再结合已有 PRD、设计稿、测试用例、埋点或用户说明
- 输出当前流程概览、关键页面、角色、状态流转、主要痛点和本次改动影响范围

现有流程扫描时，优先关注：

- 路由入口和页面跳转
- 按钮、表单、弹窗、审批、提交流程
- 权限控制和角色差异
- 状态管理、接口调用顺序、错误处理
- 后端校验、服务编排、异步任务、通知或回写逻辑

然后选择下一步：

- 已有 `.spec/` 且正在改版：进入 `version` 或 `iterate`
- `1 到 N` 但现有流程还不清楚：先进入 `constitution`，并在同一轮补做现有流程扫描，必要时再展开 `requirement`
- 已有完整需求和设计材料：直接进入 `specify` 或 `plan`
- 只有模糊想法：从 `constitution` 开始
- 有 PRD 但没有 UI 方案：从 `ui` 或 `reqdoc` 开始
- AI 需求但模型边界、兜底和评估方式还不清楚：先进入 `constitution`，再补 `requirement`

### 2. `/speckit.constitution`

产出 `constitution.md`，用于定义项目不轻易改变的原则。这是默认的第一步，用来先收敛项目原则、边界和交付约束，再决定后续需求分析和方案展开方式。至少包含：

- 产品原则
- 设计原则
- 技术原则
- 技术架构
- 质量门槛
- 性能/安全底线
- 交付约束

其中“技术架构”最好按真实项目结构展开，优先写清：

- 前端架构：端类型、技术栈、路由/状态管理、组件体系、构建与发布方式
- 后端架构：服务边界、接口分层、核心模块、同步/异步链路、依赖的中间件或基础设施
- AI 端架构（若有）：模型类型、推理链路、Prompt/Agent 编排、知识库/RAG、工具调用、人工兜底与评估方式
- 数据架构：核心数据对象、关键数据流、数据表结构、主外键关系、索引、缓存、搜索或数仓依赖
- 集成关系：上下游系统、第三方服务、消息队列、定时任务、Webhook、鉴权和回写链路

如果仓库已有真实技术栈、数据库结构、系统边界或团队规范，宪章要优先引用它们，而不是写空泛口号。能从代码、表结构、接口定义、部署配置里确认的内容，尽量写成真实约束，不要写成理想化方案。

### 3. `/speckit.requirement`

先做需求分型，再产出 `requirement.md`。

`/speckit.requirement` 的核心目标不是“记录一份表面需求”，而是 **通过问题驱动的调研，把模糊表述逐步逼近为真实需求**。执行这一阶段时，要先思考这个需求可能涉及哪些问题，再围绕这些问题，按优先级依次向需求提出者提问，直到能较稳定地还原需求真相。

默认要先从下面这些问题域里检查有没有缺口，并据此补问：

- 业务目标：为什么要做、要解决什么问题、不做会怎样
- 用户与角色：谁在用、谁受益、谁发起、谁审批、谁维护
- 使用场景：在什么场景下发生、频率多高、入口在哪里、前后步骤是什么
- 流程与规则：主流程是什么、分支是什么、判断条件是什么、异常怎么处理
- 权限与范围：谁能看、谁能做、数据看多大范围、是否存在差异权限
- 数据与对象：会新增或改哪些业务对象、字段、状态、表、关联关系
- UI 与交互：涉及哪些页面、按钮、弹窗、表单、列表、详情、反馈和状态提示
- AI 能力（若有）：为什么必须用 AI、模型在哪个环节、怎么兜底、怎么评估
- 技术与集成：依赖哪些系统、接口、中间件、消息、任务、第三方服务
- 验收与边界：做到什么算完成、哪些不做、有哪些风险和待确认项

提问时不要一次性平铺罗列问题，而是应该：

1. 先找出当前信息里最可能导致误解、返工或方案失真的点
2. 优先追问会影响范围、流程、权限、数据、验收的关键问题
3. 根据回答继续追问，直到关键概念、边界条件、例外情况足够清晰
4. 把已经确认的内容、仍然模糊的点、需要用户拍板的选择明确区分

如果需求提出者不是产品经理、设计师或技术开发，而是直接业务方、运营方、销售方、客服方、审核方、实施方等非专业角色，提问要尽量使用 **业务语言**，不要默认对方理解产品和技术术语。优先从“现状”问起，例如：

- 你们现在这件事是怎么做的
- 现在是谁在处理、谁发起、谁审批、谁跟进
- 原本线下是如何工作的，线上哪些环节已经有，哪些还没有
- 一次完整处理通常会经过哪几个步骤
- 哪一步最花时间、最容易出错、最依赖人工判断
- 如果遇到特殊情况，现在通常怎么处理
- 现在最麻烦、最容易被投诉、最容易返工的地方是什么

先把业务方讲出来的现有流程、角色分工、线下做法、异常处理和痛点整理清楚，再把这些内容翻译成产品需求、系统流程、权限规则和实现约束。

如果用户给的只是一个方向、口号或功能名，不要直接进入写文档；先把问题问透，再沉淀 `requirement.md`。

必须先判断两个维度：

- **需求类型**：传统需求，还是 AI 需求
- **演进方式**：`0 到 1`，还是 `1 到 N`

判断规则：

- **传统需求**：核心价值主要来自固定流程、规则编排、表单、审批、展示、查询、交易、配置等确定性能力
- **AI 需求**：核心价值明显依赖模型推理、生成、检索、分类、总结、对话、智能推荐、自动化决策辅助等能力
- **0 到 1**：当前业务流程、产品形态、页面结构基本还不存在，重点是定义首版闭环
- **1 到 N**：当前系统、页面、角色、流程或代码已存在，重点是增量优化、扩展、重构、提效或 AI 化改造

在需求调研阶段，必须主动补问 **权限相关问题**。如果用户没有主动说明，就要至少确认：

- 有哪些角色、用户类型或组织层级
- 不同角色分别能看什么、做什么、不能做什么
- 数据范围是“全部可见”还是“按组织 / 区域 / 个人 / 业务线隔离”
- 哪些页面、字段、按钮、操作、审批节点需要权限控制
- 是否存在仅查看、仅编辑、仅提交、仅审批、仅导出、仅配置等差异权限
- 是否有超管、管理员、运营、审核人、普通用户、外部协作方等特殊角色
- 权限是沿用现有系统，还是本次要新增 / 调整
- 权限边界不清时，是否先按最小权限原则设计并列入待确认项

如果当前阶段拿不到完整权限信息，不要跳过，至少要把“已知角色”“待确认权限点”“可能影响范围”写进 `requirement.md`。

如果是 `1 到 N`，`requirement.md` 中必须增加 **现有流程分析**，而且优先基于真实代码完成，不只依赖口述或旧文档。

现有流程分析的优先级：

1. 先读代码中的真实用户操作链路
2. 再参考已有文档、原型、设计稿、埋点、测试用例
3. 最后再用用户口述补齐代码里看不到的业务规则

读取代码时，要尽量还原用户操作逻辑，例如：

- 页面入口和路由跳转
- 角色权限与可见范围
- 表单录入、按钮点击、弹窗确认
- 列表筛选、详情查看、提交审批、状态流转
- 前端状态管理、接口调用顺序、异常处理
- 后端服务编排、校验规则、异步任务、通知回写

如果仓库里能读到这些逻辑，就把它整理成：

- 当前用户旅程
- 现有流程步骤
- 每一步的输入、输出、参与角色、系统反馈
- 现有痛点、重复劳动、断点、等待点、人工判断点
- 本次需求要改动的环节和影响范围

产出 `requirement.md` 时，至少包含：

- 需求类型判断：传统需求 / AI 需求
- 演进方式判断：`0 到 1` / `1 到 N`
- 项目背景
- 目标用户
- 角色与权限概览
- 核心问题
- 目标与非目标
- 现有流程分析（仅 `1 到 N` 必填）
- 功能优先级
- 关键流程
- 非功能要求
- 风险与待确认项

对于 **AI 需求**，还要额外补充：

- 为什么必须用 AI，而不是普通规则或搜索就能解决
- 模型在流程中的位置：主流程、辅助流程，还是仅提效工具
- 输入上下文、输出格式、可接受误差、人工兜底方式
- 评估方式：准确率、召回率、成功率、耗时、人工节省量、用户满意度等

如果用户明确要竞品分析、行业调研、最新信息，且当前环境可联网，先补充外部调研再写入文档。不要把“最新”内容当成静态知识猜测。

### 4. `/speckit.reqdoc`

产出 `reqdoc.html`，把需求整理成可执行的产品方案。

这里的产物不是 Markdown，而是 **可直接在浏览器打开的 HTML 文档**。默认要求：

- 使用语义化 HTML 结构输出
- 尽量自包含，便于本地打开、评审、流转和继续补充
- 允许使用简洁内联样式或最小样式块，让结构清晰、层级明确、可读性稳定
- 如果用户明确要求“先给草稿”，可以先在对话中给出结构草稿，再落成 `reqdoc.html`
- 默认优先参照同目录下的 [reqdoc.template.html](./reqdoc.template.html) 生成，除非用户明确要求改结构或改视觉样式
- 输出时要明显突出“该需求研发需要优先查看、重点注意、容易漏掉、阻塞开发、影响联调和验收”的内容，而不是把所有信息写成平均密度的平铺说明

`reqdoc.html` 的内容结构固定为以下 8 个一级部分，顺序不要变：

1. `需求背景与目标`
2. `需求范围`
3. `需求详情`
4. `功能开发事项`
5. `验收标准`
6. `风险与处理策略`
7. `非功能需求`
8. `待确认问题`

各部分至少包含：

#### 1. 需求背景与目标

- 项目背景
- 业务目标
- 用户目标
- 本轮要解决的问题
- 不在本轮解决的问题（如有）

#### 2. 需求范围

必须包含两部分：

- `需求清单`
- `核心流程`

需求清单建议明确到：

- 需求名称
- 优先级
- 适用角色
- 关键用户旅程
- 是否属于本期必做

核心流程建议明确到：

- 优先使用 **纵向步骤流** 形式展示，默认采用深色大块承载步骤、每步之间用向下箭头串联
- 展示效果应接近“流程面板”，而不是普通列表或轻量示意图
- 如果确实需要，也可以用 Mermaid、HTML 流程块、箭头图或其他清晰的流程化表达，但默认优先使用模板中的纵向流程样式
- 不需要强行拆成“入口 / 关键步骤 / 用户动作 / 系统反馈 / 结束状态”这类固定字段
- 只要能让读者快速看清主流程、分支、判断条件、异常路径和结束结果即可
- 如果流程较复杂，可以在流程图下补少量文字说明关键节点、规则或异常分支

#### 3. 需求详情

这一部分必须 **按需求范围逐项展开**，并且要结合 UI 图一起说明。

优先规则：

- 如果用户提供了 `MasterGo` 交互图、页面图、截图、导出图或可读取链接，优先结合这些材料输出
- 如果当前环境不能直接读取 `MasterGo` 原稿，不要假装读过；要明确说明，并改用用户提供的截图、导出图、页面说明或 `ui.md`
- 如果已有 `ui.md`，要把 `ui.md` 中的页面结构、交互、状态说明一起合并进这一部分

每条需求详情至少说明：

- 对应需求项
- 适用角色与权限
- 触发入口
- 页面或视图
- 交互步骤
- 关键状态
- 业务规则
- 数据输入输出
- 异常或边界情况
- 对应 UI 图说明
- 开发必看
- 重点注意
- 风险提醒

**触发入口写法规范**：

必须明确区分主入口和辅助入口，禁止模糊表述（如"本期先做A，B作为P1"）。正确示例：

```
入口 1 — 批量同步（本期主入口）：列表顶部「xxx」按钮，支持多选后批量触发
入口 2 — 单条同步（辅助入口）：列表操作列「同步」按钮，方便快速单条触发
```

**UI 图占位规范**：

- 在文档中预留图片引用：`![描述](images/截图名称.png)`
- 截图文件名与需求章节对应，如：`images/知识类别配置-列表页.png`
- 建议创建 `images/README.md` 截图指引文件，列明每张截图的截取位置和保存文件名

**页面与视图写法规范**：

```
> 界面原型：参考 demo 文件查看。以下为关键界面说明：

**xxx 页面**：

![xxx-列表页](images/xxx-列表页.png)

- 页面标题：
- 操作按钮：
- 列表字段：
  | 字段 | 说明 |
  |------|------|
  | ... | ... |
```

**字段一致性要求**：

- 如果在需求详情中新增、拆分或修改了字段，必须同步检查并更新文档中**所有引用该字段的位置**
- 需要同步更新的位置包括：列表字段表、表单字段表、唯一性校验规则、业务规则、数据输入输出说明、交互步骤示例、后端接口说明、验收场景、风险描述、待确认问题
- 不允许在文档中出现同一字段前后描述不一致的情况

#### 4. 功能开发事项

从产品方案视角整理给研发的开发关注点，包含：

- 前端开发事项
- 后端开发事项
- AI 开发事项（若为AI需求）
- 接口或数据依赖
- 状态管理或流程编排事项
- 埋点、日志、消息、通知、权限等补充事项

#### 5. 验收标准

建议按需求项或流程节点列出，至少包含：

- 验收场景
- 验收标准
- 前置条件
- 操作步骤
- 期望结果
- 失败判定
- AI 评测集（若为AI需求）

#### 6. 风险与处理策略

至少包含：

- 需求理解风险
- 交互或流程风险
- 技术依赖风险
- 数据或接口风险
- 排期风险
- 对应处理策略

#### 7. 非功能需求

至少覆盖适用项：

- 性能
- 安全
- 稳定性
- 易用性
- 可维护性
- 兼容性
- 可观测性

#### 8. 待确认问题

要明确列出：

- 问题描述
- 影响范围
- 需要谁确认
- 不确认会带来的风险
- **确认结果**（必须包含此列）

**待确认问题的迭代规则**：

- 当问题得到答案后，必须在"确认结果"列标注 `**已确认：xxx**`
- 确认后，必须**同步更新需求详情中受影响的章节**（如确认"本期做批量同步"，需同步修改触发入口的描述、开发必看块、接口设计说明等）
- 确认结果不是装饰，是推动文档迭代的信号

如果 `ui.md` 已存在，更新 `reqdoc.html` 时要同步修正页面、交互、状态说明，避免两份文档打架。

生成 `reqdoc.html` 时，优先遵循以下落地方式：

1. 先以 `reqdoc.template.html` 为骨架
2. 再把当前项目的真实需求内容填进去
3. 如果用户提供了品牌样式、公司规范、截图、MasterGo、`ui.md`，在不打乱 8 个一级章节顺序的前提下补充页面结构、表格、卡片、图示说明
4. 如果需求较复杂，允许在一级章节下增加二级分组，但不要改动一级章节命名
5. 在 HTML 中优先增加以下高亮区域：
   - 开发重点速览
   - 开发必看
   - 重点注意
   - 阻塞依赖
   - 风险提醒
6. 高亮不是装饰，要承载真实信息，不能只写空话或重复正文

#### 文件命名规范

| 文档类型 | 命名格式 | 示例 |
|----------|----------|------|
| 需求方案 | `【需求文档】项目名-需求方案.md` | `【需求文档】麦宝知识后台-需求方案.md` |
| 交互原型 | `demo.html` | `demo.html`（一般放在项目根目录） |
| 流程图 | `【流程图】项目名-模块名.drawio` | `【流程图】麦宝知识后台-核心流程.drawio` |
| 截图 | `images/页面说明-视图名.png` | `images/知识类别配置-列表页.png` |

#### demo 原型规范

`reqdoc.html` 之外，鼓励同步产出 `demo.html` 作为可交互原型，用于直观展示界面和交互流程。

**设计规范来源**：

生成网页原型时，优先读取同目录下的 `DESIGN_RULES_BUNDLE.md` 作为视觉规范基础。

**结构与交互**：

- 自包含的单个 HTML 文件（内联 CSS + JS），无需外部依赖
- 每个页面展示完整界面布局：顶部操作栏、搜索/筛选区、数据表格、分页
- 支持弹窗（Modal）、抽屉（Drawer）等交互组件
- 按钮和链接可点击，有基本交互反馈（弹窗打开、页面切换、toast 提示）
- 弹窗内表单需覆盖全量字段，展示两列布局等真实排版

**数据与文案一致性**：

- 表格数据、表单字段、下拉选项与 `reqdoc.html` **严格一致**
- 统计图表数据使用合理的示例数据，**百分比必须同时标注具体数量**（如：质量 46%（12个））
- 提示文案、确认框文案与需求文档一致
- 不使用 Lorem ipsum 等占位文本，用真实场景数据

**与 reqdoc.html 联动**：

- 当需求发生变更（新增字段、调整交互入口、修改数据展示方式）时，**同步更新 demo 原型**
- 当需求方案中预留了界面截图占位时，按占位要求从原型中截取对应界面保存到 `images/` 目录
- 在 `reqdoc.html` 的"页面与视图"小节标注"参考 demo 原型 → 某菜单/按钮查看"

#### 推荐落地方式

1. 先以 `reqdoc.template.html` 为骨架产出 `reqdoc.html` 结构化正文
2. 同步生成 `demo.html` 可交互原型，引入 `DESIGN_RULES_BUNDLE.md` 视觉规范
3. 把当前项目的真实需求内容填进去，用真实数据而非占位符
4. 如果用户提供了品牌样式、公司规范、截图、MasterGo、`ui.md`，在不打乱 8 个一级章节顺序的前提下补充
5. 如果需求较复杂，允许在一级章节下增加二级分组，但不要改动一级章节名称
6. 在文档中优先增加以下高亮区域：开发重点速览、开发必看、重点注意、阻塞依赖、风险提醒
7. 高亮不是装饰，要承载真实信息，不能只写空话或重复正文
8. 同步创建 `images/` 目录和截图指引文件
9. 如果流程复杂，同步创建 `.drawio` 流程图文件，避免用 ASCII 流程图
10. 数据描述务必具体：百分比标注绝对数量、时间标注到年-月-日 时:分、接口超时标注具体秒数

#### 迭代与修改规则

1. **先改 `reqdoc.html`**，再同步 demo 原型
2. **修改字段时做全局一致性检查**：确认所有引用该字段的位置已同步更新
3. **确认问题后联动更新**：待确认问题获答复后，在确认结果列记录，并同步修改受影响章节
4. **版本号递增**：每次正式修改后更新版本号和日期
5. **截图同步**：界面变更后，重新截取原型中的界面替换旧图

### 5. `/speckit.ui`

`/speckit.ui` 默认按一条 **视觉优先的设计主线** 推进：

1. **先整理页面骨架与轻量版 `ui.md` 设计底稿**
2. **先用 `imagegen` 产出高保真方向图给用户确认**
3. **确认后，补全 `ui.md`，同步拆分素材切图，再生成可点击交互的 HTML 网页效果稿**

这里的“阶段”更像默认设计策略，不是死板的流程开关。只要最终满足这些目标，就允许在相邻阶段之间来回微调：

- 视觉方向已经成立，而不是只剩结构正确
- 设计规范边界没有跑偏
- HTML 尽量按效果图 `1:1` 还原，而不是重新退回线框味

`/speckit.ui` 默认支持两种工作模式：

1. **视觉优先模式（主路径）**
2. **规范方案模式（复核路径）**

模式选择规则：

- **默认先走视觉优先模式**。除非用户明确要求“这次只做结构方案 / 只做规范稿 / 先不要做高保真探索”，否则都先按更像设计师工作的路径出视觉方向。
- 如果用户明确说“想要更漂亮”“先出高保真视觉方向”“先看图”“当前稿子像线框图”“先做图片再反推代码”，直接进入 **视觉优先模式**
- 如果用户没有明确说明，但当前页面属于首页、工作台、核心列表页、关键结果页、品牌感较强页面，也默认进入 **视觉优先模式**
- **规范方案模式** 不再作为默认主路径，而是用来做这些事：复核业务结构是否成立、复核规范是否被遵守、复核组件是否与现有系统一致、复核交互与实现是否可落地
- 如果视觉优先模式已经产出方向图或高保真稿，规范方案模式的职责是回头做收边界、补说明、校准实现，而不是把视觉重新拉回线框稿

`ui.md` 仍然是结构化设计产物，用于表达可实现的界面方案，而不是一开始就直接依赖某个外部设计平台。

但如果当前走的是 **视觉优先模式**，第一轮给用户看的外显产物默认应是 **`imagegen` 生成的高保真方向图**；`ui.md` 可以先保留为轻量版设计底稿，等方向图确认后再补全为完整方案。

完整版 `ui.md` 至少包含：

- 设计推导结论
- 设计目标
- 适用端：移动端 / PC 端 / 双端
- 灵感检索结论
- 参考图分析结论
- 公司规范约束摘要
- 布局策略
- 风格策略
- 颜色策略
- 信息架构
- 页面层级
- 关键页面结构
- 核心组件
- 交互说明
- 状态说明
- 文案基调
- 视觉方向
- 响应式要求
- 与现有代码或现有流程的对应关系

`/speckit.ui` 现在是 **自包含的 UI/UE 设计阶段**。执行这一阶段时，不再依赖其他 skill 的隐式继承，而是直接在本阶段完成：

- 需求反推页面布局与风格
- 灵感检索与经典页面参考
- 参考图审美分析与设计迁移
- 公司设计规范约束合并
- `ui.md` 产出与确认
- 效果图中的控件拆分与切图整理
- 确认后的 HTML 交互网页输出

`/speckit.ui` 默认优先读取这份 **内置设计规范包**：

- [DESIGN_RULES_BUNDLE.md](/Users/fallin/.codex/skills/speckit/DESIGN_RULES_BUNDLE.md)

这份包已经统一吸收并维护了原先分散的 PC 端规范、雪花移动端规范解读和移动端规范来源。执行阶段默认先吃这份包，不再把三份资料当作运行时外部依赖逐个理解。

执行 UI 方案前，先按更接近真实设计师的顺序工作：

1. **先主动询问用户有没有参考图、参考页面、竞品截图、历史设计稿或喜欢的风格示例**
2. 如果用户给了参考图，先读参考图，再提炼可迁移的风格、布局、颜色、组件语言和细节处理
3. 如果用户暂时没有参考图，再读需求，提炼页面目标、用户类型、核心任务、关键动作和风格倾向
4. 再梳理页面骨架，确定首屏结构、阅读路径、固定区与滚动区
5. 再确定颜色策略，明确主题色、辅助色、强调色、中性色、状态色如何分工
6. 再检查现有项目组件、样式变量和历史页面，尽量保持一致性
7. 如果用户没给够参考，再补做灵感检索和经典页面分析
8. 最后再细化页面稿，而不是一开始就直接拼组件

如果这个顺序没有走完，不要太快进入高保真细化。

也就是说，**画 UI 前默认先问参考图**；只有用户明确说没有、暂时不给，或者现有参考不足以支撑设计方向时，才进入自找参考和灵感检索。

默认把 `/speckit.ui` 拆成下面这几个阶段思考和推进，而不是一次性把整套页面同时画完：

1. **视觉探索阶段**
2. **重点页面高保真阶段**
3. **视觉确认阶段**
4. **素材拆分与切图阶段**
5. **整套页面扩展阶段**
6. **HTML 交互网页阶段**

这些阶段有默认顺序，但不要求机械串行。允许在视觉确认、素材拆分、HTML 还原之间反复迭代，直到视觉完成度和还原度都过关。

两种模式的默认路径如下：

- **视觉优先模式（主路径）**：需求拆解 -> 页面骨架 -> `imagegen` 生成 `2~3` 版高保真方向图 -> 选方向 -> refinement -> 回写 `ui.md` -> 按照规范约束，`imagegen` 生成所有高保真效果图，并同步规划关键素材 -> 用户确认 -> 素材拆分与切图 -> HTML 生成交互网页
- **规范方案模式（复核路径）**：在视觉方向已经比较清楚后，对 `ui.md` / 高保真稿 / HTML 效果稿进行结构、规范、组件一致性、可实现性复核，并补齐约束说明

视觉优先模式不是跳过结构和规范，而是先用图片把审美方向拉起来，再按需求、规范详细设计；规范方案模式则负责在这个基础上做收口，而不是抢主线。

执行 `/speckit.ui` 时，要根据项目阶段选择不同的设计路径：

- 如果是 **`0 到 1` 项目**，先做“参考图审美分析与设计迁移”：分析参考图的风格、色彩、布局、组件语言和交互节奏，再结合公司设计规范完成 UI 方案。
- 如果是 **`1 到 N` 需求**，先分析原有 UI / 前端界面的审美、布局、组件语言、交互节奏和可迁移部分，再结合本次需求目标与公司设计规范完成 UI 方案。

也就是说：

- `0 到 1`：**先看参考图怎么迁移，再按规范设计**
- `1 到 N`：**先看现有界面怎么迁移，再按规范设计**

不要跳过“审美分析与设计迁移”这一步，直接只按规范堆页面；规范负责收敛边界，迁移分析负责保证方案有来源、有延续性、有业务场景匹配度。

不管有没有参考图，真正开始设计前，都要先从需求反推页面该长什么样。至少明确：

- 页面类型：工作台、列表页、表单页、详情页、分析页、弹层、结果页、流程页
- 首屏任务：首屏是看状态、做决策、填信息、查结果，还是快速操作
- 阅读路径：用户先看哪里，再看哪里，最后在哪里做动作
- 信息密度：这页适合紧凑高效，还是舒展清晰
- 风格强度：这页更需要稳重、专业、克制，还是允许更强一点的品牌表达

然后据此决定：

- 是否需要强主视觉区，还是应该把重点放在工具区和内容区
- 是否需要分栏、分组、卡片化、吸顶、底部固定操作区
- 颜色是以中性色为主、品牌色点亮，还是允许更明显的色块承载重点
- 哪些地方必须“稳”，哪些地方可以有一点设计巧思

如果用户没有给参考图、给得不够，或者当前需求仍然需要补充设计灵感，要主动说明“现在将补做一轮参考检索”，而不是闭门造车。如果当前环境可以联网，优先从这些站点寻找参考：

- `Pinterest`：适合找风格、色彩、版式、插画、情绪氛围
- `Mobbin`：适合找真实产品界面、移动端流程、成熟组件用法
- `Dribbble` / `Behance`：适合看视觉表达、品牌感、概念方向和细节处理

检索时不要泛搜“大屏设计”“高级感 UI”，尽量带上真实功能语义，例如：

- `行业词 + 页面类型 + 关键功能 + 端类型`
- `审批 / 列表 / 工作台 / 详情 / 搜索 / 表单 / 推荐 / 报表 + mobile / app / dashboard / admin`
- `品牌感 / 科技感 / 业务系统 / 运营工具 / 消费体验`

检索后至少完成这些动作：

1. 选出 `3 ~ 5` 个最接近当前需求的参考
2. 判断哪些是真正功能相似，哪些只是视觉好看但不适用
3. 分析这些参考的色彩搭配、页面骨架、分区逻辑、插画或图形是否必要、图标语言、重点信息强化方式、哪些细节让页面更有品质感
4. 沉淀成“可迁移策略”，而不是原样照抄

如果当前环境不能联网，就明确说明，并优先使用：

- 用户提供的参考图
- 仓库里的历史页面
- 本地设计规范
- 已有设计稿截图或导出图

如果当前任务已经明显进入 **视觉优先模式**，并且目标是“先把 UI 图做漂亮”，允许直接接入 [imagegen](/Users/fallin/.codex/skills/.system/imagegen/SKILL.md) 生成高保真视觉方向图。

接入 `imagegen` 时，默认规则是：

1. 先完成页面骨架、首屏重心、颜色策略和页面类型判断
2. 先把内置设计规范里的关键约束吃进去，再把这些信息整理成高保真图片生成提示词
3. 一次先生成 `2 ~ 3` 个不同但相近的视觉方向，不要只出一版
4. 先选方向，再做 refinement，不要第一版就直接当最终稿

也就是说，高保真效果图不是“先自由发挥画一版，再回头拿规范修补”，而是**在生成第一轮图片时就要把端类型、设计规范、信息密度、组件风格和颜色边界一起考虑进去**。

这里的“`2 ~ 3` 个方向”，默认指 **`2 ~ 3` 张不同风格的单页面高保真图**，不是把 `5` 个页面拼成一张总览板，也不是做带标题编号的方案展示图。

视觉优先模式下，`imagegen` 的第一轮默认目标是：

- **先画 1 个重点页面的成品级高保真 UI mockup**
- 不是多页面拼贴
- 不是流程总览图
- 不是白底汇报板
- 不是线框图上色版
- 不是在大画布上摆一排手机界面

如果用户没有明确要求“一次看多页流程”，第一轮禁止输出：

- `M01 / M02 / M03` 这种页面编号标题
- 一张图里摆很多手机屏
- 白色或浅灰大底板上的方案拼贴
- 带大量说明性标签的演示板
- 过于稀疏、占位块明显、像原型图的页面

第一轮更推荐的构图是：

- 单个重点页面
- 接近真实产品截图或设计稿截图的视角
- 页面内容完整、信息密度真实
- 组件细节完整
- 视觉重心明确
- 像“已经做完的设计稿”，而不是“设计过程说明图”

第一轮 `imagegen` 的输出方式默认是：

- **先直接把生成图片给用户确认**
- 第一轮默认不进入 Figma
- 不要在用户还没确认视觉方向时抢先生成整套网页或同步设计稿
- 可以同步整理这张图对应的页面骨架、颜色策略、组件气质和 refinement 观察，但“看图确认”优先级更高

只有在用户明确说“按这版继续”“这版可以推进”“按这个方向生成网页”之后，才进入 HTML 交互网页阶段。

在高保真效果图逐步确认的同时，要同步规划一轮 **素材拆分与切图**，而不只是等到最后才被动补切图。

在进入 HTML 阶段之前，默认先执行一轮 **素材拆分与切图**：

- 从最终确认的高保真效果图中，拆出关键控件、可复用视觉块和需要高保真还原的图形元素
- 这些切图统一放到当前版本目录下的 `ui-assets/` 文件夹
- 默认同时生成一个 `ui-assets/manifest.md`，记录每个切图的名称、来源页面、用途和建议还原方式
- 如果页面里有明显影响视觉气质的插画、icon、渐变组件、装饰图形、品牌波纹、光晕、纹理块，默认也要单独拆出来，供 HTML 阶段直接调用

默认优先拆分这些对象：

- 按钮：主按钮、次按钮、描边按钮、危险按钮、禁用态按钮
- 导航块：顶部栏、底部栏、标签切换、分段控件
- 卡片块：数据卡、任务卡、结果卡、提示卡
- 标签与徽标：状态标签、角标、评分标签、提示条
- 输入与筛选：搜索框、输入框、下拉、筛选条
- 图标：业务 icon、功能 icon、状态 icon、品牌风格 icon
- 插画：首屏插画、空态插画、弱插画、场景图形
- 渐变组件：渐变卡片、渐变背景片、光感高亮块、带纹理或特殊质感的色块
- 装饰图形：品牌波纹、光晕、背景形状、特殊分隔图形、气泡或光效元素

不必机械把整页每一块都切出来，而是优先切那些会影响 HTML `1:1` 还原、且短期内不适合只靠 CSS 复刻的视觉单元。重点不是“切得多”，而是**让 HTML 不丢掉效果图里的设计美学**。

命名建议：

- `screen-home-card-training.png`
- `button-primary-large-default.png`
- `tag-warning-score-low.png`
- `nav-mobile-top-default.png`
- `illustration-empty-state-training.png`
- `icon-score-warning.svg`
- `gradient-card-hero-blue.png`
- `shape-brand-wave-header.png`

如果切图背景需要透明，优先导出透明底；如果是整块位图质感区，也可以保留带背景切图。默认建议：

- 简单 icon：优先 `SVG`
- 复杂 icon、插画、渐变位图、纹理块：优先 `PNG` 或 `WebP`
- 需要透明背景的素材：优先透明底导出

`imagegen` 更适合先解决这些问题：

- 页面是否足够有视觉重心
- 配色是否有张力
- 卡片、按钮、标签、图标、弱插画是否有质感
- 页面整体气质是否已经像成品设计稿

但 `imagegen` 不能直接替代结构化设计判断，所以不要把第一张生成图直接当最终交付物。

为了避免生成结果再次落回“线框味”，提示词里默认主动加入这些反向约束：

- `high-fidelity polished product UI`
- `real app screenshot aesthetic`
- `finished visual design, not wireframe`
- `single key screen, not storyboard`
- `no presentation board, no annotations, no page labels`
- `dense but clean information hierarchy`
- `refined cards, typography, iconography, and spacing`

同时避免使用会把图带偏的表达，例如：

- `overview`
- `multi-screen`
- `flow board`
- `wireframe`
- `layout sheet`
- `presentation`
- `case study board`

完成灵感检索后，先沉淀一份 **视觉探索包**，至少包括：

- `moodboard`：这轮设计准备借鉴的整体气质与参考方向
- `layout board`：页面骨架、分区方式、阅读路径、主次关系
- `color board`：主题色、辅助色、强调色、中性色、状态色的搭配方式
- `component tone board`：按钮、卡片、表单、标签、列表、弹层等组件的气质方向
- `do / don't`：哪些设计处理值得借鉴，哪些不能照搬

如果这份视觉探索包还不能让人感受到明确的风格方向，不要继续往下扩页面。

如果当前走的是 **视觉优先模式**，视觉探索包之后，默认还要追加一份 **图片探索结果**，至少记录：

- 使用了哪一版图片提示词
- 生成了哪几版方向图
- 最终保留的是哪一版
- 保留理由是什么
- 哪些地方还需要继续 refinement

在遵守规范和业务目标的前提下，页面还要满足基础美观度要求。默认主动优化：

- 层次：不要所有模块权重一样，要有清晰的主次、强弱、远近
- 节奏：区块之间要有呼吸感，间距和留白要有节奏
- 重心：首屏要有视觉重心，不要页面每个角落都在抢注意力
- 配色：颜色要有克制和重点，不要整页只会铺一个品牌色
- 组件质感：按钮、标签、表单、卡片、表格、筛选区的圆角、描边、底色、阴影要统一
- 细节：图标、数字、标签、空态、提示语、状态反馈要细腻

允许适度加入“小巧思”，但要满足三个前提：

1. 不影响业务效率
2. 不破坏公司规范和现有系统一致性
3. 不是为了装饰而装饰

可以加入的小巧思例如：

- 更自然的标题与摘要组合
- 更轻巧的分区背景或弱层级底色
- 更有记忆点的重点数据强调方式
- 更细腻的空态、结果态、完成态表达
- 更克制但更舒服的操作反馈和状态切换

不要把“小巧思”理解成堆渐变、堆装饰、堆阴影、堆卡片。

### 5.1 重点页面高保真优先

不要一开始就把所有页面一起铺开。默认先选 `1 ~ 2` 个最关键页面做高保真优先设计，例如：

- 首页 / 工作台
- 核心列表页
- 关键表单页
- 关键详情页
- 关键结果页或分析页

先把这 `1 ~ 2` 个页面做到足够有视觉完成度，再决定是否扩整套页面。

这一步至少要明确：

- 哪个页面最能代表整套设计方向
- 哪个页面最能暴露布局、配色、组件气质和品牌表达问题
- 哪个页面最需要先打磨，才能避免后续整套页面一起平掉

如果重点页面看起来仍然像线框图、组件拼装稿或只有结构没有审美，不要扩整套页面，继续 refinement。

如果当前走的是 **视觉优先模式**，这一阶段优先通过 `imagegen` 完成：

- 先出重点页面高保真图
- 先直接展示给用户确认视觉方向
- 再根据选中的图片方向反推组件气质、颜色策略、层级节奏和小巧思
- 然后把这些结论写回 `ui.md`

默认先从 **单个关键页面** 开始，例如工作台首页、核心列表页、关键表单页、关键结果页；不要一开始就生成整套流程页拼图。只有当单页已经足够漂亮、方向稳定后，才允许继续补第二张、第三张页面。

不要反过来先把代码结构铺满，再试图补救视觉。

### 5.2 视觉 refinement 要求

默认至少做 `2` 轮视觉 refinement，再把页面视为“可评审的设计稿”。

每一轮 refinement 至少检查并优化：

- 首屏重心是否足够明确
- 主次层级是否已经拉开
- 配色是否有重点、有节奏，而不是单一品牌色平铺
- 模块之间是否有足够呼吸感
- 组件的描边、底色、圆角、阴影、图标是否统一
- 是否已经出现至少 `1 ~ 2` 处自然的小巧思，而不是纯规范拼装
- 页面是否已经看起来像“成品设计稿”，而不是“产品线框草图”
- 页面是否还残留“汇报板 / 拼贴板 / 多屏总览图”的气质；如果有，继续收敛成单页成品级设计图

如果答案是否，就继续 refinement，不要急着宣称 UI 完成。

### 5.3 扩整套页面的前提

只有在下面条件成立时，才扩展整套页面：

1. 重点页面的视觉方向已经稳定
2. 颜色策略已经明确
3. 组件气质已经明确
4. 用户认可这版视觉方向，或明确表示“按这版继续扩”

在此之前，优先打磨代表页面，不要平均铺开所有页面。

### 5.4 素材拆分与切图阶段

当重点页面方向已经确认，且准备进入 HTML 交互网页阶段时，先执行素材拆分与切图。

这一阶段的目标不是为了沉淀一套完整设计系统，而是为了让后续 HTML 尽量 **按效果图 1:1 还原**，避免在实现阶段把已经确认的视觉稿重新翻译回“线框味”。

重点不是只拆“控件”，而是把那些会直接影响页面气质的视觉素材一起拆出来，包括：

- 控件位图或复杂视觉块
- icon
- 插画
- 渐变组件
- 装饰图形
- 光晕、波纹、纹理、背景图形等特殊元素

切图输出默认放在：

- `.spec/<current-version>/ui-assets/`

推荐按页面或模块分子目录，例如：

- `.spec/v1/ui-assets/home/`
- `.spec/v1/ui-assets/dialog/`
- `.spec/v1/ui-assets/result/`

`ui-assets/manifest.md` 至少记录：

- 切图文件名
- 来源页面
- 所属类型：控件 / icon / 插画 / 渐变组件 / 装饰图形
- 在 HTML 中建议作为背景图 / 前景图 / 独立图片 / 遮罩素材 / 内联 SVG 使用
- 是否允许后续替换为纯 CSS / SVG 实现

执行时遵循这些原则：

- 优先切那些明显影响视觉气质、且 CSS 很难短时间高质量复刻的元素
- 对于可以稳定用 CSS / SVG 复刻的简单块，不要为了切图而切图
- 切图与 HTML 还原之间要一一对应，避免生成一堆没人用的素材
- 如果最终高保真图里存在关键插画、关键 icon、关键渐变组件或装饰图形，HTML 阶段默认必须有对应素材或明确替代策略，不能直接省掉

如果当前任务是 **移动端 UI**，默认按 `375 × 812` 的设计尺寸输出方案。没有额外说明时，`ui.md`、第一轮方向图和后续 HTML 效果页中的移动端页面结构、关键区块尺寸、弹层、底部操作区和页面示意，都应以这个基准尺寸来表达，并考虑安全区、底部手势区和滚动区。

如果用户明确要求适配其他尺寸、特定机型、横屏、平板或多端自适应，可以在 `375 × 812` 基准上再补充适配规则；但默认主稿尺寸仍按 `375 × 812`。

如果当前任务是 **PC 端 UI**，默认先遵循 `speckit` 内置设计规范包里的桌面端规范，优先考虑：

- 页面栅格、内容宽度和信息密度
- 工作台、列表、筛选、详情、弹层等桌面端典型结构
- 组件层级、按钮尺寸、表格可读性、导航与操作区关系
- 浏览器视口下的首屏重心与关键操作可达性

如果用户还没有确认 `ui.md` 或第一轮方向图，不要抢先声称“网页已经完成”或直接进入 HTML 落地。默认应先把页面结构、交互、状态、视觉方向、颜色策略和组件方案在 `ui.md` 中讲清楚，等用户看过方向图并确认后，再进行 HTML 交互网页输出。

`ui.md` 中除了写结构和策略，还要显式写出：

- 当前这版是否已经完成视觉探索
- 当前重点页面是哪几个
- 当前采用了哪些参考图策略
- 如果走视觉优先模式，当前采用了哪一版图片探索结果
- 当前页面最重要的视觉记忆点是什么
- 当前还需要继续 refinement 的地方是什么

如果当前 UI 方案属于 PC 管理后台、桌面端工作台、数据平台、运营系统、审批系统、B 端业务系统、CRM 或管理控制台等场景，默认把 `speckit` 内置设计规范包中的 PC 端规则作为第一设计规范来源；只有在项目现有组件库和明确业务约束要求下，才允许在不破坏整体规范的前提下做局部偏移。

如果页面方案中需要使用图标，按以下图标选型规则执行：

- 默认先到以下三个网站查找与整体视觉风格一致的图标：`Iconify`、`SVG Repo`、`Flaticon`
- 先判断当前页面的图标风格需求：线性、面性、双色、圆角、商务、轻量、工具化、品牌化等
- 优先选择与当前页面字体、圆角、线条粗细、信息密度一致的图标，不要混用明显不同体系
- 如果已有设计系统或公司规范对图标有约束，先遵守规范，再去上述网站中寻找相近素材
- 找到合适图标后，优先下载 `SVG` 等可编辑、可复用格式，再用于 UI 方案、设计稿拼装或高保真原型输出
- 如果三个网站都没有足够匹配的图标，要说明原因，并基于最接近的风格给出替代方案
- 如果图标进入商业项目或对外发布物料，必须注意对应网站和单个素材的授权范围

如果图标对页面视觉风格影响较大，`ui.md` 中最好额外写明：

- 图标风格来源
- 选择理由
- 是否需要后续统一描边、尺寸、留白或填充方式

允许使用以下输入：

- 用户上传的截图、线框图、设计稿导出图
- 仓库里已有页面
- 现有设计系统

如果后续要真正落地前端：

- 先让 `ui.md` 与 `reqdoc.html` 保持一致
- 生成 Vue 代码前读取 [基于vue3前端开发规范.md](./基于vue3前端开发规范.md)
- 如果有本地可运行前端，改完后用浏览器能力验证关键页面

用户确认视觉方向后，默认进入 **HTML 交互网页阶段**，至少满足：

- 第一轮 `imagegen` 图片已经先给用户看过，并且用户已明确认可该视觉方向
- `ui.md` 已被用户认可，或用户明确表示“按这版继续出网页”
- 素材拆分与切图已经完成，或者已经明确说明本页哪些元素不需要切图、可直接用 CSS / SVG 复刻
- 输出的是 **可直接在浏览器打开的 HTML 网页效果稿**，而不是纯静态截图
- 页面至少包含关键点击反馈、分段切换、弹层 / 抽屉 / 标签切换 / 按钮态等基础交互中的一部分，避免只是不可点的摆拍页
- 如果是移动端效果页，默认按 `375 × 812` 视口组织布局，并考虑安全区、滚动区、底部固定操作区
- 如果是 PC 端效果页，默认按桌面浏览器视口组织布局，并遵循桌面端规范、信息密度和关键操作层级
- HTML、CSS、JS 的实现要尽量贴近最终产品体验，不要为了快而退回线框式 demo
- 优先复用 `ui-assets/` 中已经拆出的控件切图、插画、icon、渐变组件和装饰图形，按效果图做视觉还原
- 如果效果图中存在关键视觉元素，HTML 阶段不能无声省略；要么直接调用素材，要么明确写出替代实现方式
- 产出后用浏览器验证关键页面，检查桌面端 / 移动端的视觉完成度与点击交互是否成立

如果用户后续要求从视觉稿进一步落成正式前端实现，并且当前 UI 是通过视觉优先模式得到的，先按下面顺序处理：

1. 先从最终选中的高保真图中提炼页面骨架、色彩 token、组件气质和关键状态
2. 再把这些内容结构化回 `ui.md`
3. 同步整理 `ui-assets/`，确保关键插画、icon、渐变组件和图形素材已经可用
4. 先生成 HTML 交互效果页并验证
5. 最后再按项目技术栈生成正式前端代码

不要直接把第一版图片机械翻译成代码，否则很容易把“好看”重新翻译回“线框味”。

### 6. `/speckit.specify`

产出 `specification.md`，把产品方案变成功能规范。至少包含：

- 功能清单
- 每个功能的输入/输出
- 业务规则
- 状态迁移
- 边界情况
- 错误处理
- 数据契约
- API 或事件约束
- 验收标准

这是面向实现和测试的规格，不要写成 PRD 的重复版本。

### 7. `/speckit.plan`

产出 `plan.md`，把规范变成技术落地方案。至少包含：

- 现状分析
- 目标架构
- 模块拆分
- 数据模型
- 接口设计
- 状态管理策略
- 依赖与约束
- 风险点
- 测试策略
- 发布或迁移方案

如果仓库已存在代码，先读代码再写方案，说明哪些是复用、扩展、替换。

### 8. `/speckit.tasks`

产出 `tasks.md`，把 `plan.md` 拆成可执行任务。要求：

- 任务按依赖顺序排列
- 每个任务有明确输出
- 每个任务有验证方式
- 区分实现、测试、文档、联调任务
- 标明可并行项和阻塞项

任务粒度要能直接进入编码，而不是停留在“完善模块”“优化体验”这种空层级。

### 9. `/speckit.implement`

Codex 需要：

1. 先读取 `tasks.md`、`plan.md`、`specification.md`
2. 检查仓库现状和未提交改动
3. 按现有代码风格实现，不做无关重构
4. 必要时同步更新相关 `.spec` 文档
5. 运行测试、构建、静态检查，或至少执行最接近的验证步骤
6. 如果涉及前端可视改动，尽量做本地页面验证

输出时优先说清：

- 做了什么
- 哪些任务完成了
- 怎么验证的
- 还剩什么风险

### 10. `/speckit.version`

读取 `.spec/manifest.json`、当前版本目录和 `changelog.md`，汇总：

- 当前版本号
- 已有产物
- 每份文档最后更新时间
- 版本状态
- 最近一次迭代摘要

如果 `.spec/` 不存在，就说明还没初始化版本体系。

### 11. `/speckit.iterate`

在已有版本基础上开启新版本：

1. 找到当前最高版本号
2. 复制上一版本的基线文档到新版本目录
3. 更新根 `manifest.json`
4. 为新版本创建 `manifest.json`
5. 在 `changelog.md` 追加一条迭代记录
6. 记录本轮迭代目标与变更范围

如果用户只是在当前版本上微调，不要擅自升级版本号。

## 初始化与保存规则

首次使用且 `.spec/` 不存在时，初始化：

- `.spec/manifest.json`
- `.spec/changelog.md`
- `.spec/v1/`

建议根 `manifest.json` 使用这种最小结构：

```json
{
  "current_version": "v1",
  "versions": [
    {
      "version": "v1",
      "status": "draft"
    }
  ]
}
```

版本目录内的 `manifest.json` 可使用这种最小结构：

```json
{
  "version": "v1",
  "status": "draft",
  "artifacts": {
    "requirement": "requirement.md",
    "constitution": "constitution.md",
    "reqdoc": "reqdoc.html",
    "ui": "ui.md",
    "specification": "specification.md",
    "plan": "plan.md",
    "tasks": "tasks.md"
  }
}
```

如果用户要求“先看看草稿”，可以先在对话里给出内容，再等用户确认后落盘。

## 同步规则

当以下情况发生时，Codex 要主动同步相关文档：

- `reqdoc.html` 改了页面范围、角色、流程：同步更新 `ui.md`
- `ui.md` 改了交互、页面结构、组件状态：同步更新 `reqdoc.html`
- `specification.md` 改了功能边界：同步更新 `tasks.md` 和必要的 `plan.md`
- 实现与文档不一致：优先修正文档，除非文档明显过时

**迭代同步规则**：

需求文档迭代时遵循以下规则：

1. **先改 `reqdoc.html`**，再同步 demo 原型和其他关联文档
2. **修改字段时做全局一致性检查**：确认所有引用该字段的位置已同步更新（列表字段表、表单字段表、业务规则、验收场景、风险描述、待确认问题等）
3. **确认问题后联动更新**：待确认问题获答复后，在确认结果列记录 `**已确认：xxx**`，并同步修改受影响章节
4. **版本号递增**：每次正式修改后更新版本号和日期
5. **截图同步**：界面变更后，重新截取原型中的界面替换 `images/` 中的旧图
6. **多文档联动**：如果 `ui.md` 已存在，更新 `reqdoc.html` / demo 原型时要同步修正页面、交互、状态说明，避免几份文档内容冲突

## 前端实现补充

如果任务落到 Vue 前端：

1. 先读取 [基于vue3前端开发规范.md](./基于vue3前端开发规范.md)
2. 再检查仓库真实技术栈和目录结构
3. 优先复用已有组件、状态管理、路由模式
4. 改完后验证桌面端和移动端关键视图

如果仓库不是 Vue 项目，就把该规范视为参考而不是强制覆盖现有栈。

## 不要做的事

- 不要声称已经调用了不存在的 CodeBuddy agent、MasterGo、私有 MCP
- 不要把 UI 设计写成空泛的视觉形容词堆砌
- 不要在没有阅读代码的前提下写技术方案
- 不要在没有验证的情况下宣称实现完成
- 不要为了走全流程而强迫用户补所有文档

## 默认执行心法

在 Codex 里，Speckit 不是“把流程走完才开始干活”，而是：

- 用文档把需求和实现绑紧
- 用版本目录保留阶段性产物
- 用任务拆解直接推动编码
- 在需要时跳步，在关键处补文档

优先让流程服务交付，而不是让交付迁就流程。