write-atomic-tasks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write Atomic Tasks

编写原子任务

Quick Start

快速入门

Transform vague task descriptions into precise, autonomous-execution-ready specifications:

markdown

❌ BEFORE (vague):
- [ ] Add error handling

✅ AFTER (precise):
- [ ] Task 1: Add ConnectionError and TimeoutError handling to ClaudeAgentClient.query()
      - Retry 3 times with exponential backoff (1s, 2s, 4s)
      - Raise AgentConnectionError after retries exhausted
      - Location: src/temet_run/agent/client.py:ClaudeAgentClient.query
      - Verify: pytest tests/unit/agent/test_client.py passes

将模糊的任务描述转换为精确的、可自动执行的规范：

markdown

❌ 之前（模糊）：
- [ ] 添加错误处理

✅ 之后（精确）：
- [ ] 任务1：为ClaudeAgentClient.query()添加ConnectionError和TimeoutError处理
      - 采用指数退避策略重试3次（间隔1秒、2秒、4秒）
      - 重试耗尽后抛出AgentConnectionError
      - 位置：src/temet_run/agent/client.py:ClaudeAgentClient.query
      - 验证：执行pytest tests/unit/agent/test_client.py并通过

When to Use This Skill

何时使用该技能

Explicit Triggers:

"Write a task for..."
"Create todo items for..."
"Break down this feature into tasks"
"Make this task more precise"
"How should I write this as a task?"

Implicit Triggers:

Task description lacks file paths
No verification command specified
Vague action verbs ("fix", "add", "update" without specifics)
Missing success criteria
Task would require clarifying questions before starting

Debugging/Quality Scenarios:

Reviewing task list for autonomous execution readiness
Agent keeps asking clarifying questions about tasks
Tasks take longer than expected due to ambiguity
Post-mortem reveals task interpretation issues

显式触发词：

"为...编写任务"
"为...创建待办事项"
"将此功能拆分为任务"
"让这个任务更精确"
"我该如何把这个写成任务？"

隐式触发场景：

任务描述缺少文件路径
未指定验证命令
使用模糊动作动词（如“修复”“添加”“更新”但未说明具体内容）
缺少成功标准
任务开始前需要澄清问题

调试/质量优化场景：

检查任务列表是否具备自动执行条件
Agent持续询问任务相关澄清问题
任务因歧义导致耗时超出预期
事后分析发现任务理解偏差

What This Skill Does

该技能的作用

This skill transforms vague task descriptions into precise, autonomous-execution-ready specifications by:

Applying SMART+ Framework - Ensuring every task is Specific, Measurable, Actionable, Referenced, Testable, with Context
Adding Critical Metadata - File paths, verification commands, success criteria
Decomposing Large Work - Breaking complex tasks into 30-minute chunks
Eliminating Vague Patterns - Replacing forbidden phrases with precise alternatives
Validating Precision - Checking that tasks answer all 6 precision questions

本技能通过以下方式将模糊任务描述转换为精确的、可自动执行的规范：

应用SMART+框架 - 确保每个任务具备具体性、可衡量性、可操作性、可溯源性、可测试性及上下文
添加关键元数据 - 文件路径、验证命令、成功标准
分解大型工作 - 将复杂任务拆分为30分钟内可完成的子任务
消除模糊表述 - 用精确表述替代禁用的模糊短语
验证精确性 - 检查任务是否回答了所有6个精确性问题

The SMART+ Framework

SMART+框架

Every task MUST include these components:

Component	Description	Example
Specific	What exactly to do	"Add retry logic to `ClaudeAgentClient.query()` " not "Add retry logic"
Measurable	How to verify completion	"Tests pass, mypy clean"
Actionable	Clear first step	"Create file `src/temet_run/agent/retry.py` "
Referenced	File paths, functions, classes	"in `agent/client.py:ClaudeAgentClient` "
Testable	Success criteria	"3 retries with exponential backoff, circuit breaker after 5 failures"
+Context	Why this matters (optional)	"Needed for ADR-016 conversation persistence"

每个任务必须包含以下组成部分：

组成部分	说明	示例
S具体性	明确要做的具体内容	"为 `ClaudeAgentClient.query()` 添加重试逻辑"而非"添加重试逻辑"
M可衡量性	如何验证任务完成	"测试通过，mypy检查无问题"
A可操作性	明确第一步动作	"创建文件 `src/temet_run/agent/retry.py` "
R可溯源性	文件路径、函数、类	"位于 `agent/client.py:ClaudeAgentClient` "
T可测试性	成功标准	"3次指数退避重试，5次失败后触发断路器"
+上下文	任务的意义（可选）	"为ADR-016对话持久化需求而设计"

