Claude Code 操作指南：Task、Spec 与实战工作流

原创于 2026-06-19 13:45:00 发布 · 518 阅读

8 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#ai #agent #coding

话题

#AI编程·六月创作之星博客挑战赛

Vibe-Coding 专栏收录该内容

27 篇文章

订阅专栏

Claude Code 操作指南：Task、Spec 与实战工作流

Claude Code 的核心交互模型

先把模型搞清楚。Claude Code 不是"你问一句 AI 答一句"的聊天工具——它是一个能自主执行多步操作的 Agent。

聊天工具（ChatGPT Web）:
  你: "写一个排序函数"
  AI: [输出代码]
  你: [复制粘贴] → [跑一下] → [有问题回来继续问]
  → 每次交互是独立的

Claude Code:
  你: "帮我实现用户注册功能"
  AI: [读项目文件] → [创建 models.py] → [创建 routes.py]
     → [写测试] → [运行测试] → [发现失败] → [自己修复] → [测试通过]
  你: [审阅 diff] → 合并
  → AI 自主完成多步骤任务闭环

关键差异：Claude Code 有工具——它能读文件、写文件、执行命令、搜索代码。你的任务是学会编排这些工具，而不是把 AI 当问答机器人用。

一次性任务 vs 多步骤项目

用 Claude Code 之前，先判断任务类型：

一次性任务（一个回合搞定）:
  → "这个错误是什么意思？"
  → "帮我把这个 for 循环改成列表推导式"
  → "给这个函数加类型标注"
  策略: 直接说，不用规划

多步骤任务（需要多个回合、多个文件）:
  → "给项目加用户认证系统"
  → "把订单模块从 REST 改成 GraphQL"
  → "重构整个错误处理机制"
  策略: 需要规划——Plan Mode 或 Spec 驱动

大多数人用不好 Claude Code 的原因：把多步骤任务当一次性任务用。 AI 写了第一步，你没跟进第二步，就停在半成品状态了。

技巧一：Plan Mode——先设计再施工

什么时候用 Plan Mode

触发条件（满足任一就用 Plan Mode）:
  ✅ 任务涉及 3 个以上文件
  ✅ 需要做技术选型（选什么库、什么模式）
  ✅ 你不确定最佳方案——想让 AI 先帮你分析
  ✅ 任务有多个独立步骤，需要排依赖顺序

怎么用

在 Claude Code 中输入：

/plan 给用户模块加上角色权限控制。目前用户表有 id/email/password_hash，
需要支持 admin/editor/viewer 三种角色。admin 能管理用户，editor 能编辑内容，
viewer 只能看。要求不破坏现有 API。

AI 会进入 Plan Mode：

先探索项目结构（读文件、理解现有代码）
提出设计方案（数据库改动、新增 API、权限中间件）
列出实施步骤（Task 列表）
等你确认后才开始写代码

Plan Mode 的正确用法

❌ 错误: 把 Plan Mode 当搜索引擎
  /plan 怎么用 React？ → AI 输出泛泛的教程

✅ 正确: 把 Plan Mode 当架构师
  /plan 在这个项目里加角色权限，要兼容现有的 JWT 认证方式
  → AI 读你项目的实际代码 → 给出针对你项目的具体方案

关键: 提供足够的上下文。Plan Mode 的质量 = 你给的上下文质量。
      至少告诉 AI: 改什么模块、不动什么、有什么硬约束。

国产模型的 Plan 模式适配

DeepSeek / Qwen 在 Plan Mode 下:
  → 分析现有代码的能力弱于 Claude（可能读不全文件、漏掉关键依赖）
  → 应对: 手动开关键文件给 AI 看
    /plan 基于 @src/models/user.py @src/middleware/auth.py 
          为项目加上角色权限。不要改动现有的 JWT 验证逻辑。
  
  用 @文件路径 明确告诉 AI 读哪些文件，不要让它自己探索。

技巧二：Spec 驱动——PRD → Architecture → Tasks

Plan Mode 适合中等任务。对于大型功能（10+ 文件、3+ 天开发），用 Spec 驱动更稳。

Spec 三件套

specs/
├── 01-prd.md          # 要做什么
├── 02-architecture.md  # 怎么做
└── 03-tasks.md         # 分几步做

第一步：生成 PRD

在 Claude Code 中:
  "帮我为"用户积分系统"写一份 PRD。
  
  背景: 电商平台，用户下单获得积分，积分可以抵扣金额。
  约束: 100 积分 = 1 元，积分有效期 1 年，支持部分使用。
  
  PRD 要包含:
  - 用户故事（谁需要什么功能，为什么）
  - 功能列表（按优先级排列）
  - 验收标准（每个功能怎么算"做完了"）
  - 不做什么（明确范围边界）
  
  输出到 specs/01-prd.md"

