命令¶

这是 CodexSpec 斜杠命令的参考文档。这些命令在 Claude Code 的聊天界面中调用。

关于工作流程模式和何时使用每个命令，请参阅工作流程。关于 CLI 命令，请参阅 CLI。

快速参考¶

命令	用途
`/codexspec:constitution`	创建或更新项目宪法，带有跨工件验证
`/codexspec:specify`	通过交互式问答澄清需求
`/codexspec:generate-spec`	从澄清的需求生成 spec.md 文档
`/codexspec:clarify`	扫描现有规格说明中的歧义（迭代细化）
`/codexspec:spec-to-plan`	将规格说明转换为技术实现方案
`/codexspec:plan-to-tasks`	将方案分解为原子级、强制 TDD 的任务
`/codexspec:implement-tasks`	使用条件 TDD 工作流执行任务
`/codexspec:review-spec`	验证规格说明的完整性和质量
`/codexspec:review-plan`	审查技术方案的可行性和一致性
`/codexspec:review-tasks`	验证任务分解的 TDD 合规性
`/codexspec:analyze`	跨工件一致性分析（只读）
`/codexspec:checklist`	生成需求质量检查清单
`/codexspec:tasks-to-issues`	将任务转换为 GitHub issues
`/codexspec:commit-staged`	从暂存更改生成提交消息（含会话上下文感知）

命令分类¶

核心工作流程命令¶

用于主要 SDD 工作流程的命令：Constitution → 规格 → 方案 → 任务 → 实现。

审查命令（质量关卡）¶

在每个工作流程阶段验证工件的命令。建议在进入下一阶段之前使用。

高级命令¶

用于迭代细化、跨工件验证和项目管理集成的命令。

命令参考¶

`/codexspec:constitution`¶

创建或更新项目宪法。宪法定义了指导所有后续开发决策的架构原则、技术栈、代码标准和治理规则。

语法：

/codexspec:constitution [原则描述]

参数：

参数	必需	描述
`原则描述`	否	要包含的原则描述（如未提供将提示输入）

功能：

如果不存在则创建 .codexspec/memory/constitution.md
用新原则更新现有宪法
验证与模板的跨工件一致性
生成同步影响报告，显示更改和受影响的文件
包含依赖模板的合规性审查

创建的文件：

.codexspec/
└── memory/
    └── constitution.md    # 项目治理文档

示例：

你: /codexspec:constitution 专注于代码质量、测试标准和整洁架构

AI:  正在创建宪法...

     ✓ 已创建 .codexspec/memory/constitution.md
     版本: 1.0.0

     同步影响报告:
     - plan-template-*.md: ✅ 已对齐
     - spec-template-*.md: ✅ 已对齐
     - tasks-template-*.md: ✅ 已对齐

     核心原则:
     1. 代码质量优先
     2. 测试驱动开发
     3. 整洁架构

     建议提交: docs: create constitution v1.0.0

提示：

在项目早期定义原则，确保决策一致
同时包含技术和流程原则
在重大功能开发前审查宪法
宪法更改会触发跨工件验证

`/codexspec:specify`¶

通过交互式问答澄清需求。此命令探索你的初始想法而不创建任何文件——你保持完全控制。

语法：

/codexspec:specify [你的想法或需求]

参数：

参数	必需	描述
`你的想法或需求`	否	你想构建的内容的初始描述（如未提供将提示输入）

功能：

提出澄清问题以理解你的想法
探索你可能没有考虑到的边界情况
通过对话共同创建高质量需求
关注"做什么"和"为什么"，而非技术实现
不生成文件 - 由你决定何时创建文档

不创建的文件：

此命令期间不创建任何文件
需求保留在对话中，直到你批准

示例：

你: /codexspec:specify 我想构建一个任务管理应用

AI:  好的！让我帮你澄清需求。

     首先，这个应用的目标用户是谁？
     - 个人专业人士
     - 小团队
     - 企业组织
     - 以上全部

你: 小团队，主要是软件开发团队

