Claude Code — 调用指南

目录

1. 核心原则
2. 速查表
3. 调用方式
   • 3.1 交互式 TUI
   • 3.2 非交互单次
   • 3.3 规划模式
   • 3.4 其他常用参数
4. 工作流
   • 4.1 新项目搭建
   • 4.2 现有项目修改
   • 4.3 代码审查
   • 4.4 调试流程
   • 4.5 多文件重构
5. Subagent 并发模式
   • 5.1 适用场景
   • 5.2 调用模式
   • 5.3 注意事项
6. Prompt 编写最佳实践
   • 6.1 推荐做法
   • 6.2 避免的做法
   • 6.3 决策原则
7. 超时与进度策略
   • 7.1 核心设定
   • 7.2 进度汇报机制
   • 7.3 任务时长参考
8. 错误处理与 Fallback
   • 8.1 分层策略
   • 8.2 Fallback 规则
   • 8.3 常见错误处理
9. 性能调优
   • 9.1 执行效率优化
   • 9.2 本机资源考量
10. 交互 vs 非交互选择指南
11. Windows 环境说明
    • 11.1 路径约定
    • 11.2 PowerShell 兼容性
    • 11.3 Git 集成
    • 11.4 已知限制
12. 附录：完整速查表

1. 核心原则

所有代码相关工作一律通过 Claude Code CLI (claude) 完成，涵盖：编写、修改、重构、审查、调试、项目搭建。严禁使用内置工具（Write / Edit / Bash 中执行代码修改命令）直接操作源代码文件。

唯一例外：当 Claude Code 返回错误或 CLI 不可用时，回退到内置工具。回退前必须明确告知用户。

2. 速查表

3. 调用方式

3.1 交互式 TUI

claude

适用：探索性任务、需要多轮对话的复杂重构、需要中途决策的场景。

要求：pty: true（终端模拟）。

优势：用户可实时介入、调整方向；上下文在对话中持续累积。

3.2 非交互单次

claude -p "prompt"

适用：目标明确、边界清晰的单次任务。

优势：执行完成后自动退出，不占用终端；适合自动化脚本和 subagent 调用。

3.3 规划模式

claude -p "plan: \x3C需求描述>"

交互式下等价于输入 /plan。

工作方式：Claude Code 先生成实施方案并展示给用户，用户审阅确认后再进入执行阶段。适用于中大型任务，避免方向性返工。

3.4 其他常用参数

4. 工作流

4.1 新项目搭建

1. 创建目录 — 在 D:\claw\ 下创建项目文件夹。
2. 初始化 — 进入项目目录，执行 claude init 生成 CLAUDE.md，确保后续变更都走 Claude Code。
3. 规划 — 使用 claude -p "plan: \x3C需求>" 生成方案，用户确认后再执行，避免盲目开工。
4. 决策默认值 — Claude Code 在执行中提出功能选型、UI 框架、数据库、架构方案等问题时，默认选择功能最大化的选项；仅当方案超出本机性能（内存 / CPU / GPU）时才降级。
5. 验证交付 — 完成后要求 Claude Code 运行测试、构建或启动服务，确保交付物可用。

4.2 现有项目修改

4.3 代码审查

审查类型

审查输出规范

• 按严重程度分级：
  • 🔴 阻塞（Blocker）：必须修复才能合并
  • 🟡 建议（Warning）：推荐修复，不阻塞合并
  • 🟢 可选（Info）：锦上添花的改进
• 每条问题附带：具体代码位置 + 问题描述 + 建议修复方案
• 结尾总结：总体评价 + 是否建议合并 + 重点风险提示

4.4 调试流程

标准流程

1. 收集信息 — 整理问题描述、复现步骤、错误日志、相关文件路径。
2. 提交调试 — claude -p "debug: \x3C问题描述 + 复现步骤 + 错误日志>"，附带相关代码文件路径。
3. 定位根因 — Claude Code 搜索关联代码、追踪调用链、分析数据流。
4. 最小修复 — 提出最小化修复方案，不改动无关代码。
5. 验证修复 — 运行相关测试或用例确认问题已解决，同时跑完整测试套件确保无回归。

高效调试 Prompt 模板

claude -p "debug: 用户登录后 token 未写入 cookie。

复现步骤：
1. 访问 /login → 输入有效凭据
2. 登录成功后跳转 /dashboard
3. 检查 cookie → token 字段为空

相关文件：src/auth/login.ts, src/middleware/session.ts
错误日志：[粘贴完整错误日志]
预期行为：登录成功后 Set-Cookie 应包含 httpOnly token"

调试原则

