Appearance
Claude Code最佳实践：15K星的8条核心经验
上下文窗口填满后性能会崩，所有最佳实践都围绕这个约束展开。
仓库简介
GitHub仓库：shanraisshan/claude-code-best-practice
15K⭐，作者写了句狠话：practice made claude perfect。
这不是理论教程，是参考实现——用真实可跑的代码展示Claude Code的Commands、Agents、Skills、Hooks怎么组合使用。
01 核心架构：Command → Agent → Skill
用一个天气查询实例完整演示三层架构：
| 层级 | 职责 | 说明 |
|---|---|---|
| Command | 用户入口 | 收集参数，编排流程 |
| Agent | 执行工作 | 独立上下文，有自己的工具和权限 |
| Skill | 领域知识 | 按需加载，不占用上下文窗口 |
实例流程
用户输入 /weather-orchestrator
↓
Command 问你要摄氏度还是华氏度
↓
调用 weather-agent
↓
Agent 预加载 weather-fetcher Skill 查温度
↓
调用 weather-svg-creator Skill 生成SVG天气卡片精髓：渐进式披露（Progressive Disclosure）——Skill内容只有被Agent调用时才进入上下文窗口，平时只加载一行描述。
这对省Token至关重要。
02 CLAUDE.md：写好这个文件比什么都重要
社区案例：有人用500词的CLAUDE.md，把一个500MB的坏项目修到只剩30KB的干净代码。
关键原则
| 原则 | 说明 |
|---|---|
| 控制长度 | 单个CLAUDE.md控制在200行以内，60行更理想。太长了Claude会有选择地忽略 |
| Monorepo分层 | 多个CLAUDE.md分层加载，不要硬塞在一个文件里 |
| 写规则不写感受 | 用具体的、可执行的指令，而不是抽象的"必须"。MUST加全大写也不能保证Claude一定听 |
| 别把memory.md当救命稻草 | memory.md、constitution.md都不能保证任何事情。真正管用的是结构化的CLAUDE.md + 分层加载 |
03 Sub-Agent：别让主会话胀死
Claude Code的上下文窗口是有限的，填满后性能明显下降。
解法
用Sub-Agent把耗上下文的任务卸载出去。
案例：做代码审查时，不要在主会话里摆开十几个文件慢慢看。创建一个专门的code-reviewer Agent：
- 给它限定工具权限
- 指定模型
- 预加载相关Skill
- 在独立上下文里完成任务
- 把结果返回主会话
用法：在prompt里说use subagents就能让Claude自动拆分任务给子智能体。
Agent配置关键字段
| 字段 | 说明 |
|---|---|
| tools | 工具白名单 |
| model | haiku/sonnet/opus |
| skills | 预加载技能 |
| memory | 持久化记忆 |
| maxTurns | 最大循环次数 |
04 上下文管理：大多数人踩的坑
Claude Code的几乎所有最佳实践，都围绕一个约束：上下文窗口填满得很快，填满后性能会崩。
具体做法
| 技巧 | 说明 |
|---|---|
| 避免"笨区" | 上下文用到50%时手动/compact，不要等系统自动压缩 |
| 切换任务用/clear | 重置上下文 |
| MCP别贪多 | 如果MCP占了超过20K Token，实际能用于工作的上下文就所剩无几。精简配置，只挂真正需要的服务 |
| 小任务用原生 | vanilla CC在小任务上比任何复杂工作流都好用。别为了用工具而用工具 |
05 先规划再动手
社区里多个独立来源得出同一结论：生产级项目里，规划先行是不可协商的。
推荐流程
进入Plan模式 → 给Claude高层描述和现有代码指引
↓
Claude研究并提出方案
↓
你审查方案，不满意说哪里不对让它改
↓
在计划阶段捕捉误解，比写完代码再返工便宜太多实用技巧
用不同模型做规划和审查：Opus做方案，Sonnet挑刺。
跨模型QA能发现很多单模型发现不了的问题。
06 Hooks：让质量检查自动跑
这个repo有一套Hook系统——包括音效通知。
Claude提交代码时播放声音，子智能体启动/停止时也有音效。你可以不盯屏幕就知道Claude在干什么。
更实用：自动质量检查Hook
配置一个Stop Hook：Claude每次完成响应后，自动跑构建、检查TypeScript错误。
| 错误数量 | 动作 |
|---|---|
| 少于5个 | 直接让Claude修 |
| 超过5个 | 建议启动专门的error-resolver Agent |
坑
自动格式化Hook可能消耗大量Token。有人报告3轮就吃掉160K Token。
建议：把格式化放在会话间隙手动跑，不要每次自动触发。
07 散但很管用的技巧
| 技巧 | 说明 |
|---|---|
| 挑战Claude | 别只会说fix。试试"烤问我这些改动，不通过别提PR"，或"抛弃现有方案，重新实现一个优雅的解法" |
| 勤提交 | 每完成一个步骤就commit。出问题随时revert，不用从头再来 |
| 开思考模式 | 始终开启thinking mode，配合Explanatory输出风格，能看到推理过程。遇到难题用ultrathink触发深度推理 |
| 别堆自定义命令 | 如果你有一长串复杂的自定义slash command，你就创建了一个反模式。Claude Code的精髓是用自然语言就能得到结果 |
08 三步上手
| 步骤 | 动作 |
|---|---|
| 1 | 把这个repo当课程读。搞清Command、Agent、Skill、Hook各是什么 |
| 2 | Clone下来实际操作。跑一遍/weather-orchestrator，听听Hook音效，跑跑Agent团队 |
| 3 | 回到自己项目，让Claude建议哪些最佳实践适合你。把这个repo作为参考传给Claude |
结语
Claude Code的学习曲线比大多数人想象的陡。
它不是聊天机器人，是智能体编程环境——你描述想要什么，Claude来研究、规划、实现。
前提是：你得学会给它正确的上下文、合理的约束、清晰的任务边界。
practice made claude perfect —— perfect practice made you更有的放矢。
工具在那里，能用到什么程度，纯看你愿意花多少功夫去理解它。
关键词：Claude Code, 最佳实践, Sub-Agent, CLAUDE.md, Hooks, 上下文管理
