开发工作流

执行开发任务的工作流指导，支持单任务和批量执行，采用自顶向下开发模式和分层 TDD。

语言规则

支持中英文提问
统一中文回复

模式选择

入口处根据任务规模选择合适的开发模式：

| 模式 | 适用场景 | 流程 | |------|---------|------| | 轻量 | Bug fix、小改动、配置变更 | → /devdocs-bugfix（已有） | | 标准 | 新功能、需求变更 | → 完整 Requirements→Design→Tests→Tasks→Dev | | 探索 | 原型、技术调研 | → 允许跳过部分验证，事后 /devdocs-retrofit 补文档 |

模式判断指引

若任务来自 devdocs-dev-tasks（已有完整文档链）→ 标准模式
若用户描述为 bug/hotfix/配置变更 → 轻量模式，路由到 /devdocs-bugfix
若用户描述为原型/调研/探索/spike → 探索模式，跳过对抗式验证和追溯标注强制，开发完成后提示运行 /devdocs-retrofit

以下流程为标准模式。轻量模式和探索模式见上述路由。

触发条件

用户开始执行某个任务（如 T-01）
用户批量执行任务（如 T-01~T-05、F-001、--all）
用户需要继续开发（断点续做）
用户需要开发指导
用户从 devdocs-dev-tasks 进入开发阶段
关键词："开发任务"、"执行任务"、"开始 T-XX"、"批量开发"、"继续开发"

运行模式

语法

| 指定符 | 示例 | 说明 | |--------|------|------| | 单任务 | T-03 | 执行单个任务（现有行为） | | 范围 | T-01~T-05 | 执行范围内所有任务 | | 枚举 | T-01,T-03,T-07 | 执行指定任务列表 | | 功能点 | F-001 | 通过 关联需求 字段反查所有关联任务 | | 用户故事 | US-001 | 同上 | | 全部 | --all | 所有 状态≠已完成 的任务 | | 无人值守 | --headless | 批量模式 + 全自动决策（fail-fast） | | 自动提交 | --auto-commit | 测试通过自动提交，仅 Blocker 时暂停（与 --headless 互斥） |

模式对比

| 特性 | 单任务模式 | 批量模式（交互） | --auto-commit | --headless | |------|-----------|----------------|----------------|--------------| | 依赖解析 | 自动补充前置依赖 | 拓扑排序全部任务 | 拓扑排序全部任务 | 拓扑排序 + 前置校验 | | 断点检测 | 执行 | 编排器轻量执行 | 编排器轻量执行 | 编排器轻量执行 | | 提交方式 | 用户选择 | 子 Agent 内交互确认 | 测试通过自动提交 | 自动提交（安全不变量保证） | | 中断处理 | N/A | 子 Agent 内交互 | Blocker 时暂停询问 | fail-fast 终止 + 续做命令 | | 完成汇总 | 无 | 批量执行报告 | 批量执行报告 | 交付报告 + 检查点文件 | | 执行模式 | 主 Agent 直接执行 | 编排器 + 子 Agent | 编排器 + 子 Agent | 编排器 + 子 Agent | | 上下文隔离 | 无需 | 每任务独立上下文 | 每任务独立上下文 | 每任务独立上下文 |

批量执行流程

解析指定符 → 依赖解析 + 拓扑排序 → 逐任务循环（断点检测 → 执行 → 原子提交）→ 汇总

详见 task-orchestration.md

前置条件

任务文档：docs/devdocs/04-dev-tasks.md
任务已定义并包含：关联需求、验收标准、测试方法

工作流程

1. 读取任务定义
   ├── 从 04-dev-tasks.md 获取任务详情
   ├── 确认关联的 F-XXX、AC-XXX
   └── 确认关联的测试用例 UT/IT/E2E-XXX
           │
           ▼
2. 生成骨架代码（自顶向下）
   ├── 接口骨架 + @requirement/@satisfies 标注
   └── 测试骨架 + @verifies/@testcase 标注
           │
           ▼
3. 执行开发（统一流程，分级强制）
   ├── 所有层级遵循统一 11 步流程
   ├── 层级标记（🔴🟡🟢⚪）决定各步骤强制程度
   └── 详见 execution-flow.md 强制程度矩阵
           │
           ▼
