当 AI Agent 在生产环境中失败时，你很少能准确知道它是何时出错的。你看到的只是最终输出——一个幻觉答案、一个跳过的步骤，或者一个参数错误的工具调用——但实际的失败可能发生在三个步骤之前。这是软件工程尚未解决的核心调试问题：Agent 以一系列决策的形式执行，当你意识到出问题时，证据已经埋藏在交织的 LLM 调用、工具调用和状态变更的长轨迹中。
传统的调试假设确定性。你可以重现 bug，设置断点，检查状态。Agent 调试同时打破了这三个假设。相同的输入可以产生不同的执行路径。重现失败需要捕获发生那一刻的精确上下文、模型温度和外部状态。而且在实时推理循环中“设置断点”甚至不是大多数 Agent 框架所支持的功能。
人工智能编程助手已经从简单的代码补全工具进化为成熟的开发伙伴。Claude Code 代表了这一演进的下一个阶段，它提供了一个可被称为**“自主编程”**的框架。这款工具旨在深度集成到你的工作流中，做很多之前 AI coding 做不到的事情：
接下来，让我们深入探索这些能助你驾驭其强大功能的技巧。
坚实的配置是高效工作流的基石。在这一步投入的时间，将在后续的每一次交互中为你带来丰厚的回报。
CLAUDE.md 作为项目记忆：在任何项目的根目录下，都应该有一个简洁的 CLAUDE.md 文件。该文件充当项目的“短期记忆”，包含了关键的架构原则、编码规范和测试流程。为了保持文件简洁、重点突出，可以使用 imports 语法（如 @docs/testing.md）来引用更详细的文档。你可以通过以 # 开头的消息快速添加新规则，或使用 /memory 命令直接编辑这份记忆。--add-dir 标志，或在你的 .claude/settings.json 文件中定义 additionalDirectories。这对于跨越代码库多个部分的任务至关重要。Esc Esc 快速编辑上一条消息。运行一次 /terminal-setup 命令，即可启用 Shift+Enter 来输入换行符。对于 Vim 爱好者，/vim 命令可以让你在熟悉的 Vim 模式下进行编辑。有了坚实的基础，你就可以引入一些实践来减少阻力，提升日常工作效率。
CLI 提供了几种权限模式，以适应不同的任务和风险偏好：
default：最安全的新手起点。在执行有潜在风险的操作前，它会提示你进行确认，在安全和速度之间取得了良好平衡。acceptEdits：一种“实时编码”模式，它会自动接受文件编辑而无需提示。非常适合快速迭代以及在你密切监督流程的场景。plan：一种为代码审查等任务设计的“安全”模式。在此模式下，Claude 可以分析和讨论代码，但不能修改任何文件。bypassPermissions：完全跳过所有权限提示。请极其谨慎地使用此模式，并且只在意外更改不会造成任何后果的沙盒环境中使用。你可以在 .claude/settings.json 中设置默认模式，或使用 --permission-mode 标志为单次会话指定模式。
重复性任务是自动化的绝佳候选。通过创建自定义斜杠命令，将你最常用的提示词转化为可复用的工具。只需将它们作为带有 YAML frontmatter 的 Markdown 文件存储在 .claude/commands/ 目录中即可。
allowed-tools 来限制命令可以执行的操作，增加一层安全性。! 前缀可以运行 shell 命令（例如 !git status -sb） ，并将其输出直接注入到你的提示词上下文中。$ARGUMENTS 向你的命令传递参数，使其更加灵活和强大。claude --continue：立即跳回到你最近一次的会话中。claude --resume：列出过去的所有会话，让你能精确地从上次中断的地方继续。git worktree 创建隔离的分支。这允许你并行运行多个独立的 Claude 会话，每个会话都有自己的上下文，从而避免混淆和冲突。/output-style explanatory：在响应中增加一个“洞察 (Insights)”部分，非常适合用于指导初级开发者或在 Pull Request 中解释复杂的变更。/output-style learning：在响应中添加 TODO(human) 占位符，主动邀请你参与协作，填补空白。真正的自主需要有护栏。将质量检查和安全网直接集成到你的工作流中，让你能充满信心地进行开发。
钩子是在特定生命周期事件中自动运行的 shell 命令，提供了一种确定性的方式来强制执行规则。你可以在 .claude/settings.json 中配置它们。
PreToolUse：在工具使用前运行检查。例如，你可以阻止对敏感文件的编辑，或要求必须存在相应的测试文件才允许写入操作。PostToolUse：在工具使用后自动执行清理任务。这非常适合在每次编辑后运行 prettier 或 gofmt 等格式化工具，以及代码检查器和快速测试。Notification：当 Claude 需要你输入时发送桌面提醒，这样你就可以在切换任务的同时不会忘记这边的进度。例如，让 Mac 在任务完成后通知你 - code ~/.claude/settings.json
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "say \"job's done!\""
}
]
}
]
}
}
在你的设置中定义明确的 allow（允许）、ask（询问）和 deny（拒绝）规则，以便在无需频繁提示的情况下管理工具的访问权限。
Bash(npm run test:*)。Bash(git push:*)。Read(./.env) 或 Read(./secrets/**)。对于复杂的项目，你可以定义具有特定角色的项目级代理，例如 code-reviewer（代码审查员）、test-runner（测试运行器）或 debugger（调试器）。每个代理都配置了有限的工具集，以防止其越权操作。Claude 可以自动将任务委派给合适的代理，你也可以明确地调用某个代理。可以参考这个仓库获取示例。
通过集成视觉上下文和外部服务，超越基本的文件访问，提升你的工作流。
一图胜千言，尤其是在调试 UI 问题时。有三种可靠的方法可以向 Claude Code 提供图片：
Ctrl+V 粘贴到终端中（注意：在 macOS 上也是 Ctrl+V，而不是 Cmd+V）。分析这张截图：/path/to/screenshot.png。MCP 使 Claude 能够连接到 Jira、GitHub、Notion 或 Sentry 等外部服务。在添加并认证一个 MCP 服务器后，你就可以在提示词中直接引用外部资源，例如 实现 JIRA-ENG-4521 中描述的功能。
对于自动化和脚本编写，可以使用带 -p 标志的打印模式。
--output-format json 或 --output-format stream-json 结合使用，可以生成机器可读的输出，然后通过管道传递给 jq 等其他工具进行进一步处理。--max-turns 为交互次数设置硬性上限，防止自动化脚本中出现失控循环。强大的模型需要明智地使用。养成这些习惯，以管理你的开销并优化性能。
/cost 命令，获取当前会话成本的实时摘要。ccusage 工具是实现此功能的常用选择。这里提供了一些可直接复制粘贴的配置文件，助你快速上手。
此文件用于建立项目范围的权限、钩子和 monorepo 设置。
{
"defaultMode": "acceptEdits",
"permissions": {
"allow": [
"Read(**/*)",
"Edit(src/**)",
"Bash(npm run test:*)",
"Bash(npm run lint:*)",
"Bash(go test:*)",
"Bash(git status:*)",
"Bash(git diff:*)"
],
"ask": [
"Bash(git push:*)",
"Bash(pnpm publish:*)",
"Bash(npm publish:*)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
],
"additionalDirectories": ["../apps", "../packages", "../services"]
},
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|MultiEdit|Write",
"hooks": [
{
"type": "command",
"command": "python3 - <<'PY'\nimport json,sys\np=json.load(sys.stdin).get('tool_input',{}).get('file_path','')\nblock=['.env','/secrets/','.git/']\nsys.exit(2 if any(b in p for b in block) else 0)\nPY"
}
]
}
],
"PostToolUse": [
{
"matcher": "Edit|MultiEdit|Write",
"hooks": [
{ "type": "command", "command": "npx prettier --write . --loglevel silent || true" },
{ "type": "command", "command": "npm run -s lint || true" },
{ "type": "command", "command": "npm run -s test || true" }
]
}
],
"Notification": [
{ "matcher": "", "hooks": [ { "type": "command", "command": "command -v terminal-notifier >/dev/null && terminal-notifier -message 'Claude needs input' -title 'Claude Code' || true" } ] }
]
},
"statusLine": { "type": "command", "command": "~/.claude/statusline.sh" }
}
这个自定义命令利用 shell 输出起草一条符合 Conventional Commit 规范的消息。
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
description: Create a conventional commit from current changes
## Context
- Status: !`git status -sb`
- Diff: !`git diff --staged; git diff`
## Task
Write a Conventional Commit subject (<= 72 chars) and a concise body.
Call out BREAKING CHANGE if needed. Stage relevant files and commit.
一个专门负责代码审查的代理定义。
name: code-reviewer
description: Senior review with focus on correctness, security, tests, readability, performance.
tools: Read, Grep, Glob, Bash
Return a checklist grouped by **Critical**, **Warnings**, and **Suggestions**.
Propose minimal patches where possible. Include test guidance for each critical item.
一个定义了工作风格、质量标准和关键项目文档的示例记忆文件。
# Working style
- Start in **Plan mode**; outline approach, tests, and risks. Wait for approval.
- Execute in **small, reversible steps**; propose staged commits with diffs.
- Place generated docs in `docs/ai/`. Avoid ad-hoc files elsewhere.
# Code quality
- Prefer pure functions and dependency injection.
- JS/TS: strict TS, eslint + prettier; tests via vitest/jest.
- Go: table-driven tests; `gofmt`/`golangci-lint`.
- Security: never read `.env*` or `./secrets/**`; do not write tokens to disk.
# Project map
@README.md
@docs/architecture.md
@docs/testing.md
bypassPermissions 模式（通过 claude --dangerously-skip-permissions 启动）。更好的方法是使用 acceptEdits 模式，并结合明确定义的 allow/ask/deny 规则。在合并前，务必审查所有差异。CLAUDE.md 文件变得太大了。可以通过将细节移至导入的文档文件中来缩短它。你也可以在会话期间重申关键规则以重新聚焦，或使用 /compact 命令清理会话历史。Claude Code 不仅仅是一个代码生成器，它是一个用于构建高效的、AI 增强开发流程的平台。通过超越基础的提示词并采纳这些中高级技巧，你可以建立一个更快、更安全、更具协作性的工作流。大胆尝试这些功能，根据你的项目进行调整，并探索软件开发的新范式吧。
我是 Tian Pan，一名工程师型创始人，专注于智能体工程——构建自主 AI 系统并扩展工程团队。我撰写关于系统设计、技术领导力和 AI 智能体实战的实用指南。曾在 Uber、Brex 和 IoTeX 担任早期工程师。
