Claude Code 通识 - claude_0x01

用户223586218202026-04-19 9:51

目录概要

  1. 为什么想写这篇文章
  2. AI 编程助手的发展背景
  3. Claude Code 是什么
  4. 6 个核心概念全览
  5. .claude/ 目录结构解剖
  6. 三层编排架构
  7. 这套生态究竟解决了什么问题

1. 为什么想写这篇文章

最近开始用 Claude Code 做工程开发，从一开始的"AI 聊天工具"心态，到后来发现这玩意儿能读写文件、跑命令、管 git、调用外部 API，完全是另一个物种，遇到了一些奇奇怪怪的问题------

"为什么我写的 CLAUDE.md 它有时候听有时候不听？" "command 和 skill 看起来都是一段提示词，到底有什么区别？" "subagent 又是什么？跟 skill 又有什么不一样？" "为什么我的 hook 没生效？"

为了搞清楚这些问题的产生原因，以及这套生态各个概念背后的设计思想，把一些问题和了解之后的原理记录下来，特此总结一篇文章，尝试系统地串联起 Claude Code 的整个工作模型。

这篇文章是整个系列的第一篇，主要做整体认知的建立，不深入任何一个细节，目的是让你看完之后，脑子里有一张完整的"地图"。后续文章会逐个展开。

如果说理解技术问题要"知其然并知其所以然"，那这篇就是知其然------先告诉你这个生态长什么样、有什么、放在哪。所以然要等到后续每个细节展开的时候。

2. AI 编程助手的发展背景

这段没什么干货，可以跳过。但是历史挺有意思------AI 编程助手为什么演化到今天这个形态，理解这个有助于理解为什么 Claude Code 是这样设计的。

AI 写代码这件事，最早可以追溯到 2021 年 GitHub Copilot 公测。那时候 Copilot 的形态非常简单------就是一个自动补全器，根据你正在写的代码，预测下一行该写什么。

graph LR A[你在 IDE 里打字] --> B[Copilot 看到上下文] B --> C[预测下几行代码] C --> D[Tab 接受 / Esc 拒绝]

这个模式持续了大概两年，所有的 AI 编程助手都是"自动补全 + 聊天框"的形态------Cursor、Copilot Chat、Tabnine 都是。

2.1 Chat 形态的局限

Chat 形态的问题很快暴露：

  • 没有持久化上下文：每次新对话都要重新解释项目背景
  • 不能执行：AI 给你代码，你自己复制粘贴运行
  • 不能反馈：跑出错了，你又要把错误粘回去
  • 单次交互：复杂任务被切成一次一次的对话，AI 看不到全貌

那时候大家做的就是 vibe coding------靠感觉、靠对话、靠人肉串联各个步骤。

2.2 Agentic 转向

2024 年下半年开始，所有人都意识到一件事：AI 不应该只是建议者，应该是执行者。

Cursor Composer、Devin、SWE-Agent 一窝蜂地涌出来，核心思路就一个------让 AI 自己跑 agentic loop：

graph TD A[用户描述任务] --> B[AI 思考] B --> C[AI 选择工具] C --> D[AI 执行工具] D --> E{结果满足?} E -->|否| B E -->|是| F[返回结果给用户]

这就是所谓的"agentic engineering"------从 vibe coding 到 agentic engineering，本质上就是从"聊天"变成"驱动一个能自己干活的 agent"。

2.3 Claude Code 的定位

Anthropic 在 2024 年底发布的 Claude Code，跟其他工具的区别是：

它不是一个 IDE 插件，是一个终端工具。

这个选择很有意思。当时所有竞品都在卷 IDE 集成，Anthropic 反其道而行之------做 CLI。Boris Cherny（Claude Code 的创始人）后来在播客里说，做 CLI 是因为 CLI 是工程师真正的"主场"------git、npm、docker 都在终端里，把 AI 放进终端意味着 AI 可以无缝接入所有现有的工作流。

脑洞大一点，可以说：如果 Anthropic 当时做的是 IDE 插件，今天的 Claude Code 生态可能完全是另一个局面------不会有 hooks、不会有 MCP、不会有 subagents 这些"工程化"的东西。