生成后你逐项审阅，重点是：

功能范围对不对（有没有漏掉的，有没有多余的）
验收标准够不够具体（能不能直接用来验证）
边界画得对不对（什么不在范围内）

审阅通过后才进入下一步。

第二步：生成架构设计

"基于 specs/01-prd.md，设计技术方案。

  现有技术栈: Python 3.12 + FastAPI + SQLAlchemy + PostgreSQL + Redis
  约束: 不引入新的数据库，利用现有基础设施
  
  输出到 specs/02-architecture.md，包含:
  - 数据模型设计（表结构、索引、迁移方案）
  - API 设计（接口路径、请求/响应格式）
  - 积分计算流程（时序图或流程描述）
  - 关键决策及原因（为什么这样设计）"

第三步：拆解任务

"基于 specs/01-prd.md 和 specs/02-architecture.md，生成任务列表。

  规则:
  1. 每个 Task 是可独立完成和验证的最小单元
  2. Task 之间有依赖关系的注明（Task 3 依赖 Task 1,2）
  3. 按依赖顺序排列
  
  输出到 specs/03-tasks.md"

生成的 tasks.md 大概长这样：

# 用户积分系统 - 任务列表

## Phase 1: 数据库
- [ ] Task 1.1: 创建积分账户表（user_id, balance, total_earned, total_spent）
- [ ] Task 1.2: 创建积分流水表（user_id, amount, type, order_id, expires_at）
- [ ] Task 1.3: 数据库迁移脚本 + 回滚脚本

## Phase 2: 核心逻辑
- [ ] Task 2.1: 积分获取 Service（下单完成后调用）  ← 依赖 1.1, 1.2
- [ ] Task 2.2: 积分消费 Service（下单时抵扣）      ← 依赖 1.1, 1.2
- [ ] Task 2.3: 积分过期处理（定时任务）             ← 依赖 1.2

## Phase 3: API
- [ ] Task 3.1: GET /api/points/balance               ← 依赖 1.1
- [ ] Task 3.2: GET /api/points/history               ← 依赖 1.2
- [ ] Task 3.3: POST /api/orders（集成积分抵扣）       ← 依赖 2.2

## Phase 4: 测试
- [ ] Task 4.1: 积分获取单元测试
- [ ] Task 4.2: 积分消费单元测试（含并发场景）
- [ ] Task 4.3: 积分过期单元测试

第四步：逐 Task 执行

这是最关键的实操环节：

每开始一个 Task:
  1. 在 Claude Code 中说: "基于 specs/02-architecture.md，实现 Task 2.1: 积分获取 Service"
  2. AI 读 Spec 理解设计 → 找相关文件 → 写代码 → 跑测试
  3. 你审阅 diff → 确认合并
  4. 在 tasks.md 中把 Task 2.1 标记为 ✅
  5. 开始下一个 Task

每个 Task 的执行循环:
  AI 写代码 → 你审阅 → 有问题纠正 → AI 修改 → 你通过 → 下一个

一个 Task 通常 10-30 分钟。不要跳步，不要并行。

为什么不能跳过 Spec 直接写代码？ 因为 Claude Code 的上下文有限。如果直接把整个需求丢给它，它会忘记前半部分的要求。Spec 文档等于给每个 Task 提供了精确的约束范围——AI 每次只处理一个 Task，但每个 Task 的输入（Spec）是完整且一致的。

技巧三：TODO 追踪——让 AI 自己管理进度

什么时候用 TODO

对于中大型任务（3+ 步骤），让 AI 在对话中自建 TODO，你就不用反复提醒"下一步做什么"。

在 Claude Code 中:
  "帮我实现用户积分系统。先读 @specs/03-tasks.md，
   然后从 Task 1.1 开始。每完成一个 Task 更新 TODO 状态。"

AI 会：

在对话中创建 TODO 列表（对应 tasks.md）
开始执行 Task 1.1
完成后标记 [x]，自动开始 Task 1.2
遇到阻塞停下来告诉你

你不用盯着，AI 自己管理执行进度。

TODO 的正确用法

✅ 好的 TODO（具体可执行）:
  [ ] 创建 points_accounts 数据库表
  [ ] 实现 award_points(user_id, order_id, amount) 函数
  [ ] 写单元测试：正常获取积分、订单金额为0、重复获取

❌ 差的 TODO（太模糊）:
  [ ] 完成积分获取功能
  → AI 不知道"完成"是什么意思，你也不知道什么时候该检查

技巧四：用 @ 引用精准喂上下文