AI:  明白了。对于小型开发团队：
     - 需要实时协作功能吗？
     - 任务应该支持子任务还是仅支持扁平列表？
     - 有任何集成需求吗（GitHub、Slack 等）？

你: 实时很重要。子任务要。GitHub 集成就好了。

AI:  [继续探索需求...]

     澄清的需求摘要：
     - 目标：小型开发团队（5-20 人）
     - 核心：带子任务的任务、实时更新
     - 集成：GitHub（可选）
     - 优先级：实时协作 > 子任务 > GitHub

     准备好生成规格文档了吗？
     使用 /codexspec:generate-spec 创建 spec.md

提示：

用于初始需求探索
不必担心完整性——细化是迭代的
如果 AI 做出假设，请提问
在生成规格之前审查摘要

`/codexspec:generate-spec`¶

从澄清的需求生成 spec.md 文档。此命令充当"需求编译器"，将你澄清的需求转换为结构化的规格说明。

语法：

/codexspec:generate-spec

参数：

参数	必需	描述
无	-	使用之前 `/codexspec:specify` 会话的上下文

功能：

创建 .codexspec/specs/{NNN}-{feature-name}/ 目录
生成包含以下内容的综合 spec.md：
功能概述和目标
带验收标准的用户故事
功能需求（REQ-XXX 格式）
非功能需求（NFR-XXX 格式）
边界情况及处理方法
范围外项目

创建的文件：

.codexspec/
└── specs/
    └── 001-task-management/
        └── spec.md

示例：

你: /codexspec:generate-spec

AI:  正在生成规格说明...

     ✓ 已创建 .codexspec/specs/001-task-management/spec.md

     包含的部分：
     - 概述：小型开发团队的任务管理
     - 4 个带验收标准的用户故事
     - 12 个功能需求（REQ-001 到 REQ-012）
     - 3 个非功能需求（NFR-001 到 NFR-003）
     - 5 个记录的边界情况
     - 范围外：移动应用、企业 SSO

     下一步：
     - 使用 /codexspec:review-spec 审查规格
     - 或继续 /codexspec:spec-to-plan

提示：

在 /codexspec:specify 澄清需求后运行
在继续之前审查生成的规格
使用 /codexspec:review-spec 进行质量验证
如果需要微调，直接编辑 spec.md

`/codexspec:clarify`¶

扫描现有规格说明中的歧义和缺口。在初始规格创建后用于迭代细化。

语法：

/codexspec:clarify [spec.md 路径]

参数：

参数	必需	描述
`spec.md 路径`	否	规格文件路径（如未提供则自动检测）

功能：

使用 4 个聚焦的歧义类别扫描规格
提出有针对性的澄清问题（最多 5 个）
用澄清答案更新 spec.md
如果可用，与 review-spec 发现集成

歧义类别：

类别	检测内容
完整性缺口	缺失部分、空内容、缺少验收标准
具体性问题	模糊术语（"快速"、"可扩展"）、未定义的约束
行为清晰度	错误处理缺口、未定义的状态转换
可衡量性问题	没有指标的非功能需求

示例：

你: /codexspec:clarify

AI:  正在扫描 spec.md 中的歧义...

     在 3 个类别中发现问题。

     ## 问题 1/5：具体性

     **上下文**：NFR-001 声明"系统应该快速响应"

     **问题**：目标响应时间是多少？

     | 选项 | 描述 | 影响 |
     |------|------|------|
     | A | 所有操作 < 100ms | 高性能要求 |
     | B | 读取 < 500ms，写入 < 1s | 平衡方法 |
     | 自定义 | 提供不同的答案 | - |

     **推荐**：选项 B - 适合典型 Web 应用

你: B

AI:  ✓ 已更新 NFR-001：响应时间 读取 < 500ms，写入 < 1s
     已添加到 spec.md 的澄清部分

提示：

当 spec.md 存在但需要细化时使用
与 /codexspec:review-spec 发现集成
每个会话最多 5 个问题
对于复杂规格说明可多次运行

`/codexspec:spec-to-plan`¶

