# codex-workflow

**Repository Path**: bruceleelg/codex-workflow

## Basic Information

- **Project Name**: codex-workflow
- **Description**: codex工作流
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-04-28
- **Last Updated**: 2026-05-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Codex Workflow

Codex Workflow（曾用名：OpenSpec）是一套可以复制到任意软件项目里的 AI 协作开发流程包。它把需求分析、原型设计、规格说明、架构决策、实施计划、开发实现、验证和归档串成一条稳定流程，适合在 Codex 或其他支持项目规则的 AI Agent 环境中使用。

最简单的使用方式：

```text
把 AGENTS.md 和 openspec/ 复制到你的项目根目录。
之后让 agent 按 openspec 工作流执行任务。
```

`archives/` 不需要一开始手动创建。第一次任务真正进入 Archive 阶段时再创建即可。

## 适合什么场景

- 新项目从 0 到 1 搭建，需要先做需求、原型、架构再实现。
- 现有项目持续迭代，需要每次需求、Bug、优化都有记录可追溯。
- 多个 agent 或多人协作，需要统一任务分类、验证标准和归档方式。
- 前端 UI 质量需要加强，希望把设计来源、设计验证和浏览器验证纳入流程。
- 后端接口、SQL、数据库表、migration、seed 和 API 文档需要统一合同、验证和回滚记录。
- 想把项目历史沉淀成可恢复的“项目记忆”，避免每次新需求都全项目扫描。

## 核心流程

默认完整路径：

```text
Intake -> Discovery -> Prototype -> Spec -> Architecture -> Plan -> Implement -> Verify -> Archive
```

轻量路径：

```text
Intake -> Spec Lite -> Architecture Lite -> Plan -> Implement -> Verify -> Archive
```

无论走完整路径还是轻量路径，都不能跳过：

- `change-id`
- 范围说明
- 验证证据
- 本地实现提交
- 归档记录
- 归档提交

Archive 前还有一条默认门禁：**用户验收确认**。Verify 通过只表示技术验证通过，不等于用户已经满意。

## UI 原型优先策略

涉及 UI 的任务默认先输出轻量可视化原型，让你先看到大概样式、布局和产品气质，再决定是否继续深入设计或实现。

推荐分级：

- 小 UI 调整：文字说明 + 截图或页面标注
- 普通页面：1 个 HTML、临时页面或截图级原型
- 新项目首个 UI / 核心页面：2-3 个视觉方向草案，用户选择后再细化
- 大型设计系统：再进入 Figma、组件库、变量和完整设计系统流程

原型的目标是快速确认方向，不要求一开始达到最终代码质量。用户确认方向后，再进入 Architecture / Implement。

如果项目没有设计系统但需要快速比较视觉方向，agent 必须先向用户展示 2-3 个候选 `DESIGN.md` 参考方向，说明适用场景、tradeoff 和来源 URL。用户确认或授权自主选择后，才可参考 Google Stitch 导出、`awesome-design-md` 等来源，并最终改写为项目自己的 `DESIGN.md`。

选择视觉方向、页面密度、交互方式、颜色、字体、间距、导航或组件策略前，应先使用 `ui-ux-pro-max` 做产品类型、信息密度、响应式、可访问性和交互风险判断；缺少该 skill 时，必须记录人工替代 checklist。

当 UI 原型或 Figma 后续要进入代码开发时，应补齐设计到开发交接：组件清单、状态清单、响应式规则、token 映射、Figma/code 映射、后端 / API 依赖和验证方式。复杂 UI 可使用 `openspec/templates/design-to-code-handoff-template.md`，避免实现阶段临场猜设计。

## 后端 / SQL / API 文档流程

接口、SQL、数据库表、migration、rollback、seed / 初始化数据和跨服务数据交互默认归为 `data-api-change`。

## 轻量部署检查

OpenSpec 不新增强制 Deploy 阶段，也不规定具体平台。具体部署方式由项目自身的 `DEPLOYMENT.md`、`docs/deployment.md`、CI/CD 配置、服务器脚本或项目 scripts 决定。

Verify 阶段应判断本次是否需要部署；需要部署时记录部署环境、部署方式、部署前检查、部署后验证和回滚方式；不需要部署时记录不适用原因。Archive 阶段记录最终部署状态。

## 截图验证与登录阻塞

截图验证不应直接舍弃，但遇到登录页、SSO、权限页、验证码或会话过期时必须停止截图循环。agent 应记录一次诊断证据，然后请用户协助登录、提供测试账号 / 测试 cookie / 已登录会话，或记录降级验证和残余风险。不得把“卡在登录页”当作验证通过。

