Claw Claude

Call Claude Code CLI for coding tasks — write, refactor, review, debug, and scaffold new projects. Use when the user asks for code creation, modification, review, or debugging. Fall back to built-in tools only if Claude Code errors out.

duplicate of @dajiaohuang/claw-claude-code

Audits

Pass

ClawScanPass

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPass

Multi-engine malware detections and file reputation.

Install

openclaw skills install claw-claude

Claude Code — 调用指南

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

1. 核心原则

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

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

2. 速查表

场景	命令 / 方式	关键配置
交互式 TUI	`claude`	需要 `pty: true`
单次任务	`claude -p "prompt"`	非交互，跑完即退出
规划模式	`claude -p "plan: 需求..."`	先生成方案，确认后执行
代码审查	`claude -p "审查 <目标>"`	详见 §4.3
安全审查	`claude -p "security-review"` 或 `/security-review`	聚焦 OWASP Top 10
调试	`claude -p "debug: <问题>"`	详见 §4.4
批量并行	spawn subagent × N	详见 §5
已 init 项目	一律 `claude` / `claude -p`	禁止内置工具直接操作文件
Fallback	内置工具	仅当 Claude Code 报错时，且须告知用户

3. 调用方式

3.1 交互式 TUI

claude

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

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

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

3.2 非交互单次

claude -p "prompt"

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

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

3.3 规划模式

claude -p "plan: <需求描述>"

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

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

3.4 其他常用参数

参数	用途	示例
`--output-format stream-json`	流式 JSON 输出（便于脚本解析）	`claude -p "..." --output-format stream-json`
`--model`	指定模型	`--model haiku`（轻量任务）/ `--model opus`（复杂任务）
`--max-turns`	限制最大轮次	`--max-turns 20`（防止无限循环）
`--resume`	恢复上次交互会话	`claude --resume`（接续之前中断的对话）

4. 工作流

4.1 新项目搭建

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

4.2 现有项目修改

需求状态	做法
无详细需求	先让 Claude Code 浏览代码 → 列出可改进点 + 方案 → 返回让用户决策
有详细需求	直接将需求传给 Claude Code 执行
已 `claude init` 的项目	禁止使用内置工具修改文件，所有变更必须通过 Claude Code

4.3 代码审查

审查类型

类型	命令模板	关注维度
单文件审查	`claude -p "审查 path/to/file.ts"`	逻辑正确性、命名规范、边界处理、错误处理
PR / 分支审查	`claude -p "审查当前分支相对于 main 的改动"`	整体一致性、测试覆盖、破坏性变更、向后兼容
安全审查	`claude -p "security-review"` 或 `/security-review`	OWASP Top 10、注入攻击、认证授权、敏感数据暴露
架构审查	`claude -p "审查项目架构，识别耦合点和改进机会"`	模块边界、依赖方向、抽象层次、循环依赖

审查输出规范

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

4.4 调试流程

标准流程

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

高效调试 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 多文件重构

标准流程

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

重构原则

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

跨模块并行重构示例

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

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 在执行中提出多个可选方案时，默认决策顺序：

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

7. 超时与进度策略

7.1 核心设定

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

7.2 进度汇报机制

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

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

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

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

7.3 任务时长参考

任务类型	预估时长	是否需要进度汇报
单文件修改（小改动）	< 2 分钟	不需要
中等重构（3–10 文件）	5–15 分钟	建议（每 10 分钟）
大型重构（10+ 文件）	15–60 分钟	必须（每 10 分钟）
新项目脚手架搭建	10–30 分钟	必须（每 10 分钟）
批量代码审查	按文件数量线性增长	批量任务建议汇报

8. 错误处理与 Fallback

8.1 分层策略

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

8.2 Fallback 规则

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

8.3 常见错误处理

错误现象	原因	处理方式
`claude: command not found`	CLI 未安装	`npm install -g @anthropic-ai/claude-code`
认证失败 / 401	Token 过期或未登录	执行 `claude login` 重新认证
项目未初始化	缺少 `CLAUDE.md`	进入项目目录执行 `claude init`
输出被截断	任务范围过大	缩小 prompt 范围或拆分为多次调用
API 限流 / 429	请求频率过高	降低 subagent 并行数，错开调用间隔

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`	非交互 `claude -p`
任务清晰度	模糊、需探索	明确、边界清晰
执行步骤	多步、需中途决策	单步或线性步骤
用户参与度	需要实时反馈和方向确认	可自主完成全程
上下文依赖	需多轮对话累积	一次性给足即可
涉及文件	多文件、跨模块	少量文件（1–5 个）
决策复杂度	有多个岔路口需用户拍板	执行路径唯一

选择原则：不确定时优先用 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 兼容性

注意事项	说明
Node.js 路径	确保 Node.js 在 `$env:PATH` 中，可在 PowerShell 中执行 `node --version` 验证
中文编码	`claude -p` 的 prompt 含中文时，确保文件以 UTF-8 编码保存；PowerShell 中执行 `[Console]::OutputEncoding = [Text.Encoding]::UTF8`
链式操作符	PowerShell 5.1 不支持 `&&` 和 `
here-string	多行 commit message 等场景使用 `@'...'@`（单引号、字面量），不要在 here-string 内使用 `$` 变量名
重定向	原生 exe 的 stderr 不要用 `2>&1` 重定向到 PowerShell 管道，会导致 NativeCommandError

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. 附录：完整速查表

命令速查

目的	命令
启动交互式会话	`claude`
单次代码修改	`claude -p "修改 src/foo.ts：将 X 改为 Y"`
代码审查	`claude -p "审查 src/bar.ts，关注安全性和性能"`
安全审查	`/security-review` 或 `claude -p "security-review"`
调试	`claude -p "debug: <问题描述 + 复现步骤 + 日志>"`
规划模式	`claude -p "plan: <需求>"` 或交互式下 `/plan`
新项目初始化	`claude init`（在项目目录下执行）
指定模型	`claude -p "..." --model haiku`
JSON 流式输出	`claude -p "..." --output-format stream-json`
分支/PR 审查	`claude -p "审查当前分支相对于 main 的所有改动"`

模式选择速查

任务特征	推荐模式
单文件、边界清晰	`claude -p`
多文件、跨模块、需探索	`claude`（交互式）
批量独立任务	Subagent 并行 `claude -p`
需确认方案再执行	`claude -p "plan: ..."`
Claude Code 不可用	内置工具（告知用户）

决策速查

场景	默认决策
功能选型（A vs B）	功能更全的方案
框架/库版本	最新稳定版 / LTS
超出本机性能	降级至轻量方案
不确定用哪种模式	先用 `claude -p`，不够再升级交互式
Subagent 数量	≤ CPU 核心数，建议 ≤ 4
任务超时	不设超时，每 10 分钟汇报进度

Claw Claude

Audits

Install

Claude Code — 调用指南

目录

1. 核心原则

2. 速查表

3. 调用方式

3.1 交互式 TUI

3.2 非交互单次

3.3 规划模式

3.4 其他常用参数

4. 工作流

4.1 新项目搭建

4.2 现有项目修改

4.3 代码审查

审查类型

审查输出规范

4.4 调试流程

标准流程

高效调试 Prompt 模板

调试原则

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. 附录：完整速查表

命令速查

模式选择速查

决策速查