writing-implementation-tasks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing Implementation Tasks as Commands

将实现任务编写为命令

Create implementation task breakdowns as Claude Code custom slash commands. Each task becomes an invokable

/command

that guides the agent through a single atomic implementation step.

Use this skill when breaking a feature spec and technical design into implementable tasks, planning implementation order, or defining what to build next.

Supporting files: CONTEXT-LAYERS.md for layer mapping details, EXAMPLES.md for complete examples.

将实现任务拆解为Claude Code自定义斜杠命令。每个任务都成为一个可调用的

/command

，指导Agent完成单个原子性的实现步骤。

适用场景：将功能规格和技术设计拆解为可落地的任务、规划实现顺序，或是确定下一步开发内容时。

参考文件：CONTEXT-LAYERS.md 包含层级映射细节，EXAMPLES.md 提供完整示例。

Why Commands?

为什么使用命令？

Implementation tasks as Claude Code commands provide:

On-demand execution: User runs
```
/task-1-data-model
```
to start a specific task
Self-contained context: Each command has all info needed for that task
Clear workflow: Progress tracked via a overview command
No wasted tokens: Only the current task is loaded, not the full task list

将实现任务作为Claude Code命令具备以下优势：

按需执行：用户运行
```
/task-1-data-model
```
即可启动特定任务
独立上下文：每个命令包含完成该任务所需的全部信息
清晰工作流：通过概览命令跟踪进度
高效token利用：仅加载当前任务，而非完整任务列表

Output Structure

输出结构

.claude/commands/{feature-name}/
├── overview.md                     # Progress tracker, run with /{feature-name}/overview
├── task-1-{short-name}.md          # Task 1 command
├── task-2-{short-name}.md          # Task 2 command
├── task-3-{short-name}.md          # Task 3 command
└── ...

.claude/commands/{feature-name}/
├── overview.md                     # 进度跟踪器，运行/{feature-name}/overview调用
├── task-1-{short-name}.md          # 任务1命令
├── task-2-{short-name}.md          # 任务2命令
├── task-3-{short-name}.md          # 任务3命令
└── ...

Template: Overview Command

模板：概览命令

.claude/commands/{feature-name}/overview.md

markdown

---
description: Show progress and next steps for {Feature Name} implementation
allowed-tools: Read, Glob, Grep
---

.claude/commands/{feature-name}/overview.md

markdown

---
description: Show progress and next steps for {Feature Name} implementation
allowed-tools: Read, Glob, Grep
---

{Feature Name} - Implementation Overview

{Feature Name} - 实现概览

<background_information>

PRD: skills/prd-{feature-name}/SKILL.md
Design: specs/design-{feature-name}.md (if exists)
Mission: Track implementation progress and guide to next task </background_information>

<background_information>

PRD：skills/prd-{feature-name}/SKILL.md
设计文档：specs/design-{feature-name}.md（若存在）
目标：跟踪实现进度并指导下一步任务 </background_information>

Execution Steps

执行步骤

Check the status of each task file in
```
.claude/commands/{feature-name}/
```
For each task, check if the "Done when" verification commands pass
Report progress summary and recommend the next task to run

检查
```
.claude/commands/{feature-name}/
```
中每个任务文件的状态
针对每个任务，检查“完成条件”中的验证命令是否全部通过
汇报进度摘要并推荐下一个待执行任务

Progress

进度

Task 1: {title} →
```
/{feature-name}/task-1-{short-name}
```
Task 2: {title} →
```
/{feature-name}/task-2-{short-name}
```
Task 3: {title} →
```
/{feature-name}/task-3-{short-name}
```
Task 4: {title} →
```
/{feature-name}/task-4-{short-name}
```

任务1：{标题} →
```
/{feature-name}/task-1-{short-name}
```
任务2：{标题} →
```
/{feature-name}/task-2-{short-name}
```
任务3：{标题} →
```
/{feature-name}/task-3-{short-name}
```
任务4：{标题} →
```
/{feature-name}/task-4-{short-name}
```

Dependency Order

依赖顺序

Task 1 (no deps)
  └─► Task 2 (depends: Task 1)
       └─► Task 3 (depends: Task 2)
            └─► Task 4 (depends: Task 2, Task 3)

</instructions>

任务1（无依赖）
  └─► 任务2（依赖：任务1）
       └─► 任务3（依赖：任务2）
            └─► 任务4（依赖：任务2、任务3）

</instructions>

Output Description

输出说明

Report: which tasks are done, which is next, and the command to run it.

undefined

汇报内容：已完成的任务、下一个待执行任务及其调用命令。

undefined

Template: Task Command

模板：任务命令

.claude/commands/{feature-name}/task-{N}-{short-name}.md

markdown