新增或修改 API 时，必须同步接口合同或 API 文档。优先使用项目已有的 OpenAPI / Swagger、项目 docs 或代码生成来源；如果项目没有现成 API 文档体系，默认创建：

```text
openspec/changes/<change-id>/api-contract.md
```

涉及数据库、SQL、migration、rollback 或 seed 时，必须记录数据库变更。优先使用项目已有 migration / 数据库文档体系；如果项目没有现成数据库变更记录体系，默认创建：

```text
openspec/changes/<change-id>/database-change.md
```

Verify 阶段必须检查 API 文档与实际请求 / 响应一致，并记录 migration、rollback、seed、schema、索引、SQL 参数化、权限和调用方同步结果。

## 快速接入

### 1. 复制最小文件

在目标项目根目录放入：

```text
your-project/
├── AGENTS.md
└── openspec/
```

如果目标项目已经有 `AGENTS.md`，不要直接覆盖，应把本仓库 `AGENTS.md` 中的 OpenSpec 入口规则合并进去。

### 2. 第一次启动先读这些文件

建议按顺序阅读：

1. `openspec/quickstart.md`
2. `openspec/README.md`
3. `openspec/skills/skill-manifest.md`
4. `openspec/skills/skill-checklist.md`
5. `openspec/checklists/preflight-checklist.md`

如果是接入已有项目，再读：

- `openspec/docs/migration-guide.md`

### 3. 开始第一个任务

你可以这样对 agent 说：

```text
请按 openspec 工作流执行这个需求，先做 Intake，生成 change-id，并判断走完整路径还是轻量路径。
```

如果是 Bug：

```text
这是一个 bugfix，请按 openspec 轻量路径执行，先生成 change-id，记录复现条件，再进入 Plan、Implement、Verify、Archive。
```

如果是新项目：

```text
这是一个新项目，请按 openspec 完整路径执行，先做 Intake 和 Discovery，不要跳过 Prototype。
```

## 强制规则摘要

### 新任务先恢复记忆

新任务进入 Intake 时，不默认全项目扫描。应先读取：

- `archives/README.md`
- `archives/index/by-date.md`
- `archives/index/by-type.md`
- `archives/index/by-module.md`

命中相关历史后，再读取对应归档目录和必要的 Git 提交。

### 每个任务必须有 `change-id`

功能新增、Bug 修复、UI 调整、接口改动、技术优化，都必须绑定一个稳定的 `change-id`。

### 新项目和大变更必须先做原型

`new-project`、`major-change`、核心流程重做、设计系统重构，不能跳过 Prototype 直接实现。

如果是 UI 相关任务，Prototype 阶段优先采用轻量可视化原型，而不是一上来就进入重型 Figma 或完整设计系统流程。

### 架构阶段必须确认 4 项选择

新项目和大需求变更必须明确：

- 前端框架
- UI 框架或组件体系
- 后端框架
- 数据库

### UI 任务必须有设计来源

涉及 UI 的任务应明确设计来源：

- `DESIGN.md`
- Figma 文件 / 节点
- 已确认截图或原型
- `design-consultation` / `design-shotgun` / `design-html` 产物
- 明确的降级说明

如果缺少统一设计入口，可使用：

- `openspec/templates/design-template.md`

如果没有设计系统但需要参考第三方 `DESIGN.md`，agent 必须先提示候选方向并获得用户选择或授权，不得静默替用户选择参考风格。

涉及 UI 结构、视觉方向、交互体验或设计质量判断时，必须优先使用 `ui-ux-pro-max`，或记录人工替代判断和残余风险。

### API / 数据改动必须有接口文档和数据库变更记录

新增或修改 API 时，必须同步接口合同或 API 文档。无现成体系时，默认使用：

- `openspec/changes/<change-id>/api-contract.md`

涉及数据库、SQL、migration、rollback 或 seed 时，必须记录数据库变更。无现成体系时，默认使用：

- `openspec/changes/<change-id>/database-change.md`

Verify 阶段必须检查文档与实际接口行为一致，并记录 migration、rollback、seed、SQL 参数化和权限边界。

### 没有验证证据，不得宣称完成

Verify 阶段必须记录执行过的命令、结果和已知风险。前端任务还应尽量覆盖浏览器检查、控制台错误、响应式和截图证据。

### 用户未验收，不得归档

需求修改、新功能、UI 调整和大需求变更，默认需要在 Verify 后交给用户确认。

