Claw Claude

Claude Code — 调用指南 目录 核心原则 速查表 调用方式 3.1 交互式 TUI 3.2 非交互单次 3.3 规划模式 3.4 其他常用参数 工作流 4.1 新项目搭建 4.2 现有项目修改 4.3 代码审查 4.4 调试流程 4.5 多文件重构 Sub代理 并发模式 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 已知限制 附录：完整速查表

• 核心原则

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

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

• 速查表

场景 命令 / 方式 关键配置 交互式 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 "调试: <问题>" 详见 §4.4 批量并行 spawn sub代理 × N 详见 §5 已 init 项目 一律 claude / claude -p 禁止内置工具直接操作文件 Fallback 内置工具 仅当 Claude Code 报错时，且须告知用户

• 调用方式

3.1 交互式 TUI claude

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

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

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

3.2 非交互单次 claude -p "prompt"

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

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

3.3 规划模式 claude -p "plan: <需求描述>"

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

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

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

• 工作流

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）：必须修复才能合并 🟡 建议（警告）：推荐修复，不阻塞合并 🟢 可选（信息）：锦上添花的改进 每条问题附带：具体代码位置 + 问题描述 + 建议修复方案 结尾总结：总体评价 + 是否建议合并 + 重点风险提示 4.4 调试流程 标准流程 收集信息 — 整理问题描述、复现步骤、错误日志、相关文件路径。 提交调试 — claude -p "调试: <问题描述 + 复现步骤 + 错误日志>"，附带相关代码文件路径。 定位根因 — Claude Code 搜索关联代码、追踪调用链、分析数据流。 最小修复 — 提出最小化修复方案，不改动无关代码。 验证修复 — 运行相关测试或用例确认问题已解决，同时跑完整测试套件确保无回归。 高效调试 Prompt 模板 claude -p "调试: 用户登录后 令牌 未写入 cookie。

复现步骤：

• 访问 /记录in → 输入有效凭据
• 登录成功后跳转 /仪表盘
• 检查 cookie → 令牌 字段为空

相关文件：src/auth/记录in.ts, src/中间件/会话.ts 错误日志：[粘贴完整错误日志] 预期行为：登录成功后 设置-Cookie 应包含 httpOnly 令牌"

调试原则 优先排查最近改动的代码（git diff HEAD~1 辅助定位） 一次只修改一个变量/逻辑，验证通过后再继续 修复后跑完整测试套件，不只跑相关用例 对不确定的推断，先加日志验证假设，再改代码 4.5 多文件重构 标准流程 圈定范围 — 通过关键字搜索和依赖分析，列出所有涉及改动的文件清单。 Plan 先行 — claude -p "plan: 重构 <范围描述>"，生成重构方案并经用户确认。 分步执行 — 按依赖顺序逐步完成，每完成一步验证一次（测试 + 构建），确保每步可回滚。 最终验证 — 全量测试 + lint 检查 + 确认无行为变更。 重构原则 小步提交：每完成一个独立步骤（如"提取接口"→"迁移调用方"→"删除旧代码"）做一次提交。 行为不变：在不动外部行为的前提下调整内部结构。 先测试：如果目标代码缺少测试覆盖，先补齐测试，再重构。 并行处理：跨模块重构使用 sub代理 并行处理互不依赖的模块（见§5）。 跨模块并行重构示例 主会话 → claude -p "plan: 确定重构方案 + 模块边界划分" ├─ spawn sub代理 A → claude -p "重构 模块 A：<具体任务>" └─ spawn sub代理 B → claude -p "重构 模块 B：<具体任务>" 主会话 ← 汇总结果 → 集成测试验证 → 统一提交

• Sub代理 并发模式

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

5.1 适用场景 同时修改多个互不依赖的独立文件 批量代码审查（多文件各自独立审查） 前后端同时改动（各自独立上下文） 大型项目的分模块重构（每个模块独立处理） 5.2 调用模式 主会话 → spawn sub代理 A (claude -p "任务A") → spawn sub代理 B (claude -p "任务B") → spawn sub代理 C (claude -p "任务C") → 等待全部完成 → 汇总结果 → 集成验证

Sub代理 之间无通信，不共享文件写入锁。

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

• Prompt 编写最佳实践

6.1 推荐做法 描述目标，而非步骤："重构 User服务 使每个方法不超过 20 行" 优于 "拆分 User服务 的 记录in 方法" — Claude Code 比你更了解代码结构，让它自己找最优路径。 提供必要上下文：相关文件路径、已有架构决策、不可变更的约束条件。 指定输出格式：控制输出密度，如 "列出 5 个优化点，每个一行"、"生成 JSON 格式的结果"。 审查类任务指明维度：安全性、性能、可读性、架构一致性、测试覆盖率。 调试类任务提供三要素：问题描述 + 复现步骤 + 错误日志。 对于超过 3 个文件的任务，先 plan 再执行：claude -p "plan: ..." 生成方案确认后再行动。 6.2 避免的做法 ❌ 模糊指令："帮我看看代码"、"优化一下" — 没有范围，结果不可控。 ❌ 过度约束："只能用 X 库、Y 模式、Z 框架" — 除非是硬性约束，否则限制 Claude Code 的方案空间。 ❌ 一个 prompt 塞太多无关任务 — 拆分成独立调用，每个聚焦一个主题。 ❌ 空泛的上下文："这个项目很大" — 具体点出哪些文件/模块是关键的。 6.3 决策原则

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

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

• 超时与进度策略

7.1 核心设定 永不超时 — exec / sub代理 不设置 timeout 参数，运行TimeoutSeconds 设为 0 或完全省略。 Claude Code 运行至自然完成（任务结束）或报错退出，不因时长中断。 7.2 进度汇报机制

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

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

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

Cla