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，并严格遵循其中约定。
6. 如果仓库已有实现，优先贴合现有代码结构、设计系统和测试方式，不要强行套模板。

目录约定

使用以下结构：

.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.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. 高亮不是装饰，要承载真实信息，不能只写空话或重复正文

文件命名规范

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

这份包已经统一吸收并维护了原先分散的 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 生成高保真视觉方向图。

接入 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
• 如果有本地可运行前端，改完后用浏览器能力验证关键页面

用户确认视觉方向后，默认进入 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 使用这种最小结构：

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

版本目录内的 manifest.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
2. 再检查仓库真实技术栈和目录结构
3. 优先复用已有组件、状态管理、路由模式
4. 改完后验证桌面端和移动端关键视图

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

不要做的事

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

默认执行心法

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

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

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