Back to Details

claude-code-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
文档中的关键词"MUST"、"MUST NOT"、"REQUIRED"、"SHALL"、"SHALL NOT"、"SHOULD"、"SHOULD NOT"、"RECOMMENDED"、"MAY"和"OPTIONAL"应按照RFC 2119中的描述进行解释。

Claude Code Workflow

Claude Code 工作流

Guidelines for effective AI-assisted development with Claude Code.
使用Claude Code进行高效AI辅助开发的指南。

Task Value Matrix

任务价值矩阵

ValueTask TypeExample
HighBoilerplate generationCRUD endpoints, test scaffolding
HighRefactoringExtract function, rename across files
HighDocumentationDocstrings, README updates
MediumBug investigationError analysis, log interpretation
MediumCode reviewPattern suggestions, security review
LowNovel architectureRequires deep domain knowledge
LowAmbiguous requirementsNeeds human clarification
价值任务类型示例
高样板代码生成CRUD接口、测试脚手架
高代码重构提取函数、跨文件重命名
高文档编写文档字符串、README更新
中错误排查错误分析、日志解读
中代码评审模式建议、安全评审
低新型架构设计需要深厚领域知识
低模糊需求处理需要人工澄清

Workflow Patterns

工作流模式

Explore-Plan-Code-Commit (EPCC)

Explore-Plan-Code-Commit (EPCC)

The RECOMMENDED workflow for most development tasks:
  1. Explore: Use Glob, Grep, Read to understand existing code
    • MUST understand context before making changes
    • SHOULD identify related files and dependencies
    • MAY use subagents for parallel exploration
  2. Plan: Outline changes before implementation
    • SHOULD create TodoWrite items for multi-step tasks
    • MUST validate plan covers edge cases
  3. Code: Implement changes incrementally
    • MUST run tests after each significant change
    • SHOULD use Edit over Write for existing files
    • SHALL NOT introduce breaking changes without tests
  4. Commit: Create logical, atomic commits
    • MUST follow semantic commit conventions
    • SHALL NOT commit secrets or credentials
适用于大多数开发任务的推荐工作流：
  1. 探索（Explore）：使用Glob、Grep、Read工具理解现有代码
    • 必须在修改前理解上下文
    • 应该识别相关文件和依赖
    • 可以使用子代理进行并行探索
  2. 规划（Plan）：在实现前概述修改内容
    • 应该为多步骤任务创建TodoWrite项
    • 必须验证计划覆盖边缘情况
  3. 编码（Code）：增量式实现修改
    • 必须在每次重要修改后运行测试
    • 应该对现有文件使用Edit而非Write工具
    • 不得在未测试的情况下引入破坏性变更
  4. 提交（Commit）：创建逻辑化、原子化的提交
    • 必须遵循语义化提交规范
    • 不得提交密钥或凭证

Test-Driven Development with AI

结合AI的测试驱动开发

1. Write failing test → 2. Implement minimum to pass → 3. Refactor → 4. Repeat
  • MUST run tests between each step
  • SHOULD use targeted test execution during development
1. 编写失败的测试 → 2. 实现最小代码使测试通过 → 3. 重构 → 4. 重复
  • 必须在每个步骤之间运行测试
  • 应该在开发过程中使用针对性的测试执行

Spike-Then-Implement

原型验证后实现（Spike-Then-Implement）

For uncertain implementations: Create throwaway spike, validate, delete, implement properly with tests.
对于不确定的实现：创建一次性原型，验证可行性后删除，再结合测试正式实现。

Context Management

上下文管理

Efficient Prompting

高效提示词编写

MUST: Provide specific file paths, include error messages verbatim, state expected vs actual behavior
SHOULD: Reference previous context, specify output format, include constraints upfront
SHOULD NOT: Repeat information in context, include unnecessary background, ask multiple unrelated questions
必须：提供具体文件路径、逐字包含错误信息、说明预期与实际行为差异
应该：引用之前的上下文、指定输出格式、提前说明约束条件
不应该：在上下文中重复信息、包含无关背景、询问多个不相关问题

Conversation Structure

对话结构

[Initial Context] → [Specific Task] → [Iterative Refinement]
  • SHOULD front-load critical information
  • MUST NOT bury important constraints at end of message
[初始上下文] → [具体任务] → [迭代优化]
  • 应该将关键信息前置
  • 不得将重要约束隐藏在消息末尾

Context Window Optimization

上下文窗口优化

  • SHOULD use subagents for isolated subtasks
  • MUST NOT paste entire files when snippets suffice
  • 应该使用子代理处理孤立子任务
  • 不得在代码片段足够时粘贴整个文件

Subagent vs Direct Tool Usage

子代理 vs 直接工具使用