Claude Code 中 @ 是最有用的快捷键。与其用自然语言描述文件位置，不如直接引用：

引用文件:
  "帮我重构 @src/services/user_service.py，把 SQL 查询抽到 @src/repositories/user_repo.py"

引用目录:
  "检查 @src/modules/orders/ 目录下所有文件的类型标注是否完整"

引用多个文件:
  "对比 @models/user.py 和 @schemas/user.py，schema 应该和 model 保持一致"

引用 git diff:
  "review 一下 @git:staged 的改动"
  "解释 @git:main...feature-branch 的变更"

引用对话历史:
  "根据刚才 @chat:previous 中讨论的方案，开始实现"

为什么 @ 比描述更有效？ 因为它消除了"文件在哪、叫什么名字"的歧义。AI 不需要猜，它直接读取文件内容。

国产模型下 @ 引用特别注意

DeepSeek 在同时引用 5 个以上文件时，可能出现:
  → 只读了前 3 个，后 2 个的内容被忽略
  → 或者全部读了但后几个的细节在生成时被遗忘

应对: 一次引用不超过 3 个文件。如果确实需要 5 个文件的上下文:
  第 1 步: 引用文件 A、B、C → 让 AI 先理解和总结
  第 2 步: 引用文件 D、E + AI 上一步的总结 → 继续

技巧五：回退和分支——安全网

Git Worktree 隔离

Claude Code 支持 Git Worktree——在隔离环境中改代码，不影响主工作区：

在 Claude Code 中:
  /worktree 帮我实现积分过期逻辑

AI 的操作:
  1. 创建独立 Worktree（新分支）
  2. 在 Worktree 中修改文件
  3. 跑测试确认通过
  4. 把改动以 PR 形式展示给你
  5. 你确认 → 合并回主分支
  6. Worktree 自动清理

好处:
  ✅ 万一 AI 改坏了 → Worktree 隔离，主分支毫发无伤
  ✅ 能同时开多个 Worktree 做不同 Task（但注意磁盘空间）
  ✅ 每个 Worktree 是独立上下文，不会互相污染

随时可以回退

AI 改了 5 个文件，你发现第 3 步开始方向偏了:

不要手动改回去。用 git:
  git diff → 看 AI 改了什么
  git checkout -- <file> → 回退单个文件
  git stash → 暂时保存改动，重置到干净状态

然后在 Claude Code 中:
  "刚才的改动不要了，我们重来。这次 @src/services/order_service.py 
   中的 calculate_total 函数不要动，只改积分相关的部分。"

技巧六：自定义 Slash Command——高频操作一键触发

创建自定义命令

在 .claude/commands/ 目录下创建 markdown 文件：

<!-- .claude/commands/review.md -->

Review 当前所有 staged 文件的改动。检查:
1. 安全问题（SQL 注入、XSS、密钥硬编码）
2. 逻辑错误（边界条件、错误处理、并发安全）
3. 代码风格（命名、函数长度、类型标注）
4. 性能问题（N+1 查询、不必要循环）

对每个问题标注 🔴/🟡/🟢，输出分级报告。

使用：在 Claude Code 中输入 /review 即可触发。

常用自定义命令

命令         用途                    实现方式
─────────────────────────────────────────────────
/review      审查 staged 改动        上述示例
/fix         自动修复 lint 错误      "运行 ruff check，修复所有错误"
/test        运行相关测试            "找出当前改动相关的测试文件并运行"
/deploy      部署到 staging         "构建 Docker 镜像 + 推送 + 重启服务"
/log         查看今日开发日志        "git log --since=midnight --author=me"
/new-func    生成新函数模板          "根据项目规范生成带类型标注的函数模板"

技巧七：上下文管理——保持 AI 在最佳状态

会话管理

对话轮数     AI 表现
─────────────────────────────────────
1-10 轮     🟢 最佳：上下文充足，响应准确
11-20 轮    🟡 良好：历史开始堆积，响应速度略降
21-30 轮    🟠 注意：上下文已经很大，AI 可能忽略早期指令
30+ 轮      🔴 建议重置：token 消耗大、回复速度慢、质量下降

最佳实践:
  完成一个功能模块 → /clear → 开始下一个
  不要把 3 个不相关的功能堆在同一场对话里

定期清理上下文

/compact  → 压缩对话历史（保留关键信息，丢弃冗余内容）
/clear    → 清空对话（从头开始，所有上下文丢失）

什么时候用 /compact:
  → 对话超过 20 轮
  → 你感觉 AI 开始"忘记"你之前说的东西
  → Token 消耗明显变慢

什么时候用 /clear:
  → 功能完成，开始一个完全不同的任务
  → AI 的行为明显混乱，不如重来

完整实战流程：一个功能的诞生