如果用户说“不满意”“继续改”“不是这个意思”“再调整一下”，这仍属于同一个 `change-id` 的迭代，不应新建归档，也不应把未接受结果写入长期记忆。

只有用户确认可接受、明确接受残余风险，或一开始明确授权自动验收归档后，才进入实现提交和 Archive。

### Archive 必须包含本地 Git 提交

推荐顺序：

```text
Implement -> Verify -> 用户验收 -> Git 提交代码 -> Archive -> Git 提交归档 -> 用户确认后 push
```

Git 提交信息必须清楚可读。实现提交应说明本次新增、修复、调整和验证内容；归档提交应说明归档的 `change-id` 和归档内容。优先使用中文提交信息，可参考 [openspec/templates/commit-message-template.md](openspec/templates/commit-message-template.md)。

如果目标项目还不是 Git 仓库，应在 Intake 阶段先执行：

```bash
git init
```

`push` 默认由用户手动执行，除非用户明确授权 agent 推送。

## 目录结构

```text
├── AGENTS.md                    # 项目执行规则与 agent 默认行为
├── README.md                    # 中文入口说明
├── README.en.md                 # 英文入口说明
├── archives/                    # 本仓库自身的归档记录
└── openspec/                    # 可复制到其他项目的工作流包
    ├── agents/                  # agent 角色定义
    ├── archive/                 # 归档标准与索引规则
    ├── changes/                 # 本仓库流程变更记录
    ├── checklists/              # 流程自检与分类验证清单
    ├── decisions/               # 技术选型参考
    ├── docs/                    # 迁移接入等补充说明
    ├── examples/                # 示例目录说明
    ├── routing/                 # 任务分类与路径选择
    ├── skills/                  # skills 清单、选择规则和降级策略
    ├── templates/               # 规格、计划、验证、归档、设计模板
    └── workflow/                # 00-09 阶段流程定义
```

## 常用入口

- 快速开始：[openspec/quickstart.md](openspec/quickstart.md)
- OpenSpec 总览：[openspec/README.md](openspec/README.md)
- 任务分流：[openspec/routing/task-routing.md](openspec/routing/task-routing.md)
- 生命周期：[openspec/routing/lifecycle.md](openspec/routing/lifecycle.md)
- 阶段总览：[openspec/workflow/00-overview.md](openspec/workflow/00-overview.md)
- Skill 清单：[openspec/skills/skill-manifest.md](openspec/skills/skill-manifest.md)
- Skill 检查：[openspec/skills/skill-checklist.md](openspec/skills/skill-checklist.md)
- 流程自检：[openspec/checklists/preflight-checklist.md](openspec/checklists/preflight-checklist.md)
- 分类验证：[openspec/checklists/verify-by-type.md](openspec/checklists/verify-by-type.md)
- 迁移指南：[openspec/docs/migration-guide.md](openspec/docs/migration-guide.md)
- 归档规范：[openspec/archive/archive-standard.md](openspec/archive/archive-standard.md)
- 原型阶段：[openspec/workflow/03-stage-prototype.md](openspec/workflow/03-stage-prototype.md)
- DESIGN.md 参考源：[openspec/docs/design-md-reference-sources.md](openspec/docs/design-md-reference-sources.md)
- 后端 / SQL / API 文档流程：[openspec/docs/backend-data-api-workflow.md](openspec/docs/backend-data-api-workflow.md)
- API 接口合同模板：[openspec/templates/api-contract-template.md](openspec/templates/api-contract-template.md)
- 数据库变更模板：[openspec/templates/database-change-template.md](openspec/templates/database-change-template.md)
- 模板目录：[openspec/templates/](openspec/templates/)

## 推荐 Skills

最小闭环建议具备：

- `brainstorming`
- `writing-plans`
- `review`
- `qa`
- `investigate`
- `superpowers:verification-before-completion`

前端项目建议额外具备：

- `browse` / `gstack` / `agent-browser`
- `design-review`
- `frontend-design-system`
- `ui-ux-pro-max`
- `design-consultation`
- `design-shotgun`
- Figma 相关 skills

缺失 skills 时流程仍可降级运行，但必须在 Intake 或 Verify 中记录缺失项、替代方式和残余风险。

## 设计原则

- 流程先于实现，避免边做边猜。
- 证据先于结论，避免凭感觉说完成。
- 用户验收先于归档，避免把未满意结果写进长期记忆。
- Git 提交先于归档，保证归档能追溯稳定代码状态。
- 归档先于遗忘，把每次变更沉淀成项目记忆。
- agent 代表职责，skill 代表方法，主控会话负责调度。

## 许可证

本项目文档采用 [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) 许可证。