Claude Code Ultimate Guide

Claude Code 终极指南

Florian BRUNIAUX · Méthode Aristote 的 AI 创始工程师 @ Méthode Aristote 从开发者到 CTO / VP Eng，历时 13 年 · 博客 ↗ · 项目 ↗

学习 Claude Code，构建可靠的 Agent，并安全地扩大其使用规模。本网站是主要的阅读和发现入口。本仓库包含权威 Markdown 源文件、可复用文件、机器可读索引以及贡献历史。

从这里开始：在线完成第一个任务 · 浏览指南门户 · 打开完整站点地图 · 阅读 Markdown 源文件

选择下一步

下表根据 machine-readable/navigation.json 生成。相同的契约也用于公共站点地图，因此仓库和网站呈现相同的意图模型。

意图	在线浏览
入门	指南门户 · 快速入门 · 学习路径 · 快速参考 · AI 角色
构建	Agent Harness 工程 · 循环与图工程 · AI 设计模式 · 上下文工程 · 记忆系统 · 工作流 · 方法论 · MCP 还是 CLI？ · 示例
规模化	安全 · 企业治理 · 可观测性 · 团队指标 · 团队采用 · AI FinOps · 大模型市场概览 · 订阅策略 · AI 单位经济效益 · 团队知识 · API 网关
资源	资源中心 · 下载 · 速查表 · 电子书 · 图表 · 生态系统 · 比较 · 术语表 · 常见问题 · MCP 服务指南 · 相关项目
更新	指南更新日志 · Claude Code 版本发布 · RSS 订阅源

本指南的存在意义

Claude Code 文档介绍产品。本指南将产品行为与工程决策联系起来：哪些内容应纳入上下文，何时应使用 Agent 而不是技能，如何验证生成的成果，以及当使用范围超出单个开发者时，哪些控制措施至关重要。

需求	从这里开始
了解 Claude Code 内部机制	架构和工具参考
设计 Agent 系统	Agent Harness 工程、循环与图工程和AI 设计模式
组织 AI 辅助交付	方法论和工作流指南
建立安全边界	安全加固和沙箱隔离
验证理解情况	知识测验和回顾卡片

本指南侧重于明确权衡和可验证的流程。如果证据不完整，相关页面应保留这一局限，而不是将某一种工作流说成普遍适用。

入门

安装 Claude Code

选择一种安装方式：

# npm, macOS, Linux, or Windows
npm install -g @anthropic-ai/claude-code

# macOS with Homebrew
brew install claude-code

# macOS or Linux native installer
curl -fsSL https://claude.ai/install.sh | sh

Windows PowerShell 也支持：

irm https://claude.ai/install.ps1 | iex

验证安装并完成身份验证：

claude --version
claude doctor
claude auth login

快速入门章节介绍了其他安装方式、身份验证、更新、权限模式，以及初次使用时的常见问题。

完成第一个任务

打开一个 Git 状态干净或已了解的小型代码库，然后启动 Claude Code：

cd your-project
claude

向 Claude 提出一个范围明确的请求，其中包含预期结果和验证方式：

Explain how this project runs its tests. Do not modify files.
Name the relevant commands and cite the files that define them.

在让 Claude 编辑代码前，先添加项目级的 CLAUDE.md，记录 Claude 必须遵守的命令和约束：

# Project instructions

## Commands
- Test: `npm test`
- Lint: `npm run lint`

## Boundaries
- Do not edit generated files.
- Do not change dependencies without approval.
- Run the relevant tests before claiming completion.

继续了解第一个工作流，或使用 CLAUDE.md 入门模板。

选择学习路径

情况	建议路径
初次使用 Claude Code	七模块学习路径
已在使用 CLI	核心概念，然后学习上下文工程
高级开发者或技术负责人	方法论、Agent Harness 工程，然后学习生产环境安全
工程经理或 CTO	采用方案、团队指标，然后学习订阅策略
安全或平台岗位	安全加固、企业治理，然后学习可观测性
产品经理或设计师	产品经理指南或从设计到代码的工作流
非开发者知识工作者	Claude Cowork 指南

