docs: add task management workflow and update guides
- Add guide/workflows/task-management.md (comprehensive workflow) - Update ultimate-guide.md with task management sections - Add task management quick reference to cheatsheet - Update machine-readable/reference.yaml with new content - Update .gitignore for docs/ directory Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
1136dc683f
commit
821c900ba0
8 changed files with 997 additions and 3 deletions
2
.gitignore
vendored
2
.gitignore
vendored
|
|
@ -29,7 +29,7 @@ __pycache__/
|
|||
*.mp3
|
||||
*.onnx
|
||||
|
||||
# Personal notes & temp files
|
||||
# Personal notes & temp filesà
|
||||
to-ignore/
|
||||
.grepai/
|
||||
whitepapers/
|
||||
|
|
|
|||
|
|
@ -46,6 +46,7 @@ Hands-on guides for effective development patterns:
|
|||
| [workflows/plan-driven.md](./workflows/plan-driven.md) | Using /plan mode effectively |
|
||||
| [workflows/iterative-refinement.md](./workflows/iterative-refinement.md) | Iterative improvement loops |
|
||||
| [workflows/tts-setup.md](./workflows/tts-setup.md) | Add text-to-speech narration to Claude Code (18 min) |
|
||||
| [workflows/task-management.md](./workflows/task-management.md) | Multi-session task tracking, TodoWrite migration |
|
||||
|
||||
## Recommended Reading Order
|
||||
|
||||
|
|
|
|||
|
|
@ -351,6 +351,47 @@ claude -p "fix typos" --dangerously-skip-permissions
|
|||
|
||||
---
|
||||
|
||||
## Task Management (v2.1.16+)
|
||||
|
||||
**Two systems available:**
|
||||
|
||||
| System | When to Use | Persistence |
|
||||
|--------|-------------|-------------|
|
||||
| **Tasks API** (v2.1.16+) | Multi-session projects, dependencies | ✅ Disk (`~/.claude/tasks/`) |
|
||||
| **TodoWrite** (Legacy) | Simple single-session | ❌ Session only |
|
||||
|
||||
### Tasks API Commands
|
||||
|
||||
```bash
|
||||
# Enable persistence across sessions
|
||||
export CLAUDE_CODE_TASK_LIST_ID="project-name"
|
||||
claude
|
||||
|
||||
# Inside Claude: Create task hierarchy
|
||||
> "Create tasks for auth system with dependencies"
|
||||
|
||||
# Resume later (new session)
|
||||
export CLAUDE_CODE_TASK_LIST_ID="project-name"
|
||||
claude
|
||||
> "TaskList to see current state"
|
||||
```
|
||||
|
||||
**Key capabilities:**
|
||||
- 📁 **Persistent**: Survives session end, context compaction
|
||||
- 🔗 **Dependencies**: Task A blocks Task B
|
||||
- 🔄 **Multi-session**: Broadcast state to multiple terminals
|
||||
- 📊 **Status**: pending → in_progress → completed/failed
|
||||
|
||||
**Migration flag** (v2.1.19+):
|
||||
```bash
|
||||
# Revert to old TodoWrite system
|
||||
CLAUDE_CODE_ENABLE_TASKS=false claude
|
||||
```
|
||||
|
||||
**→ Full workflow**: [guide/workflows/task-management.md](../workflows/task-management.md)
|
||||
|
||||
---
|
||||
|
||||
## The Golden Rules
|
||||
|
||||
1. **Always review diffs** before accepting
|
||||
|
|
|
|||
|
|
@ -3122,7 +3122,150 @@ Claude Code has 8 core tools:
|
|||
| `Grep` | Search file contents (ripgrep-based) |
|
||||
| `Glob` | Find files by pattern |
|
||||
| `Task` | Spawn sub-agents (isolated context) |
|
||||
| `TodoWrite` | Track progress |
|
||||
| `TodoWrite` | Track progress (legacy, see below) |
|
||||
|
||||
### Task Management System
|
||||
|
||||
**Version**: Claude Code v2.1.16+ introduced a new task management system
|
||||
|
||||
Claude Code provides two task management approaches:
|
||||
|
||||
| Feature | TodoWrite (Legacy) | Tasks API (v2.1.16+) |
|
||||
|---------|-------------------|---------------------|
|
||||
| **Persistence** | Session memory only | Disk storage (`~/.claude/tasks/`) |
|
||||
| **Multi-session** | ❌ Lost on session end | ✅ Survives across sessions |
|
||||
| **Dependencies** | ❌ Manual ordering | ✅ Task blocking (A blocks B) |
|
||||
| **Coordination** | Single agent | ✅ Multi-agent broadcast |
|
||||
| **Status tracking** | pending/in_progress/completed | pending/in_progress/completed/failed |
|
||||
| **Enabled by** | Always available | Default since v2.1.19 |
|
||||
|
||||
#### Tasks API (v2.1.16+)
|
||||
|
||||
**Available tools:**
|
||||
- `TaskCreate` - Initialize new tasks with hierarchy and dependencies
|
||||
- `TaskUpdate` - Modify task status, metadata, and dependencies
|
||||
- `TaskGet` - Retrieve individual task details
|
||||
- `TaskList` - List all tasks in current task list
|
||||
|
||||
**Core capabilities:**
|
||||
- **Persistent storage**: Tasks saved to `~/.claude/tasks/<task-list-id>/`
|
||||
- **Multi-session coordination**: Share state across multiple Claude sessions
|
||||
- **Dependency tracking**: Tasks can block other tasks (task A blocks task B)
|
||||
- **Status lifecycle**: pending → in_progress → completed/failed
|
||||
- **Metadata**: Attach custom data (priority, estimates, related files, etc.)
|
||||
|
||||
**Configuration:**
|
||||
|
||||
```bash
|
||||
# Enable multi-session task persistence
|
||||
export CLAUDE_CODE_TASK_LIST_ID="project-name"
|
||||
claude
|
||||
|
||||
# Example: Project-specific task list
|
||||
export CLAUDE_CODE_TASK_LIST_ID="api-v2-auth-refactor"
|
||||
claude
|
||||
```
|
||||
|
||||
**⚠️ Important**: Use repository-specific task list IDs to avoid cross-project contamination. Tasks with the same ID are shared across all sessions using that ID.
|
||||
|
||||
**Task schema example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "task-auth-login",
|
||||
"title": "Implement login endpoint",
|
||||
"description": "POST /auth/login with JWT token generation",
|
||||
"status": "in_progress",
|
||||
"dependencies": [],
|
||||
"metadata": {
|
||||
"priority": "high",
|
||||
"estimated_duration": "2h",
|
||||
"related_files": ["src/auth/login.ts", "src/middleware/auth.ts"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**When to use Tasks API:**
|
||||
- Projects spanning multiple coding sessions
|
||||
- Complex task hierarchies with dependencies
|
||||
- Multi-agent coordination scenarios
|
||||
- Need to resume work after context compaction
|
||||
|
||||
#### TodoWrite (Legacy)
|
||||
|
||||
**Tool**: `TodoWrite` - Creates task lists stored in session memory
|
||||
|
||||
**Capabilities:**
|
||||
- Simple task tracking within a single session
|
||||
- Status tracking: pending/in_progress/completed
|
||||
- Lost when session ends or context is compacted
|
||||
|
||||
**When to use TodoWrite:**
|
||||
- Single-session, straightforward implementations
|
||||
- Quick fixes or exploratory coding
|
||||
- Claude Code < v2.1.16
|
||||
- Prefer simplicity over persistence
|
||||
|
||||
**Migration flag** (v2.1.19+):
|
||||
|
||||
```bash
|
||||
# Temporarily revert to TodoWrite system
|
||||
CLAUDE_CODE_ENABLE_TASKS=false claude
|
||||
|
||||
# Use new Tasks API (default)
|
||||
claude
|
||||
```
|
||||
|
||||
#### Best Practices
|
||||
|
||||
**Task hierarchy design:**
|
||||
```
|
||||
Project (parent)
|
||||
└── Feature A (child)
|
||||
├── Component A1 (leaf task)
|
||||
│ ├── Implementation
|
||||
│ └── Tests (depends on Implementation)
|
||||
└── Component A2
|
||||
```
|
||||
|
||||
**Dependency management:**
|
||||
- Always define dependencies when creating tasks
|
||||
- Use task IDs (not titles) for dependency references
|
||||
- Verify dependencies with `TaskGet` before execution
|
||||
|
||||
**Status transitions:**
|
||||
- Mark `in_progress` when starting work (prevents parallel execution)
|
||||
- Update frequently for visibility
|
||||
- Only mark `completed` when fully accomplished (tests passing, validated)
|
||||
- Use `failed` status with error metadata for debugging
|
||||
|
||||
**Metadata conventions:**
|
||||
```json
|
||||
{
|
||||
"priority": "high|medium|low",
|
||||
"estimated_duration": "2h",
|
||||
"related_files": ["path/to/file.ts"],
|
||||
"related_issue": "https://github.com/org/repo/issues/123",
|
||||
"type": "feature|bugfix|refactor|test"
|
||||
}
|
||||
```
|
||||
|
||||
#### Complete Workflow
|
||||
|
||||
**→ See**: [Task Management Workflow](./workflows/task-management.md) for:
|
||||
- Task planning phase (decomposition, hierarchy design)
|
||||
- Task execution patterns
|
||||
- Session management and resumption
|
||||
- Integration with TDD and Plan-Driven workflows
|
||||
- TodoWrite migration guide
|
||||
- Patterns, anti-patterns, and troubleshooting
|
||||
|
||||
#### Sources
|
||||
|
||||
- **Official**: [Claude Code CHANGELOG v2.1.16](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) - "new task management system with dependency tracking"
|
||||
- **Official**: [System Prompts - TaskCreate](https://github.com/Piebald-AI/claude-code-system-prompts) (extracted from Claude Code source)
|
||||
- **Community**: [paddo.dev - From Beads to Tasks](https://paddo.dev/blog/from-beads-to-tasks/)
|
||||
- **Community**: [llbbl.blog - Two Changes in Claude Code](https://llbbl.blog/2026/01/25/two-changes-in-claude-code.html)
|
||||
|
||||
### Context Management
|
||||
|
||||
|
|
|
|||
|
|
@ -249,3 +249,4 @@ Plans in `.claude/plans/` serve as decision documentation:
|
|||
- [tdd-with-claude.md](./tdd-with-claude.md) — Combine with TDD
|
||||
- [spec-first.md](./spec-first.md) — Combine with Spec-First
|
||||
- [iterative-refinement.md](./iterative-refinement.md) — Post-plan iteration
|
||||
- [task-management.md](./task-management.md) — Track plan execution across sessions with Tasks API
|
||||
|
|
|
|||
775
guide/workflows/task-management.md
Normal file
775
guide/workflows/task-management.md
Normal file
|
|
@ -0,0 +1,775 @@
|
|||
# Task Management Workflow
|
||||
|
||||
**Version**: Claude Code v2.1.16+
|
||||
**Prerequisites**: Understanding of multi-session workflows, basic CLI proficiency
|
||||
**Time**: 15-30 min to learn, applies to all complex projects
|
||||
|
||||
## Overview
|
||||
|
||||
Task management in Claude Code evolved significantly in v2.1.16 with the introduction of the **Tasks API**, complementing the original **TodoWrite** tool. This workflow teaches you when to use each system and how to leverage multi-session task coordination for complex projects.
|
||||
|
||||
**When to use this workflow:**
|
||||
- Projects spanning multiple coding sessions
|
||||
- Multi-agent coordination scenarios
|
||||
- Complex task hierarchies with dependencies
|
||||
- Need to resume work after context compaction or session interruption
|
||||
|
||||
**When NOT to use:**
|
||||
- Single-session, straightforward implementations
|
||||
- Quick fixes or exploratory coding
|
||||
- Tasks completable in <10 minutes
|
||||
|
||||
---
|
||||
|
||||
## System Comparison Quick Reference
|
||||
|
||||
| Feature | TodoWrite (Legacy) | Tasks API (v2.1.16+) |
|
||||
|---------|-------------------|---------------------|
|
||||
| **Persistence** | Session memory only | Disk storage (`~/.claude/tasks/`) |
|
||||
| **Multi-session** | ❌ Lost on session end | ✅ Survives across sessions |
|
||||
| **Dependencies** | ❌ Manual ordering | ✅ Task blocking (A blocks B) |
|
||||
| **Coordination** | Single agent | ✅ Multi-agent with broadcast |
|
||||
| **Status tracking** | pending/in_progress/completed | pending/in_progress/completed/failed |
|
||||
| **When to use** | Simple single-session todos | Complex multi-session projects |
|
||||
|
||||
**Migration flag** (v2.1.19+):
|
||||
```bash
|
||||
# Use old system (TodoWrite)
|
||||
CLAUDE_CODE_ENABLE_TASKS=false claude
|
||||
|
||||
# Use new system (Tasks API) - default since v2.1.19
|
||||
claude
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow Phase 1: Task Planning
|
||||
|
||||
**Goal**: Decompose complex work into trackable, executable units
|
||||
|
||||
### Step 1: Analyze Scope
|
||||
|
||||
Before creating tasks, understand what you're building:
|
||||
|
||||
```bash
|
||||
# Discovery pattern
|
||||
claude
|
||||
> "Analyze this codebase for implementing JWT authentication:
|
||||
- Glob for existing auth patterns
|
||||
- Grep for security-related code
|
||||
- Identify integration points"
|
||||
```
|
||||
|
||||
### Step 2: Design Task Hierarchy
|
||||
|
||||
Break work into logical phases with dependencies:
|
||||
|
||||
**Example: Authentication System**
|
||||
```
|
||||
Authentication System (parent)
|
||||
├── 1. Login endpoint (no dependencies)
|
||||
├── 2. Token refresh (depends on #1)
|
||||
├── 3. Logout endpoint (depends on #1)
|
||||
└── 4. Integration tests (depends on #1, #2, #3)
|
||||
```
|
||||
|
||||
### Step 3: Create Task Structure
|
||||
|
||||
Use `TaskCreate` to materialize your plan:
|
||||
|
||||
```bash
|
||||
# Session 1: Planning phase
|
||||
export CLAUDE_CODE_TASK_LIST_ID="auth-system-v2"
|
||||
claude
|
||||
|
||||
# Inside Claude session:
|
||||
> "Create a task hierarchy for JWT authentication:
|
||||
|
||||
Parent task: 'Implement JWT authentication system'
|
||||
- Description: Add JWT-based auth with refresh tokens and secure storage
|
||||
|
||||
Child tasks:
|
||||
1. 'Create login endpoint' (no dependencies)
|
||||
2. 'Implement token refresh logic' (depends on task 1)
|
||||
3. 'Create logout endpoint' (depends on task 1)
|
||||
4. 'Write integration tests' (depends on tasks 1, 2, 3)
|
||||
|
||||
Use TaskCreate with proper metadata."
|
||||
```
|
||||
|
||||
**Expected output from Claude:**
|
||||
```json
|
||||
{
|
||||
"tasks": [
|
||||
{
|
||||
"id": "task-auth-parent",
|
||||
"title": "Implement JWT authentication system",
|
||||
"status": "pending",
|
||||
"children": ["task-login", "task-refresh", "task-logout", "task-tests"]
|
||||
},
|
||||
{
|
||||
"id": "task-login",
|
||||
"title": "Create login endpoint",
|
||||
"status": "pending",
|
||||
"dependencies": [],
|
||||
"metadata": {"priority": "high", "estimated_duration": "2h"}
|
||||
},
|
||||
{
|
||||
"id": "task-refresh",
|
||||
"title": "Implement token refresh logic",
|
||||
"status": "pending",
|
||||
"dependencies": ["task-login"],
|
||||
"metadata": {"priority": "high", "estimated_duration": "1h"}
|
||||
}
|
||||
// ... other tasks
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow Phase 2: Task Execution
|
||||
|
||||
**Goal**: Execute tasks systematically with progress tracking
|
||||
|
||||
### Execution Pattern
|
||||
|
||||
```
|
||||
TaskList → TaskGet (next pending) → Execute → TaskUpdate → Validate → Repeat
|
||||
```
|
||||
|
||||
### Step 1: Discover Next Task
|
||||
|
||||
```bash
|
||||
# Session 2: Start implementation
|
||||
export CLAUDE_CODE_TASK_LIST_ID="auth-system-v2"
|
||||
claude
|
||||
|
||||
> "TaskList to show all pending tasks"
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
Tasks for 'auth-system-v2':
|
||||
✅ task-login: Create login endpoint [completed]
|
||||
⏳ task-refresh: Implement token refresh logic [pending, blocked by: none]
|
||||
⏳ task-logout: Create logout endpoint [pending, blocked by: none]
|
||||
⏳ task-tests: Write integration tests [pending, blocked by: task-refresh, task-logout]
|
||||
```
|
||||
|
||||
### Step 2: Get Task Details
|
||||
|
||||
```bash
|
||||
> "TaskGet task-refresh to see full requirements"
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
{
|
||||
"id": "task-refresh",
|
||||
"title": "Implement token refresh logic",
|
||||
"description": "Create endpoint POST /auth/refresh that validates refresh token and issues new access token",
|
||||
"status": "pending",
|
||||
"dependencies": ["task-login"],
|
||||
"metadata": {
|
||||
"priority": "high",
|
||||
"estimated_duration": "1h",
|
||||
"files": ["src/auth/refresh.ts", "src/middleware/auth.ts"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Execute & Update
|
||||
|
||||
```bash
|
||||
> "Mark task-refresh as in_progress, then implement the token refresh endpoint according to requirements"
|
||||
|
||||
# Claude executes: TaskUpdate task-refresh status=in_progress
|
||||
# Claude implements the feature...
|
||||
# Upon completion:
|
||||
|
||||
> "Mark task-refresh as completed"
|
||||
# Claude executes: TaskUpdate task-refresh status=completed
|
||||
```
|
||||
|
||||
### Step 4: Validate
|
||||
|
||||
```bash
|
||||
> "Run tests for token refresh functionality"
|
||||
|
||||
# If tests pass:
|
||||
# ✅ Task remains completed
|
||||
|
||||
# If tests fail:
|
||||
> "TaskUpdate task-refresh status=failed, add error details to metadata"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow Phase 3: Session Management
|
||||
|
||||
**Goal**: Seamlessly resume work across sessions and context boundaries
|
||||
|
||||
### Persistence Mechanism
|
||||
|
||||
**Storage location**: `~/.claude/tasks/<task-list-id>/`
|
||||
|
||||
Tasks survive:
|
||||
- Session termination
|
||||
- Context compaction (`/compact`)
|
||||
- System restarts
|
||||
- Multiple days of interruption
|
||||
|
||||
### Resume Pattern
|
||||
|
||||
```bash
|
||||
# Days later, different terminal session
|
||||
export CLAUDE_CODE_TASK_LIST_ID="auth-system-v2"
|
||||
claude
|
||||
|
||||
> "TaskList to show current state"
|
||||
|
||||
# Output shows exactly where you left off:
|
||||
# ✅ task-login [completed]
|
||||
# ✅ task-refresh [completed]
|
||||
# ⏳ task-logout [pending]
|
||||
# ⏳ task-tests [pending, blocked by: task-logout]
|
||||
|
||||
> "Continue with next pending task that isn't blocked"
|
||||
```
|
||||
|
||||
### Multi-Terminal Coordination
|
||||
|
||||
**Use case**: Run multiple Claude instances working on the same project
|
||||
|
||||
```bash
|
||||
# Terminal 1: Frontend work
|
||||
export CLAUDE_CODE_TASK_LIST_ID="auth-system-v2"
|
||||
claude
|
||||
> "Work on task-logout endpoint"
|
||||
|
||||
# Terminal 2: Test writing (simultaneous)
|
||||
export CLAUDE_CODE_TASK_LIST_ID="auth-system-v2"
|
||||
claude
|
||||
> "TaskList - check what's completed so I can write tests"
|
||||
|
||||
# Both terminals see real-time state updates
|
||||
```
|
||||
|
||||
**⚠️ Warning**: Use repository-specific task list IDs to avoid cross-project contamination:
|
||||
```bash
|
||||
# ❌ BAD: Generic ID used across multiple repos
|
||||
export CLAUDE_CODE_TASK_LIST_ID="my-project"
|
||||
|
||||
# ✅ GOOD: Repo-specific with context
|
||||
export CLAUDE_CODE_TASK_LIST_ID="mycompany-api-auth-refactor"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration: TDD + Task Management
|
||||
|
||||
Combine Test-Driven Development with task tracking for systematic test coverage.
|
||||
|
||||
### Pattern: Test-First Task Execution
|
||||
|
||||
```bash
|
||||
export CLAUDE_CODE_TASK_LIST_ID="tdd-feature-x"
|
||||
claude
|
||||
|
||||
# Create tasks with test-first approach
|
||||
> "Create task hierarchy for feature X:
|
||||
|
||||
For each feature component:
|
||||
1. Task: 'Write failing tests for [component]'
|
||||
2. Task: 'Implement [component] to pass tests' (depends on #1)
|
||||
3. Task: 'Refactor [component]' (depends on #2)
|
||||
|
||||
Use TDD red-green-refactor cycle per task."
|
||||
```
|
||||
|
||||
### Example: Login Feature with TDD
|
||||
|
||||
```bash
|
||||
# Phase 1: Red (failing tests)
|
||||
TaskCreate: {
|
||||
title: "Write failing tests for login endpoint",
|
||||
description: "Test cases: valid credentials, invalid password, user not found, rate limiting",
|
||||
status: "pending"
|
||||
}
|
||||
|
||||
# Execute test writing
|
||||
> "Implement task-login-tests, ensure all tests fail initially"
|
||||
|
||||
# Phase 2: Green (minimal implementation)
|
||||
TaskCreate: {
|
||||
title: "Implement login endpoint (minimal)",
|
||||
description: "Make tests pass with simplest possible implementation",
|
||||
dependencies: ["task-login-tests"],
|
||||
status: "pending"
|
||||
}
|
||||
|
||||
# Phase 3: Refactor
|
||||
TaskCreate: {
|
||||
title: "Refactor login endpoint",
|
||||
description: "Optimize, remove duplication, improve readability",
|
||||
dependencies: ["task-login-impl"],
|
||||
status: "pending"
|
||||
}
|
||||
```
|
||||
|
||||
**Full workflow reference**: See [TDD with Claude](tdd-with-claude.md#task-management-integration)
|
||||
|
||||
---
|
||||
|
||||
## Integration: Plan-Driven + Task Management
|
||||
|
||||
Convert strategic plans into executable task hierarchies.
|
||||
|
||||
### Pattern: Plan-to-Tasks Transformation
|
||||
|
||||
```bash
|
||||
# Step 1: Enter plan mode
|
||||
claude
|
||||
> "Shift+Tab×2" # Enter plan mode
|
||||
|
||||
# Step 2: Create architectural plan
|
||||
> "Design architecture for microservices migration:
|
||||
- Identify service boundaries
|
||||
- Plan data migration strategy
|
||||
- Design API contracts"
|
||||
|
||||
# Step 3: Exit plan mode with task creation
|
||||
> "Convert this plan into a task hierarchy using TaskCreate"
|
||||
```
|
||||
|
||||
### Example: Microservices Migration
|
||||
|
||||
**Plan output:**
|
||||
```
|
||||
Phase 1: Analysis (Week 1)
|
||||
- Map monolith dependencies
|
||||
- Identify bounded contexts
|
||||
- Design service boundaries
|
||||
|
||||
Phase 2: Infrastructure (Week 2)
|
||||
- Set up service templates
|
||||
- Configure API gateway
|
||||
- Establish monitoring
|
||||
|
||||
Phase 3: Migration (Week 3-6)
|
||||
- Extract user service
|
||||
- Extract order service
|
||||
- Migrate database schemas
|
||||
```
|
||||
|
||||
**Tasks transformation:**
|
||||
```bash
|
||||
TaskCreate: {
|
||||
title: "Microservices migration",
|
||||
children: [
|
||||
{
|
||||
title: "Phase 1: Analysis",
|
||||
children: [
|
||||
{title: "Map monolith dependencies", priority: "critical"},
|
||||
{title: "Identify bounded contexts", dependencies: ["map-deps"]},
|
||||
{title: "Design service boundaries", dependencies: ["bounded-contexts"]}
|
||||
]
|
||||
},
|
||||
{
|
||||
title: "Phase 2: Infrastructure",
|
||||
dependencies: ["phase-1"],
|
||||
children: [
|
||||
{title: "Set up service templates"},
|
||||
{title: "Configure API gateway", dependencies: ["templates"]},
|
||||
{title: "Establish monitoring"}
|
||||
]
|
||||
}
|
||||
// ... Phase 3
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Full workflow reference**: See [Plan-Driven Development](plan-driven.md#task-hierarchy-design)
|
||||
|
||||
---
|
||||
|
||||
## TodoWrite Migration Guide
|
||||
|
||||
### When to Migrate
|
||||
|
||||
**Stay with TodoWrite if:**
|
||||
- ✅ All work completes in a single session
|
||||
- ✅ No multi-agent coordination needed
|
||||
- ✅ Simple linear task lists (no dependencies)
|
||||
- ✅ Using Claude Code < v2.1.16
|
||||
|
||||
**Migrate to Tasks API if:**
|
||||
- ✅ Work spans multiple sessions
|
||||
- ✅ Need task persistence across days/weeks
|
||||
- ✅ Complex dependency graphs
|
||||
- ✅ Multi-terminal collaboration
|
||||
- ✅ Want to resume after context compaction
|
||||
|
||||
### Migration Steps
|
||||
|
||||
#### Step 1: Identify TodoWrite Usage
|
||||
|
||||
```bash
|
||||
# Find existing TodoWrite usage in your CLAUDE.md or workflows
|
||||
grep -r "TodoWrite" .claude/
|
||||
```
|
||||
|
||||
#### Step 2: Convert TodoWrite Lists to Tasks
|
||||
|
||||
**Before (TodoWrite):**
|
||||
```markdown
|
||||
- [ ] Implement user authentication
|
||||
- [ ] Add password hashing
|
||||
- [ ] Create session management
|
||||
- [ ] Write tests
|
||||
```
|
||||
|
||||
**After (Tasks API):**
|
||||
```bash
|
||||
export CLAUDE_CODE_TASK_LIST_ID="user-auth-2026"
|
||||
claude
|
||||
|
||||
> "Create tasks:
|
||||
1. 'Implement user authentication' (parent)
|
||||
- Child: 'Add password hashing'
|
||||
- Child: 'Create session management' (depends on hashing)
|
||||
- Child: 'Write tests' (depends on auth, hashing, sessions)"
|
||||
```
|
||||
|
||||
#### Step 3: Update CLAUDE.md Instructions
|
||||
|
||||
**Before:**
|
||||
```markdown
|
||||
For complex tasks:
|
||||
- Use TodoWrite to create task list
|
||||
- Execute tasks sequentially
|
||||
```
|
||||
|
||||
**After:**
|
||||
```markdown
|
||||
For complex tasks:
|
||||
- Set CLAUDE_CODE_TASK_LIST_ID=<project-name>
|
||||
- Use TaskCreate for hierarchical planning
|
||||
- Execute with TaskUpdate status tracking
|
||||
- Resume with TaskList in new sessions
|
||||
```
|
||||
|
||||
#### Step 4: Test Migration
|
||||
|
||||
```bash
|
||||
# Create test task list
|
||||
export CLAUDE_CODE_TASK_LIST_ID="migration-test"
|
||||
claude
|
||||
|
||||
> "Create 3 test tasks with dependencies, mark one completed, then exit"
|
||||
|
||||
# Relaunch in new session
|
||||
export CLAUDE_CODE_TASK_LIST_ID="migration-test"
|
||||
claude
|
||||
|
||||
> "TaskList - verify tasks persisted correctly"
|
||||
|
||||
# Expected: See all 3 tasks with correct states
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Patterns & Anti-Patterns
|
||||
|
||||
### ✅ Good Patterns
|
||||
|
||||
#### 1. Hierarchical Task Decomposition
|
||||
|
||||
```bash
|
||||
Project (parent)
|
||||
└── Feature A (child of project)
|
||||
├── Component A1 (child of Feature A)
|
||||
│ ├── Implementation (leaf task)
|
||||
│ └── Tests (leaf task, depends on Implementation)
|
||||
└── Component A2
|
||||
└── ...
|
||||
```
|
||||
|
||||
**Why it works**: Mirrors natural project structure, makes dependencies explicit
|
||||
|
||||
#### 2. Dependency-First Ordering
|
||||
|
||||
```bash
|
||||
# Always define dependencies when creating tasks
|
||||
TaskCreate: {
|
||||
title: "Deploy to production",
|
||||
dependencies: ["run-tests", "code-review", "backup-database"],
|
||||
metadata: {blocking_reason: "Safety checks required"}
|
||||
}
|
||||
```
|
||||
|
||||
**Why it works**: Prevents premature execution, enforces quality gates
|
||||
|
||||
#### 3. Granular Status Updates
|
||||
|
||||
```bash
|
||||
# Bad: Large task marked completed without intermediate updates
|
||||
TaskCreate: {title: "Build entire auth system"}
|
||||
# ... hours later ...
|
||||
TaskUpdate: {id: "auth-system", status: "completed"}
|
||||
|
||||
# Good: Frequent status updates as work progresses
|
||||
TaskUpdate: {id: "auth-system", status: "in_progress", progress: "25%"}
|
||||
TaskUpdate: {id: "auth-system", status: "in_progress", progress: "50%"}
|
||||
TaskUpdate: {id: "auth-system", status: "in_progress", progress: "75%"}
|
||||
TaskUpdate: {id: "auth-system", status: "completed"}
|
||||
```
|
||||
|
||||
**Why it works**: Provides visibility, enables context-aware resumption
|
||||
|
||||
#### 4. Metadata-Rich Tasks
|
||||
|
||||
```bash
|
||||
TaskCreate: {
|
||||
title: "Optimize database queries",
|
||||
description: "Reduce query time for user dashboard from 2s to <200ms",
|
||||
metadata: {
|
||||
priority: "high",
|
||||
estimated_duration: "3h",
|
||||
related_files: ["src/db/queries.ts", "src/db/indexes.sql"],
|
||||
performance_baseline: "2000ms",
|
||||
performance_target: "200ms",
|
||||
related_issue: "https://github.com/org/repo/issues/123"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Why it works**: Context-rich resumption, easier delegation, better documentation
|
||||
|
||||
### ❌ Anti-Patterns
|
||||
|
||||
#### 1. Monolithic Tasks (>10 steps)
|
||||
|
||||
```bash
|
||||
# ❌ BAD: Task too large, hard to track progress
|
||||
TaskCreate: {
|
||||
title: "Implement entire payment system",
|
||||
description: "Stripe integration, webhooks, refunds, disputes, reporting, admin UI, ..."
|
||||
}
|
||||
|
||||
# ✅ GOOD: Break into phases
|
||||
TaskCreate: {
|
||||
title: "Payment system - Phase 1: Core integration",
|
||||
children: [
|
||||
{title: "Stripe SDK setup"},
|
||||
{title: "Payment intent creation"},
|
||||
{title: "Webhook handling"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Missing Dependencies
|
||||
|
||||
```bash
|
||||
# ❌ BAD: Tasks can execute in wrong order
|
||||
TaskCreate: {title: "Deploy to production"} # No dependencies
|
||||
TaskCreate: {title: "Write tests"} # No dependencies
|
||||
|
||||
# ✅ GOOD: Explicit ordering
|
||||
TaskCreate: {
|
||||
title: "Deploy to production",
|
||||
dependencies: ["write-tests", "run-tests", "code-review"]
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. Orphan Tasks Without Context
|
||||
|
||||
```bash
|
||||
# ❌ BAD: Future you won't remember what this means
|
||||
TaskCreate: {
|
||||
title: "Fix the bug",
|
||||
description: "That one from yesterday"
|
||||
}
|
||||
|
||||
# ✅ GOOD: Self-contained context
|
||||
TaskCreate: {
|
||||
title: "Fix login timeout on Safari",
|
||||
description: "Users on Safari 17.2+ experience session timeout after 5min. Expected: 30min timeout. Root cause: cookie SameSite=Strict not supported.",
|
||||
metadata: {
|
||||
browser: "Safari 17.2+",
|
||||
error_message: "Session expired",
|
||||
related_commit: "a1b2c3d",
|
||||
slack_thread: "https://slack.com/archives/C123/p456"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. Status Mismatch
|
||||
|
||||
```bash
|
||||
# ❌ BAD: Task marked completed but tests fail
|
||||
TaskUpdate: {id: "login-feature", status: "completed"}
|
||||
# Tests run later: 3 failures
|
||||
|
||||
# ✅ GOOD: Validation before completion
|
||||
> "Run tests for login feature"
|
||||
# If tests pass:
|
||||
TaskUpdate: {id: "login-feature", status: "completed", metadata: {test_results: "pass"}}
|
||||
# If tests fail:
|
||||
TaskUpdate: {id: "login-feature", status: "failed", metadata: {test_results: "3 failures", error_log: "..."}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Q: Tasks don't persist across sessions
|
||||
|
||||
**Symptom**: `TaskList` shows empty after restarting Claude
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Ensure CLAUDE_CODE_TASK_LIST_ID is set before launching
|
||||
export CLAUDE_CODE_TASK_LIST_ID="your-project-name"
|
||||
claude
|
||||
|
||||
# Verify storage directory exists
|
||||
ls ~/.claude/tasks/your-project-name/
|
||||
```
|
||||
|
||||
### Q: Multiple projects sharing task lists
|
||||
|
||||
**Symptom**: Seeing tasks from Project A when working on Project B
|
||||
|
||||
**Cause**: Using same task list ID across different repositories
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Use repo-specific IDs with context
|
||||
cd ~/projects/api
|
||||
export CLAUDE_CODE_TASK_LIST_ID="api-v2-migration"
|
||||
claude
|
||||
|
||||
cd ~/projects/frontend
|
||||
export CLAUDE_CODE_TASK_LIST_ID="frontend-redesign"
|
||||
claude
|
||||
```
|
||||
|
||||
### Q: TodoWrite still used instead of Tasks API
|
||||
|
||||
**Symptom**: Tasks not persisting even with task list ID set
|
||||
|
||||
**Cause**: `CLAUDE_CODE_ENABLE_TASKS=false` set in environment
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check environment
|
||||
env | grep CLAUDE_CODE_ENABLE_TASKS
|
||||
|
||||
# Unset if present
|
||||
unset CLAUDE_CODE_ENABLE_TASKS
|
||||
|
||||
# Or explicitly enable (v2.1.19+ defaults to enabled)
|
||||
export CLAUDE_CODE_ENABLE_TASKS=true
|
||||
```
|
||||
|
||||
### Q: Task dependencies not enforced
|
||||
|
||||
**Symptom**: Claude executes blocked tasks before dependencies complete
|
||||
|
||||
**Cause**: Dependencies not properly defined in TaskCreate
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Ensure dependencies use correct task IDs
|
||||
TaskCreate: {
|
||||
title: "Task B",
|
||||
dependencies: ["task-a-id"], # ✅ Use actual task ID
|
||||
# NOT dependencies: ["Task A"] # ❌ Task title won't work
|
||||
}
|
||||
|
||||
# Verify dependencies:
|
||||
TaskGet task-b-id
|
||||
# Should show: "blockedBy": ["task-a-id"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced: Custom Task Metadata
|
||||
|
||||
Extend tasks with domain-specific metadata for enhanced workflows.
|
||||
|
||||
### Metadata Conventions
|
||||
|
||||
**Performance optimization tasks:**
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"type": "performance",
|
||||
"baseline_metric": "2000ms",
|
||||
"target_metric": "200ms",
|
||||
"profiling_tool": "Chrome DevTools",
|
||||
"measurement_location": "dashboard load time"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Security tasks:**
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"type": "security",
|
||||
"severity": "critical",
|
||||
"cve_id": "CVE-2024-1234",
|
||||
"affected_versions": "< 2.1.0",
|
||||
"mitigation": "Update package X to v3.0+"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Bug fix tasks:**
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"type": "bugfix",
|
||||
"issue_url": "https://github.com/org/repo/issues/456",
|
||||
"reported_by": "user@example.com",
|
||||
"reproduction_steps": "1. Login 2. Navigate to dashboard 3. Click export",
|
||||
"error_message": "TypeError: Cannot read property 'map' of undefined"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Querying by Metadata
|
||||
|
||||
```bash
|
||||
# Filter tasks by type (requires scripting, not built-in)
|
||||
TaskList | jq '.tasks[] | select(.metadata.type == "security")'
|
||||
|
||||
# Find high-priority pending tasks
|
||||
TaskList | jq '.tasks[] | select(.metadata.priority == "high" and .status == "pending")'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Workflows
|
||||
|
||||
- **[TDD with Claude](tdd-with-claude.md)** - Test-first development with task tracking
|
||||
- **[Plan-Driven Development](plan-driven.md)** - Strategic planning to task hierarchies
|
||||
- **[Iterative Refinement](iterative-refinement.md)** - Incremental improvements with tasks
|
||||
- **[Exploration Workflow](exploration-workflow.md)** - Discovery phase before task creation
|
||||
|
||||
---
|
||||
|
||||
## Reference
|
||||
|
||||
**Tool documentation**: See [Ultimate Guide Section 5.X](../ultimate-guide.md#5x-task-management-system)
|
||||
|
||||
**Sources:**
|
||||
- Official: [Claude Code CHANGELOG v2.1.16](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
|
||||
- Official: [System Prompts - TaskCreate](https://github.com/Piebald-AI/claude-code-system-prompts)
|
||||
- Community: [paddo.dev - From Beads to Tasks](https://paddo.dev/blog/from-beads-to-tasks/)
|
||||
- Community: [llbbl.blog - Two Changes in Claude Code](https://llbbl.blog/2026/01/25/two-changes-in-claude-code.html)
|
||||
|
||||
**Version tracking**: This workflow documents Claude Code v2.1.16+ (released 2026-01-22). Verify latest changes in [claude-code-releases.yaml](../../machine-readable/claude-code-releases.yaml).
|
||||
|
|
@ -302,3 +302,4 @@ Run tests after each change to ensure they stay green.
|
|||
- [Tight Feedback Loops](../ultimate-guide.md) — Section 9.5
|
||||
- [examples/skills/tdd-workflow.md](../../examples/skills/tdd-workflow.md) — TDD skill template
|
||||
- [Anthropic Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
|
||||
- [task-management.md](./task-management.md) — Track TDD cycles across sessions with Tasks API
|
||||
|
|
|
|||
|
|
@ -115,6 +115,37 @@ deep_dive:
|
|||
semantic_anchors: 2872
|
||||
semantic_anchors_catalog: "examples/semantic-anchors/anchor-catalog.md"
|
||||
memory_files: 3160
|
||||
# Task Management System (v2.1.16+) - Added 2026-01-26
|
||||
task_management_system: 3127
|
||||
task_management_comparison: 3140
|
||||
tasks_api_overview: 3150
|
||||
tasks_api_tools: 3160
|
||||
tasks_api_capabilities: 3170
|
||||
tasks_api_configuration: 3180
|
||||
tasks_api_schema: 3195
|
||||
tasks_api_when_to_use: 3210
|
||||
todowrite_legacy: 3220
|
||||
todowrite_when_to_use: 3230
|
||||
todowrite_migration_flag: 3240
|
||||
task_best_practices: 3250
|
||||
task_hierarchy_design: 3252
|
||||
task_dependency_management: 3256
|
||||
task_status_transitions: 3260
|
||||
task_metadata_conventions: 3264
|
||||
task_complete_workflow: 3270
|
||||
task_sources: 3280
|
||||
# Task Management Workflow (guide/workflows/task-management.md)
|
||||
workflows_task_management: "guide/workflows/task-management.md"
|
||||
task_workflow_overview: "guide/workflows/task-management.md:15"
|
||||
task_workflow_planning: "guide/workflows/task-management.md:48"
|
||||
task_workflow_execution: "guide/workflows/task-management.md:160"
|
||||
task_workflow_session_mgmt: "guide/workflows/task-management.md:260"
|
||||
task_workflow_tdd_integration: "guide/workflows/task-management.md:370"
|
||||
task_workflow_plan_integration: "guide/workflows/task-management.md:440"
|
||||
task_workflow_migration: "guide/workflows/task-management.md:510"
|
||||
task_workflow_patterns: "guide/workflows/task-management.md:620"
|
||||
task_workflow_troubleshooting: "guide/workflows/task-management.md:740"
|
||||
task_workflow_advanced: "guide/workflows/task-management.md:820"
|
||||
claude_folder: 3413
|
||||
settings: 3464
|
||||
precedence_rules: 3686
|
||||
|
|
@ -354,7 +385,8 @@ deep_dive:
|
|||
# ════════════════════════════════════════════════════════════════
|
||||
decide:
|
||||
simple_task: "just ask Claude"
|
||||
complex_task: "/plan first, then TodoWrite"
|
||||
complex_task: "/plan first, then use Tasks API (v2.1.16+) or TodoWrite"
|
||||
complex_task_multi_session: "use Tasks API with CLAUDE_CODE_TASK_LIST_ID"
|
||||
context_high: "/compact (>70%) or /clear (>90%)"
|
||||
repeating: "create agent or command"
|
||||
need_docs: "Context7 MCP"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue