解构 Claude Code

大多数开发者认为 AI 编码工具就是一个聊天界面。你输入它回复。你复制代码。你继续前进。Claude Code 完全不同。1、传统方式 vs Claude Code 方式想象雇佣一位聪明的开发者他他* 每次关闭对话就忘记一切不知道自己在什么项目除非你每次都描述工具否则无法使用逘需要你监督他们的每一个动作这是一个传统的 AI 聊天工具。现在想象一位开发者他 以下特点**在开始每个会话之前阅读项目文档自动遵循你的代码风格和架构规则拥有可以委派工作的专家同事可以连接到你的数据库、GitHub、Slack 等拥有防止他们犯下危险错误的护栏在接触每个文件后自动运行质量检查这就是 Claude Code。它不是一个带有代码块的聊天界面。它是一个完整的智能体开发环境—— Claude 不仅仅是响应还会行动、决策、委托和持久化。在我们我们探索功能之前先了解智能体循环意味着。在传统聊天机器人中:你输入 → AI 回复 → 完成在 Claude Code 中循环是这样的:你给出目标 ↓ Claude 读取项目上下文 (CLAUDE.md, 规则) ↓ Claude 制定计划 ↓ Claude 使用工具(读取文件、 运行命令, 调用 API) ↓ ←──────────────────────────────────┐ Claude 检查结果 │ ↓ │ 需要更多信息? ──── 是 ─────────────────┘ ↓ 否 Claude 交付结果 ↓ 钩子运行(格式化代码, 运行测试, 记录活动)Claude 不会在每一步等待你。它会自主行动——读取文件、运行命令、 修复错误, 并重试。Claude Code 的强大之处在于你可以将自定义逻辑插入这个循环的每一个部分。2、6 个扩展点宏观图如下。每个功能插入 Claude 智能体循环的不同部分:让我们逐个探索。3、CLAUDE.md — 持久记忆插入点会话开始 —— 在 Claude 编写任何代码行之前加载。3.1 它解决的问题每次开始新的 Claude 会话时,它对项目一无所知。你必须重新解释如何运行测试哪些文件夹包含哪些代码使用什么命名约定做出了什么架构决策CLAUDE.md解决了这个问题。这是一个 markdown 文文件,Claude在每次会话开始时自动读取——就像新开发者的入职文档。示例CLAUDE.md# CLAUDE.md ## 构建和测试命令 - 安装: npm install - 运行开发服务器: npm run dev - 运行测试: npm test - 运行单个测试: npm test -- --testPathPatternfilename - 代码检查: npm run lint ## 代码风格 - 2 空格缩进 - TypeScript 严格模式 - 优先使用 const,避免 var ## 架构 - API 夌理程序: src/api/ - React 组件: src/components/ - 所有 API 响应用: { success, data, error } ## 命名约定 - 组件: PascalCase → UserProfile.tsx - 函数: camelCase → getUserProfile - 常量: UPPER_SNAKE_CASE → MAX_RETRIES现在每个会话中,Claude 已经知道如何构建项目、东西在哪里, 以及要遵循什么编码风格——无需你重复自己。3.2 CLAUDE.md 可以存在哪里Claude 遵循层次结构。更具体的文件优先 专业提示保持在 200 行以内。每一行都会消耗 Claude 上下文窗口中的令牌。简短具体胜过冗长模糊。4、.claude/rules/ — 条件指令插入点在规划期间 —— 仅当 Claude 处理匹配文件时加载。4.1 它解决的问题你的项目对不同部分的代码库有不同的规则。API 代码有不同的约定, React 组件。数据库查询有不同的安全要求,工具函数。如果把所有内容都放在CLAUDE.md中,它会变得庞大。而且 Claude 每次都会加载所有内容——即使在处理不相关的文件时也是如此。.claude/rules/通过条件加载解决了这个问题。4.2 如何工作在.claude/rules/中创建 markdown 文件。在顶部添加paths部分以指定哪些文件触发此规则.claude/ └── rules/ ├── api-rules.md ← 仅用于 src/api/** ├── frontend-rules.md ← 仅用于 src/components/** └── security.md ← 始终加载(无 paths)示例api-rules.md--- paths: - src/api/**/*.ts --- # API 开发规则 - 每个端点必须在处理前验证输入 - 始终返回: { success: boolean, data: any, error: string | null } - 使用正确的 HTTP 状态码: 200, 400, 401, 404, 500 - 永远不要向客户端暴露内部错误消息 - 记录所有错误并附带时间戳和请求 ID示例frontend-rules.md--- paths: - src/components/**/*.{ts,tsx} --- # 前端规则 - 仅使用带 hooks 的函数组件(禁止类组件) - 始终使用 TypeScript interface 类型 props - 对具有稳定 props 的组件使用 React.memo - 数据获取必须使用 TanStack Query (react-query) - 禁止内联样式 - 仅使用 Tailwind CSS 类示例security.md无 paths 始终加载)# 安全规则 - 永远不要在源代码中硬编码 API 密钥、令牌或密码 - 始终使用环境变量存储机密信息 - 在数据库查询之前清理所有用户输入 - 永远不要记录密码、令牌或个人信息4.3 与 CLAUDE.md 的关键区别5、技能 —— 可重用工作流插入点按需 — 手动调用或 Claude 识别任务时自动调用5.1 它解决的问题你不断要求 Claude 执行相同类型的任务“向我解释这段代码”“为这个函数编写测试”“审查这个 PR”每次,你都需要编写一个长提示,准确描述想要的格式、包含内容、避免内容。技能让你可以定义一次提示并永远重用。5.2 如何工作在.claude/skills/skill-name/中创建一个带有SKILL.md文件的文件夹.claude/ └── skills/ ├── explain-code/ │ └── SKILL.md └── write-tests/ └── SKILL.md示例explain-code/SKILL.md--- name: explain-code description: 用类比、图表和分步演练解释代码。 当用户问这是如何工作的?或解释这段代码时使用。 --- 解释代码时,始终遵循此结构: ## 1. 一行总结 以 这段代码做了 X。 开头 ## 2. 现实世界类比 将代码与日常生活的事物进行比较 ## 3. 可视化图表 绘制显示流程的 ASCII 图表 ## 4. 分步演练 逐块解释每个部分的作用 ## 5. 注意事项 以人们在使用此代码时常犯的一个常见错误结尾示例write-tests/SKILL.md--- name: write-tests description: 为给定函数或文件编写 Jest 单元测试。 当被要求编写测试或添加测试覆盖率时使用 argument-hint: [filename or function name] --- 为 $ARGUMENTS 编写 Jest 测试 覆盖: 1. 快乐路径 - 正常预期输入 2. 边缘情况 - 空、null、 鰶、 大值 3. 错误情况 - 无效输入,缺失字段 每个测试的结构: - 安排(设置输入) - 操作(调用函数) - 断言(检查结果)5.3 如何使用技能使用斜杠命令手动调用:/explain-code /write-tests getUserProfile$ARGUMENTS会被你输入技能名称后的内容替换/write-tests getUserProfile→ Claude 专门为getUserProfile编写测试自动调用description字段告诉 Claude 何时自动使用技能。如果你输入你能解释一下这个认证中间件是如何工作吗,Claude 会识别匹配并使用explain-code技能,而无需你输入/explain-code5.4 技能 vs CLAUDE.md6、子智能体 —— 专家团队成员插入点在执行期间 —— Claude 将复杂或隔离的任务委托给专家6.1 它解决的问题想象让 Claude 在编写新功能的同时进行完整的代码审查。代码审查是一个完全独立的关注点——它不应与主任务的上下文混合。它还需要特定的工具(只读访问,无写入)子智能体让你可以创建 Claude 可以委派工作的专家 AI 工作者——每个都有自己独立的上下文、特定工具和专注的专业知识。6.2 如何工作在.claude/agents/agent-name/中创建一个带有 markdown 文件的文件夹.claude/ └── agents/ └── code-reviewer/ └── agent.md示例code-reviewer/agent.md--- name: code-reviewer description: 专家代码审查专家。审查代码的质量、安全性、bug 和和可维护性。 在编写或修改代码后使用 tools: Read, Grep, Glob, Bash model: sonnet --- 你是一位高级软件工程师,正在进行彻底的代码审查 调用时: 1. 运行 git diff 查看最近的更改 2. 读取修改的文件 3. 立即开始审查 ## 审查清单 ### 代码质量 - [ ] 代码可读且自文档化 - [ ] 函数只做一件事 - [ ] 没有重复代码 ### 安全性 - [ ] 没有硬编码的密钥或 API 密钥 - [ ] 用户输入已验证 ### 错误处理 - [ ] 所有异步调用都有 try/catch6.3 无子智能体 vs 主 Claude 上下文主 Claude 上下文 仅你的任务 代码审查员上下文 分离的窗口,仅包含审查相关内容子智能体:在自己的隔离上下文窗口中运行拥有受限工具(例如,审查员只读)** 可以 Claude 继续其他工作的同时在后台运行可以跨会话**记住内容(使用持久记忆)7、MCP — 外部工具和数据插入点在执行期间 —— 让 Claude 访问代码库外部的工具。它解决的问题Claude 本身只能读写项目中的文件。它无法:查询你的数据库读取 GitHub issues检查 Sentry 锑误日志发送 Slack 消息查看 Figma 设计MCP (模型上下文协议)是一个开放标准,将 Claude 连接到外部服务——为其提供在真实世界中行动的真实工具。7.1 如何工作在项目根目录下的.mcp.json中配置 MCP 服务器{ mcpServers: { github: { type: http, url: https://api.githubcopilot.com/mcp/, headers: { Authorization: Bearer ${GITHUB_TOKEN} } }, postgres: { type: stdio, command: npx -y bytebase/dbhub --dsn \postgresql://... } }示例工作流你要求 Claude 总结 Sentry 锌误 ↓ Claude 调用 Sentry MCP → 读取错误日志 → 总结它们7.2 安装 MCP 服务器# 添加远程 HTTP 服务器(例如 GitHub) claude mcp add --transport http github https://api.githubcopilot.com/mcp/ # 添加本地进程服务器(例如 PostgreSQL) claude mcp add --transport stdio db -- npx -y bytebase/dbhub --dsn postgresql://... # 列出所有已安装的服务器 claude mcp list7.3 两种类型的 MCP 服务器8、钩子 —— 护栏和自动化插入点在每次工具调用前后 —— 最强大的扩展点8.1 它解决的问题Claude 是自主的——它会做出决策并采取行动。但但有时你需要:阻止某些操作发生(阻止rm -rf)自动化应该始终发生的事情(每次编辑后运行 Prettier)监控Claude 在做什么(记录每个工具调用)通知你 Claude 需要关注时钩子让你可以用自己的逻辑包装 Claude 的每个操作。8.2 如何工作钩子在.claude/settings.json中配置,并指向 shell 脚本{ hooks: { PreToolUse: [...], PostToolUse: [...], Notification: [...] } }每个钩子条目有:matcher— 监视哪个工具(Bash,Edit|Write,表示所有)type—command(运行脚本),http,prompt(询问 Claude),agentcommand— shell 脚本的路径8.3 退出代码系统Shell 脚本使用退出代码与 Claude 通信exit 0 → 允许(正常继续) exit 2 → 阻止(停止操作,通过 stderr 告诉 Claude 原因) exit 1 → 警告(继续但记录错误)钩子 1: 阻止危险命令文件.claude/hooks/protect-bash.sh#!/bin/bash # 在 Claude 运行 Bash 命令之前运行 INPUT$(cat) FILE_PATH$(echo $INPUT | jq -r .tool_input.file_path) # Only format JS/TS files if [[ ! $FILE_PATH ~ \.(ts|tsx|js|jsx|json|css)$ ]]; then exit 0 fi # Block dangerous patterns if [[ $INPUT ~ \.(rm -rf|sudo rm|drop table|truncate)\ ]]; then echo ERROR: Dangerous command blocked: $INPUT 12 exit 2 fi exit 0配置在settings.jsonPreToolUse: [ { matcher: Bash, hooks: [{ type: command, command: .claude/hooks/protect-bash.sh, timeout: 10 }] } ]钩子 2: 保护敏感文件文件.claude/hooks/protect-files.sh#!/bin/bash # 在 Claude 编辑或写入任何文件之前运行 INPUT$(cat) FILE_PATH$(echo $INPUT | jq -r .tool_input.file_path) # Block edits to sensitive files if [[ $FILE_PATH ~ \.(env|.credentials|.pem|.key)\ ]]; then echo ERROR: Cannot edit sensitive file: $FILE_PATH 12 exit 2 fi exit 0配置在settings.jsonPreToolUse: [ { matcher: Edit|Write, hooks: [{ type: command, command: .claude/hooks/protect-files.sh, timeout: 10 }] } ]钩子 3: 自动格式化代码文件.claude/hooks/auto-format.sh#!/bin/bash # 在 Claude 编辑或写入任何文件之后运行 npx prettier --write $FILE_PATH --log-level silent exit 0配置在settings.jsonPostToolUse: [ { matcher: Edit|Write, hooks: [{ type: command, command: .claude/hooks/auto-format.sh, async: true }] } ]钩子 4: 记录所有工具调用文件.claude/hooks/log-tools.sh#!/bin/bash # 在 Claude 使用任何工具之后运行 INPUT$(cat) TOOL_NAME$(echo $INPUT | jq -r .tool_name) TIMESTAMP$(date -u %Y-%m-%d %H:%M.%SZ) echo {\timestamp\: \$TIMESTAMP\, \tool\: \$TOOL_NAME\} $CLAUDE_PROJECT_DIR/.claude/tool-usage.log exit 0配置在settings.jsonPostToolUse: [ { matcher: , hooks: [{ type: command, command: .claude/hooks/log-tools.sh, async: true }] } ]钩子 5: 桌面通知文件.claude/hooks/notify.sh#!/bin/bash # 当 Claude 等待你的输入时发送 macOS 通知 osascript -e display notification Claude is waiting for your input with title Claude Code exit 0配置在settings.jsonNotification: [ { matcher: idle_prompt, hooks: [{ type: command, command: .claude/hooks/notify.sh }] } ]宧完整的 settings.json{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: \$CLAUDE_PROJECT_DIR\/.claude/hooks/protect-bash.sh, timeout: 10 } ] }, { matcher: Edit|Write, hooks: [ { type: command, command: \$CLAUDE_PROJECT_DIR\/.claude/hooks/protect-files.sh, timeout: 10 } ] } ], PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: \$CLAUDE_PROJECT_DIR\/.claude/hooks/auto-format.sh, async: true } ] }, { matcher: , hooks: [ { type: command, command: \$CLAUDE_PROJECT_DIR\/.claude/hooks/log-tools.sh, async: true } ] } ], Notification: [ { matcher: idle_prompt, hooks: [ { type: command, command: \$CLAUDE_PROJECT_DIR\/.claude/hooks/notify.sh } ] } ] } }9、所有 6 个功能组合这是完整的项目结构claude_code_blog_demo/ │ ├── CLAUDE.md ← 持久记忆(会话开始) ├── .mcp.json ← 外部工具(GitHub, PostgreSQL) │ └── .claude/ ├── settings.json ← 钩子配置 │ ├── rules/ ← 条件指令 │ ├── api-rules.md ← 为 src/api/** 加载 │ ├── frontend-rules.md ← 为 src/components/** 加载 │ └── security.md ← 始终加载 │ ├── skills/ ← 可重用工作流 │ ├── explain-code/SKILL.md ← /explain-code │ └── write-tests/SKILL.md ← /write-tests │ ├── agents/ ← 专家子智能体 │ └── code-reviewer/agent.md ← 鵚离代码审查 │ └── hooks/ ← 护栏和自动化 ├── protect-bash.sh ← 阻止危险命令 ├── protect-files.sh ← 阻止敏感文件编辑 ├── auto-format.sh ← 编辑后格式化代码 ├── log-tools.sh ← 宷计所有工具使用 └── notify.sh ← 桌面通知每个功能插入智能体循环的位置会话开始 │ └── CLAUDE.md 加载 ──────────────── 这个项目如何工作 │ ▼ Claude 规划 │ ├── 规则加载(如果文件匹配) ───── 这里文件特定规则 └── 技能可用 ───────────────── 这里可重用工作流 │ ▼ Claude 行动 │ ├── PreToolUse 钩子运行 ────────────── 应该允许这个吗 │ │ │ exit 2 → 阻止 │ exit 0 → 允许 │ │ ▼ ▼ 工具执行 │ └── PostToolUse 钩子运行 ─────────── 自动格式化、 记录 │ ▼ Claude 交付原文链接解构 Claude Code - 汇智网