• 优先排查最近改动的代码（git diff HEAD~1 辅助定位）
• 一次只修改一个变量/逻辑，验证通过后再继续
• 修复后跑完整测试套件，不只跑相关用例
• 对不确定的推断，先加日志验证假设，再改代码

4.5 多文件重构

标准流程

1. 圈定范围 — 通过关键字搜索和依赖分析，列出所有涉及改动的文件清单。
2. Plan 先行 — claude -p "plan: 重构 \x3C范围描述>"，生成重构方案并经用户确认。
3. 分步执行 — 按依赖顺序逐步完成，每完成一步验证一次（测试 + 构建），确保每步可回滚。
4. 最终验证 — 全量测试 + lint 检查 + 确认无行为变更。

重构原则

• 小步提交：每完成一个独立步骤（如"提取接口"→"迁移调用方"→"删除旧代码"）做一次提交。
• 行为不变：在不动外部行为的前提下调整内部结构。
• 先测试：如果目标代码缺少测试覆盖，先补齐测试，再重构。
• 并行处理：跨模块重构使用 subagent 并行处理互不依赖的模块（见§5）。

跨模块并行重构示例

主会话 → claude -p "plan: 确定重构方案 + 模块边界划分"
       ├─ spawn subagent A → claude -p "重构 Module A：\x3C具体任务>"
       └─ spawn subagent B → claude -p "重构 Module B：\x3C具体任务>"
主会话 ← 汇总结果 → 集成测试验证 → 统一提交

5. Subagent 并发模式

首选并行策略 — 通过 subagent spawn 并行调用多个 Claude Code 实例，避免阻塞主会话。

5.1 适用场景

• 同时修改多个互不依赖的独立文件
• 批量代码审查（多文件各自独立审查）
• 前后端同时改动（各自独立上下文）
• 大型项目的分模块重构（每个模块独立处理）

5.2 调用模式

主会话 → spawn subagent A (claude -p "任务A")
       → spawn subagent B (claude -p "任务B")
       → spawn subagent C (claude -p "任务C")
       → 等待全部完成 → 汇总结果 → 集成验证

Subagent 之间无通信，不共享文件写入锁。

5.3 注意事项

• 各 subagent 任务必须互不依赖 — 不能存在文件写入冲突。
• 所有 subagent 完成后，由主会话统一汇总、处理冲突、执行集成测试。
• Subagent 同样不设超时，自然运行至完成或报错。
• 并行数量不超过本机 CPU 核心数（避免资源争抢）。

6. Prompt 编写最佳实践

6.1 推荐做法

• 描述目标，而非步骤："重构 UserService 使每个方法不超过 20 行" 优于 "拆分 UserService 的 login 方法" — Claude Code 比你更了解代码结构，让它自己找最优路径。
• 提供必要上下文：相关文件路径、已有架构决策、不可变更的约束条件。
• 指定输出格式：控制输出密度，如 "列出 5 个优化点，每个一行"、"生成 JSON 格式的结果"。
• 审查类任务指明维度：安全性、性能、可读性、架构一致性、测试覆盖率。
• 调试类任务提供三要素：问题描述 + 复现步骤 + 错误日志。
• 对于超过 3 个文件的任务，先 plan 再执行：claude -p "plan: ..." 生成方案确认后再行动。

6.2 避免的做法

• ❌ 模糊指令："帮我看看代码"、"优化一下" — 没有范围，结果不可控。
• ❌ 过度约束："只能用 X 库、Y 模式、Z 框架" — 除非是硬性约束，否则限制 Claude Code 的方案空间。
• ❌ 一个 prompt 塞太多无关任务 — 拆分成独立调用，每个聚焦一个主题。
• ❌ 空泛的上下文："这个项目很大" — 具体点出哪些文件/模块是关键的。

6.3 决策原则

当 Claude Code 在执行中提出多个可选方案时，默认决策顺序：

1. 功能最大化优先 — 选择实现功能最完整的方案。
2. 资源约束降级 — 仅当方案超出本机资源（内存不足、GPU 不可用、磁盘空间不够）时选择轻量方案。
3. 最新稳定技术 — 依赖库选最新稳定版（不锁定过时版本），框架选当前主流 LTS 版本。

7. 超时与进度策略

7.1 核心设定

• 永不超时 — exec / subagent 不设置 timeout 参数，runTimeoutSeconds 设为 0 或完全省略。
• Claude Code 运行至自然完成（任务结束）或报错退出，不因时长中断。

7.2 进度汇报机制

每 10 分钟轮询一次进度，方式二选一：

