doc-tasks

doc-tasks

用途

创建任务分解（TASKS）——SDD 工作流中的第 11 层制品，将 SPEC 分解为可执行、面向 AI 的结构化 TODO 任务，以供实现。

层级：11

上游：BRD（第 1 层）、PRD（第 2 层）、EARS（第 3 层）、BDD（第 4 层）、ADR（第 5 层）、SYS（第 6 层）、REQ（第 7 层）、IMPL（第 8 层）、CTR（第 9 层）、SPEC（第 10 层）

下游制品：代码（第 12 层）

前置条件

上游制品验证（关键）

创建本文档之前，必须：

1. 列出已有的上游制品：

   ls docs/01_BRD/ docs/02_PRD/ docs/03_EARS/ docs/04_BDD/ docs/05_ADR/ docs/06_SYS/ docs/07_REQ/ 2>/dev/null
   

2. 在可追溯性标签中仅引用已有文档

3. 仅当上游制品类型确实不存在时，才使用 null

4. 绝不使用 BRD-XXX 或 TBD 等占位符

5. 不要创建缺失的上游制品——应跳过相关功能

创建 TASKS 之前，请阅读：

1. 共享标准：.claude/skills/doc-flow/SHARED_CONTENT.md
2. 上游 SPEC：阅读技术规范（主要来源）
3. 模板：ai_dev_flow/11_TASKS/TASKS-TEMPLATE.md
4. 创建规则：ai_dev_flow/11_TASKS/TASKS_CREATION_RULES.md
5. 验证规则：ai_dev_flow/11_TASKS/TASKS_VALIDATION_RULES.md
6. 验证脚本：./ai_dev_flow/scripts/validate_tasks.sh
7. 实现契约指南：ai_dev_flow/11_TASKS/IMPLEMENTATION_CONTRACTS_GUIDE.md

何时使用此技能

在以下情况下使用 doc-tasks：

• 已完成从 BRD 到 SPEC 的各层文档（第 1–10 层）
• 准备将 SPEC 分解为可执行任务
• 为实现规划（第 12 层）做准备
• 需要为 AI Agent 提供结构化 TODO 格式
• 当前处于 SDD 工作流的第 11 层

保留 ID 豁免（TASKS-00_*）

范围：ID 为保留值 000 的文档完全免于验证。

模式：TASKS-00_*.md

文档类型：

• 索引文档（TASKS-00_index.md）
• 可追溯性矩阵模板（TASKS-00_TRACEABILITY_MATRIX-TEMPLATE.md）
• 实现契约检查清单（TASKS-00_IMPLEMENTATION_CONTRACTS_CHECKLIST.md）
• 术语表、注册表

原因：保留 ID 为 000 的文档属于框架基础设施（索引、模板、参考资料），而非需要可追溯性或质量门禁的项目制品。

验证行为：当文件名匹配 TASKS-00_* 模式时，跳过所有检查。

元素 ID 格式（强制）

模式：TASKS.{DOC_NUM}.{HASH}（3 个以点分隔的段）

元素类型	代码	示例
任务	18	TASKS.02.1801
任务项	30	TASKS.02.3001

已移除的模式——不要使用：

• TASK-XXX → 使用 TASKS.NN.18.SS
• T-XXX → 使用 TASKS.NN.18.SS

参考：ID_NAMING_STANDARDS.md — 跨引用链接格式

修正示例：将 ### TASK-01: Implementation 替换为 ### TASKS.02.1801: Implementation

TASKS 专属指南

1. 面向 AI 的结构化 TODO 格式

用途：将 SPEC 分解为 AI 编码 Agent 可使用的任务

格式：

## Tasks

### Phase 1: Project Setup (3 tasks)

**TASKS.01.1801: Initialize Project Structure**
- **Action**: Create directory structure per SPEC architecture
- **Files to Create**:
  - `src/controllers/data_validation_controller.py`
  - `src/services/data_validator.py`
  - `src/repositories/data_repository.py`
  - `src/models/data_request.py`
