Claude Code Agent 编程最佳实践官方指南

Claude Code Agent 编程最佳实践官方指南 | 前端进阶之旅

Full translation

完整中文译文

给 Claude 一种验证工作的方式

在一个提示中：让 Claude 在同一条消息中运行检查并迭代，如上表所示。

跨会话：将检查设置为 /goal 条件。一个单独的评估器在每一轮之后重新检查，Claude 继续工作直到满足条件。

作为确定性的门：一个 Stop 钩子运行你的检查作为脚本，并阻止转轮结束直到通过。Claude Code 覆盖钩子并在 8 次连续块之后结束转轮。

通过第二意见：一个验证 subagent 或动态工作流检查自己的发现，一个新鲜的模型尝试反驳结果，所以做工作的代理不是给它评分的。

先探索，再计划，再编码

read /src/auth and understand how we handle sessions and login.
also look at how we manage environment variables for secrets.

I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.

implement the OAuth flow from your plan. write tests for the
callback handler, run the test suite and fix any failures.

commit with a descriptive message and open a PR

在提示中提供具体上下文

提供丰富的内容

使用 @ 而不是描述代码的位置来引用文件。Claude 在响应之前读取文件。

直接粘贴图像。将图像复制/粘贴或拖放到提示中。

为文档和 API 参考提供 URL。使用 /permissions 来许可经常使用的域。

通过运行 cat error.log | claude 来管道数据以直接发送文件内容。

让 Claude 获取它需要的内容。告诉 Claude 使用 Bash 命令、MCP 工具或通过读取文件来自己拉取上下文。

配置你的环境

编写有效的 CLAUDE.md

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

See @README.md for project overview and @package.json for available npm commands.

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

主文件夹（~/.claude/CLAUDE.md）：应用于所有 Claude 会话

项目根目录（./CLAUDE.md）：检入 git 与你的团队共享

项目根目录（./CLAUDE.local.md）：个人项目特定的笔记；将此文件添加到你的 .gitignore 以便不与团队共享

父目录：对于单体仓库有用，其中 root/CLAUDE.md 和 root/foo/CLAUDE.md 都会自动拉入

子目录：当 Claude 读取这些目录中的文件时，会按需拉入子 CLAUDE.md 文件

配置权限

自动模式：一个单独的分类器模型审查命令并仅阻止看起来危险的内容：权限提升、未知基础设施或恶意内容驱动的操作。当你信任任务的总体方向但不想逐步点击时最佳

权限许可列表：允许你知道安全的特定工具，如 npm run lint 或 git commit

沙箱化：启用操作系统级隔离，限制文件系统和网络访问，允许 Claude 在定义的边界内更自由地工作

---
name: api-conventions
description: REST API design conventions for our services
---
# API Conventions
- Use kebab-case for URL paths
- Use camelCase for JSON properties
- Always include pagination for list endpoints
- Version APIs in the URL path (/v1/, /v2/)

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Analyze and fix the GitHub issue: $ARGUMENTS.

1. Use `gh issue view` to get the issue details
2. Understand the problem described in the issue
3. Search the codebase for relevant files
4. Implement the necessary changes to fix the issue
5. Write and run tests to verify the fix
6. Ensure code passes linting and type checking
7. Create a descriptive commit message
8. Push and create a PR

创建自定义 subagent

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling

Provide specific line references and suggested fixes.

有效地沟通

询问代码库问题

记录是如何工作的？

我如何制作一个新的 API 端点？

foo.rs 第 134 行的 async move { ... } 做什么？

CustomerOnboardingFlowImpl 处理哪些边界情况？

为什么这段代码在第 333 行调用 foo() 而不是 bar()？

让 Claude 采访你

I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.

Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

尽早且经常进行路线纠正

Esc：使用 Esc 键在中途停止 Claude。上下文被保留，所以你可以重定向。