3. Claude Code 是什么

简单一句话：

Claude Code 是一个跑在终端里的 agentic 编程助手。

但这句话是废话，重点在它能做什么：

能力 说明
读写文件 直接操作你的工作目录
执行 shell 命令 npm/git/docker 任意
调用外部 API 通过内置 WebFetch 工具
管理 git commit、push、PR
编排 subagent 在隔离上下文里执行子任务
通过 MCP 连接外部工具 浏览器、数据库、Slack 等
在事件点触发 hooks 工具调用前后、会话开始结束
持久化记忆 跨会话记住项目上下文

它不是普通的 chatbot，是一个有手有脚、有记忆、可编排的 AI 工作系统。

3.1 这个仓库 vs 应用代码库

这里要澄清一个容易混淆的事情：

claude-code-best-practice 这个仓库本身不是一个"应用程序" ，它是一个 Claude Code 配置模式的参考实现。它的目的是告诉你：

如何把 Claude Code 调教成一个真正高效的工程伙伴。

类比的话，它有点像 dotfiles 仓库------不是软件本身，是软件的配置最佳实践。

4. 6 个核心概念全览

Claude Code 的扩展能力，归根结底是 6 个概念。下面这张表先有个印象，每个概念后续文章会详细展开。

mindmap root((Claude Code)) Commands 用户主动触发 工作流模板 .claude/commands/ Skills Claude 自动匹配 可复用知识单元 .claude/skills/ Subagents 自主 AI actor 独立上下文 .claude/agents/ Hooks 事件驱动 工具前后/会话前后 .claude/hooks/ MCP Servers 连接外部世界 浏览器/DB/API .mcp.json Memory 持久化上下文 跨会话记忆 CLAUDE.md

4.1 Commands（命令）

一句话：把你常用的工作流封装成 /slash-command。

  • 位置 ：.claude/commands/<name>.md
  • 触发 ：用户主动输入 /command-name
  • 类比：像键盘宏，把多步操作压缩成一个动作
  • 典型场景 ：/commit-push-pr 一键提交、推送、开 PR

4.2 Skills（技能）

一句话：注入到上下文的"专业技能手册"，Claude 看到相关任务自动翻出来用。

  • 位置 ：.claude/skills/<name>/SKILL.md
  • 触发 ：Claude 根据 description 自动匹配，也可以手动 /skill-name
  • 类比：像专科医生的诊疗手册，遇到对症的问题就翻开
  • 典型场景 ：weather-svg-creator skill，用户说"给我天气卡片"就自动触发

4.3 Subagents（子代理）

一句话：在独立上下文中自主运行的 AI actor，有自己的工具权限、模型、记忆。

  • 位置 ：.claude/agents/<name>.md
  • 触发 ：通过 Agent 工具调用，或 Claude 根据 description 自动派遣
  • 类比：像一个专职员工，你交给他一个任务，他自己搞定，不占用你的主上下文
  • 典型场景 ：weather-agent 自主调用 API 获取天气数据

4.4 Hooks（钩子）

一句话：在特定事件（工具调用前/后、会话开始/结束等）触发的自定义处理器。

  • 位置 ：.claude/hooks/ + .claude/settings.json
  • 触发：事件发生时自动触发
  • 类比：像 git hooks，但更强大------可以是 shell 脚本、HTTP 请求、AI 提示词、subagent
  • 典型场景 ：每次 Write 文件后自动跑 npm run format

4.5 MCP Servers（模型上下文协议服务器）

一句话：标准化协议，让 Claude 连接外部工具、数据库、API。

  • 位置 ：.mcp.json
  • 触发 ：Claude 调用 mcp__<server>__<tool> 工具时
  • 类比：像 VSCode 的扩展市场，每个 MCP server 给 Claude 增加一类新能力
  • 典型场景：Playwright MCP 让 Claude 控制浏览器

4.6 Memory（记忆）