将功能规格说明转换为技术实现方案。这是你定义功能如何构建的地方。

语法：

/codexspec:spec-to-plan [spec.md 路径]

参数：

参数	必需	描述
`spec.md 路径`	否	规格文件路径（如未提供则从 `.codexspec/specs/` 自动检测）

功能：

读取规格说明和宪法
定义带版本约束的技术栈
执行合规性审查（如果存在宪法则必须）
创建带模块依赖图的架构
记录技术决策及理由
规划实现阶段

创建的文件：

.codexspec/
└── specs/
    └── 001-task-management/
        └── plan.md    # 技术实现方案

示例：

你: /codexspec:spec-to-plan 使用 Python FastAPI 作为后端，React 作为前端，PostgreSQL 作为数据库

AI:  正在生成技术方案...

     合规性审查：
     ✓ 整洁架构：具有清晰边界的模块化设计
     ✓ TDD：在阶段中强制测试优先方法
     ✓ 代码质量：需要代码检查和类型提示

     架构：
     - 后端：FastAPI 分层架构
     - 前端：React 组件结构
     - 数据库：PostgreSQL 迁移策略

     模块依赖图：
     ┌─────────────┐
     │    API      │
     └──────┬──────┘
            │
     ┌──────▼──────┐
     │  Services   │
     └──────┬──────┘
            │
     ┌──────▼──────┐
     │    Data     │
     └─────────────┘

     ✓ 已创建 plan.md
     定义了 5 个实现阶段

提示：

在规格审查完成且稳定后运行
如果存在宪法，合规性审查是必须的
根据项目类型包含相关部分
在继续任务之前审查方案

`/codexspec:plan-to-tasks`¶

将技术方案分解为带有 TDD 强制的原子级可执行任务。

语法：

/codexspec:plan-to-tasks [spec.md 路径 plan.md 路径]

参数：

参数	必需	描述
`路径`	否	规格和方案路径（如未提供则自动检测）

功能：

创建原子任务（每个任务一个主文件）
强制 TDD：测试任务在实现任务之前
用 [P] 标记可并行化任务
为每个任务指定精确的文件路径
定义阶段检查点

创建的文件：

.codexspec/
└── specs/
    └── 001-task-management/
        └── tasks.md    # 任务分解

任务结构：

### Task 2.1: 编写实体 A 的测试 [P]
- **类型**: 测试
- **文件**: `tests/test_entity_a.py`
- **描述**: 为实体 A 编写单元测试
- **依赖**: Task 1.3
- **预估复杂度**: 低

示例：

你: /codexspec:plan-to-tasks

AI:  正在将方案分解为任务...

     ✓ 已创建 tasks.md
     总计：24 个任务
     可并行化：8 个任务（33%）

     阶段 1：基础（4 个任务）
     阶段 2：核心实现 - TDD（10 个任务）
     阶段 3：集成（4 个任务）
     阶段 4：接口层（3 个任务）
     阶段 5：测试与文档（3 个任务）

     执行顺序：
     阶段 1 → [阶段 2 任务按并行组] → 阶段 3 → 阶段 4 → 阶段 5

     在每个阶段边界定义了检查点。

提示：

每个任务应该只涉及一个主文件
测试任务总是在实现任务之前
[P] 标记真正独立的可并行化任务
在实现之前审查依赖关系

`/codexspec:implement-tasks`¶

使用条件 TDD 工作流执行实现任务。系统地完成任务列表。

语法：

/codexspec:implement-tasks [tasks 路径]
/codexspec:implement-tasks [spec 路径 plan 路径 tasks 路径]

参数：

参数	必需	描述
`tasks 路径`	否	tasks.md 路径（如未提供则自动检测）
`spec 路径 plan 路径 tasks 路径`	否	三个文档的显式路径

文件解析：

无参数：从 .codexspec/specs/ 自动检测
一个参数：视为 tasks.md 路径，从同一目录推导其他文件
三个参数：spec.md、plan.md 和 tasks.md 的显式路径

