Claude Code 通识 - claude_0x01 ## 目录概要 1. 为什么想写这篇文章 2. AI 编程助手

目录概要

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

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，是这套生态最浓缩的项目级说明

外部链接

Claude Code 官方文档
Building Claude Code with Boris Cherny — The Pragmatic Engineer（Boris 亲自讲为什么做 CLI 而非 IDE）
Inside Claude Code With Its Creator Boris Cherny — Y Combinator

Claude Code 通识 - claude_0x01