Task Template

任务模板

markdown

- [ ] Task N: [ACTION VERB] [SPECIFIC TARGET] [SUCCESS CRITERIA]
      Location: [file paths or module names]
      Verify: [how to confirm completion]

Complete Example:

markdown

- [ ] Task 1: Add ConversationError exception hierarchy to agent/errors.py
      - Create: ConversationError(base), MessageError, StateError
      - Location: src/temet_run/agent/errors.py
      - Verify: mypy passes, errors importable from temet_run.agent

markdown

- [ ] 任务N：[动作动词] [具体目标] [成功标准]
      位置：[文件路径或模块名]
      验证：[确认完成的方式]

完整示例：

markdown

- [ ] 任务1：为agent/errors.py添加ConversationError异常层级
      - 创建：ConversationError(基类)、MessageError、StateError
      - 位置：src/temet_run/agent/errors.py
      - 验证：mypy检查通过，错误可从temet_run.agent导入

Precision Checklist

精确性检查清单

Before writing a task, verify it answers ALL these questions:

✅ WHAT file(s)? → Include full path from project root
✅ WHAT function/class? → Name the specific target
✅ WHAT action? → Use precise verbs: Create, Add, Modify, Remove, Rename, Extract, Move
✅ WHAT inputs/outputs? → Specify types, fields, parameters

✅ HOW to verify? → Command to run:

pytest path

mypy src/

uv run temet-run ...

✅ WHY doing this? → Link to ADR, issue, or parent task (optional but helpful)

编写任务前，需验证任务是否回答了以下所有问题：

✅ 涉及哪些文件？ → 包含从项目根目录开始的完整路径
✅ 涉及哪些函数/类？ → 明确具体目标
✅ 执行什么动作？ → 使用精确动词：创建、添加、修改、删除、重命名、提取、移动
✅ 输入/输出是什么？ → 指定类型、字段、参数
✅ 如何验证？ → 执行命令：
```
pytest 路径
```
、
```
mypy src/
```
、
```
uv run temet-run ...
```
✅ 为什么要做这件事？ → 关联到ADR、问题或父任务（可选但有帮助）

Forbidden Vague Patterns

禁用的模糊表述

NEVER write tasks containing these vague phrases:

❌ Forbidden Pattern	✅ Precise Alternative
"Implement the feature"	"Implement X method in Y class with Z behavior"
"Add tests"	"Add unit tests for X covering cases A, B, C"
"Fix the bug"	"Fix TypeError in X:line Y caused by Z"
"Update the code"	"Update X function to accept Y parameter"
"Handle errors"	"Add try/except for ConnectionError in X, retry 3 times"
"Refactor"	"Extract X logic from Y into new Z class"
"Improve performance"	"Reduce X function runtime from 500ms to <100ms by caching Y"
"Add logging"	"Add structlog info-level logging to X function for events A, B, C"
"Document the code"	"Add Google-style docstring to X function with Args, Returns, Raises"

任务中绝对不能包含以下模糊短语：

❌ 禁用表述	✅ 精确替代方案
"实现该功能"	"在Y类中实现X方法，具备Z行为"
"添加测试"	"为X添加覆盖A、B、C场景的单元测试"
"修复bug"	"修复X文件第Y行由Z导致的TypeError"
"更新代码"	"更新X函数以接受Y参数"
"处理错误"	"为X中的ConnectionError添加try/except块，重试3次"
"重构"	"将Y中的X逻辑提取到新的Z类中"
"提升性能"	"通过缓存Y将X函数的运行时间从500ms缩短至<100ms"
"添加日志"	"为X函数添加structlog info级日志，记录A、B、C事件"
"编写文档"	"为X函数添加Google风格的文档字符串，包含Args、Returns、Raises"

Task Decomposition Rules

任务分解规则

Large tasks MUST be broken down:

One concern per task - Don't mix "create model AND write tests AND add CLI"
Max 30 minutes of work - If longer, split it
Dependencies explicit - "Task 3 depends on Task 2" or use sub-numbering (2.1, 2.2)
Verification per task - Each task independently verifiable

Decomposition Example:

markdown

undefined

大型任务必须拆分：

