当前位置： 首页 > news >正文

Claude Code 最佳实践指南

news 2026/5/24 18:37:18

Claude Code 最佳实践指南

来源：https://github.com/shanraisshan/claude-code-best-practice
更新时间：2026年3月29日

仓库概述

这是一个关于 Claude Code 最佳实践的集合，包含了使用 Claude Code 进行 AI 编程的核心概念、技巧、工作流程和实用建议。仓库由社区维护，整合了 Claude Code 团队的经验分享。

仓库价值

  • ⭐ 120k+ Stars
  • 包含详细的最佳实践文档
  • 丰富的示例和工作流
  • 覆盖从基础到高级的所有主题

核心功能与概念

功能位置描述
Subagents.claude/agents/独立的 AI 角色，具有自定义工具、权限、模型、内存和持久身份
Commands.claude/commands/用户调用的提示模板，用于工作流编排
Skills.claude/skills/可配置、可预加载、可自动发现的知识模块，支持渐进式披露和上下文分叉
Workflows-工作流编排模式：研究 → 计划 → 执行 → 审查 → 发布
Hooks.claude/hooks/特定事件触发的用户定义处理器（脚本、HTTP、提示词、代理）
MCP Servers.mcp.json连接外部工具、数据库和 API 的模型上下文协议
Pluginsdistributable可分发包，包含技能、子代理、钩子、MCP 服务器和 LSP 服务器
Settings.claude/settings.json分层配置系统：权限、模型配置、输出样式、沙箱、快捷键
MemoryCLAUDE.md通过文件和 @path 导入实现持久化上下文
Checkpointing自动（基于 git）自动跟踪文件编辑，支持回滚（Esc Esc 或 /rewind）和针对性摘要

关键最佳实践

提示词技巧

✅ 推荐做法

  • 挑战 Claude：要求"审查这些变更，直到通过测试再提交 PR"
  • 优雅修复：在修复后说"基于所有已知信息，废弃这个实现，采用优雅的解决方案"
  • 避免微管理：Claude 能自动修复大部分 Bug，只需描述问题，不要指定具体修复方式
  • 使用 ultraslim 关键字：触发高努力推理模式

避免做法

  • 不要过度指示 Claude 的每一步操作
  • 不要手动修复 Claude 自动能解决的问题

️ 规划与规格

✅ 核心原则

  • 始终使用 Plan Mode：以计划模式开始，使用 /model 选择模型
  • 分阶段计划：每个阶段包含多个测试（单元测试、自动化测试、集成测试）
  • 详细规格：写详细的规格文档并减少歧义，越具体输出越好
  • 原型优于 PRD：构建 20-30 个原型而不是写规格文档，构建成本低，多尝试

交叉审查

  • 启动第二个 Claude 作为高级工程师审查计划
  • 使用跨模型工作流进行审查
  • 让 Claude 使用 AskUserQuestion 工具来采访你，然后创建新会话执行规格

CLAUDE.md 文档

✅ 推荐做法

  • 控制在 200 行以内：每个文件不超过 200 行（理想情况 60 行）
  • 使用标签包裹：用 <specific-rules> 标签包裹特定规则，防止文件增长时被忽略
  • Monorepo 使用多个文件：使用祖先+后代加载模式
  • 分割大型指令：使用 .claude/rules/ 目录分割大型指令
  • 快速上手：任何开发者都应该能够启动 Claude，说"运行测试"并首次成功

文档结构

.claude/
├── rules/              # 分割大型指令
├── memory.md           # 不保证任何内容
├── constitution.md     # 不保证任何内容
└── settings.json       # 强制行为配置（归属、权限、模型）

Agents & Skills

Subagents 最佳实践

  • 功能特定化：使用功能特定的子代理（带有额外上下文），而不是通用的 QA 或后端工程师
  • 说"use subagents"：向问题投入更多计算，卸载任务以保持主上下文清洁和专注
  • 代理团队：使用 tmux 代理团队和 git worktrees 进行并行开发
  • 测试时间计算：分离上下文窗口使结果更好；一个代理可能引起 Bug，另一个代理可以发现