4. 完成检查
   ├── 基础检查（始终执行）
   │   ├── 验收标准全部满足
   │   ├── 测试通过
   │   └── Review 要点自查
   │
   ├── 前置验证（--review 触发时，对抗式验证之前）
   │   ├── /devdocs-verify --impl：AC 满足度 + 设计一致性（若存在 DevDocs 文档）
   │   └── /devdocs-verify --ui：设计稿↔实现对齐（仅 UI 任务 + 有设计稿）
   │
   └── 对抗式验证（🔴自动触发 / 其他层级 --review 手动触发）
       ├── 🔍 代码质量审查（/code-quality 视角）
       ├── 🧪 测试完备性审查（/testing-guide 视角）
       └── 📋 综合审查报告
           │
           ▼
4.5 更新自描述（/code-self-describe --update）
           │
           ▼
5. 提交代码（Commit 1: 代码，遵循 /commit-convention）
           │
           ▼
6. 更新追溯 + 文档提交（/devdocs-sync → Commit 2: 文档）
        │
        ▼
6.5 更新 AGENTS.md "当前状态"（若存在）
    ├── 更新活跃任务编号 (T-XX)
    └── 更新进度统计 (X/Y)
        │
        ▼
7. [推荐] 知识沉淀（/devdocs-compound）
    ├── 批量模式完成后默认执行（用户可跳过）
    └── 单任务模式：提示用户是否运行 /devdocs-compound

步骤状态追踪

11 步执行流程中，每步完成后记录状态标记（S1~S11），用于断点恢复时精确定位。比原有 5 步检查点更精确，减少重复工作。

详见 execution-flow.md 步骤状态追踪表

代码追溯标注规范

实现文档↔代码的双向追溯，AI 在生成代码时自动添加标注。

标注类型

| 标注 | 用途 | 位置 | |------|------|------| | @requirement F-XXX | 关联功能点 | 接口/类/模块 | | @satisfies AC-XXX | 满足的验收标准 | 接口/方法 | | @verifies AC-XXX | 验证的验收标准 | 测试用例 | | @testcase UT/IT/E2E-XXX | 测试编号 | 测试用例 |

标注示例

/**
 * 创建用户
 * @requirement F-001 - 用户注册
 * @satisfies AC-001 - 邮箱格式校验
 * @satisfies AC-002 - 密码强度校验
 */
export async function createUser(dto: CreateUserDTO): Promise<User> {
  // 实现代码
}

/**
 * @verifies AC-001 - 邮箱格式校验
 * @testcase UT-001
 */
test('createUser 应该拒绝无效邮箱格式', () => {
  // 测试代码
});

标注规则

| 层级 | 标注位置 | 强制性 | |------|----------|--------| | 公共接口 | Service/API 入口方法 | 必须 | | 测试文件 | 每个测试用例 | 必须 | | 内部实现 | 复杂逻辑 | 可选 |

自顶向下开发模式

先定义骨架，后填充细节。确保追溯链在代码生成时就建立。

开发流程

Step 1: 生成接口骨架
        ├── 方法签名（来自 02-system-design.md）
        ├── 添加 @requirement/@satisfies 标注
        └── 方法体: throw new Error('Not implemented')
                │
                ▼
Step 2: 生成测试骨架
        ├── 测试结构（来自 03-test-cases.md）
        ├── 添加 @verifies/@testcase 标注
        └── 测试体: test.skip() 或 test.todo()
                │
                ▼
Step 3: 实现接口细节（遵循 /code-quality）
                │
                ▼
Step 4: 完善测试（遵循 /testing-guide）
                │
                ▼
Step 5: 运行 /devdocs-sync 更新追溯矩阵

骨架生成约束

[ ] 接口骨架必须包含完整签名（参数、返回值、泛型）
[ ] 接口骨架必须添加追溯标注
[ ] 未实现方法必须抛出 Error 并注明任务编号
[ ] 测试骨架必须使用 skip/todo 标记
[ ] 测试骨架必须添加 @verifies 和 @testcase 标注

详见 skeleton-examples.md

分层 TDD 模式