单一关注点 - 不要混合“创建模型+编写测试+添加CLI”这类多任务
最大30分钟工作量 - 如果超过，必须拆分
显式依赖 - 标注“任务3依赖任务2”或使用子编号（2.1、2.2）
独立验证 - 每个任务可单独验证完成情况

分解示例：

markdown

undefined

Feature: Add conversation history command

功能：添加对话历史命令

Task 1: Create ConversationRepository protocol Location: src/temet_run/domain/repositories.py Verify: mypy passes
Task 2: Implement JsonlConversationRepository Location: src/temet_run/infrastructure/repositories/conversation.py Verify: Unit tests pass (create tests/unit/infrastructure/test_conversation_repo.py)
Task 3: Add
```
history
```
subcommand to CLI Location: src/temet_run/main.py (add to agents group) Verify:
```
uv run temet-run agents history --help
```
shows usage
Task 4: Integration test for history command Location: tests/integration/test_cli_history.py Verify: pytest tests/integration/test_cli_history.py passes

undefined

任务1：创建ConversationRepository协议位置：src/temet_run/domain/repositories.py 验证：mypy检查通过
任务2：实现JsonlConversationRepository 位置：src/temet_run/infrastructure/repositories/conversation.py 验证：单元测试通过（创建tests/unit/infrastructure/test_conversation_repo.py）
任务3：为CLI添加
```
history
```
子命令位置：src/temet_run/main.py（添加到agents组）验证：执行
```
uv run temet-run agents history --help
```
可显示使用说明
任务4：为历史命令编写集成测试位置：tests/integration/test_cli_history.py 验证：执行pytest tests/integration/test_cli_history.py并通过

undefined

Examples: Vague → Precise Transformation

示例：模糊→精确转换

See

examples/transformation-examples.md

for comprehensive examples covering:

Error handling tasks
Data model implementation
Test writing tasks
Bug fixes
Feature additions
Refactoring work

Inline Example:

markdown

❌ VAGUE:
- [ ] Add error handling to the client

✅ PRECISE:
- [ ] Add ConnectionError and TimeoutError handling to ClaudeAgentClient.query()
      - Retry 3 times with exponential backoff (1s, 2s, 4s)
      - Raise AgentConnectionError after retries exhausted
      - Location: src/temet_run/agent/client.py:ClaudeAgentClient.query
      - Verify: pytest tests/unit/agent/test_client.py passes

可查看

examples/transformation-examples.md

获取全面示例，涵盖：

错误处理任务
数据模型实现
测试编写任务
Bug修复
功能添加
重构工作

内联示例：

markdown

❌ 模糊：
- [ ] 为客户端添加错误处理

✅ 精确：
- [ ] 为ClaudeAgentClient.query()添加ConnectionError和TimeoutError处理
      - 采用指数退避策略重试3次（间隔1秒、2秒、4秒）
      - 重试耗尽后抛出AgentConnectionError
      - 位置：src/temet_run/agent/client.py:ClaudeAgentClient.query
      - 验证：执行pytest tests/unit/agent/test_client.py并通过

Validation Process

验证流程

To validate a task for precision:

Read the task description
Apply the 6-question checklist (Section 5)
Check for forbidden vague patterns (Section 6)
Verify SMART+ components present (Section 3)
Confirm task is <30 minutes of work

Validation Script (if available):

bash

python ~/.claude/skills/write-atomic-tasks/scripts/validate_task.py "task description"

Manual Validation Output:

Task: "Add error handling to the client"

❌ FAILED Precision Check:
- Missing: Specific file path
- Missing: Function/class name
- Missing: Verification command
- Vague pattern: "Add error handling" (see Section 6)

Suggested rewrite:
- [ ] Add ConnectionError handling to ClaudeAgentClient.query()
      Location: src/temet_run/agent/client.py:ClaudeAgentClient.query
      Verify: pytest tests/unit/agent/test_client.py passes

验证任务精确性的步骤：

阅读任务描述
应用6项问题检查清单（第5节）
检查是否包含禁用的模糊表述（第6节）
验证SMART+组成部分是否齐全（第3节）
确认任务工作量<30分钟

验证脚本（若可用）：

bash

python ~/.claude/skills/write-atomic-tasks/scripts/validate_task.py "任务描述"

手动验证输出示例：

任务："为客户端添加错误处理"

❌ 精确性检查未通过：
- 缺失：具体文件路径
- 缺失：函数/类名称
- 缺失：验证命令
- 模糊表述："添加错误处理"（见第6节）