功能：

读取 tasks.md 并识别未完成任务
对代码任务应用 TDD 工作流：
红：先编写失败的测试
绿：实现以通过测试
验证：运行所有测试
重构：在保持测试通过的同时改进
对不可测试任务（文档、配置）直接实现
随着进展更新任务复选框
如果遇到阻塞，记录到 issues.md

代码任务的 TDD 工作流：

红 → 绿 → 验证 → 重构 → 标记完成

不可测试任务的直接实现：

文档文件
配置文件
静态资源
基础设施文件

示例：

你: /codexspec:implement-tasks

AI:  开始实现...

     加载上下文：
     - spec.md ✓
     - plan.md ✓
     - tasks.md ✓
     - constitution.md ✓

     技术栈：Python 3.11+ / FastAPI / PostgreSQL / pytest

     正在处理任务 1.1：设置项目结构
     ✓ 已创建 src/taskman/__init__.py
     ✓ 已创建 pyproject.toml
     [x] 任务 1.1 完成

     正在处理任务 2.1：编写任务实体测试 [P]
     ✓ 已创建 tests/test_task.py
     运行测试... 5 通过（所有预期失败）
     [x] 任务 2.1 完成

     正在处理任务 2.2：实现任务实体
     ✓ 已创建 src/taskman/models/task.py
     运行测试... 5 通过
     [x] 任务 2.2 完成

     ...

提示：

如果中断可以从上次停止的地方恢复
阻塞问题记录在 issues.md 中
在重要任务/阶段后进行提交
先运行 /codexspec:review-tasks 进行验证

`/codexspec:review-spec`¶

验证规格说明的完整性、清晰度、一致性及技术规划准备度。

语法：

/codexspec:review-spec [spec.md 路径]

参数：

参数	必需	描述
`spec.md 路径`	否	规格文件路径（如未提供则自动检测）

功能：

检查所有必需部分的完整性
评估清晰度和具体性
验证内部一致性
评估需求可测试性
检查宪法一致性
生成带评分的审查报告

审查维度：

维度	权重	验证内容
完整性	25%	所有部分存在且实质性
清晰度	25%	无模糊语言，单一解释
一致性	20%	无内部矛盾
可测试性	20%	需求可验证
宪法一致性	10%	与项目原则一致

示例：

你: /codexspec:review-spec

AI:  正在审查规格说明...

     # 规格审查报告

     ## 摘要
     - **总体状态**: ⚠️ 需要改进
     - **质量评分**: 72/100
     - **准备度**: 需要修订

     ## 部分分析
     | 部分 | 状态 | 完整性 | 质量 |
     |------|------|--------|------|
     | 概述 | ✅ | 100% | 高 |
     | 目标 | ✅ | 100% | 高 |
     | 用户故事 | ⚠️ | 80% | 中 |
     | 功能需求 | ✅ | 100% | 高 |
     | 非功能需求 | ⚠️ | 50% | 中 |
     | 边界情况 | ❌ | 0% | N/A |

     ## 关键问题（必须修复）
     - [SPEC-001]: 边界情况部分为空
       - 影响：可能遗漏重要的失败场景
       - 建议：至少记录 3-5 个边界情况

     ## 警告（应该修复）
     - [SPEC-002]: NFR-001 使用模糊术语"快速"
       - 影响：没有指标无法验证
       - 建议：指定具体的响应时间

     ## 建议
     1. 添加边界情况部分及处理方法
     2. 量化非功能需求
     3. 为用户故事 3 添加验收标准

     可用的后续操作：
     - /codexspec:clarify - 解决歧义
     - /codexspec:spec-to-plan - 如果问题已解决

提示：

在 /codexspec:spec-to-plan 之前运行
在继续之前解决关键问题
警告不会阻止但表示风险
修复后重新运行

`/codexspec:review-plan`¶

审查技术实现方案的可行性、架构质量和与规格说明的一致性。

语法：

/codexspec:review-plan [plan.md 路径]

参数：

参数	必需	描述
`plan.md 路径`	否	方案文件路径（如未提供则自动检测）