Skills 最佳实践

  • 命令优先：对于工作流使用命令而不是子代理
  • 每日工作流：将每天多次重复的"内部循环"工作流转换为斜杠命令
  • 技能化：如果每天做某事不止一次，将其转换为技能或命令
  • 技能子目录：对于 monorepos，使用技能的子文件夹
  • 渐进式披露：技能是文件夹，不是文件 — 使用 references/、scripts/、examples/ 子目录
  • Gotchas 部分：在每个技能中构建 Gotchas 部分 — 最高信号内容，随时间添加 Claude 的失败点
  • 描述字段：技能描述字段是触发器，不是摘要 — 为模型编写（"什么时候应该触发？"）
  • 避免显而易见：不要在技能中陈述显而易见的内容 — 专注于推动 Claude 超出其默认行为
  • 不强制指导：不要在技能中强制指导 Claude — 给出目标和约束，而不是规定性的分步指令
  • 脚本和库：在技能中包含脚本和库，让 Claude 组合而不是重建样板代码

Git & PR

✅ 推荐做法

  • 保持 PR 小而专注：中位数 118 行（141 个 PR，45K 行变更），每个 PR 一个功能，更容易审查和回退
  • 始终 squash merge：干净的线性历史，每个功能一个提交，容易 git revert 和 git bisect
  • 频繁提交：至少每小时提交一次，任务完成后立即提交
  • 使用 @claude 标签：在同事的 PR 上标签 @claude 自动生成重复审查反馈的 lint 规则
  • 使用 /code-review：用于多代理 PR 分析 — 在合并前捕获 Bug、安全漏洞和回归

调试技巧

✅ 推荐做法

  • 截屏分享：遇到问题时总是截屏并分享给 Claude
  • 使用 MCP：使用 Claude in Chrome、Playwright、Chrome DevTools MCP 让 Claude 自动查看浏览器控制台日志
  • 后台任务运行：总是让 Claude 作为后台任务运行终端命令（你想查看日志的）
  • 使用 /doctor：诊断安装、认证和配置问题
  • 压缩错误修复：压缩期间的错误可以通过使用 /model 选择 1M token 模型，然后运行 /compact 来解决
  • 交叉模型 QA：使用跨模型工作流进行 QA — 例如 Codex 用于计划和实现审查
  • 代理搜索优于 RAG：glob + grep 比 RAG 更好 — Claude Code 尝试并放弃了向量数据库，因为代码会不同步且权限复杂

️ 实用工具

工具用途
iTerm/Ghostty/tmux终端替代 IDE（VS Code/Cursor）
Wispr Flow语音提示（10 倍生产力）
claude-code-hooksClaude 反馈钩子
status line上下文感知和快速压缩
Settings.json 功能Plans Directory、Spinner Verbs 等，用于个性化体验

⚙️ 工作流最佳实践

基础工作流

  • 避免代理愚蠢区：进行手动 /compact，最多 50%
  • Vanilla CC 更好：对于较小任务，vanilla Claude Code 比任何工作流都好
  • 使用交互模式命令：
    • /model - 选择模型和推理
    • /context - 查看上下文使用
    • /usage - 检查计划限制
    • /extra-usage - 配置溢出计费
    • /config - 配置设置
  • 最佳模型组合：使用 Opus 进行计划模式，使用 Sonnet 进行代码，获得最佳效果
  • 始终使用思考模式：设置 thinking mode: true（查看推理）和 Output Style: Explanatory（查看带有 ★ Insight 框的详细输出）
  • 重命名和恢复：使用 /rename 重命名重要会话（例如 [TODO - 重构任务]），稍后使用 /resume 恢复
  • 回滚而不是修复：使用 Esc Esc 或 /rewind 撤销，当 Claude 走偏时，而不是在相同上下文中尝试修复