以"给博客加标签系统"为例：

准备工作:
  □ 检查 CLAUDE.md 是否最新（标签系统相关的规则有没有）
  □ 确认项目结构清晰（AI 找得到要改的文件）

第1步: 对齐需求（5 分钟）
  👤: "我想给博客文章加标签功能。每篇文章可以有多个标签。
      标签需要支持搜索（按标签筛选文章）和展示（文章详情页显示标签）。
      目前文章模型在 @src/models/post.py，API 在 @src/routes/posts.py。
      先帮我分析方案，不要写代码。"
  
  🤖: [分析现有代码 → 提出方案]
      "方案: 新增 tags 表 + post_tags 关联表 + GET /api/posts?tag=xxx 接口。
       不改动现有 API 的响应格式，标签作为文章的扩展字段返回。"
  
  👤: "可以。但标签名要唯一，不区分大小写。开始吧。"

第2步: 创建 Spec（如果任务大） 或 直接进入 Plan Mode（中等任务）
  👤: /plan 实现博客标签系统。方案已确认：tags 表 + post_tags 关联表。
      约束: 不改动现有 API 响应格式，标签名唯一且不区分大小写。

  🤖: [进入 Plan Mode]
      "实施计划:
       1. 新建 @src/models/tag.py — Tag 和 PostTag 模型
       2. 修改 @src/models/post.py — Post 模型添加 tags 关系
       3. 数据库迁移
       4. 新建 @src/routes/tags.py — 标签 CRUD + 搜索接口
       5. 修改 @src/routes/posts.py — 文章接口返回标签数据
       6. 单元测试
       确认后开始执行？"

  👤: "第 4 步和第 5 步换一下顺序——先改现有接口，再新增标签管理接口。"

第3步: 逐步执行（每个步骤 5-20 分钟）
  Step 1: "创建 Tag 模型"
     🤖: [写代码] → 👤: [审阅] → ✅
  
  Step 2: "修改 Post 模型添加关系"
     🤖: [写代码] → 👤: "tag 关系加 lazy='selectin'，不然 N+1 查询"
     🤖: [修改] → 👤: [审阅] → ✅
  
  Step 3: "生成迁移脚本"
     🤖: [生成 migration] → 👤: [审阅 SQL] → ✅
  
  Step 4: "修改文章接口返回标签"
     🤖: [修改 routes/posts.py] → 👤: "标签数据只返回 name 字段，不要 id"
     🤖: [修改] → 👤: [curl 测试] → ✅
  
  Step 5: "新增标签管理接口"
     🤖: [写代码] → 👤: "POST /api/tags 加权限校验，只有 admin 能创建"
     🤖: [修改] → ✅
  
  Step 6: "写测试"
     🤖: [生成测试] → 👤: [跑测试] → 通过 ✅

第4步: 复盘
  👤: "复盘一下标签功能。有什么可以优化的？"
  🤖: "两点:
       1. get_post_tags 查询可以加 Redis 缓存（现在每次都查关联表）
       2. Tag 模型的不区分大小写规则可以加进 CODEBUDDY.md"
  👤: "好。这两点都加上。"

整个过程：你主导方向和决策，AI 负责代码实现和细节。节奏由你控制。

常见问题速查

Q: AI 说"我来分析一下"然后就卡住了？

通常是上下文太大了。/compact 压缩后再试。国产模型（DeepSeek）在 >60K Token 时特别容易卡住。

Q: @ 引用文件时 AI 说找不到？

检查路径是否正确。用 Tab 键可以自动补全路径。如果文件刚创建还没保存，AI 读不到。

Q: Worktree 模式下改的东西怎么合并？

AI 会以 PR 形式呈现改动。你在 Claude Code 中审阅 diff → 确认 → AI 执行 merge。如果冲突了，AI 会告诉你冲突文件，你手动解决。

Q: 会话断了（关闭终端），怎么继续？

重新打开 Claude Code，它会恢复上次的对话上下文。但国产模型可能在恢复长对话时丢失部分上下文——建议每个功能模块完成后 /clear。

操作清单

□ 区分任务类型: 一次性任务直接说，多步骤任务上 Plan Mode
□ 大功能（10+ 文件）写 Spec 三件套: PRD → Architecture → Tasks
□ 用 @ 引用文件，不描述文件位置
□ 每个 Task 独立完成和验证，不跳步
□ Task 完成审阅 diff（git diff --cached）
□ AI 反复犯错 → 写入 CLAUDE.md 规则
□ 对话超过 20 轮 → /compact
□ 功能完成 → /clear → 下一个
□ 大改动前用 Worktree 隔离
□ 国产模型下一次 @ 引用不超过 3 个文件