1. 引言Claude Code 是 Anthropic 推出的命令行 AI 编程助手它不仅能理解自然语言指令还能通过一系列机制实现高度可定制、可扩展的自动化编码工作流。对于想要真正驾驭 Claude Code 的开发者来说仅仅会提问远远不够理解其四大核心扩展机制——CLAUDE.md、Hooks、Skills和Subagents——才是从「会用」走向「精通」的关键。本文将深入剖析这四大机制的原理与实战用法通过大量可复制的代码示例帮助你构建一套属于自己的高效 AI 编码工作流。2. CLAUDE.md项目的「记忆」与「行为准则」2.1 什么是 CLAUDE.mdCLAUDE.md是 Claude Code 在项目中的核心配置文件。它相当于给 Claude 的一份「项目说明书」告诉它项目的结构、技术栈、编码规范、常用命令以及需要特别注意的事项。每次会话启动时Claude Code 会自动读取该文件并将其作为长期记忆和上下文的一部分。2.2 文件层级与加载机制Claude Code 支持多级CLAUDE.md文件它们按以下优先级从高到低加载企业级策略文件/etc/claude-code/managed-settings.json中配置用户级全局文件~/.claude/CLAUDE.md项目级文件项目根目录的CLAUDE.md子目录级文件各子目录下的CLAUDE.md作用于该目录及其子目录当多个层级的文件同时存在时Claude 会合并它们的内容但更具体的层级如子目录会覆盖更通用层级如用户级的冲突指令。2.3 实战编写一份高质量的项目 CLAUDE.md下面是一份针对一个 Python FastAPI 项目的CLAUDE.md示例# 项目OrderAPI ## 项目概述 这是一个基于 FastAPI 的订单管理系统使用 PostgreSQL 存储数据通过 Redis 做缓存。 ## 技术栈 - Python 3.11 - FastAPI 0.100 - SQLAlchemy 2.0 - Alembic数据库迁移 - Pytest测试 ## 常用命令 - 启动开发服务器uvicorn app.main:app --reload - 运行测试pytest - 数据库迁移alembic upgrade head - 代码格式化ruff format . ## 编码规范 - 所有 API 路由必须使用 /api/v1/ 前缀 - 使用类型注解禁止使用 Any 类型 - 数据库会话必须通过依赖注入获取禁止直接创建 - 所有业务逻辑写在 service 层路由层只做参数校验和响应封装 ## 架构约定 - app/models/SQLAlchemy 模型 - app/schemas/Pydantic 模型 - app/services/业务逻辑 - app/api/路由定义 ## 注意事项 - 修改数据库模型后必须生成新的 Alembic 迁移 - 不要提交 .env 文件到版本控制 - 所有新增接口必须附带对应的单元测试2.4 进阶技巧使用引用外部文件当项目文档较多时可以在CLAUDE.md中使用语法引用其他文件让 Claude 按需加载## 架构设计 docs/architecture.md ## API 规范 docs/api-conventions.md这样既能保持主文件简洁又能让 Claude 在需要时获取详细文档。3. Hooks自动化工作流的「触发器」3.1 什么是 HooksHooks 是 Claude Code 的生命周期回调机制。它允许你在 Claude 执行特定操作如开始编辑文件、执行命令、完成一次回复时自动运行自定义脚本。这为工作流自动化、代码质量保障和安全防护提供了强大的支持。3.2 Hook 的类型与触发时机Hooks 通过settings.json配置主要分为以下几类Hook 类型触发时机典型用途PreToolUse调用工具之前权限校验、参数检查、敏感操作拦截PostToolUse调用工具之后自动格式化、运行测试、日志记录Notification需要用户通知时发送桌面通知、消息推送UserPromptSubmit用户提交提示词时注入额外上下文、敏感信息过滤StopClaude 完成回复时自动提交代码、清理临时文件SubagentStop子代理完成时汇总子代理结果3.3 实战配置一个 PreToolUse Hook 拦截危险命令下面通过一个实际案例演示如何用 Hook 拦截rm -rf这类危险命令。首先创建 Hook 脚本hooks/guard.js#!/usr/bin/env node// 接收 stdin 中的 JSON 输入letinput;process.stdin.on(data,(chunk)(inputchunk));process.stdin.on(end,(){consteventJSON.parse(input);consttoolNameevent.tool_name;consttoolInputevent.tool_input;// 拦截 Bash 工具中的危险命令if(toolNameBash){constcommandtoolInput.command||;if(command.includes(rm -rf)||command.includes(git push --force)){// 返回非零退出码并输出拦截原因console.error(危险命令已被 Hook 拦截command);process.exit(2);}}// 放行process.exit(0);});然后在settings.json中注册该 Hook{hooks:{PreToolUse:[{matcher:Bash,hooks:[{type:command,command:node hooks/guard.js}]}]}}3.4 实战PostToolUse Hook 自动格式化代码每次 Claude 编辑完 Python 文件后自动运行ruff格式化{hooks:{PostToolUse:[{matcher:Edit|Write,hooks:[{type:command,command:ruff format --quiet $(git diff --name-only | grep \\.py$)}]}]}}3.5 Hook 的输入输出协议Claude Code 通过 stdin 向 Hook 脚本传递 JSON 格式的事件数据Hook 脚本通过 stdout 输出 JSON 格式的响应。核心字段如下输入事件示例{session_id:abc123,tool_name:Edit,tool_input:{file_path:/path/to/app.py,old_string:def foo():,new_string:def foo():\n pass}}输出响应示例用于 PreToolUse 拦截{decision:block,reason:该文件属于只读目录禁止修改}4. Skills可复用的「技能包」4.1 什么是 SkillsSkills 是 Claude Code 中的可复用能力模块。一个 Skill 通常包含一组指令、示例和资源文件用于教会 Claude 完成某一类特定任务。与CLAUDE.md的「被动记忆」不同Skills 是「主动能力」Claude 会在需要时自动调用它们。4.2 Skill 的目录结构一个标准的 Skill 目录结构如下~/.claude/skills/ └── code-review/ ├── SKILL.md # 技能定义文件必需 ├── prompts/ # 可选的提示词模板 │ └── review.md └── scripts/ # 可选的辅助脚本 └── analyze.py4.3 实战创建一个代码审查 Skill创建~/.claude/skills/code-review/SKILL.md--- name: code-review description: 对代码变更进行全面的代码审查检查代码质量、安全性和潜在 bug。当用户要求「审查代码」「code review」或提交 PR 前使用。 --- # 代码审查技能 当你被要求进行代码审查时请遵循以下流程 ## 审查步骤 1. **获取变更范围**使用 git diff 获取当前分支的变更内容 2. **逐文件审查**对每个变更文件执行以下检查 - 逻辑正确性是否存在边界条件遗漏或逻辑错误 - 安全性是否存在 SQL 注入、XSS、敏感信息泄露等风险 - 性能是否存在明显的性能瓶颈 - 代码规范是否符合项目的编码规范 3. **输出审查报告**按以下格式输出 markdown ## 审查报告 ### 严重问题 - [文件:行号] 问题描述 ### 建议改进 - [文件:行号] 改进建议 ### 亮点 - 值得肯定的设计注意事项优先关注严重问题不要过度纠结于代码风格如果变更涉及数据库迁移必须检查迁移脚本的安全性### 4.4 在 CLAUDE.md 中声明 Skill 为了让 Claude 知道在什么场景下使用哪些 Skill可以在 CLAUDE.md 中声明 markdown ## 可用技能 - 当需要审查代码时使用 code-review 技能 - 当需要编写单元测试时使用 test-writer 技能4.5 实战创建一个「提交信息生成」Skill创建~/.claude/skills/commit-message/SKILL.md--- name: commit-message description: 根据代码变更生成符合 Conventional Commits 规范的提交信息。当用户要求「生成提交信息」「写 commit message」时使用。 --- # 提交信息生成技能 ## 执行步骤 1. 运行 git diff --stat 和 git diff 查看变更内容 2. 分析变更类型确定 commit type - feat新功能 - fix修复 bug - refactor重构 - docs文档变更 - test测试相关 - chore构建或辅助工具变动 3. 生成符合以下格式的提交信息():示例输入修改了用户登录接口的密码加密方式输出fix(auth): 修复密码加密方式 将 MD5 加密替换为 bcrypt提升安全性。5. Subagents并行协作的「专业团队」5.1 什么是 SubagentsSubagents 是 Claude Code 中的子代理机制。你可以创建多个具有不同「角色设定」和「专业领域」的子代理让主 Claude 在需要时委派任务给它们。每个 Subagent 拥有独立的上下文窗口可以并行工作大幅提升复杂任务的完成效率。5.2 Subagent 的配置方式Subagents 通过.claude/subagents/目录下的 Markdown 文件定义。每个文件定义一个子代理.claude/subagents/ ├── frontend-expert.md ├── security-auditor.md └── test-writer.md5.3 实战定义一个前端专家 Subagent创建.claude/subagents/frontend-expert.md--- name: frontend-expert description: 前端开发专家精通 React、Vue、TypeScript 和现代 CSS。当需要实现或修改前端界面时使用。 tools: Read, Grep, Glob, Edit, Write, Bash model: sonnet --- # 前端专家 你是一名资深前端工程师拥有 10 年以上的 Web 开发经验。 ## 专业领域 - React 18 / Vue 3 组件开发 - TypeScript 类型系统 - 响应式布局与 CSS 动画 - 前端性能优化 - 无障碍访问a11y ## 工作准则 1. 所有组件必须使用 TypeScript 编写 2. 组件样式使用 CSS Modules 或 Tailwind禁止使用全局样式 3. 必须处理 loading、error、empty 三种状态 4. 性能敏感场景使用 React.memo 或 useMemo 优化 5. 代码提交前必须通过 ESLint 检查 ## 输出规范 - 提供完整的组件代码包含样式和类型定义 - 说明组件的 props 接口 - 给出使用示例5.4 实战定义一个安全审计 Subagent创建.claude/subagents/security-auditor.md--- name: security-auditor description: 安全审计专家擅长发现代码中的安全漏洞。当需要检查代码安全性或进行安全审查时使用。 tools: Read, Grep, Glob, Bash model: sonnet --- # 安全审计专家 你是一名应用安全工程师专注于 Web 应用安全。 ## 审查重点 1. **注入攻击**SQL 注入、命令注入、模板注入 2. **认证与授权**越权访问、会话管理缺陷 3. **敏感数据**硬编码密钥、日志泄露、不安全的存储 4. **XSS 攻击**反射型、存储型、DOM 型 5. **依赖安全**存在已知漏洞的第三方库 ## 工作流程 1. 使用 grep 搜索敏感模式如 password、secret、api_key 2. 审查用户输入的处理流程 3. 检查数据库查询语句的构造方式 4. 输出安全审查报告按严重程度分级 ## 输出格式 markdown ## 安全审查报告 ### 严重漏洞 - 位置、漏洞类型、攻击路径、修复建议 ### 中危问题 - 位置、问题描述、改进建议 ### 安全实践 - 做得好的地方5.5 在 CLAUDE.md 中声明 Subagents## 子代理 - 涉及前端界面开发时委派给 frontend-expert - 涉及安全审查时委派给 security-auditor - 涉及测试编写时委派给 test-writer5.6 Subagent 的调用方式当主 Claude 判断任务适合委派时会自动调用 Subagent。你也可以在提示词中显式要求请让 frontend-expert 子代理审查一下这个 React 组件的性能问题。6. 四大机制协同实战构建一个完整的自动化工作流下面通过一个综合案例展示如何将四大机制组合起来构建一个完整的开发工作流。6.1 场景描述假设我们要开发一个 Node.js 的 REST API 服务希望实现以下自动化每次 Claude 编辑代码后自动运行测试提交代码前自动进行安全审查生成符合规范的提交信息6.2 项目结构my-api/ ├── CLAUDE.md ├── .claude/ │ └── subagents/ │ ├── security-auditor.md │ └── test-writer.md ├── ~/.claude/ │ ├── settings.json │ └── skills/ │ ├── code-review/ │ │ └── SKILL.md │ └── commit-message/ │ └── SKILL.md6.3 配置 CLAUDE.md# 项目MyAPI ## 技术栈 - Node.js 20 - Express 4 - Jest测试 ## 常用命令 - 启动npm start - 测试npm test ## 子代理 - 涉及安全审查时使用 security-auditor - 涉及测试编写时使用 test-writer ## 技能 - 提交代码前使用 commit-message 技能生成提交信息6.4 配置 Hooks在~/.claude/settings.json中配置{hooks:{PostToolUse:[{matcher:Edit|Write,hooks:[{type:command,command:npm test -- --silent}]}],PreToolUse:[{matcher:Bash,hooks:[{type:command,command:node ~/.claude/hooks/guard.js}]}]}}6.5 工作流效果当开发者对 Claude 说「帮我实现用户注册接口」时整个工作流如下主 Claude读取CLAUDE.md了解项目结构和规范主 Claude编写代码使用Edit工具修改文件PostToolUse Hook自动触发运行npm test验证代码如果涉及安全敏感操作主 Claude委派security-auditor子代理进行审查开发完成后开发者要求「生成提交信息」主 Claude调用commit-message技能生成规范提交信息7. 最佳实践与注意事项7.1 CLAUDE.md 编写建议保持简洁只写必要的信息避免冗长使用明确的指令用「必须」「禁止」等强约束词定期更新随