Global InfinityAgent Intelligence
← Back to Agent Radar

智能体式编程工具

Claude Code

详细 Claude Code 指南，涵盖安装、提示词、CLAUDE.md、权限、Skills、子智能体、Hooks、MCP、并行工作、CI 和排错。

Claude Code 详细实战手册

简体中文版本。本手册根据 Anthropic 官方 Claude Code 文档及其关联学习页面重新编写，并按真实开发流程组织。内容不是网站逐页复制，而是包含可直接调整的命令、配置、提示词、工作流和排错示例。

Claude Code 任务流程：理解、规划、执行、验证
实用循环：收集背景、选择方案、执行工作，再验证结果。

1. Claude Code 是什么

Claude Code 是智能体式编程工具，可以理解代码仓库、编辑文件、运行命令并连接开发工具。应根据数据位置和任务需要选择界面。

界面适合工作起点
终端 CLI完整代码仓库工作、Shell 命令和自动化claude
VS Code / JetBrains选区、行内差异和方案审阅在项目中打开 Claude Code 面板
桌面应用并行会话、可视化差异、预览及集成工具为文件夹创建 Code 会话
网页 / 移动设备在已连接的 GitHub 仓库中运行云端任务claude.ai/code

2. 安装和首次启动

# macOS、Linux 或 WSL 原生安装
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew 稳定频道
brew install --cask claude-code

# Windows WinGet
winget install Anthropic.ClaudeCode
cd ~/projects/example-app
claude

# 检查安装和登录
claude doctor
claude auth status --text

应从真正需要处理的代码仓库或软件包目录启动。目录过高会引入噪声；目录过深则可能看不到项目级指引。

3. 编写能够完成的任务

清楚说明目标、相关背景、限制条件和完成证据。陌生或高风险工作应先探索和规划，再批准实施。

含糊要求

修复结账功能。

可执行提示词

目标：避免客户重试付款时产生重复订单。

背景：
- 结账处理：src/checkout/submit.ts
- 付款客户端：src/payments/client.ts
- 复现：两个相同 idempotency key 的请求创建两张订单

限制：
- 保持现有 API 响应
- 沿用现有事务辅助函数
- 不修改无关格式

完成标准：
- 增加并发重试回归测试
- 相关结账测试通过
- 说明根本原因和修改文件

只要求规划

探索登录和会话刷新流程，现在不要编辑文件。
列出请求路径、竞态条件和安全边界，再提出包含测试和回滚考虑的方案。
等我确认后再开始实施。

4. 有意识地使用智能体循环

  1. 收集背景：找到入口、测试、约定和未提交修改。
  2. 选择方案：模糊、架构性或高风险修改使用规划模式。
  3. 执行：保持修改范围小而完整。
  4. 验证：运行测试、查看真实输出并审阅差异。
为我建立这个代码仓库的导览图。指出运行入口、主要数据流、测试策略、
配置层，以及最值得先阅读的三个文件。引用路径，不要修改内容。
修复前先复现超时问题。跟踪一个失败请求，检查附近日志和测试，
区分已确认事实和假设。只有证据支持根本原因后才做最小修复。
先运行最小范围测试，通过后再运行完整测试。
界面修改要打开真实流程，检查页面、交互、响应式布局和控制台错误。
HTTP 200 不是视觉验证。

5. 管理上下文窗口

上下文窗口包含对话、工具结果、文件、指引、Skills 等信息。一个会话应集中处理一个完整目标；目标改变时开启新会话，内容过长则使用有明确重点的压缩。

/context
/compact 保留已批准方案、修改文件、失败测试和下一步。
/clear

使用 @path/to/file 或 IDE 选区提供高价值信息，避免在少数入口和测试已经足够时读取整个代码仓库。

6. 使用 CLAUDE.md 保存长期指引

CLAUDE.md 是团队编写的指引；自动记忆是 Claude 跨会话保存的学习。两者都能影响行为，但不是强制安全控制。

# 项目指引

## 命令
- 安装：npm ci
- 单元测试：npm test
- 端到端测试：npm run test:e2e
- 代码检查：npm run lint

## 架构
- HTTP 处理器位于 src/api/handlers/。
- 业务规则放在 src/domain/，不得导入界面模块。

## 交付规则
- 保留任务范围以外的用户修改。
- 每次错误修复都增加回归测试。
- 未收到明确要求时不得部署或推送。
- 交付时列出实际运行过的命令。
/init
/memory
/context

仅适用于指定路径的规则

---
paths:
  - "src/api/**/*.ts"
---

# API 规则
- 验证所有外部输入。
- 使用共享错误响应辅助函数。
- 为授权边界增加集成测试。

已有 AGENTS.md 的代码仓库，可以在 CLAUDE.md 中使用 @AGENTS.md 导入，再添加 Claude 专用指引。

7. 配置、权限和沙箱

