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

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 → TasksPlan 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.pyschema 应该和 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. 性能问题N1 查询、不必要循环 对每个问题标注 //输出分级报告。使用在 Claude Code 中输入/review即可触发。常用自定义命令命令 用途 实现方式 ───────────────────────────────────────────────── /review 审查 staged 改动 上述示例 /fix 自动修复 lint 错误 运行 ruff check修复所有错误 /test 运行相关测试 找出当前改动相关的测试文件并运行 /deploy 部署到 staging 构建 Docker 镜像 推送 重启服务 /log 查看今日开发日志 git log --sincemidnight --authorme /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.pyAPI 在 src/routes/posts.py。 先帮我分析方案不要写代码。 : [分析现有代码 → 提出方案] 方案: 新增 tags 表 post_tags 关联表 GET /api/posts?tagxxx 接口。 不改动现有 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 关系加 lazyselectin不然 N1 查询 : [修改] → : [审阅] → ✅ 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 完成审阅 diffgit diff --cached □ AI 反复犯错 → 写入 CLAUDE.md 规则 □ 对话超过 20 轮 → /compact □ 功能完成 → /clear → 下一个 □ 大改动前用 Worktree 隔离 □ 国产模型下一次 引用不超过 3 个文件延伸阅读Claude Code 官方文档 / Slash Commands