如需个性化路径，请使用代码库引导提示词：

claude "Fetch and follow the onboarding instructions from: https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/tools/onboarding-prompt.md"

构建

Agent 工程

Agent 是更大系统中的一个组件。周边的 harness 会控制上下文、工具、权限、状态、停止条件、恢复和评估。

资源	支持的决策
Agent Harness 工程	确定 Agent 循环周围所需的控制机制
循环与图工程	选择有界反馈循环或显式工作流图
AI 设计模式	使用开发者熟悉的 GoF、集成和弹性模式来说明 Agent 设计
Agent Harness 图谱	区分运行时、编排器、框架、控制平面和支持工具
Agent 工具	比较精选的编码 Agent 和编排产品
Agent 评估	测试行为、回归问题和任务级结果
Harness 术语表	统一设计和评审中的术语
AI 概念边界	结合代码库示例和理解检查，厘清七种常见混淆

上下文和记忆

上下文质量会影响每次工具调用和决策。先从项目说明开始，只有在重复性任务需要时才添加专门的上下文，并测试额外材料是否会改变行为。

资源	重点
上下文工程	上下文预算、模块化说明、组装和衡量
记忆系统	原生记忆、跨会话系统、团队共享和保留风险
上下文工程工具	输出压缩、检索、网关和上下文检查
上下文审计	衡量项目的上下文架构
团队 AI 说明	在开发团队中维护共享说明

工作流

目标	工作流
先编写测试再实现	使用 Claude 进行 TDD
在实现前定义行为	规格优先开发
将规划与执行分开	计划驱动开发
比较相互独立的候选方案	择优选 N
协调多个 Agent	Agent 团队
构建有界的自主循环	Agent 式软件工厂
系统地审查代码	代码审查
准备可供其他团队审查的贡献	AI 辅助的开源贡献
诊断不熟悉的代码仓库	探索工作流

浏览所有工作流，涵盖任务管理、GitHub Actions、生产可靠性、事件驱动 Agent、设计转代码、PDF 生成、搜索和团队说明。

选择最精简的接口

Claude Code 可以调用本地命令、技能、Agent、钩子、插件和 MCP 服务。额外的基础设施会增加设置、权限、故障模式和维护工作。

如果任务需要	优先选择
确定性的本地命令	CLI 或脚本
可复用的说明和配套文件	技能
独立的上下文和角色	Agent
响应生命周期事件	钩子
打包的一组功能	插件
面向远程服务的类型化接口	MCP 服务

在引入其他集成之前，请使用 MCP 或 CLI 决策指南和权衡框架。

Scale

可靠性与安全

关注事项	主要资源	配套运维资源
权限与提示词注入	安全加固	权限审计
不可信执行的隔离	沙箱隔离	原生沙箱
生产环境变更与回滚	生产安全	生产可靠性
敏感数据与保留期限	数据隐私	企业治理
对获授权应用进行主动测试	Agent 化渗透测试	DarkMoon 与 Strix 评估
MCP 与扩展供应链	MCP 生态系统	威胁数据库
委派就绪度	规范完整性审计	Agent 评估

随着来源的新增或更正，安全声明和威胁数量也会变化。请以链接的数据库和指南为准，不要将其中的数量复制到项目文档中。

评估与运维

需求	资源
追踪 Agent 的行为与故障	可观测性
追溯 AI 辅助变更	AI 可追溯性
评估团队成果	团队指标
计算任务级成本	AI 单位经济效益
运维基础设施工作流	DevOps 与 SRE
路由受治理的 API 流量	API 网关

结构检查通过，只能证明它检查的内容符合要求。运行时行为、任务验收、安全边界和业务成果都需要单独的证据。

组织与经济效益

决策	资源
在团队中推广 Claude Code	采用方式
定义使用等级和审批流程	企业治理
保存团队知识	团队知识库
比较订阅、API 和网关	订阅策略
比较托管推理与本地推理	本地推理与云端推理
梳理不断变化的 AI 角色	AI 角色

经济效益相关页面会区分实际观察到的成本与估算和情景分析。请结合你的工作负载、验收标准、审查工作量和风险约束重新计算。