Esc + Esc 或 /rewind：按 Esc 两次或运行 /rewind 以打开倒回菜单并恢复之前的对话和代码状态，或从选定的消息总结。

"撤销那个"：让 Claude 恢复其更改。

/clear：在不相关的任务之间重置上下文。长会话与无关的上下文可能会降低性能。

积极管理上下文

在任务之间频繁使用 /clear 以完全重置上下文窗口

当自动压缩触发时，Claude 总结最重要的内容，包括代码模式、文件状态和关键决策

为了获得更多控制，运行 /compact <instructions>，如 /compact Focus on the API changes

要压缩对话的一部分，使用 Esc + Esc 或 /rewind，选择消息检查点，并选择从这里总结或总结到这里。第一个从该点前进压缩消息，同时保持早期上下文完整；第二个压缩早期消息，同时保持最近的消息完整。参见倒回菜单的总结选项。

在 CLAUDE.md 中自定义压缩行为，带有诸如"压缩时，始终保留已修改文件的完整列表和任何测试命令"之类的指示，以确保关键上下文在总结中存活

对于不需要保留在上下文中的快速问题，使用 /btw。答案出现在可关闭的覆盖层中，从不进入对话历史，所以你可以检查细节而无需扩大上下文。

使用 subagent 进行调查

Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.

use a subagent to review this code for edge cases

使用检查点倒回

恢复对话

运行非交互式模式

# One-off queries
claude -p "Explain what this project does"

# Structured output for scripts
claude -p "List all API endpoints" --output-format json

# Streaming for real-time processing
claude -p "Analyze this log file" --output-format stream-json --verbose

运行多个 Claude 会话

工作树：在隔离的 git 检出中运行单独的 CLI 会话，以便编辑不会碰撞

桌面应用：在视觉上管理多个本地会话，每个都在自己的工作树中

网络上的 Claude Code：在隔离虚拟机中的 Anthropic 管理的云基础设施上运行会话

Agent 团队：多个会话的自动协调，具有共享任务、消息和团队领导

跨文件扇出

编写脚本以循环遍历列表

for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

在几个文件上进行测试，然后大规模运行

claude -p "<your prompt>" --output-format json | your_command

使用自动模式自主运行

claude --permission-mode auto -p "fix all lint errors"

添加对抗性审查步骤

Use a subagent to review the rate limiter diff against PLAN.md. Check that
every requirement is implemented, the listed edge cases have tests, and
nothing outside the task's scope changed. Report gaps, not style preferences.

避免常见的失败模式

厨房水槽会话。你从一个任务开始，然后问 Claude 一些不相关的问题，然后回到第一个任务。上下文充满了无关的信息。修复：在不相关的任务之间使用 /clear。

一遍又一遍地纠正。Claude 做错了什么，你纠正它，它仍然是错的，你再次纠正。上下文被失败的方法污染了。修复：在两次失败的纠正后，/clear 并写一个更好的初始提示，结合你学到的内容。

过度指定的 CLAUDE.md。如果你的 CLAUDE.md 太长，Claude 会忽视一半内容，因为重要规则在噪音中丢失。修复：无情地修剪。如果 Claude 已经在没有指示的情况下正确地做了某事，删除它或将其转换为钩子。

信任然后验证的间隙。Claude 产生看起来合理的实现，但不处理边界情况。修复：始终提供验证（测试、脚本、截图）。如果你无法验证它，不要部署它。

无限探索。你要求 Claude"调查"某些东西而不限定范围。Claude 读取数百个文件，填充上下文。修复：缩小调查范围或使用 subagent，以便探索不会消耗你的主上下文。

培养你的直觉

Claude Code 如何工作：agent 循环、工具和上下文管理

扩展 Claude Code：skills、钩子、MCP、subagent 和插件

常见工作流：调试、测试、PR 等的分步食谱

CLAUDE.md：存储项目约定和持久上下文

这个页面有帮助吗？