一句话：跨会话持久化的项目上下文，Claude 启动时自动加载。

  • 位置 ：CLAUDE.md、.claude/rules/、~/.claude/CLAUDE.md
  • 触发：会话启动时自动加载
  • 类比：像新员工的入职文档，每次启动都要读一遍
  • 典型场景 ：在 CLAUDE.md 里写"提交时每个文件单独 commit"，Claude 永远不会忘

5. .claude/ 目录结构解剖

把上面 6 个概念落到目录上，长这样：

graph TD Root[项目根目录] --> CLAUDE_MD[CLAUDE.md<br/>项目记忆] Root --> MCP_JSON[.mcp.json<br/>MCP 配置] Root --> CLAUDE_DIR[.claude/] CLAUDE_DIR --> CMDS[commands/<br/>用户触发的工作流] CLAUDE_DIR --> AGENTS[agents/<br/>自主 AI actors] CLAUDE_DIR --> SKILLS[skills/<br/>可复用知识单元] CLAUDE_DIR --> HOOKS[hooks/<br/>事件处理器] CLAUDE_DIR --> RULES[rules/<br/>拆分的规则文件] CLAUDE_DIR --> SETTINGS[settings.json<br/>权限/hooks/MCP] CLAUDE_DIR --> SETTINGS_LOCAL[settings.local.json<br/>个人配置 git 忽略] CMDS --> CMD1[weather-orchestrator.md] AGENTS --> AGT1[weather-agent.md] SKILLS --> SK1[weather-fetcher/SKILL.md] SKILLS --> SK2[weather-svg-creator/SKILL.md] HOOKS --> HK1[scripts/hooks.py]

5.1 几个值得注意的细节

1. CLAUDE.md 在根目录，不在 .claude/ 里

这个设计是有意为之的------CLAUDE.md 是给所有人（人类和 AI）看的"项目说明"，应该和 README.md 一样在显眼的位置。

2. .mcp.json 也在根目录

跟 CLAUDE.md 同理------MCP 配置是项目级的"基础设施声明"，应该在根目录。

3. Skills 是"文件夹"，不是"文件"

注意 skills/ 下面每个 skill 是一个目录，里面有 SKILL.md 主文件，可能还有 references/、scripts/、examples/ 子目录------这是 skill 设计的核心思想之一，叫"渐进式揭露"，后面的文章会详细讲。

4. settings.local.json 是个人配置

带 .local 的文件都是 git 忽略的，用来放每个开发者自己的偏好，不污染团队共享的配置。

6. 三层编排架构

把 6 个概念串起来用，最经典的模式叫 Command → Agent → Skill 三层编排。这套架构是这个仓库一直在强调的。

sequenceDiagram actor User as 用户 participant Cmd as Command<br/>(入口层) participant Agent as Subagent<br/>(执行层) participant Skill1 as Agent Skill<br/>(预加载知识) participant API as 外部 API participant Skill2 as Skill<br/>(输出层) User->>Cmd: /weather-orchestrator Cmd->>User: 摄氏 or 华氏？ User->>Cmd: 摄氏 Cmd->>Agent: 用 Agent 工具调用 Note over Agent: 启动时已注入<br/>weather-fetcher Agent->>Skill1: 读取预加载的指令 Skill1-->>Agent: API 调用方式 Agent->>API: GET temperature API-->>Agent: 26°C Agent-->>Cmd: temperature=26, unit=C Cmd->>Skill2: 用 Skill 工具调用 Skill2->>Skill2: 生成 SVG Skill2-->>User: weather.svg + output.md

6.1 三层各管什么

层 角色 关注点
Command（指挥层） 入口、协调 用户交互、流程编排
Subagent（执行层） 自主任务 多步骤推理、API 调用、外部交互
Skill（输出/知识层） 可复用知识 领域知识、流程封装、生成输出

这个分层的本质是关注点分离------每个组件只做一件事，高内聚低耦合。

这种三层架构有很多优点，并且在复杂工作流里几乎是必需的，但是在实际中并不是所有任务都需要这种结构。简单任务直接用 Claude Code 原生就够了------这点 Boris 本人也反复强调过。