功能：

验证规格需求有方案覆盖
评估技术栈选择
评估架构决策
验证实现阶段
检查宪法一致性
生成带评分的审查报告

审查维度：

维度	权重	验证内容
规格一致性	30%	所有需求有实现
技术栈	15%	适当的技术选择
架构质量	25%	合理的设计和模式
阶段规划	15%	逻辑和现实的阶段
宪法一致性	15%	遵循项目原则

示例：

你: /codexspec:review-plan

AI:  正在审查技术方案...

     # 方案审查报告

     ## 摘要
     - **总体状态**: ✅ 通过
     - **质量评分**: 85/100
     - **准备度**: 准备好进行任务分解

     ## 规格一致性
     | 需求 | 覆盖 | 状态 |
     |------|------|------|
     | REQ-001 到 REQ-012 | ✅ 完整 | 全部覆盖 |
     | US-001 到 US-004 | ✅ 完整 | 全部覆盖 |
     | NFR-001 到 NFR-003 | ⚠️ 部分 | 缓存未详细说明 |

     ## 架构审查
     优势：
     - 清晰的关注点分离
     - 明确定义的模块边界
     - 适当的设计模式

     关注点：
     - 缺少错误处理策略文档

     ## 宪法一致性
     | 原则 | 合规 |
     |------|------|
     | 整洁架构 | ✅ |
     | TDD | ✅ |
     | 代码质量 | ✅ |

     准备好使用 /codexspec:plan-to-tasks

提示：

在 /codexspec:plan-to-tasks 之前运行
关键问题应该解决
用于及早发现架构问题
验证技术栈与团队技能一致

`/codexspec:review-tasks`¶

验证任务分解的完整性、TDD 合规性、正确排序和适当依赖。

语法：

/codexspec:review-tasks [tasks.md 路径]

参数：

参数	必需	描述
`tasks.md 路径`	否	任务文件路径（如未提供则自动检测）

功能：

检查所有方案项有任务覆盖
验证 TDD 合规性（测试在实现之前）
验证任务粒度（原子级、单文件聚焦）
验证依赖（无循环、正确排序）
审查并行化标记
验证文件路径

审查维度：

维度	权重	验证内容
方案覆盖	30%	所有方案项有任务
TDD 合规	25%	强制测试优先工作流
依赖与排序	20%	正确依赖，无循环
任务粒度	15%	原子级，适当范围
并行化与文件	10%	正确标记和路径

示例：

你: /codexspec:review-tasks

AI:  正在审查任务分解...

     # 任务审查报告

     ## 摘要
     - **总体状态**: ⚠️ 需要改进
     - **质量评分**: 78/100
     - **总任务数**: 24
     - **可并行化**: 8 (33%)

     ## TDD 合规性
     | 组件 | 测试任务 | 测试在实现前 | 状态 |
     |------|----------|--------------|------|
     | 任务实体 | ✅ | ✅ | ✅ |
     | 用户实体 | ✅ | ✅ | ✅ |
     | TaskService | ❌ 缺失 | N/A | ❌ |

     ## TDD 违规
     - [TDD-001]: TaskService 缺少测试任务

     ## 依赖问题
     - [DEP-001]: 任务 2.5 标记 [P] 但依赖于 2.4

     ## 建议
     1. 在实现之前为 TaskService 添加测试任务
     2. 修复任务 2.5 的并行化标记

     在 /codexspec:implement-tasks 之前修复问题

提示：

在 /codexspec:implement-tasks 之前运行
TDD 违规对代码质量至关重要
检查并行化标记准确
验证文件路径与项目结构匹配

`/codexspec:analyze`¶

对 spec.md、plan.md 和 tasks.md 执行非破坏性的跨工件一致性分析。识别不一致、重复和覆盖缺口。

语法：

/codexspec:analyze

参数：

参数	必需	描述
无	-	分析当前功能的工件

功能：

