devdocs-dev-workflow（开发文档 开发工作流程）

开发工作流

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

语言规则

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

模式选择

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

模式判断指引

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

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

触发条件

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

运行模式

语法

模式对比

批量执行流程

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

详见 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-001 - 用户注册
 * @satisfies AC-001 - 邮箱格式校验
 * @satisfies AC-002 - 密码强度校验
 */
export async function createUser(dto: CreateUserDTO): Promise<User> {
  // 实现代码
}

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

标注规则

自顶向下开发模式

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

开发流程

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

骨架生成约束

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

详见 skeleton-examples.md

分层 TDD 模式

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

TDD 循环（统一流程核心）

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

⚠️ 红阶段核心原则：断言必须来自 03-test-*.md 中对应 AC 的测试用例，禁止从实现代码反推测试。

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

编排规范（子 Agent 调度）

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

调度原则

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

Skill 协作

约束

骨架生成约束

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

分层 TDD 约束

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

完成检查约束

• 验收标准 (AC-XXX) 全部满足
• 关联测试全部通过
• Review 要点自查完成
• 代码追溯标注完整
• 代码分支覆盖分析完成（可选，补充性质，使用 /testing-guide 分支分析；业务逻辑分支应回溯为 AC 对应的正式测试）

对抗式验证（可选）

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

触发条件

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

验证流程概要

基础完成检查（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）：

1. 确认测试状态：检查测试是否通过
2. 确认 TDD 循环（■🔴 □🟡 ○🟢⚪）：测试从失败到通过的红-绿循环
3. 检查重构（■🔴 □🟡 ○🟢⚪）：代码是否经过优化
4. 验证验收标准：检查所有 AC 是否满足
5. 对抗式验证（■🔴自动 / □🟡🟢--review / ○⚪--review）：

- Phase 1: 代码质量审查（/code-quality 视角） - Phase 2: 测试完备性审查（/testing-guide 视角） - Phase 3: 综合报告，处理 Blocker

1. 更新自描述：运行 /code-self-describe --update
2. 提交决策：

- --headless 模式：自动提交（安全不变量已在前置步骤保证） - --auto-commit 模式：测试通过 + 无 Blocker 时自动提交 - 交互模式：AskUserQuestion："任务 T-XX 已完成，是否提交代码？" - 选项："提交" / "继续修改" / "跳过"

1. 如提交（原子提交）：

- Commit 1: 代码提交 <type>(T-XX): <名称> - 更新 04-dev-tasks*.md 状态 + /devdocs-sync - Commit 2: 文档提交 docs(T-XX): 更新任务状态并同步 trace

1. 更新状态：TodoWrite 标记为已完成

提交信息格式

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

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

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

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

type 类型：feat | fix | refactor | test | docs | chore

子 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 - 无人值守模式详解