1. 从零到一为什么你需要一个结构化的Claude Code学习路径如果你已经安装了Claude Code尝试过几次对话然后感觉“好像也就这样”那你绝对不是一个人。我刚开始用的时候也是这种感觉官方文档像一本功能说明书告诉你每个按钮是干嘛的但没告诉你这些按钮怎么组合起来才能造出一台能自己跑的机器。你知道了有“斜杠命令”但不知道如何把它和“钩子”、“记忆”、“子代理”串成一个能真正帮你省下几个小时工作的自动化流水线。你面对“技能”、“MCP协议”、“子代理”这些概念就像面对一堆乐高零件知道每个零件的样子却不知道如何拼出你想要的城堡。这就是luongnv89/claude-howto这个项目诞生的背景。它不是一个简单的功能列表而是一张由社区里两万多名开发者共同绘制、验证过的“乐高搭建手册”。它解决的核心痛点是从“知道”到“会用”再到“精通”之间的巨大鸿沟。官方文档告诉你“有什么”而这个指南告诉你“怎么用”更重要的是告诉你“为什么这么用”以及“怎么组合起来用威力最大”。我自己花了大概一个周末的时间跟着这个指南的路径走了一遍。最大的感受是之前散落在各处的知识点突然被一条清晰的逻辑线串起来了。我知道在什么场景下该启用“规划模式”什么时候该派“子代理”上场如何用“钩子”在代码写入前自动做一次安全检查。这种“体系化”的理解才是让你从Claude Code的普通用户变成能驾驭它的效率工程师的关键。接下来我就结合自己的实践带你拆解这份指南的精华并补充一些官方模板之外你真正上手时才会遇到的细节和“坑”。2. 核心设计哲学模块化、渐进式与生产就绪这个项目的结构设计得非常聪明它没有采用传统的“从易到难”的线性编排而是采用了一种“按能力层级和场景需求”的模块化设计。这背后反映了一个深刻的洞察不同背景的开发者痛点完全不同。2.1 三层能力模型与你的起点项目将学习者分为三层这非常实用新手刚安装还在用基础聊天功能。他们的核心诉求是“快速获得正反馈”比如用一个斜杠命令立刻优化一段代码。所以指南让他们从/optimize这样的命令开始15分钟就能看到效果建立信心。中级用户已经会用一些基础命令但工作流还是手动的、重复的。他们需要的是“自动化”和“个性化”。CLAUDE.md项目记忆和Skills技能就是为他们准备的可以把团队规范、个人偏好固化下来让Claude自动遵守。高级用户追求的是“系统化”和“智能化”。他们需要构建复杂的多代理协作系统Subagents连接外部数据源MCP实现事件驱动的自动化Hooks。指南的后面几个模块就是为这个目标服务的。这种设计的好处是你可以直接“对号入座”不用从第一页看到最后一页。项目提供的/self-assessment自评估命令或查看LEARNING-ROADMAP.md能帮你快速定位。比如如果你已经会写简单的斜杠命令但不知道如何让Claude自动进行代码审查那你应该直接跳到Skills和Subagents模块。2.2 “复制即用”的模板降低启动成本这是该项目最具杀伤力的特点。每个模块的核心都不是理论阐述而是一堆可以直接cp复制到你的项目目录中立即生效的Markdown或配置文件。例如在01-slash-commands/目录下optimize.md的内容远不止是一个命令定义。它通常包含清晰的描述告诉Claude这个命令是干什么的。具体的执行步骤分步骤的思考或操作流程。输出格式要求比如“用表格列出优化建议包含问题描述、位置、修改方案和预期收益”。可选的参数支持动态输入比如/optimize --aggressive进行更激进的优化。# 文件名optimize.md # 路径.claude/commands/optimize.md description: 分析并优化当前文件或指定代码段的性能、可读性和最佳实践。 steps: 1. 首先理解代码的上下文和目的。 2. 逐行分析识别以下问题 - 性能瓶颈如冗余循环、低效算法 - 可读性问题如糟糕的命名、过长的函数 - 违反最佳实践如错误处理缺失、安全漏洞 - 潜在的bug 3. 对每个问题提供具体的修改代码示例。 4. 总结优化后的核心改进点。 output: 使用一个表格来呈现分析结果列包括问题类型、代码位置、问题描述、优化建议、优先级高/中/低。你复制过去后在Claude Code里直接键入/optimize它就会按照这个模板工作。这种设计将学习成本从“理解概念-自己设计-调试”压缩到了“复制-微调-使用”实现了真正的“15分钟上手”。实操心得不要直接复制粘贴后就了事。最好的方式是复制一个模板然后根据你自己项目的技术栈是React、Python还是Go和团队规范去修改模板里的具体检查项和输出格式。这个过程本身就是最好的学习。2.3 可视化解释理解“为什么”比知道“怎么做”更重要官方文档可能只会说“MCP服务器允许Claude访问外部工具”。但这个指南会用Mermaid图表展示数据流用户提问 - Claude解析意图 - 查询MCP配置 - MCP服务器调用外部API - 返回数据给Claude - Claude生成回答。这种可视化的价值在于当你后续配置MCP失败时你能清晰地定位问题可能出在哪个环节是Claude没有正确触发是MCP服务器配置不对还是API凭证失效理解了架构排查问题就有了方向。3. 核心模块深度解析与实战要点3.1 记忆系统让Claude拥有“长期记忆”Memory模块的核心是CLAUDE.md文件。它的工作原理类似于项目的“宪法”或“员工手册”Claude在会话开始时会自动读取并严格遵守其中的指令。关键点记忆是分层的。全局记忆(~/.claude/CLAUDE.md)适用于你所有项目比如你的个人编码风格偏好“我习惯用4个空格缩进”。项目记忆(./CLAUDE.md)适用于当前项目比如项目技术栈、代码规范、API设计原则、测试要求。目录记忆(./src/api/CLAUDE.md)更细粒度只对该目录下的文件生效比如定义所有API端点必须遵循RESTful规范并自动生成OpenAPI文档片段。实战配置示例 在你的项目根目录创建CLAUDE.md内容可以这样组织# 项目电商后端服务 ## 技术栈 - 语言Python 3.11 - Web框架FastAPI - 数据库PostgreSQL (SQLAlchemy ORM) - 测试pytest - 代码风格遵循Black和isort ## 代码规范 - 所有API端点必须有详细的Pydantic模型定义请求/响应。 - 错误处理必须使用自定义的HTTPException并包含错误码和详细信息。 - 数据库操作必须放在repositories目录下业务逻辑放在services下。 - 异步函数使用async/await。 ## 自动化要求 - 当修改模型时提醒我是否需要更新数据库迁移Alembic。 - 当创建新的API端点时自动建议对应的单元测试用例结构。 - 拒绝直接编写SQL字符串必须使用SQLAlchemy Core或ORM。注意事项避免冲突如果目录记忆和项目记忆冲突通常更具体的目录记忆会生效取决于Claude Code的配置和读取顺序。建议保持规则的一致性。定期更新随着项目演进CLAUDE.md也需要更新。可以把它纳入版本控制在团队内同步。不要过度指定不要把它写成一本百科全书。聚焦在那些你希望Claude“无条件遵守”的核心规则上。过于琐碎的规则可能会限制Claude的创造性。3.2 技能封装可复用的自动化工作流Skills是我认为从“中级”迈向“高级”最关键的一步。一个技能Skill是一个包含指令SKILL.md和可执行脚本的完整包。以code-review技能为例它的目录结构是code-review/ ├── SKILL.md # 技能的核心指令何时触发、做什么、输出什么 └── scripts/ ├── pre-review.sh # 评审前脚本例如运行linter └── post-review.py # 评审后脚本例如生成评审报告到JIRASKILL.md里会定义触发条件例如trigger: 当用户提及“review”、“代码审查”或修改了.py/.js/.go文件时。 action: 1. 运行scripts/pre-review.sh进行静态检查。 2. 基于以下维度分析代码逻辑正确性、性能、安全性、可维护性、测试覆盖率。 3. 运行scripts/post-review.py将结构化结果保存。 output: 提供一个详细的评审报告包含问题列表、严重等级、修改建议和关联的脚本输出。技能与斜杠命令的区别斜杠命令需要你手动输入/review来触发。技能由Claude根据上下文自动判断并触发。你只需要说“看看我刚写的这个登录函数”它就能自动调用代码评审技能。实战心得 创建技能时trigger的描述要尽可能精确避免误触发。脚本scripts是技能威力的放大器它们让Claude不仅能“分析”还能“执行”。例如一个“数据库迁移”技能可以在Claude分析完模型变更后自动运行alembic revision --autogenerate命令生成迁移脚本。3.3 子代理构建专属的AI专家团队Subagents子代理是Claude Code最强大的概念之一。你可以把它理解为为你特定任务量身定制的“迷你Claude”拥有独立的系统指令和上下文。核心机制主代理和你对话的Claude在遇到复杂任务时会根据任务类型自动将任务委派给最合适的子代理。子代理处理完后将结果返回给主代理由主代理整合后回复你。项目提供的几个子代理模板非常经典code-reviewer.md专注代码质量指令更严苛可能设置为“只读模式”防止其直接修改代码。test-engineer.md专注测试策略和用例设计其系统指令里充满了关于测试金字塔、边界条件、Mock技术的知识。secure-reviewer.md专注安全会重点检查SQL注入、XSS、敏感信息泄露等问题。如何配置一个子代理 在.claude/agents/目录下创建一个Markdown文件例如api-specialist.md# 角色API设计专家 ## 专长 - RESTful API设计原则 (HATEOAS, 资源嵌套) - OpenAPI/Swagger规范 - 认证授权设计 (JWT, OAuth2) - 错误处理标准化 - 性能优化分页、缓存策略 ## 工作方式 1. 当接收到API设计任务时首先确认需求边界。 2. 设计资源模型、端点URL、HTTP方法、状态码。 3. 提供完整的请求/响应示例包括Headers和Body。 4. 考虑版本化、兼容性和可发现性。 5. 输出格式必须包含可粘贴到OpenAPI文档的YAML片段。 ## 限制 - 不处理具体的业务逻辑实现。 - 聚焦于接口契约设计。注意事项职责清晰每个子代理的职责范围要明确且互斥避免主代理在委派时出现选择困难。上下文隔离子代理处理任务时看不到主代理和其他子代理的对话历史。这保证了专注但也意味着如果你需要它了解完整背景必须在任务描述中传递关键信息。性能开销频繁调用多个子代理会增加响应时间。对于简单任务直接让主代理处理即可。3.4 钩子事件驱动的自动化管道Hooks钩子是连接Claude Code世界和外部自动化脚本的桥梁。它允许你在Claude Code的特定生命周期事件发生时自动执行一段Shell脚本。钩子的类型4大类25种事件是精髓工具钩子在Claude使用工具如写入文件、运行命令前后触发。这是最常用的比如PreToolUse时自动格式化代码PostToolUse时运行单元测试。会话钩子在会话开始、结束、创建子代理时触发。可用于环境检查、日志记录。任务钩子在用户提交提示、任务完成时触发。可用于通知、状态同步。生命周期钩子在配置变更、工作区切换等更底层的事件触发。一个实战钩子示例format-code.sh这个脚本在Claude执行Write工具即写入代码前被调用用于自动格式化代码。#!/bin/bash # 文件~/.claude/hooks/format-code.sh # 作用在代码写入前自动格式化 FILE_PATH$1 # Claude会将正在写入的文件路径作为第一个参数传入 LANGUAGE$2 # 第二个参数可能是语言类型 # 根据文件扩展名选择格式化工具 case ${FILE_PATH##*.} in py) black $FILE_PATH 2/dev/null isort $FILE_PATH 2/dev/null ;; js|jsx|ts|tsx) npx prettier --write $FILE_PATH 2/dev/null ;; go) gofmt -w $FILE_PATH 2/dev/null ;; *) # 其他文件类型跳过格式化 ;; esac # 钩子脚本必须以退出码0表示成功 exit 0配置钩子 需要在~/.claude/settings.json中声明{ hooks: { PreToolUse: [ { matcher: Write, // 匹配“写入”工具 hooks: [~/.claude/hooks/format-code.sh] } ], PostToolUse: [ { matcher: Bash, // 匹配“运行Bash命令”工具 hooks: [~/.claude/hooks/log-bash.sh] // 记录所有执行的命令 } ] } }避坑指南脚本权限确保钩子脚本有可执行权限 (chmod x ~/.claude/hooks/*.sh)。执行失败如果钩子脚本执行失败非0退出码Claude Code对应的操作可能会失败。确保你的脚本有良好的错误处理比如2/dev/null忽略格式化工具未找到的错误。性能影响复杂的钩子如启动一个完整的测试套件会显著拖慢操作速度。考虑异步执行或将重型检查放在PostToolUse中。3.5 MCP协议为Claude连接外部世界MCPModel Context Protocol是Anthropic推出的一个开放协议让Claude可以安全、可控地访问外部工具、API和数据库。这是实现“Claude as an AI Agent”的关键。MCP的核心是服务器。你运行一个MCP服务器比如连接GitHub的服务器Claude Code通过标准协议与它通信从而获得查询GitHub Issue、读写文件等能力。项目中的github-mcp.json示例展示了如何配置{ mcpServers: { github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_TOKEN: your_personal_access_token_here } } } }实战步骤获取令牌去GitHub创建一个有适当权限的Personal Access Token。设置环境变量在终端中export GITHUB_TOKENghp_xxx或者更安全地在~/.claude/settings.json的env字段中配置注意令牌安全。添加服务器通过CLI命令claude mcp add github -- npx -y modelcontextprotocol/server-github或者直接编辑settings.json。验证重启Claude Code尝试提问“帮我看看仓库X的最新三个issue是什么”如果配置成功Claude会调用MCP服务器去获取数据。常见问题排查连接失败首先检查GITHUB_TOKEN环境变量是否已设置且有效。在终端运行echo $GITHUB_TOKEN确认。命令未找到确保npx可用。MCP服务器本质上是一个可执行程序command字段必须指向正确的可执行文件路径。权限不足令牌的权限scope是否足够例如读取私有仓库需要repo权限。4. 构建完整工作流从概念到实践掌握了单个模块后真正的威力在于将它们组合起来形成一个闭环的、智能的工作流。项目文档中给出了几个很好的例子我来展开讲讲其中一个“自动化代码审查流水线”。4.1 工作流分解目标当开发者说“请审查我刚写的用户认证模块代码”时自动触发一个高质量的、多维度审查流程。涉及模块Memory(CLAUDE.md)提供项目级的代码审查标准例如“所有密码必须加盐哈希”、“JWT令牌必须有合理的过期时间”。Skill(code-review)定义审查的触发条件当用户提到“审查”且文件是.py时和审查框架。Subagentscode-reviewer.md负责常规代码质量可读性、函数复杂度、重复代码。secure-reviewer.md负责安全检查依赖漏洞、硬编码密钥、注入风险。test-engineer.md负责评估测试覆盖率并提出测试用例建议。Hookspre-review.sh在审查前自动运行banditPython安全扫描和pylint并将结果提供给子代理作为参考。post-review.sh在审查完成后将结构化报告保存为Markdown文件或发送到团队的Slack频道。数据流用户请求审查 ↓ Claude主代理接收加载项目Memory ↓ 触发 code-review Skill ↓ Skill执行 pre-review.sh 钩子收集静态分析结果 ↓ 主代理将任务并行委派给三个子代理 - code-reviewer (分析代码质量) - secure-reviewer (分析安全性) - test-engineer (分析测试) ↓ 各子代理完成分析返回结果给主代理 ↓ 主代理整合所有结果生成综合报告 ↓ Skill执行 post-review.sh 钩子保存或发送报告 ↓ 主代理将最终报告呈现给用户4.2 配置与实现细节1. 技能配置 (SKILL.md):trigger: 当用户输入包含“review”、“审查”、“check”等词且对话上下文涉及代码文件时。 action: 1. 记录待审查的代码片段或文件路径。 2. 执行钩子脚本 scripts/pre-review.sh传入文件路径。 3. 请求主代理协调code-reviewer、secure-reviewer、test-engineer三个子代理进行并行审查。 4. 等待所有子代理返回结果。 5. 执行钩子脚本 scripts/post-review.sh传入整合后的审查结果。 6. 向用户呈现清晰的审查报告。2. 钩子脚本示例 (scripts/pre-review.sh):#!/bin/bash # pre-review.sh TARGET_FILE$1 echo 开始静态分析 /tmp/review_precheck.txt # 安全扫描 if [[ $TARGET_FILE *.py ]]; then bandit -r $(dirname $TARGET_FILE) 2/dev/null | head -20 /tmp/review_precheck.txt echo /tmp/review_precheck.txt fi # 代码质量检查 pylint $TARGET_FILE --exit-zero 2/dev/null | tail -n 20 /tmp/review_precheck.txt echo 静态分析完成结果已缓存。 # 这个结果文件路径可以被Claude或子代理读取3. 子代理协作 主代理在委派任务时需要给出清晰的指令。例如给secure-reviewer的指令可能是“请专注于分析$TARGET_FILE中的安全漏洞特别是认证逻辑、数据验证和依赖安全。这是预检查报告/tmp/review_precheck.txt。”4.3 效果与价值通过这样的组合你将得到一个标准化的审查流程确保每次审查都覆盖所有重要维度。自动化的初步检查利用现有工具linter、安全扫描器提供数据支持。专业化的分析每个领域由“专家”代理深入处理。可追溯的结果审查报告被自动保存便于后续跟踪和团队知识积累。这远远超出了手动输入“/review”命令的范畴它是一个高度定制化、自动化的质量保障流水线。5. 高级特性与性能调优5.1 规划模式与深度思考09-advanced-features/模块里有两个功能对复杂任务至关重要规划模式对于大型重构或新功能开发先让Claude输出一个详细的步骤规划包括文件结构、API变更、数据库迁移、测试策略等。你批准计划后它再开始执行。这避免了它“边想边做”可能导致的混乱。深度思考在Claude Code中按AltTMac是OptionT可以开启“深度思考”模式。在这个模式下Claude的推理链会显示出来你可以看到它是如何一步步分析问题的。这对于调试复杂的逻辑错误或理解Claude的决策过程非常有帮助。使用场景 当你提出一个模糊的请求比如“优化我们应用的加载速度”Claude可能会直接跳到一个具体的解决方案如“启用缓存”。而先开启规划模式它会先问你一系列澄清问题“是前端加载慢还是API响应慢”、“当前瓶颈点有哪些数据”然后制定一个包含多个阶段性能分析、前端优化、后端优化、缓存策略、度量的完整计划。这能确保解决方案的全面性和准确性。5.2 会话管理与后台任务会话管理Claude Code支持会话的/resume恢复、/rename重命名、/fork分支。这对于长期项目非常有用。你可以为“用户认证重构”创建一个会话做一半保存改天/resume继续。或者/fork一个会话来尝试另一种实现方案而不影响原会话。后台任务一些耗时的操作如运行完整的测试套件、生成大型报告可以设置为后台任务。这样Claude可以继续响应你的其他请求等后台任务完成后再通知你。通过CLI的-p打印模式或--background标志可以启用。5.3 权限模式与安全在settings.json中可以配置不同的权限模式控制Claude能做什么default默认模式在执行可能有风险的操作如运行脚本、写入文件前会询问。acceptEdits自动接受所有编辑文件的请求但运行命令前仍会询问。适合专注编码时。plan只做规划不执行任何实际操作。dontAsk危险。自动执行所有操作不询问。仅在高度信任的环境或容器中使用。bypassPermissions绕过所有权限检查仅用于调试或特定脚本。安全建议在个人开发环境中可以使用acceptEdits提高流畅度。但在生产环境或处理重要项目时强烈建议保持default模式并对钩子脚本、MCP服务器的权限进行严格审查。永远不要将含有敏感令牌的settings.json文件提交到公开版本库。6. 常见问题与故障排除实录在实际使用中你肯定会遇到各种问题。以下是我和社区成员遇到过的一些典型情况及其解决方案。6.1 功能不加载或无效症状配置了斜杠命令或技能但在Claude Code中不显示或无法触发。排查步骤检查文件位置和命名这是最常见的问题。斜杠命令必须在.claude/commands/目录下且是.md文件。技能必须在.claude/skills/目录下且包含SKILL.md文件。注意目录是隐藏的。检查Claude Code版本确保你的Claude Code版本与指南兼容2.1。某些新功能可能在旧版本中不可用。在Claude Code中输入/version查看。检查文件语法确保Markdown或YAML frontmatter语法正确没有格式错误。特别是缩进和冒号。重启Claude Code配置文件通常在启动时加载修改后可能需要重启应用。查看日志Claude Code通常有日志输出位置在设置中或~/.claude/logs/。查看日志中是否有加载配置时的错误信息。6.2 MCP服务器连接失败症状配置了GitHub MCP但Claude无法获取仓库信息或提示“无法连接MCP服务器”。排查步骤验证环境变量在终端中执行echo $GITHUB_TOKEN确保已设置且未过期。令牌需要repo等必要权限。测试MCP服务器命令手动在终端运行配置中的命令例如npx -y modelcontextprotocol/server-github看是否能独立运行是否有报错如网络问题、npm包缺失。检查Claude Code的MCP配置在Claude Code设置中找到MCP部分确认服务器已正确列出并启用。网络与代理如果你在公司网络或使用代理可能需要为Claude Code或Node.js配置代理。6.3 子代理不被委派症状定义了子代理但主代理似乎总是自己处理任务从不调用子代理。排查步骤检查代理描述子代理的Markdown文件中的“角色”和“专长”描述是否清晰主代理基于这些描述来判断任务是否匹配。描述越具体、越专业化匹配度越高。检查任务复杂度主代理内置了一个“委派阈值”。对于非常简单的任务如“解释这行代码”它可能认为没必要委派。尝试用更复杂、更专业的任务来测试例如“为这个微服务设计一个容错和重试机制”。手动测试子代理直接在一个新会话中将子代理的指令作为系统提示词发给Claude看它是否能很好地扮演该角色。这可以验证代理指令本身的有效性。查看会话上下文有时主代理的上下文已包含足够信息它觉得可以自己处理。尝试开启一个新会话进行测试。6.4 钩子脚本执行错误症状配置了PreToolUse钩子但文件写入时钩子没执行或执行失败导致操作中止。排查步骤脚本权限chmod x ~/.claude/hooks/your-script.sh。脚本路径在settings.json中钩子路径可以是绝对路径或相对于~/.claude/的路径。确保路径正确。脚本退出码钩子脚本必须以退出码0表示成功。任何非0退出码都会向Claude Code报告为失败。在脚本末尾加exit 0并在内部命令中使用|| true来忽略子命令的错误。脚本输出钩子脚本的stdout和stderr输出可能会被Claude Code捕获并显示。可以在脚本中加echo Hook started来调试。匹配器检查settings.json中的matcher是否正确。Write匹配所有文件写入Bash匹配所有命令执行。6.5 性能问题症状使用多个子代理和钩子后Claude响应变慢。优化建议异步钩子对于耗时的钩子如全量测试考虑让脚本在后台运行并立即返回成功退出码。可以通过在命令末尾加实现但要注意进程管理。按需加载不是所有项目都需要所有技能和子代理。可以考虑通过项目级的.claude/config.json来覆盖全局配置禁用不必要的功能。简化代理如果某个子代理的指令非常冗长可能会增加每次调用的上下文长度。尽量保持指令精炼。规划模式先行对于极其复杂的任务先用规划模式拆解然后分步执行比让Claude一次性调用大量资源更高效。7. 从学习到创造定制你的专属工作流跟着claude-howto走完一遍你最大的收获应该不是那几十个模板文件而是一套方法论如何将一个复杂的AI编码助手工具拆解成记忆、技能、代理、钩子、连接器等可组合的部件并像搭积木一样将它们组装起来解决你自己的实际问题。下一步你可以尝试为你的技术栈定制技能如果官方没有React Native的技能那就自己创建一个。把你们团队的RN最佳实践、常用库、调试命令都写进去。连接内部工具利用MCP为Claude连接你的内部JIRA、Confluence、监控系统。让它能“看到”你的工单、文档和系统状态。构建团队知识库将团队沉淀的Code Review Checklist、部署手册、事故复盘报告结构化地写入项目CLAUDE.md让新成员和Claude都能快速掌握。创造复合插件当你把一整套针对某个场景比如“上线发布”的斜杠命令、技能、子代理、钩子都配置好后可以将它们打包成一个Plugin一键分享给全团队使用。这个项目的价值在于它提供了一个经过验证的、可扩展的框架。它给你的不是鱼而是渔具和钓鱼地图。剩下的就是根据你和你团队的那片“水域”去定制最适合的钓竿和鱼饵了。开始动手从复制第一个斜杠命令到构建第一个自动化流水线那个效率提升的“啊哈时刻”很快就会到来。