检测跨工件的重复
识别缺乏可衡量标准的歧义
发现规格不足的项
检查宪法一致性
映射需求覆盖到任务
报告术语和排序的不一致

严重级别：

级别	定义
CRITICAL	宪法违规、缺少核心工件、零覆盖
HIGH	重复/冲突需求、模糊的安全属性
MEDIUM	术语漂移、缺少非功能覆盖
LOW	风格/措辞改进

示例：

你: /codexspec:analyze

AI:  正在分析工件...

     # 规格分析报告

     ## 覆盖摘要
     | 需求键 | 有任务? | 任务 ID |
     |--------|--------|---------|
     | REQ-001 | ✅ | 2.1, 2.2 |
     | REQ-002 | ✅ | 2.3, 2.4 |
     | REQ-003 | ❌ | 无 |

     ## 发现的问题

     | ID | 类别 | 严重性 | 摘要 |
     |----|------|--------|------|
     | A1 | 覆盖 | CRITICAL | REQ-003 无任务覆盖 |
     | A2 | 重复 | HIGH | REQ-005 和 REQ-008 重叠 |
     | A3 | 歧义 | MEDIUM | NFR-002 "安全"未定义 |

     ## 指标
     - 总需求数：12
     - 总任务数：24
     - 覆盖率：92%（11/12 需求）
     - 关键问题：1

     ## 下一步操作
     1. 为 REQ-003 添加任务（CRITICAL）
     2. 考虑合并 REQ-005 和 REQ-008
     3. 在 NFR-002 中定义"安全"

     在 /codexspec:implement-tasks 之前解决 CRITICAL 问题

提示：

在 /codexspec:plan-to-tasks 之后、实现之前运行
CRITICAL 问题应该阻止实现
只读分析——不修改文件
使用发现来改进工件质量

`/codexspec:checklist`¶

生成用于验证需求完整性、清晰度和一致性的质量检查清单。这些是"需求编写的单元测试"。

语法：

/codexspec:checklist [聚焦领域]

参数：

参数	必需	描述
`聚焦领域`	否	领域聚焦（如 "ux"、"api"、"security"、"performance"）

功能：

生成按质量维度组织的检查清单
在 FEATURE_DIR/checklists/ 目录创建检查清单
项目聚焦于需求质量，而非实现测试

质量维度：

需求完整性：是否所有必要需求都存在？
需求清晰度：需求是否具体且无歧义？
需求一致性：需求是否一致无冲突？
验收标准质量：成功标准是否可衡量？
场景覆盖：是否所有流程/用例都已覆盖？
边界情况覆盖：边界条件是否已定义？
非功能需求：性能、安全、可访问性是否已指定？
依赖与假设：是否已文档化？

示例检查清单类型：

ux.md - 视觉层次、交互状态、可访问性
api.md - 错误格式、速率限制、认证
security.md - 数据保护、威胁模型、泄露响应
performance.md - 指标、负载条件、降级

示例：

你: /codexspec:checklist security

AI:  正在生成安全检查清单...

     ✓ 已创建 .codexspec/specs/001-task-management/checklists/security.md

     ## 安全需求质量检查清单

     ### 认证需求
     - [ ] CHK001 - 是否为所有受保护端点定义了认证需求？ [完整性]
     - [ ] CHK002 - 密码复杂度是否明确指定？ [清晰度]
     - [ ] CHK003 - 会话超时需求是否量化？ [可衡量性]

     ### 数据保护
     - [ ] CHK004 - 静态数据加密需求是否指定？ [完整性]
     - [ ] CHK005 - 传输中数据加密需求是否指定？ [完整性]
     - [ ] CHK006 - PII 处理是否明确文档化？ [清晰度]

     总计：4 个类别中的 15 个项目

提示：

检查清单验证需求质量，而非实现正确性
用于需求审查和改进
为聚焦验证创建领域特定检查清单
在进入技术规划之前运行

`/codexspec:tasks-to-issues`¶

将 tasks.md 中的任务转换为 GitHub issues，用于项目跟踪和协作。

语法：

/codexspec:tasks-to-issues

参数：