- **Dependencies**: None
- **Estimated Effort**: 30 minutes
- **SPEC Reference**: SPEC-01:implementation.modules
- **Success Criteria**: All directories and empty files created

**TASKS.01.1802: Set Up Development Environment**
- **Action**: Configure Python environment and dependencies
- **Files to Create**: `requirements.txt`, `pyproject.toml`
- **Dependencies**: TASKS.01.1801
- **Estimated Effort**: 1 hour
- **SPEC Reference**: SPEC-01:deployment.container
- **Success Criteria**: `pip install -r requirements.txt` succeeds

### Phase 2: Data Models (2 tasks)

**TASKS.01.1803: Implement DataRequest Model**
- **Action**: Create Pydantic model per CTR-01 schema
- **Files to Modify**: `src/models/data_request.py`
- **Dependencies**: TASKS.01.1802
- **Estimated Effort**: 1 hour
- **SPEC Reference**: SPEC-01:interfaces.data_models
- **CTR Reference**: CTR-01#/components/schemas/DataRequest
- **Success Criteria**: Model validates per schema, unit tests pass

2. 必需章节

文档控制（强制——必须位于所有编号章节之前的第一节）

核心章节：

1. 概述：任务分解摘要
2. 任务层级：阶段和任务组
3. 任务：详细的任务分解（主要内容）
4. 依赖关系图：任务依赖关系可视化图（Mermaid 图表）
5. 工作量汇总：按阶段汇总的总工作量
6. 可追溯性：采用第 7 节格式，并使用累积标签
7. 实现契约：第 8 节（强制）——提供和使用的契约

3. 任务编号格式

格式：TASKS.{SPEC-ID}.18.{SEQ}（统一的元素 ID 格式）

示例：TASKS.01.1803 表示：

• SPEC-01（来自 SPEC-01_data_validation.yaml）
• 元素类型 18（任务）
• 序号 03（分解中的第 3 个任务）

优点：

• 将任务直接关联到 SPEC
• 确保项目中的任务 ID 唯一
• 便于在提交中引用

4. 任务字段（必填）

每项任务 MUST 包含：

1. 任务 ID：TASKS.{SPEC-ID}.18.{SEQ}
2. 标题：简短描述（5-10 个词）
3. 操作：要执行的操作（祈使形式）
4. 要创建/修改的文件：具体文件路径
5. 依赖项：其他 TASK ID（或“None”）
6. 预计工作量：时间估算
7. SPEC 参考：SPEC 中的章节（例如，SPEC-01:implementation.modules）
8. 成功标准：如何验证已完成
9. 可选：CTR 参考：适用时提供合约链接

5. 阶段组织

典型阶段：

1. 阶段 1：项目设置（基础设施、环境）
2. 阶段 2：数据模型（架构、模型、验证）
3. 阶段 3：业务逻辑（服务、核心算法）
4. 阶段 4：API 层（控制器、端点）
5. 阶段 5：错误处理（错误代码、中间件）
6. 阶段 6：配置（环境变量、功能标志）
7. 阶段 7：测试（单元测试、集成测试、性能测试）
8. 阶段 8：部署（Docker、CI/CD、监控）

6. 依赖关系图

仅使用 Mermaid 图（根据 ai_dev_ssd_flow/DIAGRAM_STANDARDS.md，禁止使用文本图）：

## Dependencies Graph

```mermaid
graph TD
    T001[TASKS.01.1801: Project Setup]
    T002[TASKS.01.1802: Dev Environment]
    T003[TASKS.01.1803: DataRequest Model]
    T004[TASKS.01.1804: ValidationResponse Model]
    T005[TASKS.01.1805: Data Repository]
    T006[TASKS.01.1806: Data Validator Service]
    T007[TASKS.01.1807: API Controller]

    T001 --> T002
    T002 --> T003
    T002 --> T004
    T002 --> T005
    T003 --> T006
    T004 --> T006
    T005 --> T006
    T006 --> T007

### 7. Effort Summary

**Format**:
```markdown
## Effort Summary