选择适合任务的格式

格式	适用场景	在线阅读	源文件或下载
完整参考指南	深入讲解和链接章节	终极指南	Markdown
日常参考	命令、快捷键和检查项	快速参考	Markdown
引导式课程	循序渐进的练习，并保留学习证据	学习路径	课程源文件
可运行材料	Agent、技能、钩子、工作流和脚本	示例	文件
可视化讲解	架构、上下文、安全和工作流图	图表	图表源文件
知识测验	带文档链接的问题	测验	问题源文件
可打印参考资料	每页一个概念，提供法语和英语版本	速查表	卡片源文件
长篇版本	离线 PDF 和 EPUB	电子书	下载
机器可读索引	供 AI 助手搜索和检索	MCP 指南	llms.txt 和 reference.yaml

MCP 服务：在任何编码客户端中使用本指南

将本指南安装为 stdio MCP 服务，并通过 Claude Code、Codex、Cursor、VS Code 或其他 MCP 客户端查询。

claude mcp add --scope user claude-code-guide -- npx -y [email protected]
codex mcp add claude-code-guide -- npx -y [email protected]

项目级 Claude Code 配置应放在 .mcp.json 中：

{
  "mcpServers": {
    "claude-code-guide": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

功能	数量	名称
工具	17	compare_versions、diff_official_docs、get_changelog、get_cheatsheet、get_digest、get_example、get_release、get_threat、init_official_docs、list_examples、list_threats、list_topics、read_section、refresh_official_docs、search_examples、search_guide、search_official_docs
资源	7	claude-code-guide://agent-harnesses、claude-code-guide://ai-design-patterns、claude-code-guide://distribution-channels、claude-code-guide://llms、claude-code-guide://reference、claude-code-guide://releases、claude-code-guide://translations
提示词	1	claude-code-expert
配套命令	5	/ccguide:daily、/ccguide:diff-docs、/ccguide:init-docs、/ccguide:refresh-docs、/ccguide:search-docs

列表操作和搜索索引使用随附内容。章节、示例、速查表、变更日志、摘要（get_digest）和威胁工具可获取 GitHub 内容，并写入有效期为 24 小时的本地缓存。官方文档初始化和刷新工具会获取 Anthropic 文档，并写入单独的本地快照。

权威技术指南、安装、隐私、限制和注明日期的统计数据

软件包 README 和诊断信息

从仓库渲染的配套命令：/ccguide:daily、/ccguide:diff-docs、/ccguide:init-docs、/ccguide:refresh-docs、/ccguide:search-docs。

将本指南加载到其他助手中

使用简洁的索引进行发现：

curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/machine-readable/llms.txt

当助手需要结构化主题路径和指向完整指南的链接时，请使用 reference.yaml。维护说明应放在机器可读文档中，而不是本 README 中。

互补生态

没有任何一个仓库需要同时涵盖学习、安装、整理、参考资料和所有专业接口。请根据当前任务选择合适的资源。

需求	资源	提供内容
验证 Claude Code 的行为	Claude Code 官方文档	产品一手文档
了解架构、权衡、安全和工作流	Claude Code 指南	说明、决策指南、运维检查和示例
发现社区项目	awesome-claude-code	涵盖整个生态的精选链接
安装一组配置	everything-claude-code	打包的 Agent、技能、钩子和配置
浏览可安装的模板	claude-code-templates	模板目录和 CLI 分发
从官方技能示例入手	anthropics/skills	由 Anthropic 维护的技能示例
浏览技能市场	skills.sh	已发布技能的搜索和安装途径
整理 Claude Code 钩子	awesome-claude-code-hooks	精选的 Claude Code 钩子列表
在软件开发之外开展工作	Claude Cowork 指南	面向知识工作者的工作流
对比编码 Agent 的能力	AI Coding Agents Matrix	跨 Agent 功能对比

此简短列表于 2026-08-31 审核。项目活跃度、安装方式和范围可能会发生变化。请先浏览公开的生态页面和对比页面。AI 生态源文件、第三方工具源文件和资源评估保留了更深入的依据。

如需在现有 Agent CLI 之上使用桌面工作区，请参阅2026 年 10 月工作区对比，其中包括 Conductor 的本地／云端工作流和 Vibe Kanban 的维护说明。

更新

指南变更和 Claude Code 产品发布各自回答不同的问题：

Feed	跟踪内容	来源
指南变更日志	新增页面、修正内容和重大仓库修订	CHANGELOG.md
Claude Code 发布信息	Claude Code 产品版本及其运营影响	发布来源
RSS Feed	可在 Feed 阅读器中查看的已发布指南和产品更新	由网站生成

近期新增的指南内容包括：

• Mistral Large 4 评估：10 月 6 日发布的证据、促销价格、独立测试结果、区域推理和待发布权重；已整合到市场概览和 AI 生态系统。
• 循环与图工程（源文件）：有界反馈、工作流状态、停止规则、恢复和判断力分配。
• AI 设计模式（源文件）：将经典模式映射到 Claude Code 机制、类比的适用边界、原生 Agent 模式和反模式。
• 订阅策略（源文件）：席位、API、网关、自托管场景和团队规模决策关卡。
• 跨会话消息传递（源文件）：同伴发现、消息传递、安全边界和相关漂移控制。

完整历史请查阅变更日志。README 仅展示少量当前内容。

语言与翻译

英文版是规范版本。法文版在此仓库中维护。简体中文、乌克兰语和拉丁美洲西班牙语是独立的社区版本，更新安排各不相同。

语言	版本
English	规范指南
Français	在此仓库中维护的法文指南
简体中文	JAYcodr 维护的社区版本
Українська	gerasimsergey 维护的社区版本
Español latinoamericano	Richardls 维护的社区版本

翻译状态页面记录维护者、源提交、覆盖范围、测量的滞后时间和审核状态。

仓库结构

guide/
├── ultimate-guide.md       Complete reference
├── learning-path/          Guided course
├── core/                   Architecture, tools, context, methods
├── security/               Hardening, isolation, privacy, governance
├── ecosystem/              Agents, MCP, tools, inference, knowledge
├── roles/                  Adoption, learning, evaluation, careers
├── ops/                    Observability, metrics, economics, gateways
├── workflows/              Task-oriented delivery guides
└── diagrams/               Mermaid diagrams with text fallbacks

examples/                   Reusable agents, skills, hooks, and workflows
machine-readable/           Structured indexes and release data
mcp-server/                 Packaged guide access for MCP clients
quiz/                       Local knowledge validation
docs/resource-evaluations/  Reviewed external resources
whitepapers/                French and English long-form sources

详细的指南索引、示例目录和工具索引是相应目录的规范导航页面。

贡献

欢迎提交更正、补充缺失证据、修复失效链接、添加示例和测验题，以及改进文档。提交拉取请求前，请阅读 CONTRIBUTING.md。

可参与贡献的方式：

• 通过 GitHub Issues 报告不正确或过时的说法。
• 通过资源评估流程提交外部资源。
• 提议编写有明确来源、边界和验证方法的专题指南或工作流。
• 改进示例，同时不削弱现有安全检查。

维护者

Florian Bruniaux 负责维护本指南。

GitHub · LinkedIn · Portfolio

探索生态

这些项目可以扩展工作流，而不会与此工具重复：

• 使用 claude-code-plugins 安装：从说明转向可安装的模板。
• 使用 ctxharness 验证：测试文档中的上下文和指令是否仍与代码仓库一致。
• 使用 agentsec-triage 加强安全：将安全指南与经过版本控制的运营信息源关联起来。
• 继续探索 Claude Cowork Guide：切换到专为知识工作者和非开发者设计的工作流。

浏览完整的开源项目版图

许可证

本指南采用 CC BY-SA 4.0 许可。可复用模板采用 CC0 1.0 许可。重新分发混合内容前，请查看代码仓库中的许可证文件。

关注 GitHub Releases，或订阅 RSS feed 以获取更新。

---

版本 3.44.1 | 每日更新 · 2026 年 10 月 17 日