Use Subagents (Task tool) When:

应使用子代理（Task工具）的场景：

  • Parallel independent operations (multiple searches, test runs)
  • Isolated subtasks not needing main conversation context
  • Complex multi-step work (refactoring across many files)
  • Risk isolation (exploratory changes that might fail)
  • 并行独立操作（多文件搜索、多次测试运行）
  • 不需要主对话上下文的孤立子任务
  • 复杂多步骤工作（跨多文件重构）
  • 风险隔离（可能失败的探索性修改）

Use Direct Tools When:

应直接使用工具的场景：

  • Sequential dependencies (each step depends on previous)
  • Context continuity needed (building on recent conversation)
  • Simple operations (single file read/edit)
  • Immediate feedback required (interactive debugging)
ScenarioRecommendation
Search 5+ files for patternSubagent
Edit single fileDirect
Run tests + fix failuresSubagent
Explore unfamiliar codebaseSubagent
Implement planned changesDirect
  • 有顺序依赖的任务（每一步依赖前一步结果）
  • 需要上下文连续性的任务（基于近期对话内容开展工作）
  • 简单操作（单文件读取/编辑）
  • 需要即时反馈的任务（交互式调试）
场景推荐方案
搜索5个以上文件的特定模式子代理
编辑单个文件直接工具
运行测试并修复失败用例子代理
探索不熟悉的代码库子代理
实现已规划的修改直接工具

Model Selection

模型选择

Opus (Complex Reasoning)

Opus（复杂推理）

SHOULD use for: Architecture decisions, complex debugging, multi-file refactoring, novel problem solving, security-sensitive code review
应该用于：架构决策、复杂调试、多文件重构、新型问题解决、安全敏感代码评审

Sonnet (Standard Tasks)

Sonnet（标准任务）

RECOMMENDED for: Routine code changes, test writing, documentation, code review, bug fixes with clear scope
推荐用于：日常代码修改、测试编写、文档编写、代码评审、范围明确的bug修复

Haiku (Quick Operations)

Haiku（快速操作）

MAY use for: Simple queries, syntax checking, format conversions, quick lookups, commit message generation
IF deep reasoning OR high-stakes: USE Opus
ELSE IF routine development: USE Sonnet
ELSE IF simple/quick: USE Haiku
可以用于：简单查询、语法检查、格式转换、快速查找、提交信息生成
IF 深度推理 OR 高风险场景: USE Opus
ELSE IF 常规开发任务: USE Sonnet
ELSE IF 简单/快速操作: USE Haiku

Quality Assurance

质量保障

Automated Validation

自动化验证

MUST: Test execution after changes, linting/formatting, type checking, security scanning
SHOULD: Coverage thresholds, performance benchmarks, integration tests
必须：修改后执行测试、代码检查/格式化、类型检查、安全扫描
应该：覆盖率阈值、性能基准测试、集成测试

Human Review Checkpoints

人工评审检查点

REQUIRED: Security-sensitive changes, production deployments, architecture modifications, public API changes
RECOMMENDED: Complex business logic, performance-critical code, external integrations
必需：安全敏感修改、生产环境部署、架构调整、公开API变更
推荐：复杂业务逻辑、性能关键代码、外部集成

Prompt Engineering for Code Tasks

代码任务的提示词工程

Specificity Patterns

具体化模式

Effective: "Refactor UserService in src/services/user.py to use dependency injection for database connection"
Ineffective: "Clean up the user code"
有效示例："重构src/services/user.py中的UserService，使其使用依赖注入管理数据库连接"
无效示例："整理用户代码"

Constraint Specification

约束条件说明

MUST specify: Language/framework versions, performance requirements, backward compatibility, error handling
必须指定：语言/框架版本、性能要求、向后兼容性、错误处理规则

Prompt Templates

提示词模板

Bug Fix:
File: [path] | Error: [exact message]
Expected: [behavior] | Actual: [behavior]
Relevant code: [snippet]
Feature:
Goal: [one sentence]
Criteria: [list] | Location: [file] | Constraints: [limits]
Bug修复：
文件: [路径] | 错误: [准确信息]
预期行为: [描述] | 实际行为: [描述]
相关代码: [片段]
功能开发：
目标: [一句话描述]
标准: [列表] | 位置: [文件] | 约束: [限制条件]

Session Context Management

会话上下文管理

Integration with Context Files

与上下文文件的集成

CURRENT.md - Active task state (SHOULD update when switching tasks, MUST reflect current focus)
STATUS.md - Project progress (SHOULD update at session end, MUST include blockers/next steps)
CURRENT.md - 活跃任务状态（切换任务时应该更新，必须反映当前工作重点）
STATUS.md - 项目进度（会话结束时应该更新，必须包含障碍/下一步计划）