1. Cron / Schedule wakeup — 设置每 10 分钟触发一次状态检查。
2. Monitor — 对日志输出进行监控，检测关键事件（文件改动、构建完成、报错）。

汇报内容：直接向用户同步当前状态 — "已完成 XX 文件，正在处理 YY，预计还需 ZZ 分钟"，不做沉默等待。

Claude Code 完成后发送最终结果摘要：改动文件清单 + 成功/失败状态 + 后续建议。

7.3 任务时长参考

8. 错误处理与 Fallback

8.1 分层策略

调用 Claude Code CLI
  ├─ 成功 → 返回结果给用户
  │
  ├─ 可恢复错误（prompt 被拒、输出超限等）
  │   ├─ 重试 1 次：调整 prompt 措辞或缩小范围
  │   └─ 仍失败 → Fallback 到内置工具，告知用户
  │
  ├─ 配置/环境错误（CLI 未安装、认证失败、项目未 init）
  │   └─ 给出明确的修复指引 → 问题解决后重新走 CLI
  │   └─ 若无法解决 → Fallback 到内置工具
  │
  └─ Claude Code 完全不可用（命令不存在、网络不通）
      └─ 直接用内置工具完成任务，明确告知用户当前处于 Fallback 模式

8.2 Fallback 规则

1. 仅当 CLI 返回错误时才触发 — 不可主动跳过 CLI 直接使用内置工具。
2. 必须告知用户 — "Claude Code 因 [具体原因] 不可用，已切换至内置工具模式"。
3. 完成后建议修复 — Fallback 模式结束后，建议用户排查 Claude Code 安装和配置，恢复正常工作流。
4. 禁止静默 Fallback — 用户必须知晓当前未走 CLI。

8.3 常见错误处理

9. 性能调优

9.1 执行效率优化

• 缩小单次范围：每次调用聚焦 1–3 个文件，大型任务拆解为多次调用。
• 预加载上下文：将关键代码片段直接嵌入 prompt，减少 Claude Code 自行探索文件的时间。
• 按需选择模型：简单任务（格式化、命名修正、注释补充）用 --model haiku；复杂任务（重构、调试、架构设计）使用默认模型（Opus）。
• 避免重复 init：已初始化的项目直接执行任务，不要重复运行 claude init。
• 复用 CLAUDE.md：确保项目 CLAUDE.md 准确全面，作为每次调用的基础上下文，显著减少 Claude Code 的理解成本。
• 善用 --resume：交互式会话中断后可 claude --resume 恢复，避免从头开始。
• 解析输出选对格式：脚本化场景使用 --output-format stream-json 而非纯文本，解析更可靠。

9.2 本机资源考量

• 并行 subagent 数量不超过 CPU 核心数（建议 ≤ 4）。
• 大型构建任务（npm install、docker build）在 plan 阶段评估耗时，必要时异步执行。
• GPU 训练任务：执行前确认 CUDA / GPU 资源可用。
• 磁盘空间敏感的项目，提醒 Claude Code 在生成依赖前检查剩余空间。

10. 交互 vs 非交互选择指南

选择原则：不确定时优先用 claude -p — 如果 prompt 体积过大或单轮无法完成，再升级为交互式 claude。

典型用例：

• 用 claude -p：修一个 bug、改一个函数名、审查一个文件、添加一个 API 端点。
• 用 claude（交互）：新项目从零搭建、架构级重构、跨 10+ 文件的大范围修改、需求本身还在探索中。

11. Windows 环境说明

11.1 路径约定

• 项目目录统一存放在 D:\claw\ 下。
• 路径分隔符：反斜杠 \ 和正斜杠 / 均可使用，Claude Code 在 Windows 下兼容两种形式。
• 路径含空格时使用引号包裹：claude -p "..." --project "D:\claw\my project"

11.2 PowerShell 兼容性

11.3 Git 集成

• claude init 自动处理 Windows 下的文件权限和换行符（CRLF / LF）配置。
• 建议在项目根目录配置 .gitattributes 统一换行符：

* text=auto
*.ts text eol=lf
*.js text eol=lf
*.bat text eol=crlf

11.4 已知限制

• TUI 模式下终端宽度影响输出格式，建议 ≥ 120 列。
• 推荐使用 Windows Terminal 而非传统 conhost（命令提示符），前者对 ANSI 转义序列、UTF-8 和字体渲染支持更好。
• WSL 内也可以运行 Claude Code，但项目路径应映射为 Linux 路径（/mnt/d/claw/...），与 Windows 侧的路径约定分开管理。

12. 附录：完整速查表

命令速查

模式选择速查

决策速查