Claude Code 会合并管理、用户、项目和本地配置。团队共享配置可以提交到版本控制；个人或机器专用信息应放在本地配置。权限规则可以允许、询问或拒绝工具及命令模式。

{
  "permissions": {
    "allow": ["Bash(npm test:*)", "Bash(npm run lint:*)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)"]
  },
  "sandbox": {"enabled": true}
}
模式用途注意
默认一般工作和审批提示仔细审阅陌生命令
规划只研究和设计编辑前先确认范围
接受编辑可信的文件修改流程命令仍可能需要批准
绕过权限仅用于另外隔离的环境不要在普通工作站随意使用

8. 使用 Skills 封装重复流程

.claude/skills/release-check/
└── SKILL.md

---
name: release-check
description: 部署前验证网站版本。
---

# 版本检查
1. 运行单元和集成测试。
2. 构建生产版本。
3. 使用浏览器检查主要流程。
4. 总结风险和阻塞项。
5. 未收到明确要求时不得部署。

多步骤工作流使用 Skill；长期项目事实使用 CLAUDE.md；必须机械执行的动作使用 Hook。

9. 使用子智能体分工

子智能体拥有独立上下文，也可以限制工具。适合独立研究、审查、测试或专业分析。每项工作应有清楚而有限的输出。

---
name: security-reviewer
description: 审查修改中可被利用的安全问题。
tools: Read, Grep, Glob, Bash
model: inherit
---

只审查已修改代码和可达数据流。
按严重程度列出文件、行号、利用场景、证据和最小修复。
不要编辑文件。
让 security-reviewer 子智能体审查当前差异；你同时运行相关测试。
报告前将审查发现与测试证据相互核对。

10. 使用 Hooks 自动执行规则

Hooks 可以在 Claude Code 事件前后执行格式化、阻止危险命令、验证文件、记录事件或发送完成通知。正式使用前要单独测试 Hook 命令。

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      }]
    }]
  }
}

11. MCP 和插件

MCP 连接外部工具和数据；插件把 Skills、子智能体、Hooks 和 MCP 配置组合成可安装的软件包。私有系统应使用已授权连接，并只授予需要的能力。

claude mcp add --transport http project-docs https://mcp.example.com
claude mcp list

# 会话内
/mcp
/plugin marketplace add example-org/claude-plugins
/plugin install code-review@example-marketplace

安装前检查插件来源、工具权限、Hook 命令和 MCP 目标地址。

12. 会话和并行工作

claude --continue
claude --resume
claude --resume auth-refactor

/rename auth-refactor
/branch try-streaming-approach

多项并行任务应命名会话。分支对话可以尝试另一种方案而不影响原对话；不要在两个终端中同时恢复同一会话。

claude --worktree dependency-upgrade

# 一个会话升级依赖，另一个审查界面修改；
# 最后在主目录整合并运行端到端测试。

13. 无界面运行和 CI

claude -p "审查当前差异的正确性和安全风险，不要编辑文件。"
claude -p --output-format json \
  "运行相关测试并返回简短失败摘要。" \
  > claude-result.json
git diff main --name-only | claude -p \
  "指出需要安全审查的修改文件并解释原因。"
# 在代码仓库会话内配置 GitHub Actions
/install-github-app

无人值守任务必须限制工具、成本或轮次、输出格式和失败行为；CI 不应获得超出任务需要的代码仓库或密钥权限。

14. 浏览器、桌面端、网页和远程

在 Chrome 中打开本地应用，复现结账失败，检查页面和控制台，
再在桌面和移动设备宽度验证修复。不要提交真实付款或修改生产数据。

本地会话可以访问本地文件和工具；云端任务使用隔离环境和已连接的代码仓库。选择界面前先确认数据位置和任务所需权限。

15. 排错清单

  1. 运行 claude doctor 检查安装和配置。
  2. 使用 claude auth status --text 区分登录和项目问题。
  3. 用 /context 确认 CLAUDE.md、规则和 Skills 已加载。
  4. 使用 /permissions、/hooks 或 /mcp 检查相应系统。
  5. 检查项目和本地配置是否存在无效 JSON 或冲突。
  6. 诊断启动问题时暂时禁用插件和 MCP。
  7. 上下文积累过多时使用新的聚焦会话。
  8. 修改全局配置前记录准确命令、错误、版本、操作系统和最小复现。
只进行诊断，不要修改文件或配置。复现问题、记录准确失败步骤，
检查生效配置和最近日志，并按证据排列可能原因。
清楚标记已确认事实和假设。

16. 官方资料来源

本手册逐页整理 Anthropic 官方的完整文档索引、快速开始、常用工作流、最佳实践、CLAUDE.md 和记忆、权限、沙箱、Skills、子智能体、Hooks、MCP、会话、Worktree、程序化使用、GitHub Actions和排错等页面。

编辑日期：2026 年 8 月 11 日。版本敏感的命令、方案可用性、模型行为或政策，使用前应再次核对官方页面。