| Phase | Tasks | Total Effort |
|-------|-------|--------------|
| Phase 1: Project Setup | 2 | 1.5 hours |
| Phase 2: Data Models | 2 | 2 hours |
| Phase 3: Business Logic | 3 | 4 hours |
| Phase 4: API Layer | 1 | 1.5 hours |
| Phase 5: Error Handling | 2 | 2 hours |
| Phase 6: Configuration | 1 | 1 hour |
| Phase 7: Testing | 3 | 3 hours |
| Phase 8: Deployment | 2 | 2 hours |
| **TOTAL** | **16** | **17 hours** |

**Assumptions**:
- Developer familiar with Python and FastAPI
- PostgreSQL database already provisioned
- OAuth service already available

8. 实现合约（强制）

所有 TASKS 文件都必须包含第 8 节。实现合约支持对具有依赖关系的 TASKS 文件进行并行开发。

结构：

## 8. Implementation Contracts

### 8.1 Contracts Provided by This TASKS
@icon: TASKS-XXX:ContractName
@icon-role: provider

- **Contract Name**: [Interface name]
- **Type**: Protocol Interface | Exception Hierarchy | State Machine | Data Model | DI Interface
- **Consumers**: List of TASKS IDs that depend on this contract
- **Purpose**: Brief description

### 8.2 Contracts Consumed by This TASKS
@icon: TASKS-YYY:OtherContract
@icon-role: consumer

- **Provider**: TASKS-YYY
- **Contract Name**: [Interface name]
- **Purpose**: Why this TASKS needs this contract

### 8.3 No Contracts
If this TASKS provides no contracts and consumes no contracts, state explicitly:
"This TASKS document neither provides nor consumes implementation contracts."

何时创建合约：

• TASKS 有 3 个或更多下游依赖项
• 多个实现会话之间共享接口
• 复杂的状态机或异常层级结构
• 需要并行开发

合约类型：

1. 协议接口：包含方法签名的 typing.Protocol
2. 异常层级结构：带错误代码的类型化异常
3. 状态机合约：包含有效转换的 Enum 状态
4. 数据模型：Pydantic/TypedDict 架构
5. DI 接口：用于依赖注入的 ABC 类

参考：详细指南请参阅 ai_dev_flow/11_TASKS/IMPLEMENTATION_CONTRACTS_GUIDE.md。

标签格式约定（设计如此）

SDD 框架使用两种不同的标注系统来进行交叉引用：

标注	格式	工件	用途
连字符	TYPE-NN	ADR、SPEC、CTR	技术工件——引用文件/文档
点号	TYPE.NN.xxxx	BRD、PRD、EARS、BDD、SYS、REQ、IMPL、TASKS	层级工件——引用文档内部的元素

主要区别：

• @adr: ADR-033 → 指向文档 ADR-033_risk_limit_enforcement.md
• @brd: BRD.17.0101 → 指向文档 BRD-017.md 中的元素 01.01

统一元素 ID 格式（强制）

对于层级需求（BRD、PRD、EARS、BDD、SYS、REQ）：

• 始终使用：TYPE.NN.xxxx（点号分隔符，统一的 3 段格式）
• 切勿使用：TYPE-NN:NNN（冒号分隔符——已弃用）
• 切勿使用：TYPE.NN.TT.SS（旧的 4 段格式——已弃用）

示例：

• @brd: BRD.17.0101 ✅
• @brd: BRD.017.001 ❌（旧的 3 段格式）

累积标签要求

第 11 层（TASKS）：必须包含第 1-10 层的标签

标签数量：8-10 个标签（最少 8 个，最多 10 个）

累积标签的元素类型代码

工件	元素类型	代码	示例
BRD	业务需求	01	BRD.01.0103
PRD	产品功能	07	PRD.01.0702
EARS	声明	25	EARS.01.2501
BDD	场景	14	BDD.01.1401
SYS	系统需求	26	SYS.01.2601
REQ	原子需求	27	REQ.01.2701
IMPL	实现阶段	29	IMPL.01.2901