所有层级遵循统一 11 步执行流程，层级标记仅决定各步骤的强制程度：

| 层级 | 标记 | 强制步骤 | 推荐步骤 | 可选步骤 | |------|------|----------|----------|----------| | 核心逻辑 (Service/Domain) | 🔴 | 全部 11 步 | — | — | | 接口层 (Controller/API) | 🟡 | 骨架/实现/绿/AC/自描述/提交 | 测试断言/红/重构/验证 | — | | UI 层 (Component/View) | 🟢 | 骨架/实现/绿/AC/自描述/提交 | 测试断言/验证 | 红/重构 | | 基础设施 (DB/Config) | ⚪ | 骨架/实现/绿/AC/自描述/提交 | 测试骨架 | 测试断言/红/重构/验证 |

TDD 循环（统一流程核心）

┌─────┐    ┌─────┐    ┌─────┐
│ 红  │ → │ 绿  │ → │重构 │ ──┐
│写测试│    │写实现│    │优化 │   │
│(失败)│    │(通过)│    │代码 │   │
└─────┘    └─────┘    └─────┘   │
    ↑                           │
    └───────────────────────────┘

详见 execution-flow.md 统一任务执行流程 + 强制程度矩阵

编排规范（子 Agent 调度）

dev-workflow 调用以下技能时，必须通过 Task tool 启动子 Agent：

| 阶段 | 被调度技能 | 调度方式 | |------|-----------|----------| | 前置验证 | /devdocs-verify --impl | Task tool 子 Agent | | UI 对齐 | /devdocs-verify --ui | Task tool 子 Agent | | 追溯同步 | /devdocs-sync | Task tool 子 Agent | | 知识沉淀 | /devdocs-compound | Task tool 子 Agent | | 全量测试 | /devdocs-test-run | Task tool 子 Agent |

调度原则

上下文隔离：每个子 Agent 自行读取所需文档，dev-workflow 不传递全文
摘要传递：只接收子 Agent 返回的 YAML 摘要，据此决定下一步
异常回退：子 Agent 返回 status: failed + blockers 时，展示阻塞项询问用户
不自行排障：编排层不读取子技能的完整输出文档来尝试修复

Skill 协作

| 阶段 | 协作 Skill | 说明 | |------|-----------|------| | 写业务代码 | /code-quality | MTE 原则、依赖注入、避免过度设计 | | 写测试代码 | /testing-guide | 断言质量、变异测试、覆盖率 | | UI 实现 | /ui-orchestrator | 无障碍、动画、布局约束 | | 实现审查 | /devdocs-verify --impl | 前置验证：AC 满足度 + 设计一致性（DevDocs 功能开发任务） | | UI 对齐 | /devdocs-verify --ui | 前置验证：设计稿↔实现对齐（仅 UI 任务 + 有设计稿时） | | 完成验证 | /code-quality + /testing-guide | 对抗式验证：多视角审查 | | 完成检查 | /code-self-describe | 更新模块自描述（--update） | | 代码提交 | /git-safety | 使用 git mv/rm 处理文件 | | 提交信息 | /commit-convention | 遵循项目提交规范 | | 依赖解析 | /devdocs-dev-tasks | 读取任务依赖关系和状态 | | 任务完成 | /devdocs-sync | 后续：更新追溯矩阵（追溯同步） | | 知识沉淀 | /devdocs-compound | 推荐：sync 后提取经验模式（批量模式默认执行） | | 全量测试 | /devdocs-test-run | 批量完成后：全量测试 + 追溯验证（--trace） |

约束

骨架生成约束

[ ] 接口骨架必须包含完整签名
[ ] 接口骨架必须添加追溯标注
[ ] 未实现方法必须抛出 Error
[ ] 测试骨架必须使用 skip/todo 标记
[ ] 测试骨架必须添加 @verifies 和 @testcase 标注

分层 TDD 约束

