Codecc.dev
返回博客列表
官方指南

Claude Code 最佳实践：来自 Anthropic 官方的 AI 编程指南

CodeCC Team
·
·
约 12 分钟阅读
#claude-code #最佳实践 #anthropic #AI编程 #codecc

原文来源: Claude Code: Best practices for agentic coding - Anthropic Engineering Blog

Claude Code 是一款命令行代理编程工具，作为 Anthropic 的研究项目开发，旨在为工程师和研究人员提供更原生的方式将 Claude 集成到编码工作流中。Claude Code 采用低层级、无强制约束的设计理念，提供接近原始模型的访问能力，而不强制特定的工作流程。这种设计哲学创造了一个灵活、可定制、可脚本化且安全的强大工具。

本文总结了在各种代码库、语言和环境中使用 Claude Code 的有效模式和技巧。

一、定制你的设置

1.1 CLAUDE.md 配置文件

CLAUDE.md 是一个特殊文件，Claude 在对话开始时会自动加载。这是记录项目信息的理想位置：

  • 常用 bash 命令（构建、测试、lint 等）
  • 代码风格指南和命名约定
  • 测试运行说明
  • 仓库特定信息或其他对 Claude 有用的上下文

推荐内容结构：

# Bash 命令
- npm run build: 构建项目
- npm run typecheck: 运行类型检查

# 代码风格
- 使用 ES modules (import/export) 语法，不使用 CommonJS
- 尽可能使用解构导入

# 工作流程
- 修改代码后运行类型检查
- 优先运行单个测试而非整个测试套件

文件放置位置：

位置说明
仓库根目录可提交到 git，团队共享
父级目录适用于 monorepo 项目
子目录按需加载特定模块信息
主目录 ~/.claude/CLAUDE.md适用于所有会话

优化建议：

将 CLAUDE.md 视为生产级提示词，持续测试其有效性。使用 # 键可以快速将指令自动整合到文件中。Anthropic 的工程师有时会通过提示词优化器处理这些文件，添加强调关键词以增强指令遵从度。

1.2 工具权限管理

使用 /permissions 命令或 --allowedTools 标志管理工具权限。这对于无人值守场景特别有用。

权限示例：

  • Edit - 文件编辑
  • Bash(git commit:*) - Git 提交操作
  • mcp__puppeteer__puppeteer_navigate - Puppeteer 导航

1.3 安装 GitHub CLI

强烈建议安装 GitHub CLI (gh) 并授权，Claude 可以用它来：

  • 创建和管理 Pull Request
  • 阅读和搜索 issue、PR 及其评论
  • 查找问题相关文件和操作

二、扩展 Claude 的工具能力

2.1 利用 Bash 环境

Claude 可以使用 bash 环境中的任何工具。确保为这些工具提供文档说明（放在 CLAUDE.md 中或使用 --help 提供），帮助 Claude 理解如何使用它们。

2.2 连接 MCP 服务器

Claude Code 既是 MCP 服务器也是 MCP 客户端，可以连接任意数量的 MCP 服务器以访问各种工具：

  • 图像处理：通过 Puppeteer 进行网页截图
  • 数据库查询：直接查询生产或本地数据库
  • 外部服务：Sentry、Datadog 等监控服务

2.3 自定义斜杠命令

在 .claude/commands/ 目录中创建 Markdown 文件，存储常用的提示词模板。支持 $ARGUMENTS 参数占位符。

示例 .claude/commands/fix-github-issue.md：

请分析并修复 GitHub issue: $ARGUMENTS

1. 使用 `gh issue view` 获取详情
2. 理解问题
3. 搜索代码库找到相关文件
4. 实现必要的修改
5. 编写并运行测试
6. 确保代码通过 lint 和类型检查
7. 创建描述性的提交信息
8. 推送并创建 PR

使用方式：/project:fix-github-issue 1234

三、核心工作流

3.1 探索-规划-编码-提交（推荐）

这个四步流程适用于复杂问题：

第一步：研究探索

让 Claude 阅读相关文件、图片或 URL，提供大致方向或具体文件名，但明确告诉它暂时不要写代码。对于复杂问题，强烈建议使用子代理来验证细节并保持上下文可用性。

第二步：制定计划

让 Claude 制定策略。使用触发词可以激活扩展思考：

触发词思考深度
think基础思考
think hard深入思考
think harder更深入思考
ultrathink最深度思考

将计划记录到 GitHub issue 或文件中，以便在实现偏离时可以回溯。

第三步：实现代码

让 Claude 构建解决方案，同时在整个过程中验证合理性。要求显式验证可以加强结果质量。

第四步：提交完成

让 Claude 提交更改并创建 Pull Request，根据需要更新文档。

关键洞察：步骤 1-2 至关重要——没有它们，Claude 往往会直接跳到编码环节。