参数	必需	描述
无	-	转换当前功能的所有任务

功能：

解析任务 ID、描述、依赖和文件路径
创建带结构化正文的 GitHub issues
根据任务类型添加标签（setup、implementation、testing、documentation）
在 issues 之间链接依赖
报告创建的 issues 及 URL

前提条件：

带有 GitHub 远程的 Git 仓库
GitHub CLI（gh）已安装并认证
tasks.md 文件存在

示例：

你: /codexspec:tasks-to-issues

AI:  正在将任务转换为 GitHub issues...

     仓库：github.com/example/taskman

     创建 issues：
     ✓ #42: Task 1.1 - 设置项目结构 (setup)
     ✓ #43: Task 2.1 - 编写任务实体测试 (testing)
     ✓ #44: Task 2.2 - 实现任务实体 (implementation)
     ...

     摘要：
     - 已创建 issues：24
     - 已应用标签：setup(4), implementation(12), testing(5), documentation(3)
     - 已链接依赖：18

     查看 issues：https://github.com/example/taskman/issues

提示：

需要 GitHub CLI 认证（gh auth login）
仅适用于 GitHub 仓库
在仓库的默认配置中创建 issues
运行前检查重复

`/codexspec:commit-staged`¶

基于暂存的 git 更改生成符合 Conventional Commits 的提交消息，并具有会话上下文感知能力。此命令理解你的开发会话以生成有意义的提交消息。

语法：

/codexspec:commit-staged [-p]

参数：

参数	必需	描述
`-p`	否	预览模式 - 仅显示消息而不提交

功能：

执行 git diff --staged 获取暂存的更改
分析更改和会话上下文以理解意图
遵循 Conventional Commits 规范
执行模式（默认）：生成消息后直接提交
预览模式（-p）：仅显示消息而不提交
如果没有暂存更改则报告错误

示例：

你: /codexspec:commit-staged

AI:  正在分析暂存的更改...

     已暂存的文件：
     - src/auth/service.py
     - tests/test_auth.py

     生成的提交消息：
     feat(auth): 实现令牌刷新逻辑

     - 添加刷新令牌生成
     - 包含令牌过期处理
     - 添加刷新流程的测试

     正在执行提交...

     ✓ 已提交：def5678

预览模式示例：

你: /codexspec:commit-staged -p

AI:  预览模式 - 不会执行提交

     建议的提交消息：
     feat(auth): 实现令牌刷新逻辑

     - 添加刷新令牌生成
     - 包含令牌过期处理
     - 添加刷新流程的测试

提示：

先使用 git add 暂存更改
仅分析暂存的内容 - 尊重 Git 的两阶段提交流程
考虑会话上下文以生成有意义的提交消息
使用 -p 标志在提交前预览
默认遵循 Conventional Commits 规范

工作流程概览¶

