Claude Code 最佳实践指南

Claude Code 是一个代理式编码环境agentic coding environment它能自主读取文件、运行命令、修改代码并迭代解决问题。这与传统的聊天式AI不同——你需要从自己写代码让AI审查转变为描述需求让AI实现。以下是经过 Anthropic 内部团队验证的最佳实践一、上下文管理最核心的约束Claude 的上下文窗口会快速填满性能随之下降。这是使用 Claude Code 时最重要的资源。关键策略策略说明/clear在不同任务之间清理上下文避免无关信息堆积/compact 指令手动压缩对话保留关键信息/btw对于不需要保留在上下文中的问题使用答案不会进入对话历史子代理Subagents将调研任务委派给子代理避免主会话上下文被大量文件读取撑满避免厨房水槽会话不要在一个会话中混用多个不相关任务经验法则如果同一个问题纠正了两次以上上下文已被污染建议/clear后用更精确的提示重新开始。二、给 Claude 一个验证机制这是需要全程盯着和可以走开之间的关键区别。策略差示例好示例提供验证标准“实现一个验证邮箱的函数”“写一个validateEmail函数。测试用例userexample.com返回 trueinvalid返回 false。实现后运行测试”视觉验证UI“让仪表板更好看”“[粘贴截图] 实现这个设计。截图对比结果列出差异并修复”解决根本原因“构建失败了”“构建报错[粘贴错误]。修复它并验证构建成功。解决根本原因不要压制错误”验证的四种强度单条提示中要求 Claude 运行检查并在同一条消息中迭代跨会话目标用/goal设定条件Claude 每轮自动检查直到满足确定性关卡Stop Hook脚本自动运行通过后才结束回合第二意见用子代理或动态工作流独立审查结果三、探索 → 计划 → 编码 → 提交不要直接让 Claude 开始编码这可能导致解决错误的问题。推荐四阶段工作流1. 探索Plan Mode按ShiftTab进入 Plan Mode或启动时加claude --permission-mode planClaude 只读文件、回答问题不做任何修改read /src/auth and understand how we handle sessions and login. also look at how we manage environment variables for secrets.2. 计划要求 Claude 创建详细的实现计划按CtrlG在编辑器中直接编辑计划I want to add Google OAuth. What files need to change? Whats the session flow? Create a plan.3. 实现批准计划或按ShiftTab退出 Plan Mode让 Claude 按计划编码并验证implement the OAuth flow from your plan. write tests for the callback handler, run the test suite and fix any failures.4. 提交commit with a descriptive message and open a PR⚠️ 小任务改错别字、加日志、重命名变量可直接跳过计划阶段。四、配置环境1. 编写有效的 CLAUDE.md运行/init生成基础文件然后持续迭代优化。原则保持简洁。对每一行问自己“删掉这句话 Claude 会犯错吗” 如果不会就删掉。✅ 应该包含❌ 不应该包含Claude 猜不到的 Bash 命令Claude 通过读代码就能推断的内容与默认规范不同的代码风格标准语言惯例测试指令和偏好的测试框架详细 API 文档放链接仓库规范分支命名、PR 惯例频繁变化的信息项目特定的架构决策逐文件描述代码库开发环境特殊要求必需环境变量写干净代码这类废话常见陷阱或非直观行为长篇解释或教程调优技巧用强调词如 “IMPORTANT”、“YOU MUST”提高遵守率将 CLAUDE.md 纳入版本控制团队共同维护如果 Claude 反复违反某条规则说明文件太长规则被淹没了2. 配置权限模式适用场景Auto mode信任任务方向但不想逐条确认分类器模型自动拦截高风险操作Permission allowlists用/permissions白名单化安全命令如npm run lint、git commitSandboxing启用操作系统级隔离限制文件系统和网络访问3. 连接 MCP 服务器claude mcpadd--transporthttp notion https://mcp.notion.com/mcp可连接 Notion、Figma、数据库等外部工具让 Claude 能查询 issue、分析监控数据、集成设计稿。4. 使用 HooksHooks 是确定性的与 CLAUDE.md 的建议性指令不同它们保证动作一定执行。示例“每次文件编辑后运行 eslint”“禁止写入 migrations 文件夹”配置在.claude/settings.json中用/hooks浏览已配置的 hooks。5. 创建 Skills在.claude/skills/下创建SKILL.md文件给 Claude 领域知识和可复用工作流。--- name: fix-issue description: Fix a GitHub issue disable-model-invocation: true --- 1. Use gh issue view to get issue details 2. Understand the problem 3. Search codebase for relevant files 4. Implement changes 5. Write and run tests 6. Ensure linting/type checking passes 7. Create descriptive commit and open PR调用方式/fix-issue 1234五、有效沟通1. 提供具体的上下文策略差示例好示例限定范围“给 foo.py 加测试”“给 foo.py 写测试覆盖用户未登录的边界情况。不要用 mock”指向来源“为什么 ExecutionFactory 的 API 这么奇怪”“查看 ExecutionFactory 的 git 历史总结它的 API 是怎么演变成这样的”引用现有模式“加一个日历组件”“查看首页现有组件的实现模式HotDogWidget.php 是个好例子。按这个模式实现日历组件…”描述症状“修复登录 bug”“用户反馈会话超时后登录失败。检查 src/auth/ 的 token 刷新逻辑。先写复现问题的失败测试再修复”2. 让 Claude 面试你大功能对于复杂功能让 Claude 用AskUserQuestion工具采访你I want to build [简述功能]. Interview me in detail using the AskUserQuestion tool. Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Dont ask obvious questions, dig into the hard parts. Keep interviewing until weve covered everything, then write a complete spec to SPEC.md.完成后开启新会话执行这样实现阶段有干净的上下文和明确的需求文档。六、会话管理1. 及时纠偏操作效果Esc停止当前动作保留上下文可重新定向Esc Esc或/rewind打开回滚菜单恢复之前的对话和代码状态Undo that让 Claude 撤销更改/clear重置上下文2. 检查点Checkpoints每次发送提示都会自动创建检查点。可以恢复仅对话仅代码两者都恢复⚠️ 检查点只追踪 Claude 的文件编辑工具所做的更改不追踪 Bash 命令或外部进程的更改。不能替代 git。3. 命名和恢复会话claude--continue# 继续最近会话claude--resume# 从列表中选择用/rename给会话起描述性名称如oauth-migration像分支一样管理。七、自动化与规模化1. 非交互模式# 一次性查询claude-pExplain what this project does# 结构化输出claude-pList all API endpoints--output-format json# 流式输出claude-pAnalyze this log file--output-format stream-json--verbose2. 并行会话方式说明Git Worktrees隔离的 git 检出编辑不会冲突桌面应用可视化管理多个本地会话Claude Code Web云端运行Agent Teams多会话自动协调Writer/Reviewer 模式示例会话 A实现会话 B审查实现 API 限流器审查 src/middleware/rateLimiter.ts检查边界情况、竞态条件根据审查反馈修复问题3. 批量处理forfilein$(catfiles.txt);doclaude-pMigrate$filefrom React to Vue. Return OK or FAIL.\--allowedToolsEdit,Bash(git commit *)done先用 2-3 个文件测试提示再规模化运行。八、常见失败模式问题症状解决方案厨房水槽会话一个任务中混了多个不相关问题/clear分隔任务反复纠正纠正两次仍不对/clear后用更好的初始提示重新开始过度指定的 CLAUDE.md文件太长Claude 忽略一半规则无情删减只保留 Claude 会犯错时才需要的规则信任-验证缺口看起来合理的实现不处理边界情况始终提供验证机制测试、脚本、截图无限探索让 Claude 调查某事未限定范围缩小范围或用子代理九、快速参考核心命令命令用途/init生成 CLAUDE.md 模板/context确认 Claude 加载了哪些文件/clear重置上下文/compact 指令压缩对话保留关键信息/btw临时提问不进入历史/rewind回滚到检查点/goal设定跨会话目标/hooks浏览已配置的 hooks/permissions管理权限白名单/skill-name调用自定义 skillclaude -p ...非交互模式claude --permission-mode auto自动权限模式核心原则总结把 Claude 当作一个手速极快、能深度访问仓库的初中级工程师。给它清晰的目标、验证机制、必要的上下文然后放手让它工作。上下文窗口是你最宝贵的资源——保护好它。