3.2 测试驱动开发（TDD）

这是 Anthropic 推荐的方法，与代理系统配合效果极佳：

  1. 先写测试：让 Claude 根据预期的输入/输出编写测试。明确说明你在使用 TDD，这样 Claude 就不会为尚不存在的功能创建模拟实现。

  2. 验证失败：确认测试失败后再实现。明确要求在此阶段不要写任何实现代码。

  3. 提交测试：满意后保存测试文件。

  4. 实现功能：让 Claude 编写通过测试的代码，但不修改测试。多轮迭代是正常的。可选择让子代理验证解决方案没有过度拟合测试。

  5. 最终提交：保存完成的代码。

核心原则：当 Claude 有一个清晰的目标可以迭代时表现最佳——无论是视觉模型、测试用例还是其他输出。

3.3 可视化迭代

这种方法非常适合 UI 开发：

  1. 提供设计模型的截图或草图
  2. 让 Claude 实现设计
  3. 截取结果的截图给 Claude
  4. 迭代直到满意

Claude 的视觉能力使其成为缩小设计与实现差距的优秀工具。

3.4 安全 YOLO 模式

在容器化环境中，可以跳过权限确认实现完全自主工作：

  • 使用 Docker 或类似沙箱环境
  • 让 Claude 无中断地工作
  • 适合原型开发和实验

3.5 代码库问答

Claude Code 是了解新代码库的优秀工具：

  • 让 Claude 解释某个功能的工作原理
  • 询问相关文件在哪里
  • 了解架构决策的背景

3.6 Git 操作

许多 Anthropic 工程师使用 Claude 完成 90% 以上的 git 操作：

  • 编写提交信息（自动分析 diff）
  • 搜索历史记录
  • 处理复杂的变基和合并操作

3.7 GitHub 集成

配合 GitHub CLI，Claude 可以：

  • 创建和管理 Pull Request
  • 执行代码审查
  • 处理 issue 分类

四、工作流优化技巧

4.1 具体明确的指令

清晰的指令能显著提高首次尝试的成功率：

❌ 模糊：「添加测试」

✅ 具体：「为 src/utils/auth.ts 中的 validateToken 函数添加单元测试，覆盖有效 token、过期 token 和无效格式三种情况」

4.2 提供视觉反馈

  • 使用截图展示当前状态和期望结果
  • 提供设计稿或线框图
  • 让 Claude 对比视觉差异

4.3 及时纠正方向

  • 按 Escape 键中断当前操作
  • 双击 Escape 编辑历史提示
  • 在实现前要求修改计划

4.4 使用 /clear 重置上下文

在长时间会话中频繁使用 /clear 重置上下文窗口，保持专注。

4.5 使用检查清单

对于复杂的多步骤迁移，在 Markdown 文件中使用检查清单追踪进度。

五、Headless 模式

使用 -p 标志在非交互式环境中运行 Claude：

claude -p "<prompt>"

适用场景：

  • CI/CD 管道
  • pre-commit 钩子
  • GitHub Actions 自动化
  • 批量处理脚本

GitHub 自动化示例

  • Issue 分类：自动标记、分配和响应新 issue
  • 代码审查：自动审查 PR 并提供反馈
  • 依赖更新：自动创建升级 PR

六、多 Claude 实例协作

运行多个并行的 Claude 实例可以放大能力：

6.1 分离策略

  • 一个 Claude 写代码，另一个独立审查
  • 让独立的 Claude 实例验证实现是否符合测试
  • 在实例间使用 /clear 保持专注的上下文

6.2 Git Worktrees 方法

git worktree add ../project-feature-a feature-a
cd ../project-feature-a && claude

Worktrees 支持同时进行独立任务而不产生合并冲突。每个 worktree 可以有专用的终端标签和单独的 IDE 窗口。

6.3 扇出模式

处理大型迁移列表时，通过循环调用 Claude 处理特定任务：

for file in $(cat files-to-migrate.txt); do
  claude -p "将 $file 迁移到新的 API 格式"
done

6.4 管道模式

集成到数据处理管道中：

claude -p "分析这段代码..." --json | your_command

七、核心原则总结

  1. 具体性很重要：清晰的指令能显著提高首次尝试成功率

  2. 提供视觉反馈：使用截图、图片和设计稿进行 UI 工作

  3. 及早纠正方向：用 Escape 中断，调整提示词，在实现前修改计划

  4. 基于输出迭代：视觉对比和测试结果驱动改进

  5. 充分利用工具：MCP 服务器、bash 工具和 GitHub CLI 显著扩展能力

开始使用

想要体验 Claude Code 的强大能力？访问 CodeCC 获取官方直连服务，享受完整的 Claude Code 功能支持。

延伸阅读