[ ] 所有层级遵循统一 11 步执行流程（层级标记仅决定强制程度）
[ ] 核心逻辑任务必须标记 🔴 强制 TDD（全部 11 步 ■ 必须）
[ ] 核心逻辑任务必须先写测试，后写实现
[ ] 核心逻辑任务禁止在测试通过前提交
[ ] 接口层任务标记 🟡 推荐 TDD
[ ] UI 层任务标记 🟢 可选 TDD
[ ] 基础设施任务标记 ⚪ 推荐测试骨架
[ ] TDD 任务必须包含红-绿-重构三步骤
[ ] □/○ 步骤跳过时必须在提交信息中记录原因

完成检查约束

[ ] 验收标准 (AC-XXX) 全部满足
[ ] 关联测试全部通过
[ ] Review 要点自查完成
[ ] 代码追溯标注完整
[ ] 代码分支覆盖分析完成（可选，使用 /testing-guide 分支分析）

对抗式验证（可选）

以不同角色视角审查代码，模拟 "开发 → 审查 → 测试" 的多人协作模式。

触发条件

层级判定：任务层级标记（🔴🟡🟢⚪）来自 04-dev-tasks.md 中的任务定义，由 /devdocs-dev-tasks 在任务拆分时根据任务分层规则分配。

| 任务层级 | 默认行为 | 手动控制 | |---------|---------|---------| | 🔴 核心逻辑 | 自动触发 | --skip-review 跳过 | | 🟡 接口层 | 不触发 | --review 启用 | | 🟢 UI 层 | 不触发 | --review 启用 | | ⚪ 基础设施 | 不触发 | --review 启用 |

验证流程概要

基础完成检查（AC + 测试 + 标注）→ Phase 1: 代码质量审查（/code-quality 视角）→ Phase 2: 测试完备性审查（/testing-guide 视角）→ Phase 3: 综合报告（Blocker 必须修复 / Suggestion 可跳过）

执行对抗式验证时，必须读取 verification-flow.md 获取 AC↔diff 交叉验证规则、发现数量下限、发现分类标准和 --headless 下 Blocker/Suggestion 处理细则。

对抗式验证约束

[ ] Blocker 问题必须修复后才能提交
[ ] 每个 Phase 必须明确声明当前审查角色
[ ] 审查结果必须分级（Blocker/Suggestion）
[ ] 核心逻辑任务（🔴）默认触发
[ ] 修复 Blocker 后必须重新运行验证

依赖解析约束

[ ] 执行前必须完成依赖解析
[ ] 循环依赖必须报错终止（列出循环路径）
[ ] 已完成依赖跳过，不重复执行
[ ] 自动补充未完成的前置依赖到执行队列
[ ] "进行中"依赖通过 AskUserQuestion 询问用户

原子提交约束

[ ] 每个任务独立提交，不跨任务合并
[ ] 代码提交和文档提交分离（Commit 1: 代码，Commit 2: 文档状态 + trace 同步结果）
[ ] 提交前必须通过完成检查
[ ] 提交后更新 04-dev-tasks*.md 任务状态为 已完成
[ ] --single-commit 可将代码+文档合并为单次提交

断点续做约束

[ ] 每个任务开始前执行状态检测（5 步流水线）
[ ] 不相关变更必须警告用户（AskUserQuestion：stash/忽略/终止）
[ ] 已完成任务自动跳过
[ ] 进行中任务分析续做起点（11 步精确定位：S1~S11）
[ ] 文档状态 + Git 历史 + 工作区三重验证

详见 task-orchestration.md

`--auto-commit` 约束

[ ] 交互模式（非 headless），用户仍可观察过程
[ ] 测试全部通过且无 Blocker 时自动提交，不询问
[ ] 出现 Blocker 或测试失败时暂停询问
[ ] 与 --headless 互斥（--headless 已包含自动提交语义）
[ ] 安全不变量同 --headless：测试未通过不提交、Blocker 未解决不提交

记忆文件同步约束

[ ] 任务完成后检查项目根目录是否存在 AGENTS.md
[ ] 仅允许更新 ## 当前状态 章节（活跃任务编号、进度统计）
[ ] 禁止修改结构性章节（Project Overview、Skill Architecture、Conventions 等由 /agent-memory 管理）
[ ] CLAUDE.md 通过 @AGENTS.md 自动导入，无需同步
[ ] 仅做文本替换，不调用 /agent-memory
[ ] 格式须与 /agent-memory 模板保持一致
[ ] 若 AGENTS.md 不存在则跳过