6.2 不要过度工程化

我刚开始用的时候特别想"全部都封装成 command + agent + skill"，结果发现：

  • 一次性的探索任务，封装的成本远大于收益
  • 简单的代码生成，原生 Claude 就能搞定
  • 真正值得封装的是每天重复多次的工作流

后面的实战篇会有具体的判断标准。

7. 这套生态究竟解决了什么问题

回到最开始的问题------这套生态究竟解决了什么问题？我把它整理成一张对照表：

痛点 解法 对应概念
每次都要重复输入相同的提示词 把工作流封装成 /slash-command Commands
Claude 对你的项目一无所知 持久化项目上下文 Memory（CLAUDE.md）
复杂任务多步骤，Claude 容易走偏 在独立上下文中自主完成任务 Subagents
需要复用特定的领域知识 可预加载、可共享的知识单元 Skills
需要在工具调用前后插入自定义逻辑 事件驱动的自动化 Hooks
需要连接外部工具 标准化协议 MCP Servers

这 6 个概念不是孤立的，它们组合起来构成一个完整的"AI 工程化"工作系统。

summary

奇奇怪怪的无用知识又增长了呢：

  • 为什么 AI 编程助手会从 Chat 形态演化到 Agentic 形态？
  • 为什么 Anthropic 选择 CLI 而不是 IDE 插件？
  • claude-code-best-practice 仓库为什么不是"应用代码"？

研究收获：

  • 认识了 6 个核心概念：Commands、Skills、Subagents、Hooks、MCP、Memory
  • 理解了 .claude/ 目录的组织逻辑
  • 初步了解 Command → Agent → Skill 三层编排架构
  • 明白了"不要过度工程化"------简单任务用原生 Claude 就够
  • 知道这套生态各个部分对应解决什么痛点

下一篇会重点对比 Command vs Agent vs Skill 这三个最容易混淆的概念，给出一个清晰的选择决策树。

Footnotes

参考资料（原文副本见 sources/ 目录）

  • sources/CLAUDE.md：本仓库的 CLAUDE.md，是这套生态最浓缩的项目级说明

外部链接

相关推荐
自律懒人4 分钟前
AI Agent 记忆方案横评：Memoria vs OpenClaw vs MCP，让Agent记住你的3种方式
人工智能·大模型·ai编程
Allen正心正念20254 分钟前
AI编程—claude code中plugin三种范围模式的配置方法
人工智能·ai编程
ServBay5 分钟前
别管跑分了，2026 本地编程大模型推荐与 GitHub Copilot 免费平替
llm·ai编程·github copilot
沉默王二12 分钟前
用Codex+Step 3.7Flash开发Agent工作流，198B激活11B参数，实测结果真有东西
agent·ai编程·编程语言
gogoing17 分钟前
Reasonix
ai编程
w1wi20 分钟前
【兼职】边学边练的AI网站
java·人工智能·ai·ai编程·ai写作
_未完待续40 分钟前
从零打造 AI Agent （三）—— Plan Mode：复杂任务的安全执行
agent·ai编程
颜进强41 分钟前
Claude Code -16 文件引用与加载机制完整实践：从 CLAUDE.md 到 Skills 与 Subagents
前端·后端·ai编程
悟空码字1 小时前
当 AI 遇到真正的编程痛点，Codex 攻克 5 类核心难题总结
aigc·openai·ai编程
小小神仙1 小时前
ECC：怎么让 Claude Code 变成你的全栈搭档
程序员·aigc·ai编程
热门推荐
01GitHub 镜像站点022026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf03【AI】2026 年具身智能模型和世界模型总结04【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法05Codex 下载安装指南：Windows 和 macOS 官方版下载06裂开！ChatGPT 居然开始要手机号验证，附详细解决方法07CC-Switch & Claude 基于 Linux 服务器安装使用指南08Codex 接入 DeepSeek API 完整配置文档09几个好用的ip纯净度检测网站10CC-Switch 下载、安装与使用配置指南【2026.5.29】