---
description: {Task title} for {Feature Name}
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
---

.claude/commands/{feature-name}/task-{N}-{short-name}.md

markdown

---
description: {Task title} for {Feature Name}
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
---

Task {N}: {Title}

任务{N}：{标题}

<background_information>

PRD: skills/prd-{feature-name}/SKILL.md
Design: specs/design-{feature-name}.md
Depends on: {Task M title} (task-{M}-{short-name})
Spec refs: {FR-1, FR-2, ...} </background_information>

<background_information>

PRD：skills/prd-{feature-name}/SKILL.md
设计文档：specs/design-{feature-name}.md
依赖任务：{任务M标题}（task-{M}-{short-name}）
规格参考：{FR-1, FR-2, ...} </background_information>

Core Task

核心任务

{Concise implementation instructions. 3-10 lines. Reference interface contracts from design doc, not repeat them.}

{简洁的实现说明，3-10行。参考设计文档中的接口契约，无需重复内容。}

Scope

范围

Files to create or modify:

```
{path/to/file1}
```
```
{path/to/file2}
```

Do NOT modify files outside this scope.

需创建或修改的文件：

```
{path/to/file1}
```
```
{path/to/file2}
```

禁止修改此范围外的文件。

Steps

步骤

{Step 1}
{Step 2}
{Step 3}

</instructions>

{步骤1}
{步骤2}
{步骤3}

</instructions>

Done When

完成条件

Run these verification commands. ALL must pass before this task is complete:

bash

{verification command 1}
{verification command 2}

运行以下验证命令，全部通过后方可标记任务完成：

bash

{验证命令1}
{验证命令2}

Safety & Fallback

安全与回退

If verification fails, fix and re-run — do not skip
If blocked by a dependency, report which task must be completed first
Do not modify files outside the defined scope

undefined

若验证失败，修复后重新运行——不得跳过
若被依赖任务阻塞，需汇报需先完成的任务
不得修改定义范围外的文件

undefined

Writing Guidelines

编写指南

Task Scope: Atomic and Committable

任务范围：原子性与可提交性

Each task command must be completable in a single atomic commit:

markdown

<!-- BAD: Too broad -->

每个任务命令必须可在单次原子提交内完成：

markdown

<!-- 错误示例：范围过宽 -->

Core Task

核心任务

Implement the notification system

实现通知系统

Core Task

核心任务

Create

internal/notification/model.go

(types) and

migrations/005_notifications.sql

(DDL from design doc)

创建

internal/notification/model.go

（类型定义）和

migrations/005_notifications.sql

（来自设计文档的DDL）

Scope

范围

```
internal/notification/model.go
```
```
migrations/005_notifications.sql
```

undefined

```
internal/notification/model.go
```
```
migrations/005_notifications.sql
```

undefined

Task Ordering: Dependency-Driven

任务排序：依赖驱动

Order tasks so each builds on the previous. Follow bottom-up pattern:

task-1-data-model       (no dependencies)
task-2-repository       (depends: task-1)
task-3-service          (depends: task-2)
task-4-handler          (depends: task-3)
task-5-integration      (depends: all above)
task-6-tests            (depends: task-5)

按照依赖关系对任务排序，遵循自底向上的模式：

task-1-data-model      （无依赖）
task-2-repository      （依赖：task-1）
task-3-service         （依赖：task-2）
task-4-handler         （依赖：task-3）
task-5-integration     （依赖：以上所有）
task-6-tests           （依赖：task-5）

Spec References: Link, Don't Repeat

规格参考：链接而非重复

Tasks reference requirement IDs and design components:

markdown

undefined

任务需引用需求ID和设计组件：

markdown

undefined

Core Task

核心任务

Implement the NotificationSender interface defined in specs/design-notifications.md (Component: Notification Sender). Follow the interface contract exactly. Use FCM SDK for Android delivery per Decision Summary.

undefined

实现specs/design-notifications.md中定义的NotificationSender接口（组件：Notification Sender）。严格遵循接口契约，根据决策摘要使用FCM SDK实现Android端推送。

undefined

Verification: Executable Checks

验证：可执行的检查

Every task's "Done When" must be runnable commands:

markdown

undefined

每个任务的“完成条件”必须包含可运行的命令：

markdown

undefined

Done When

完成条件

bash

go test ./internal/notification/model/...
sqlc generate
go vet ./...

undefined

bash

go test ./internal/notification/model/...
sqlc generate
go vet ./...

undefined

Command Description: Clear and Actionable

命令描述：清晰且可执行

The

description

field in frontmatter drives command discovery:

yaml

undefined

前置元数据中的

description

字段决定命令的可发现性：

yaml

undefined

BAD: vague

错误示例：模糊不清

description: Do task 1