┌──────────────────────────────────────────────────────────────────────────┐
│                    CodexSpec 人机协作工作流程                             │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  1. Constitution  ──►  定义项目原则                                      │
│         │                         带跨工件验证                           │
│         ▼                                                                │
│  2. Specify  ───────►  交互式问答澄清需求                                │
│         │               （不创建文件 - 人工控制）                        │
│         ▼                                                                │
│  3. Generate Spec  ─►  创建 spec.md 文档                                 │
│         │                                                                │
│         ▼                                                                │
│  ╔═══════════════════════════════════════════════════════════════════╗   │
│  ║  ★ 审查关卡 1: /codexspec:review-spec ★                            ║   │
│  ║  验证：完整性、清晰度、可测试性、宪法                               ║   │
│  ╚═══════════════════════════════════════════════════════════════════╝   │
│         │                                                                │
│         ▼                                                                │
│  4. Clarify  ───────►  解决歧义（迭代）                                  │
│         │               4 个有针对性的类别，最多 5 个问题                │
│         ▼                                                                │
│  5. Spec to Plan  ──►  创建技术方案，包含：                              │
│         │               • 合规性审查（必须）                             │
│         │               • 模块依赖图                                     │
│         ▼                                                                │
│  ╔═══════════════════════════════════════════════════════════════════╗   │
│  ║  ★ 审查关卡 2: /codexspec:review-plan ★                            ║   │
│  ║  验证：规格一致性、架构、技术栈、阶段                               ║   │
│  ╚═══════════════════════════════════════════════════════════════════╝   │
│         │                                                                │
│         ▼                                                                │
│  6. Plan to Tasks  ─►  生成原子任务，包含：                              │
│         │               • TDD 强制（测试在实现前）                       │
│         │               • 并行标记 [P]                                  │
│         │               • 文件路径规范                                  │
│         ▼                                                                │
│  ╔═══════════════════════════════════════════════════════════════════╗   │
│  ║  ★ 审查关卡 3: /codexspec:review-tasks ★                           ║   │
│  ║  验证：覆盖、TDD 合规、依赖、粒度                                   ║   │
│  ╚═══════════════════════════════════════════════════════════════════╝   │
│         │                                                                │
│         ▼                                                                │
│  7. Analyze  ───────►  跨工件一致性检查                                  │
│         │               检测缺口、重复、宪法问题                         │
│         ▼                                                                │
│  8. Implement  ─────►  使用条件 TDD 工作流执行                           │
│                          代码：测试优先 | 文档/配置：直接                 │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

关键点：每个审查关卡（★）都是一个人工检查点，你在投入更多时间之前验证 AI 输出。跳过这些关卡通常会导致代价高昂的返工。

故障排除¶

"找不到功能目录"¶

命令无法定位功能目录。

解决方案：

先运行 codexspec init 初始化项目
检查 .codexspec/specs/ 目录是否存在
确认你在正确的项目目录中

"找不到 spec.md"¶

规格文件尚不存在。

解决方案：

先运行 /codexspec:specify 澄清需求
然后运行 /codexspec:generate-spec 创建 spec.md

"找不到宪法"¶

不存在项目宪法。

解决方案：

运行 /codexspec:constitution 创建一个
宪法是可选的，但建议用于一致的决策

"找不到任务文件"¶

任务分解不存在。

解决方案：

确保你已先运行 /codexspec:spec-to-plan
然后运行 /codexspec:plan-to-tasks 创建 tasks.md

"GitHub CLI 未认证"¶

/codexspec:tasks-to-issues 命令需要 GitHub 认证。

解决方案：

安装 GitHub CLI：brew install gh（macOS）或等效命令
认证：gh auth login
验证：gh auth status

下一步¶

工作流程 - 常见模式和何时使用每个命令
CLI - 用于项目初始化的终端命令

命令¶

快速参考¶

命令分类¶

核心工作流程命令¶

审查命令（质量关卡）¶

高级命令¶

命令参考¶

/codexspec:constitution¶

/codexspec:specify¶

/codexspec:generate-spec¶

/codexspec:clarify¶

/codexspec:spec-to-plan¶

/codexspec:plan-to-tasks¶

/codexspec:implement-tasks¶

/codexspec:review-spec¶

/codexspec:review-plan¶

/codexspec:review-tasks¶

/codexspec:analyze¶

/codexspec:checklist¶

/codexspec:tasks-to-issues¶

/codexspec:commit-staged¶

工作流程概览¶

故障排除¶

"找不到功能目录"¶

"找不到 spec.md"¶

"找不到宪法"¶

"找不到任务文件"¶

"GitHub CLI 未认证"¶

下一步¶

`/codexspec:constitution`¶

`/codexspec:specify`¶

`/codexspec:generate-spec`¶

`/codexspec:clarify`¶

`/codexspec:spec-to-plan`¶

`/codexspec:plan-to-tasks`¶

`/codexspec:implement-tasks`¶

`/codexspec:review-spec`¶

`/codexspec:review-plan`¶

`/codexspec:review-tasks`¶

`/codexspec:analyze`¶

`/codexspec:checklist`¶

`/codexspec:tasks-to-issues`¶

`/codexspec:commit-staged`¶