高级工作流

  • ASCII 图表：大量使用 ASCII 图表来理解架构
  • 定期任务：使用 /loop 进行本地定期监控（最多 3 天）；使用 /schedule 进行基于云的定期任务（即使机器关闭也会运行）
  • Ralph Wiggum 插件：用于长期自主任务的 Ralph Wiggum 插件
  • 权限通配符：使用 /permissions 配置通配符语法（Bash(npm run *)、Edit(/docs/**)）而不是 dangerously-skip-permissions
  • 沙箱：使用 /sandbox 通过文件和网络隔离减少权限提示 — 内部减少 84%
  • 产品验证技能：投资产品验证技能（signup-flow-driver、checkout-verifier）— 值得花费一周时间完善

日常习惯

  • 每日更新：每天更新 Claude Code 并通过阅读 CHANGELOG.md 开始新的一天
  • 关注社区：关注 r/ClaudeAI、r/ClaudeCode
  • 关注关键人物：Boris Cherny、Thariq、Cat Wu、Lydia Hallie、Noah、Anthony、Alex、Kenneth、Claude

Claude Code 替代的工具

Claude Code 功能替代工具
Code ReviewGreptile, CodeRabbit, Devin Review, OpenDiff, Cursor BugBot
Voice DictationWispr Flow, SuperWhisper
Remote ControlOpenClaw
CoworkOpenAI Operator, AgentShadow
TasksBeads
Plan ModeAgent OS
Skills / PluginsYC AI wrapper startups

学习资源

关键人物（Twitter）

  • Boris Cherny (@bcherny) - Claude Code 创始人
  • Thariq (@trq212)
  • Cat Wu (@_catwu)
  • Lydia (@lydiahallie)
  • Noah (@noahzweben)
  • Anthony (@amorriscode)
  • Alex (@alexalbert__)
  • Kenneth (@neilhtennek)
  • Claude (@claudeai)

社区

  • r/ClaudeAI: https://www.reddit.com/r/ClaudeAI/
  • r/ClaudeCode: https://www.reddit.com/r/ClaudeCode/

视频和播客

  1. Building Claude Code with Boris Cherny | 2026年3月4日 | The Pragmatic Engineer
  2. Head of Claude Code: What happens after coding is solved | 2026年2月19日 | Lenny's Podcast
  3. Inside Claude Code With Its Creator Boris Cherny | 2026年2月17日 | Y Combinator
  4. The Secrets of Claude Code From the Engineers Who Built It | 2025年10月29日 | Every

相关仓库

仓库Stars主要功能
Superpowers120kwriting-plans skill
Everything Claude Code114kplanner agent
Spec Kit83kspeckit.plan command
gstack54kautoplan skill
Get Shit Done44kgsd-planner agent
BMAD-METHOD43kbmad-create-prd skill
OpenSpec35kopsx:propose command
Compound Engineering11kce-plan skill
HumanLayer10kcreate_plan command

如何使用这个仓库

  1. 像课程一样阅读仓库：在学习如何使用之前，先了解命令、代理、技能和钩子是什么
  2. 克隆并试验：克隆仓库并试验示例，尝试 /weather-orchestrator，监听钩子声音，运行代理团队，看看它们实际如何工作
  3. 应用到你的项目：让 Claude 建议从该仓库中添加哪些最佳实践，将此仓库作为参考，以便它知道可能性

❓ 未解决的问题

内存与指令（4个）

  • 应该在 CLAUDE.md 中放什么 — 以及应该省略什么？
  • 如果你已经有 CLAUDE.md，单独的 constitution.md 或 rules.md 是否真的需要？
  • 你应该多久更新一次 CLAUDE.md，以及如何知道它已经过时？
  • 为什么 Claude 仍然忽略 CLAUDE.md 指令 — 即使它们全大写写着 MUST？

代理、技能和工作流（6个）

  • 什么时候应该使用命令 vs 代理 vs 技能 — 什么时候 vanilla Claude Code 更好？
  • 随着模型的改进，你应该多久更新一次代理、命令和工作流？
  • 给子代理详细的角色设定会提高质量吗？研究/QA 子代理的"完美角色设定/提示词"是什么样的？
  • 你应该依赖 Claude Code 的内置计划模式 — 还是构建自己的计划命令/代理来强制执行团队的工作流？
  • 如果你有一个个人技能（例如 /implement 使用你的编码风格），如何在不冲突的情况下整合社区技能（例如 /simplify）— 当它们不同意时谁赢？
  • 我们到了吗？我们能将现有代码库转换为规格，删除代码，并让 AI 仅从那些规格重新生成完全相同的代码吗？

规格与文档（3个）

  • 仓库中的每个功能都应该有规格文档吗？
  • 你需要多久更新一次规格，以便在新功能实现时它们不会过时？
  • 实现新功能时，如何处理对其他功能规格的连锁反应？

相关链接

  • GitHub 仓库: https://github.com/shanraisshan/claude-code-best-practice
  • Claude Code 官方文档: https://code.claude.com/docs
  • Claude Code GitHub: https://github.com/anthropics/claude-code
  • 官方技能: https://github.com/anthropics/skills/tree/main/skills

本文档由 yumingwen 整理。

http://www.jsqmd.com/news/555009/

相关文章：

  • Phi-4-Reasoning-Vision实操手册：图文输入边界检测与异常上传拦截机制
  • 香橙派AIPro的“假死”风波：一次拨码开关引发的虚惊
  • 革新性Git文本界面：Tig如何重塑开发者工作流
  • Python词云终极指南：轻松处理多语言字符编码
  • Nunchaku-FLUX.1-dev镜像安全加固：非root运行/最小权限/网络策略限制
  • 从固定到自适应：手把手教你改进Savitzky-Golay滤波器，告别边界效应和参数调优烦恼
  • 基于Python+OpenCV的实时人脸检测系统
  • Fugu14越狱工具：从技术原理到实战部署的完整指南
  • 【AI】网络环境检测
  • 终极指南：如何在kafka-go中实现Exactly-Once消息投递语义
  • 北京高端腕表检测费用解析：鉴真科学与六大城市联保价值体系 - 时光修表匠
  • 终极翻译解决方案：sd-webui-prompt-all-in-one支持20+翻译API全解析
  • 如何高效使用loadable-components：从基础API到高级应用的完整指南
  • 从仿真到AI数据集：一条龙搞定COMSOL+MATLAB+Python数据处理流水线
  • 测试架构设计：从策略到实现
  • yfinance实战指南：解决金融数据获取难题的5个高效方案
  • 书匠策AI：课程论文创作的“智能导航仪”，解锁学术新境界！
  • 说说西安专业靠谱的婚纱摄影企业，西安青木社婚纱摄影推荐吗？ - 工业品网
  • 黑丝空姐-造相Z-Turbo在互联网产品中的应用：用户头像与表情包生成
  • 罗湖比亚迪4S店正规公司口碑如何，价格贵不贵，选哪家？ - myqiye
  • 别再手动调参了！用TPE算法自动搜索超参数，效率提升10倍（附Python代码）
  • 从河南农村到泰国拳台：张家乐在Bangla Boxing Stadium加冕泰拳冠军的荣耀
  • 保姆级教程：在Linux上从零部署Hive 3.1.3并配置MySQL元数据（含中文乱码解决方案）
  • Cuid2深度解析：10个核心特性揭秘
  • Token 中文定名词元，国产 AI 工具如何抢占词元红利？
  • class-transformer在机器人技术中的终极应用指南：如何高效处理机器人数据
  • 2026年口碑好的高新技术企业认定机构推荐，华傲知识产权实力上榜 - 工业品牌热点
  • Kronos创新应用实战指南：从技术原理到跨行业落地
  • 基于自抗扰控制的非奇异终端滑模控制在PMSM中的应用探索
  • 告别‘无法初始化此工作流’：手把手调试OSWorkflow 2.8.0示例的用户权限与内存存储