description: 完成任务1

GOOD: specific

正确示例：具体明确

description: Create notification data model and database migrations for push notifications

undefined

description: 为推送通知创建通知数据模型和数据库迁移脚本

undefined

Task Granularity Guide

任务粒度指南

Task size	Lines of code	Good for
Too small	< 20 LOC	Merge into adjacent task
Right size	20-200 LOC	Single focused change
Too large	> 200 LOC	Split into sub-tasks

Signs a task is too large:

Instructions exceed 15 lines
Scope spans 3+ unrelated directories
Multiple independent verification steps

Signs a task is too small:

Just creating a single type definition
Only adding an import
Purely mechanical rename/move

任务规模	代码行数	适用场景
过小	< 20 LOC	合并至相邻任务
合适	20-200 LOC	单一聚焦的变更
过大	> 200 LOC	拆分为子任务

任务规模过大的迹象：

说明内容超过15行
范围覆盖3个及以上不相关目录
包含多个独立的验证步骤

任务规模过小的迹象：

仅创建单个类型定义
仅添加导入语句
纯机械性的重命名/移动操作

Handling Blocked Tasks

处理阻塞任务

When a task depends on incomplete work, the command should detect and report it:

markdown

<instructions>

当任务依赖未完成的工作时，命令应能检测并汇报：

markdown

<instructions>

Pre-check

前置检查

Before starting, verify dependencies are complete:

Check that
```
internal/notification/model.go
```
exists (from Task 1)
If missing, report: "Task 1 must be completed first. Run /{feature}/task-1-data-model" </instructions>

undefined

开始前，验证依赖任务是否完成：

检查
```
internal/notification/model.go
```
是否存在（来自任务1）
若不存在，汇报：“需先完成任务1，请运行/{feature}/task-1-data-model” </instructions>

undefined

Lifecycle

生命周期

1. Start from approved feature spec (Agent Skill) + technical design
2. Identify implementation units from components in design doc
3. Order tasks by dependency (bottom-up)
4. Create .claude/commands/{feature}/ directory
5. Write overview.md with progress checklist
6. Write each task-{N}-{short-name}.md with scope, steps, verification
7. User runs /{feature}/overview to see status
8. User runs /{feature}/task-{N}-{short-name} to implement each task
9. After all tasks done, optionally archive or remove command directory

1. 从已批准的功能规格（Agent Skill）和技术设计开始
2. 从设计文档的组件中识别实现单元
3. 按照依赖关系对任务排序（自底向上）
4. 创建.claude/commands/{feature}/目录
5. 编写overview.md，包含进度检查清单
6. 编写每个task-{N}-{short-name}.md，包含范围、步骤和验证规则
7. 用户运行/{feature}/overview查看状态
8. 用户运行/{feature}/task-{N}-{short-name}执行每个任务
9. 所有任务完成后，可选择归档或删除命令目录

Quality Checklist

质量检查清单

Implementation Tasks (Commands) Quality Check:
- [ ] Directory: .claude/commands/{feature-name}/
- [ ] overview.md exists with progress checklist and dependency graph
- [ ] Each task is a separate command file: task-{N}-{short-name}.md
- [ ] Each command has frontmatter: description, allowed-tools
- [ ] Tasks ordered by dependency (bottom-up)
- [ ] Each task has: background_information, instructions, done-when
- [ ] Each task is atomic (single commit, 20-200 LOC)
- [ ] Instructions reference spec/design, don't repeat them
- [ ] "Done When" has executable verification commands
- [ ] No task spans 3+ unrelated directories
- [ ] Scope section explicitly lists files to create/modify
- [ ] Pre-check verifies dependencies before starting

实现任务（命令）质量检查：
- [ ] 目录：.claude/commands/{feature-name}/
- [ ] 存在overview.md，包含进度检查清单和依赖图
- [ ] 每个任务为独立的命令文件：task-{N}-{short-name}.md
- [ ] 每个命令包含前置元数据：description、allowed-tools
- [ ] 任务按依赖关系排序（自底向上）
- [ ] 每个任务包含：background_information、instructions、done-when
- [ ] 每个任务具备原子性（单次提交，20-200 LOC）
- [ ] 说明内容引用规格/设计文档，不重复内容
- [ ] “完成条件”包含可执行的验证命令
- [ ] 无任务覆盖3个及以上不相关目录
- [ ] 范围部分明确列出需创建/修改的文件
- [ ] 前置检查会在开始前验证依赖任务

Detailed Guides

详细指南

Context layer mapping details: See CONTEXT-LAYERS.md Complete task breakdown examples: See EXAMPLES.md

上下文层级映射细节：查看CONTEXT-LAYERS.md 完整任务分解示例：查看EXAMPLES.md