建议重写：
- [ ] 为ClaudeAgentClient.query()添加ConnectionError处理
      位置：src/temet_run/agent/client.py:ClaudeAgentClient.query
      验证：执行pytest tests/unit/agent/test_client.py并通过

Supporting Files

支持文件

examples/transformation-examples.md - 10+ examples of vague → precise transformations
references/smart-framework-deep-dive.md - Detailed explanation of SMART+ components
scripts/validate_task.py - Automated task precision validator
templates/task-template.md - Copy-paste task template with placeholders

examples/transformation-examples.md - 10+个模糊→精确转换示例
references/smart-framework-deep-dive.md - SMART+组成部分的详细说明
scripts/validate_task.py - 自动化任务精确性验证工具
templates/task-template.md - 可直接复制使用的任务模板（含占位符）

Expected Outcomes

预期成果

Successful Task Writing

任务编写成功后的效果

When tasks are written with this skill:

✅ Agents can execute autonomously - No clarifying questions needed ✅ Clear verification - Unambiguous success/failure determination ✅ Predictable effort - Tasks complete in <30 minutes ✅ Reduced rework - Fewer interpretation errors ✅ Better planning - Accurate time estimates from precise scoping

使用本技能编写任务后：

✅ Agent可自动执行 - 无需额外澄清问题 ✅ 验证标准明确 - 成功/失败判定无歧义 ✅ 工作量可预测 - 任务可在30分钟内完成 ✅ 返工减少 - 理解偏差导致的返工更少 ✅ 规划更合理 - 精确范围可提供准确时间估算

Before/After Metrics

前后对比指标

Metric	Before (Vague Tasks)	After (Precise Tasks)
Clarifying questions per task	2-5 questions	0 questions
Task completion time variance	±200%	±20%
Rework due to misunderstanding	30% of tasks	<5% of tasks
Autonomous execution success	40%	95%
Time spent planning vs doing	20/80	40/60

指标	之前（模糊任务）	之后（精确任务）
每个任务的澄清问题数	2-5个	0个
任务完成时间偏差	±200%	±20%
因误解导致的返工率	30%的任务	<5%的任务
自动执行成功率	40%	95%
规划时间与执行时间占比	20/80	40/60

Requirements

要求

Knowledge:

Understanding of SMART goal framework
Familiarity with project file structure
Awareness of verification commands (pytest, mypy, etc.)

Tools:

None (skill is language/framework agnostic)

Environment:

Works with any task management system
Compatible with todo.md, Jira, GitHub Issues, etc.

知识储备：

了解SMART目标框架
熟悉项目文件结构
知晓验证命令（pytest、mypy等）

工具：

无（本技能与语言/框架无关）

环境：

可与任意任务管理系统配合使用
兼容todo.md、Jira、GitHub Issues等

Red Flags to Avoid

需避免的警示信号

Notes

注意事项

This skill is framework-agnostic - Works for any programming language or project type
Precision scales with task complexity - Simple tasks need less metadata than complex ones
Context determines precision level - Solo developer vs distributed team changes requirements
Tasks are living documents - Update tasks when requirements change, don't let them drift
Autonomous execution is the goal - If a task requires synchronous communication, it's not precise enough

本技能与框架无关 - 适用于任意编程语言或项目类型
精确性随任务复杂度调整 - 简单任务所需元数据少于复杂任务
上下文决定精确性要求 - 独立开发者与分布式团队的要求不同
任务是动态文档 - 需求变化时需更新任务，避免任务偏离实际
自动执行是最终目标 - 如果任务需要同步沟通，则说明精确性不足

write-atomic-tasks

Original

Translation

Write Atomic Tasks

编写原子任务

Quick Start

快速入门

Table of Contents

目录

When to Use This Skill

何时使用该技能

What This Skill Does

该技能的作用

The SMART+ Framework

SMART+框架

Task Template

任务模板

Precision Checklist

精确性检查清单

Forbidden Vague Patterns

禁用的模糊表述

Task Decomposition Rules

任务分解规则

Feature: Add conversation history command

功能：添加对话历史命令

Examples: Vague → Precise Transformation

示例：模糊→精确转换

Validation Process

验证流程

Supporting Files

支持文件

Expected Outcomes

预期成果

Successful Task Writing

任务编写成功后的效果

Before/After Metrics

前后对比指标

Requirements

要求

Red Flags to Avoid

需避免的警示信号

Notes

注意事项