Session Lifecycle

会话生命周期

[Start] → [Load CURRENT.md] → [Work + TodoWrite] → [End] → [Update STATUS.md]
[开始] → [加载CURRENT.md] → [工作 + TodoWrite] → [结束] → [更新STATUS.md]

Context Preservation

上下文保留

  • MUST save context before long breaks
  • SHOULD use /snapshot for complex multi-session work
  • MAY use /pickup to resume efficiently
  • 必须在长时间中断前保存上下文
  • 应该对复杂多会话工作使用/snapshot命令
  • 可以使用/pickup命令高效恢复会话

Skill Activation Optimization

技能激活优化

Triggering Skills Efficiently

高效触发技能

  • MUST use specific keywords in descriptions
  • SHOULD include file patterns for automatic activation
  • MAY use manual invocation for specialized skills
  • 必须在描述中使用特定关键词
  • 应该包含文件模式以实现自动激活
  • 可以手动调用特定技能

Skill Composition

技能组合

Skills SHOULD be: Single-purpose, composable, self-contained
Skills MUST NOT: Conflict with others, duplicate core rules, exceed context budget
PatternTrigger
File-based
*.py
, 
Dockerfile
, 
package.json
Directory-based
.claude/
, 
tests/
, 
src/
Content-basedKeywords in conversation
Command-based
/skill-name
invocation
技能应该：单一用途、可组合、独立封装
技能不得：与其他技能冲突、重复核心规则、超出上下文预算
模式触发方式
基于文件
*.py
, 
Dockerfile
, 
package.json
基于目录
.claude/
, 
tests/
, 
src/
基于内容对话中的关键词
基于命令
/skill-name
调用

Anti-Patterns to Avoid

需避免的反模式

Conversation Anti-Patterns

对话反模式

Anti-PatternBetter Approach
Context dumpingProvide focused, relevant context
Vague requestsSpecific, measurable goals
Premature optimizationMVP first, optimize with data
Ignoring errorsAddress errors immediately
反模式更佳方案
上下文冗余提供聚焦、相关的上下文
模糊请求明确、可衡量的目标
过早优化先实现MVP，基于数据优化
忽略错误立即处理错误

Tool Usage Anti-Patterns

工具使用反模式

Anti-PatternBetter Approach
Bash for file opsUse Read/Edit/Write tools
Write over EditPrefer Edit for existing files
Single-threaded searchParallel subagent searches
Skipping ReadAlways Read before Edit
反模式更佳方案
用Bash处理文件操作使用Read/Edit/Write工具
用Write替代Edit对现有文件优先使用Edit
单线程搜索使用子代理并行搜索
跳过Read操作编辑前务必先Read

Workflow Anti-Patterns

工作流反模式

Anti-PatternBetter Approach
Coding without testsTDD or test-after minimum
Giant commitsAtomic, logical commits
Ignoring TodoWriteUpdate status in real-time
反模式更佳方案
无测试编码采用TDD或先实现最小功能再补测试
巨型提交原子化、逻辑化的提交
忽略TodoWrite实时更新状态

Prompting Anti-Patterns

提示词反模式

Anti-PatternBetter Approach
"Make it better"Define specific improvements
Assuming knowledgeProvide relevant background
Ignoring constraintsState constraints upfront
反模式更佳方案
“让它更好”定义具体的改进点
假设模型具备知识提供相关背景信息
忽略约束条件提前说明约束

Quick Reference

快速参考

Effective Session

高效会话流程

  1. Start with clear goal
  2. Load context (CURRENT.md)
  3. Use EPCC workflow
  4. Update TodoWrite in real-time
  5. Run tests frequently
  6. Save context before ending
  1. 以明确目标开始
  2. 加载上下文（CURRENT.md）
  3. 使用EPCC工作流
  4. 实时更新TodoWrite
  5. 频繁运行测试
  6. 结束前保存上下文

Model Selection

模型选择

  • Opus: Architecture, security, complex bugs
  • Sonnet: Daily development, tests, docs
  • Haiku: Quick queries, formatting
  • Opus：架构设计、安全、复杂bug
  • Sonnet：日常开发、测试、文档
  • Haiku：快速查询、格式化

Tool Selection

工具选择

  • Read: View file content
  • Edit: Modify existing files
  • Write: Create new files (rare)
  • Glob: Find files by pattern
  • Grep: Search file contents
  • Task: Parallel/isolated work
  • Bash: System operations only
  • Read：查看文件内容
  • Edit：修改现有文件
  • Write：创建新文件（少用）
  • Glob：按模式查找文件
  • Grep：搜索文件内容
  • Task：并行/孤立任务
  • Bash：仅用于系统操作