全量测试验证约束

[ ] 批量模式完成后必须调用 /devdocs-test-run --trace
[ ] 单任务模式不触发全量测试（已在开发中运行自身测试）
[ ] 全量测试失败不回滚已提交任务
[ ] 交互模式：AskUserQuestion 询问是否修复失败测试
[ ] --headless / --auto-commit 模式：记录警告到交付报告，不中断

无人值守约束（--headless）

[ ] 工作区必须洁净（启动前 + 每任务 Commit 2 后校验）
[ ] 前置依赖不得处于"进行中"状态（否则 fail-fast）
[ ] fail-fast 后输出续做命令
[ ] 修复过程中标注不得删减
[ ] 修复过程中断言数量不得减少
[ ] Suggestion 自动跳过（除非 --fix-suggestions）
[ ] 绝不推送远程

详见 auto-mode.md

任务完成流程

所有层级遵循统一完成流程（层级标记决定各步骤强制程度，详见 execution-flow.md）：

确认测试状态：检查测试是否通过
确认 TDD 循环（■🔴 □🟡 ○🟢⚪）：测试从失败到通过的红-绿循环
检查重构（■🔴 □🟡 ○🟢⚪）：代码是否经过优化
验证验收标准：检查所有 AC 是否满足
对抗式验证（■🔴自动 / □🟡🟢--review / ○⚪--review）：
- Phase 1: 代码质量审查（/code-quality 视角）
- Phase 2: 测试完备性审查（/testing-guide 视角）
- Phase 3: 综合报告，处理 Blocker
更新自描述：运行 /code-self-describe --update
提交决策：
- --headless 模式：自动提交（安全不变量已在前置步骤保证）
- --auto-commit 模式：测试通过 + 无 Blocker 时自动提交
- 交互模式：AskUserQuestion："任务 T-XX 已完成，是否提交代码？"
  - 选项："提交" / "继续修改" / "跳过"
如提交（原子提交）：
- Commit 1: 代码提交 <type>(T-XX): <名称>
- 更新 04-dev-tasks*.md 状态 + /devdocs-sync
- Commit 2: 文档提交 docs(T-XX): 更新任务状态并同步 trace
更新状态：TodoWrite 标记为已完成

提交信息格式

遵循 /commit-convention 规范，格式如下：

<type>(T-XX): <任务名称>

- <完成内容1>
- <完成内容2>

关联: F-XXX, AC-XXX
测试: UT-XXX, IT-XXX 通过

子 Agent 摘要格式

当本 Skill 作为子 Agent 运行时，返回以下结构化摘要：

skill: devdocs-dev-workflow
task: T-XX
status: success | failed | skipped
commits:
  code: "abc1234"      # Commit 1 hash
  docs: "def5678"      # Commit 2 hash
test_summary:
  passed: X
  failed: 0
  coverage: "XX%"
blockers_resolved: 0
suggestions_skipped: 0
ac_verified: [AC-001, AC-002]
next_task: T-YY | null

参考资料

skeleton-examples.md - 接口/测试骨架示例
execution-flow.md - 任务执行流程详解
verification-flow.md - 对抗式验证流程详解
task-orchestration.md - 多任务编排（批量/依赖/断点续做）
auto-mode.md - 无人值守模式详解

devdocs-dev-workflow

开发工作流

语言规则

模式选择

模式判断指引

触发条件

运行模式

语法

模式对比

批量执行流程

前置条件

工作流程

步骤状态追踪

代码追溯标注规范

标注类型

标注示例

标注规则

自顶向下开发模式

开发流程

骨架生成约束

分层 TDD 模式

TDD 循环（统一流程核心）

编排规范（子 Agent 调度）

调度原则

Skill 协作

约束

骨架生成约束

分层 TDD 约束

完成检查约束

对抗式验证（可选）

触发条件

验证流程概要

对抗式验证约束

依赖解析约束

原子提交约束

断点续做约束

--auto-commit 约束

记忆文件同步约束

全量测试验证约束

无人值守约束（--headless）

任务完成流程

提交信息格式

子 Agent 摘要格式

参考资料

`--auto-commit` 约束