最少（跳过 IMPL 和 CTR）：

## Traceability

**Required Tags** (Cumulative Tagging Hierarchy - Layer 11):
```markdown
@brd: BRD.01.0103
@prd: PRD.01.0702
@ears: EARS.01.2501
@bdd: BDD.01.1401
@adr: ADR-033, ADR-045
@sys: SYS.01.2601
@req: REQ.01.2701
@spec: SPEC-01

最多（包含 IMPL、CTR 和 ICON）：

@brd: BRD.01.0103
@prd: PRD.01.0702
@ears: EARS.01.2501
@bdd: BDD.01.1401
@adr: ADR-033, ADR-045
@sys: SYS.01.2601
@req: REQ.01.2701
@impl: IMPL.01.2901
@ctr: CTR-01
@spec: SPEC-01
@icon: TASKS-01:DataValidator  # if providing or consuming implementation contracts
@icon-role: provider  # or consumer

上游/下游产物

上游来源：

• BRD（第 1 层）- 业务需求
• PRD（第 2 层）- 产品功能
• EARS（第 3 层）- 正式需求
• BDD（第 4 层）- 测试场景
• ADR（第 5 层）- 架构决策
• SYS（第 6 层）- 系统需求
• REQ（第 7 层）- 原子需求
• IMPL（第 8 层）- 实现方案（可选）
• CTR（第 9 层）- 数据契约（可选）
• SPEC（第 10 层）- 技术规格（主要来源）

下游产物：

• Code（第 12 层）- 实现代码（在 src/ 中创建）
• Tests（第 13 层）- 测试套件

同类型文档关系（有条件）：

• @related-tasks: TASKS-NN - 共享实现上下文的 TASKS
• @depends-tasks: TASKS-NN - 必须先完成的 TASKS

验证检查

第 1 级：错误（阻止流程）

检查	说明
CHECK 1	文件名格式有效（TASKS-NN_slug_tasks.md）
CHECK 2	存在包含必填字段的 YAML frontmatter
CHECK 3	文档控制表完整（8 个字段）
CHECK 4	存在全部 8 个必需章节
CHECK 5	存在第 8 节（实现契约），且包含 8.1/8.2/8.3 小节
CHECK 6	存在全部 8 个必需的可追溯性标签
CHECK 7	父级 SPEC 引用有效且文件存在
CHECK 8	元素 ID 格式符合要求（TASKS.NN.xxxx）

第 2 级：警告

检查	说明
CHECK W1	范围章节记录了排除项
CHECK W2	计划至少包含 3 个编号步骤
CHECK W3	存在 SPEC 行引用
CHECK W4	至少有 3 个验收标准复选框
CHECK W5	验收标准中包含 BDD 场景引用
CHECK W6	使用 @icon 标签时，存在 @icon-role 标签

第 3 级：信息

检查	说明
CHECK I1	计划中包含时间估算
CHECK I2	存在可选的 @impl 和 @ctr 标签
CHECK I3	ICON 引用有效且文件存在

创建流程

第 1 步：读取上游 SPEC

读取需要分解的 SPEC（第 10 层）- 技术规格。

第 2 步：预留 ID 编号

检查 docs/11_TASKS/，找到下一个可用的 ID 编号。

ID 编号约定：以 2 位数字开头，仅在需要时扩展位数。

• ✅ 正确：TASKS-01、TASKS-99、TASKS-102
• ❌ 错误：TASKS-001、TASKS-009（无需额外的前导零）

ID 匹配：TASKS ID 通常与 SPEC ID 匹配（TASKS-01 来自 SPEC-01）。

第 3 步：创建 TASKS 文件

嵌套文件夹规则（强制）：所有 TASKS 文档都必须使用嵌套文件夹，无论文档大小如何。

文件命名：docs/11_TASKS/TASKS-NN_{slug}/TASKS-NN_{slug}.md

示例：docs/11_TASKS/TASKS-01_data_validation/TASKS-01_data_validation.md

重要：切勿在 docs/11_TASKS/ 中直接创建 TASKS 文件，而不使用嵌套文件夹结构。

第 4 步：填写文档控制章节

完成元数据和文档修订历史表。

第 5 步：撰写概述

概述任务分解方案。

第 6 步：定义阶段

将任务组织为逻辑阶段（通常为 8 个阶段）。

第 7 步：创建详细任务

对于 SPEC 中的每项任务：

• 分配 TASK ID（TASKS.{SPEC-ID}.18.{SEQ}）
• 编写清晰的操作（祈使句）
• 列出要创建/修改的文件
• 确定依赖项
• 估算工作量
• 引用 SPEC 章节
• 定义成功标准

第 8 步：创建依赖关系图

使用 Mermaid 图表展示任务依赖关系。

第 9 步：计算工作量汇总

按阶段汇总总工作量。

第 10 步：添加累积标签

包含所有 8-10 个上游标签（从 @brd 到 @spec）。

第 11 步：创建/更新可追溯性矩阵

强制：更新 docs/TASKS/TASKS-00_TRACEABILITY_MATRIX.md

第 12 步：验证 TASKS

./ai_dev_flow/scripts/validate_tasks.sh docs/TASKS/TASKS-01_*.md

python ai_dev_flow/scripts/validate_tags_against_docs.py --artifact TASKS-01 --expected-layers brd,prd,ears,bdd,adr,sys,req,impl,contracts,spec --strict

第 13 步：提交更改

提交 TASKS 文件和可追溯性矩阵。

验证

自动验证

# Quality gates
./scripts/validate_quality_gates.sh docs/TASKS/TASKS-01_*.md

# Task format validation
./ai_dev_flow/scripts/validate_tasks.sh docs/TASKS/TASKS-01_*.md

# Cumulative tagging
python ai_dev_flow/scripts/validate_tags_against_docs.py \
  --artifact TASKS-01 \
  --expected-layers brd,prd,ears,bdd,adr,sys,req,impl,contracts,spec \
  --strict

手动检查清单

• 顶部包含文档控制部分
• 概述说明了拆解方法
• 任务按阶段组织（通常为 8 个阶段）
• 每项任务都具有 TASKS.{SPEC-ID}.18.{SEQ} ID
• 每项任务都包含所有必填字段
• 已识别依赖项（或填写“无”）
• 已提供工作量估算
• 已包含 SPEC 引用
• 成功标准清晰且可测试
• 已创建依赖关系图（Mermaid 图表）
• 已计算工作量摘要
• 第 8 节实施契约已完成（提供方/使用方/无）
• 已包含累积标签：从 @brd 到 @spec（8-10 个标签）
• 如果提供/使用契约，已添加 @icon 标签
• 已更新可追溯性矩阵

图表标准

所有图表都必须使用 Mermaid 语法。禁止使用基于文本的图表（ASCII 艺术、框线图）。 请参阅 ai_dev_ssd_flow/DIAGRAM_STANDARDS.md 和 mermaid-gen 技能。

常见问题

1. 任务含糊：任务必须具体且可执行
2. 缺少依赖项：必须识别任务依赖项
3. 没有工作量估算：规划需要工作量估算
4. 缺少 SPEC 引用：每项任务都必须链接到 SPEC 章节
5. 没有成功标准：必须定义如何验证完成情况
6. 缺少累积标签：第 11 层必须包含所有 8-10 个上游标签
7. 缺少第 8 节：实施契约部分为必填项
8. 基于文本的图表：依赖关系图只能使用 Mermaid
9. 旧版任务 ID：使用 TASKS.NN.18.SS，而不是 TASK-XXX 或 T-XXX

创建后验证（必填——无需确认）

重要：创建文档后，立即执行此验证循环。验证通过前，不得继续处理下一份文档。

自动验证循环

LOOP:
  1. Run: python ai_dev_flow/scripts/validate_cross_document.py --document {doc_path} --auto-fix
  2. IF errors fixed: GOTO LOOP (re-validate)
  3. IF warnings fixed: GOTO LOOP (re-validate)
  4. IF unfixable issues: Log for manual review, continue
  5. IF clean: Mark VALIDATED, proceed

验证命令

# Per-document validation (Phase 1)
python ai_dev_flow/scripts/validate_cross_document.py --document docs/TASKS/TASKS-NN_slug.md --auto-fix

# Layer validation (Phase 2) - run when all TASKS documents complete
python ai_dev_flow/scripts/validate_cross_document.py --layer TASKS --auto-fix

特定层的上游要求

当前层	必需的上游标签	数量
TASKS（第 11 层）	@brd、@prd、@ears、@bdd、@adr、@sys、@req、@spec（如果已创建，还需 @impl、@ctr）	8-10 个标签

自动修复操作（无需确认）

问题	修复操作
缺少上游标签	添加标签并引用上游文档
标签格式无效	更正为 TYPE.NN.xxxx（三段式）或 TYPE-NN 格式
链接失效	根据当前位置重新计算路径
缺少可追溯性部分	从模板插入

验证代码参考

代码	描述	严重程度
XDOC-001	未找到引用的需求 ID	错误
XDOC-002	缺少累积标签	错误
XDOC-003	未找到上游文档	错误
XDOC-006	标签格式无效	错误
XDOC-007	累积标签链存在缺口	错误
XDOC-009	缺少可追溯性部分	错误

质量门禁

阻塞：是——第 1 阶段验证通过且错误数为 0 之前，不得继续处理下一份文档。

---

下一项技能

完成 TASKS 后，继续进行实施：

• 代码（第 12 层）- 编写实现代码
• 测试（第 13 层）- 创建测试套件
• 验证（第 14 层）- 运行验证检查

参考文档

TASKS 产物不支持 REF 文档。根据 SDD 框架，参考文档仅限 BRD 和 ADR 类型。

如需补充文档，请创建：

• BRD-REF：业务背景文档
• ADR-REF：任务估算指南、依赖关系分析报告

相关资源

• 模板：ai_dev_flow/11_TASKS/TASKS-TEMPLATE.md（主要权威来源）
• TASKS 创建规则：ai_dev_flow/11_TASKS/TASKS_CREATION_RULES.md
• TASKS 验证规则：ai_dev_flow/11_TASKS/TASKS_VALIDATION_RULES.md
• TASKS README：ai_dev_flow/11_TASKS/README.md
• 共享标准：.claude/skills/doc-flow/SHARED_CONTENT.md

章节模板（适用于超过 25K 个词元的文档）：

• 索引模板：ai_dev_flow/11_TASKS/TASKS-SECTION-0-TEMPLATE.md
• 内容模板：ai_dev_flow/11_TASKS/TASKS-SECTION-TEMPLATE.md
• 参考：ai_dev_flow/ID_NAMING_STANDARDS.md（基于章节的文件拆分）

快速参考

TASKS 目的：将 SPEC 分解为可执行的、由 AI 结构化的 TODO 任务

层级：11

元素 ID 格式：TASKS.NN.18.SS

• 任务 = 18
• 任务项 = 30

已移除的模式：TASK-XXX、T-XXX

必需标签：@brd 至 @spec（8-10 个标签）

格式：按阶段划分、由 AI 结构化的 TODO

任务 ID 格式：TASKS.{SPEC-ID}.18.{SEQ}

必需任务字段：

• 任务 ID、标题、操作
• 要创建/修改的文件
• 依赖项
• 预估工作量
• SPEC 参考
• 成功标准

关键章节：

• 任务层级（阶段）
• 详细任务（主要内容）
• 依赖关系图（Mermaid）
• 工作量摘要
• 实施约定（第 8 节 - 必需）

下一步：实施（代码 → 测试 → 验证）

---

版本历史

版本	日期	变更	作者
1.0	2026-02-08	首次定义技能并标准化 YAML frontmatter	System