Claude Code 最佳实践：上下文、权限、工作流与团队协作的实战经验

更新日期：2026-09-27

工具装好只是起点。同样的 Claude Code，有人用它改一行代码，有人能用它完成跨文件重构、自动排查线上问题、甚至接管半个 CI 流程——差距不在模型，在于是否掌握了一套把 AI 能力转化为工程产出的工作方法。

本篇把社区与官方反复验证过的实践整理为可执行的清单：上下文管理、CLAUDE.md 的写法、权限边界、从探索到提交的任务工作流、多 Agent 协作，以及团队层面的规范沉淀。安装与基础配置见我们的 Claude Code 安装指南，自定义扩展见 Skills 实战一文。

一、上下文卫生：单一最重要的习惯

Claude Code 的回答质量与上下文里"有什么"直接相关，而上下文是有限且会被污染的。三条核心实践：

一个任务一个会话。 切换任务时用 /clear 清空上下文，而不是在一个长会话里连续处理不相关的问题。上下文里堆积的无关文件内容、失败尝试和半截结论，是"越聊越笨"的第一原因。

用 /resume 恢复而不是重讲。 中断的长任务用 /resume 找回现场，比在新会话里重新解释背景质量更高——历史会话里保存着你验证过的路径和结论。

给足指向，而不是给足文本。 让它"看 src/auth/ 目录的登录实现"比粘贴十个文件更高效：模型自己读代码能保持结构感知，粘贴文本反而丢失位置信息。大仓库里先让它探索再动手，效果远好于直接下指令。

二、CLAUDE.md：写给 AI 的项目说明书

/init 生成初稿后，一份值得维护的 CLAUDE.md 通常只有几十行，集中四类信息：

# 项目速览
- 构建：pnpm build；测试：pnpm test（单测在 tests/）
- 技术栈：Next.js 16 App Router + Drizzle + PostgreSQL
- 目录约定：app/ 路由、lib/ 共享逻辑、scripts/ops/ 运维脚本

# 规范
- 提交信息用 conventional commits（feat:/fix:/docs:）
- 数据库变更必须走 drizzle 迁移，禁止手写 ALTER
- 不要修改 lib/generated/ 下的自动生成文件

# 禁区
- 生产数据库只读，写操作需 DBA 确认
- 不引入新的重型依赖，先在 issue 里讨论

反模式也很明确：把 CLAUDE.md 写成长篇架构论文、塞满模型已经知道的通用知识（"写清晰的代码"、"注意安全"）、或者当成变更日志用。它常驻每次会话的上下文，每一个字都有成本——只放"模型不知道、且每次都需要"的信息。流程类知识该拆到 Skills（见我们的 Skills 实战一文），临时说明用对话直接讲。

三、权限与安全：默认确认不是障碍，是护栏

Claude Code 默认对文件写入和命令执行要求确认，这个设计的价值在习惯之后才会显现：

维护一份允许清单而不是全盘放开。 把高频只读命令（git status、ls、测试命令）加入 allowlist，保持写操作与破坏性命令的确认。全盘 --dangerously-skip-permissions 只应用于一次性沙箱环境，日常开发与生产服务器都不要用。

探索时只读，执行时确认。 让它先做只读的调查（读代码、查日志、跑测试），给出方案后再授权执行。这个节奏能避免"一句话下去它把五个文件都改了"的事故。

生产环境用专用低权限身份。 服务器上运行 Claude Code 的账号应只开放它需要的目录与命令；配合 hooks 可以硬性拦截特定命令模式。完整的权限隔离、审计与回滚框架见我们的 AI Agent 服务器运维一文。

四、任务工作流：探索、计划、执行、验证

对超出"改一个函数"规模的任务，社区沉淀最有效的是四步节奏：

1. 探索（只读）。 让它先读相关代码、理解现状，输出它对问题的理解。这一步的关键指令是"先不要改任何代码"。你在这个阶段纠正理解偏差的成本几乎为零。

2. 计划（对照）。 让它提出实施方案：改哪些文件、分几步、有什么风险。用 plan 模式（只读规划）或直接口头约定"先给方案再动手"。方案里挑刺，比在代码写完之后挑刺便宜十倍。

3. 执行（小步）。 授权它按计划实施，但要求小步提交：每完成一个可验证的步骤跑一次测试、做一次 commit。大爆炸式的"一次性改完二十个文件"是质量事故的重灾区。

4. 验证（跑真的测试）。 验收标准是"测试通过、构建通过、你在真实界面看过效果"，而不是"它说改完了"。语言模型的自我报告不是验证，跑通的测试和构建才是。

这个节奏对修复类任务同样适用：我们的 503 排障一文给出的分层排查流程，本质上就是这个工作流在事故场景的特化。

五、让它自我验证：给 AI 一条反馈回路

单发指令的效果远差于带反馈回路的指令。实践上有三个层次：

跑测试反馈。 "修改后运行 pnpm test，失败则继续修复直到通过"——这是最简单也最有效的回路，模型会自己迭代。

跑真实环境反馈。 前端任务让它启动 dev server 并用浏览器工具截图自查；API 任务让它 curl 自己的接口验证响应结构。Claude Code 支持接入浏览器自动化能力，视觉确认比日志确认更接近真实。

让另一个 Claude 审查。 重构类任务可以开两个会话：一个执行，另一个只读审查（"审查这个 diff 的安全与边界问题"）。自己审自己会遗漏系统性盲点，这是多 Agent 协作里收益最确定的一种。

六、复杂任务的表达：给出锚点而非诗意描述

指令质量的差异直接反映在产出上。几条被反复验证的表达原则：

• 给文件与符号名做锚点："重构 lib/hicyou/sync.ts 的 upsertOne"远好于"优化同步逻辑"；
• 给验收标准："确保 npm test 全绿，且产物体积不增加超过 5%"；
• 给参照物："按照 scripts/ops/upsert-ops-blog-series 这个脚本的既有模式写一个新脚本"；
• 分阶段下指令：长任务拆成有序列的步骤，每步可验证，比一次性描述整个项目有效；
• 纠正时说原因："不要用 var，项目规范是 const"比"改一下"更能防止再犯——并且这类纠正应该沉淀进 CLAUDE.md。

七、会话内的高频命令速查

/compact 值得单独解释：它把当前会话历史压缩成摘要，保留关键结论、释放 token 空间。长会话里回答质量下降、响应变慢时，先 /compact 再继续，通常立刻恢复。

八、团队层面：把个人经验变成组织资产

CLAUDE.md 进仓库、走 review。 它是团队规范的一部分，变更应与代码同等对待。

Skill 化高频流程。 发布检查、事故排查、迁移审查这些多步骤流程写成项目级 Skills（模板见 Skills 实战一文），新成员与 AI 都按同一套流程干活。

共享提示词库。 团队内效果好的指令模式（比如"先只读探索再动手"的标准开场白）沉淀到内部文档，配合 CLAUDE.md 让所有人默认获得。

度量与复盘。 关注 AI 辅助产出的返工率：如果某类任务 AI 提交后总是被人工大改，说明该类任务缺 CLAUDE.md 约束或 Skill 指引，优先补文档而不是怪模型。

九、重构任务专场：让大改动安全的清单

重构是 AI 编程工具收益最大也最危险的场景，一套被验证过的安全流程：

1. 先写特征测试（characterization test）：在重构前锁定现有行为——不追求优雅，只求覆盖当前的真实输出。它既是安全网，也是"重构没有改变行为"的证据；
2. 让它分步提交：明确要求"每完成一个独立步骤就 commit"，回滚粒度从"整个重构"细化到"单一步骤"；
3. 禁止顺手改行为：指令里写明"只改结构不改行为，发现疑似 bug 先报告不要修"，防止重构与修复混在同一个 diff 里无法审；
4. 大迁移拆阶段：框架升级、API 替换类任务按"引入兼容层→逐步替换→删除旧路径"三段走，每段独立可验证可回滚；
5. 终局人工审 diff：AI 可以完成机械劳动，方向与取舍的最终审查留给人类——重点看边界条件、错误处理与那些"测试没覆盖到的角落"。

十、调试与事故场景的用法

线上排障是另一个高价值场景，用法有讲究：把原始证据直接喂给它——完整的报错堆栈、相关日志片段、变更时间线，而不是你的转述和猜测；让它按"先列假设、再排优先级、给出每条的验证命令"的结构化方式推进，而不是放开手脚乱试；只读验证直接执行，写操作先出方案——这条边界在事故压力下尤其重要，慌乱中的自动化操作是二次事故的温床。分层排查的决策树可以直接固化成 Skill（参考我们的 503 排障一文），让每次事故都按团队沉淀过的路径走。

十一、写测试与 TDD 顺序

对正确性敏感的逻辑，把顺序反过来——先让它写测试，再让它写实现——收益巨大：测试先行的实现代码往往接口更干净；你审查测试用例的成本远低于审查实现细节；实现阶段的每次迭代都有即时反馈回路。指令模式："为 X 模块设计测试用例清单（覆盖正常路径、边界与异常），先给我看清单不要写代码"→ 确认清单 →"生成测试文件（此时应该全部失败）"→"实现代码直到全部测试通过"。这个流程把 AI 最容易失控的自由发挥阶段，约束在了你审过的规格之内。

十二、了解模型的局限：三条边界与对策

幻觉 API：模型会自信地写出不存在的方法名或参数。对策是让它先读相关源码或文档再写调用，配合类型检查器作为客观裁判——TypeScript 项目的编译通过率就是幻觉的照妖镜。

知识截止与版本漂移：训练数据有时滞，新版本框架的 API 可能被写成旧版用法。对策是在指令里附上当前版本的官方文档片段，或让它先看项目 lockfile 确认版本。

长上下文的遗忘与稀释：会话足够长后，早期给出的关键约束会被稀释。对策是关键约束进 CLAUDE.md（常驻），阶段结论让它复述确认，超长任务主动 /compact 或拆会话。

理解这三条边界后会发现：几乎所有"AI 写的代码有坑"的案例，都能映射到其中一条——而每一条都有工程化的对策，前提是你知道边界在哪。

十三、与 IDE 的配合

官方 VS Code 扩展让终端 Agent 与图形编辑器各展所长：扩展里 diff 以编辑器视图展示，接受与拒绝在界面完成；它会感知当前打开的文件与选中范围，减少"描述位置"的成本；JetBrains 系有对应插件。CLI 会话仍是能力核心——扩展是增强而不是替代，"终端里跑 Agent、编辑器里看 diff"是最常见的组合姿势。

十四、让文档成为副产品

AI 编程会话天然产生大量"理解"，不加利用就随会话消失。几个把理解沉淀为资产的姿势：任务收尾时让它顺带更新 README 或变更日志（"本次改动涉及的配置项和使用方式更新到 docs/usage.md"）；架构调整后让它起草一份 ADR（架构决策记录），把"为什么这么做"固化下来——你只需要审阅和修订；接手陌生模块的探索会话结束时，让它**输出一份"模块现状笔记"**存进仓库。这些产出的边际成本极低（都是会话里已有信息的整理），却直接提升团队下一个新人（以及下一次会话）的起点。

十五、安全审查场景的用法

AI 也是安全审查的好帮手，两个高价值场景：依赖变更审查——升级依赖后让它读 changelog 与 diff，列出"行为变化、废弃 API、安全修复"三类要点，把几十页 release notes 压缩成你能决策的摘要；diff 自查——提交前让它按固定清单（硬编码凭据、SQL 拼接、路径穿越、错误处理缺失、越权访问）扫一遍变更，模式化的安全检查它做得比人稳定。注意边界：AI 审查是"扩大覆盖面"的手段，不能替代针对业务逻辑的安全评审，高危变更的最终判断仍需要懂这个系统的人签字。

十六、什么时候不该用 AI

诚实地说，有些场景硬用 AI 反而更慢：需求完全不明确时，先和人聊清楚，AI 无法替你定义问题；纯探索式学习——自己读文档、写 demo 踩坑建立的心智模型，是"要它给答案"换不来的长期能力；高度合规或安全敏感的最终产出——AI 可以起草和检查，签字前的最后一公里必须是人。还有一类隐性成本要警惕：把所有小到不用思考的事都交给 AI，你的核心能力会钝化。合理的姿势是把它当成放大器——放大的应该是有方向的思考，而不是替代思考本身。

十七、上手一周的练习路径

给刚装好的你一份渐进练习计划：第 1 天，在一个小项目里熟悉会话节奏，练习 /clear 与 /resume，完成三个独立小任务，每个任务一个会话；第 2 天，跑一次 /init，亲手修订 CLAUDE.md，观察约束前后它的行为差异；第 3 天，刻意练习"探索-计划-执行-验证"四步，找一个你熟悉的重构任务走完全程；第 4 天，给它一个带测试的 bug，观察它如何定位，学会在它的方案里挑毛病；第 5 天，尝试把一次排障或发布检查沉淀成第一个 Skill；第 6 天，接入 MCP 或让它调用一个外部系统，体会工具扩展的边界；第 7 天，复盘一周的会话，把反复出现的指令模式写进 CLAUDE.md。一周后你对"AI 编程到底能干嘛"的理解，会比读十篇教程扎实。

十八、多 Agent 协作：分工与制衡

单会话之外，多会话/多 Agent 的组合拳在复杂任务上收益明显，两种被验证过的分工模式：

执行与审查分离：会话 A 执行任务，会话 B 拿到 diff 做只读审查（提示词要点：明确审查维度——正确性、安全、边界条件、与既有规范的一致性；要求输出"问题清单+严重程度"而不是泛泛评价）。同一模型自己审自己会有系统性盲点，但换个上下文、换个视角的提问方式，命中率依然显著高于不审。

驱动者与执行者分离：一个会话负责任务拆解与验收（review 每步产出、决定下一步），另一个只负责执行单步指令。驱动者保持干净上下文，执行者干脏活累活频繁 /clear。这个模式把"上下文污染"限制在执行者侧，驱动者的判断力全程在线。

并行探索：方案不明确时开两个会话各探索一条技术路线，对比它们的发现再做决策。成本是单会话的两倍，但对方向性决策来说，比走错路再回头便宜。

多 Agent 的前提是任务边界清晰——边界模糊的任务拆不出干净的分工，硬拆只会增加协调成本。先练好单会话节奏，再引入协作。

十九、常见任务的模式库

几类高频任务的经过验证的指令模式，可直接套用：

修 bug："复现路径是 X。先读 A、B 文件与相关测试，给出你对根因的假设与置信度，不要改代码。" → 确认假设 →"写一个能复现该 bug 的失败测试" →"修改实现让测试通过，跑全量测试"。

接手陌生代码："总结这个模块的职责、入口、依赖与已知问题，输出一份不超过 50 行的笔记存到 docs/。" → 人工修订笔记 → 基于笔记继续任务。

写新功能："参考 C 模块的实现模式，为 D 功能写设计与文件清单，列出需要新增/修改的文件与数据流。" → 确认设计 → 分步实现，每步跑测试。

升级依赖："读 lockfile 确认当前版本，查目标版本 changelog，列出 breaking changes 与受影响的调用点，先出迁移方案再动手。"

模式化的价值在于：把"每次现想怎么说"变成"按模板填空"，指令质量稳定，产出也就稳定。团队把这些模板维护成内部文档，比推荐工具本身更有价值。

二十、远程开发与 SSH 场景

在远程服务器上使用 Claude Code 有几处环境差异要处理：SSH 会话断线会杀死进行中的长任务，配合 tmux 或 screen 使用（在 tmux 窗口里跑会话，断线重连后 attach 回来）是标准姿势；无桌面环境的服务器上，OAuth 登录回调无法打开浏览器，按终端输出的 URL 在本地浏览器完成授权即可；凭据持久化依赖 keyring 的组件在裸服务器上缺失时，改用环境变量方式的 API Key 模式。远程场景的安全边界比本地更重要：专用低权限用户、目录白名单、命令审计三件套（详见我们的 AI Agent 服务器运维一文）在服务器上是必选项而不是建议项。

二十一、和代码评审流程集成

把 Claude Code 嵌进既有评审流程而不是绕开它：提交前让它按团队清单自查 diff（硬编码凭据、错误处理、边界条件），把自查结论贴进 PR 描述作为评审上下文；评审意见的修正可以回到会话完成——"评审提出 X 问题，在保持方案不变的前提下修复"，历史上下文让修复不会偏离原方案；大 PR 让它先生成"变更摘要 + 风险点"帮助评审者分配注意力。这些用法不改变评审的权责结构——AI 产出永远是"待评审的提案"，合入决定权在人——但能让有限的评审时间集中在真正需要人类判断的部分。

正反对照速查：探索阶段说"先只读调查，给出理解与方案，不要改代码"，反例是"帮我优化这个模块"（它可能直接动手）；验收阶段说"跑 pnpm test 与 build，贴出结果"，反例是"确保没问题"（自我报告不是验证）；纠偏时说"停。回到计划第 3 步，原因是 X"，反例是"不对，重新来"（它不知道哪里错）；沉淀时说"把这条约束追加到 CLAUDE.md 的规范段"，反例是每次口头重申。把这张表贴在工位上，一周后它会内化成肌肉记忆。

表达模板速记：探索期说"只读调查，先别改代码"；计划期说"给方案，列文件清单与风险"；执行期说"小步走，每步跑测试再继续"；验证期说"跑真的测试与构建，把输出贴给我"；收尾期说"把本次的约束与结论更新进 CLAUDE.md"。这五句话覆盖了日常九成的交互场景，忘了长篇理论时先记住它们——工作流的骨架就这五步，剩下的都是细节。

从哪条开始练？ 如果读完只想先改一个习惯，选"一个任务一个会话"：它是所有习惯里实施成本最低、体感差异最大的一条——干净的上下文会让同一句话得到明显更准的回答，而你会立刻感受到这种差异，并自发地想补齐其余习惯。

补一条团队场景的私货：如果团队里只有你一个人在认真用，先别急着推全员培训——把你的产出（更快的修复、更全的测试、更干净的迁移）做成可见的 PR 示例，同事会来问你怎么用的。工具习惯的传播靠的是可见的收益示范，不是行政推行；CLAUDE.md 与 Skills 的团队库，往往就是从"第二个人主动来抄"开始长大的。

顺带一提，反模式清单里最值得警惕的是第一条与最后一条的组合：新手阶段不加隔离地长会话乱跑，熟练之后权限全开地长会话乱跑——两个阶段的形态不同，本质都是"把 AI 当黑盒，自己退出回路"。工具在迭代，模型在变强，但"人有判断、AI 有边界、回路有验证"的三角结构不会过时；这篇里所有具体技巧都会过期，这个结构不会。

二十、常见反模式清单

最后把反复见到的问题集中列出，自查：

1. 一个会话干到底不 /clear，任务串味后质量崩塌；
2. CLAUDE.md 写成散文，关键约束被淹没；
3. 放开全部权限图省事，在错误路径上批量写文件；
4. 直接下执行指令，跳过探索与计划，方向错了还在猛改；
5. 不给它测试与验证回路，用"它说好了"当验收；
6. 长会话变卡不知道 /compact，以为是工具变慢；
7. 高频流程每次口头重新描述，不沉淀成 Skill；
8. 生产服务器上用高权限账号裸奔运行，无审计无回滚。

这八条反过来看，就是一份最小可用的最佳实践清单。

官方资料与继续阅读

• Anthropic 官方 Claude Code 最佳实践：https://www.anthropic.com/engineering/claude-code-best-practices
• Claude Code 官方文档（设置与命令）：https://docs.claude.com/en/docs/claude-code/overview
• 站内相关文章：Claude Code 安装指南、Claude Code Skills 实战、把 AI Agent 接进服务器运维、Claude Code vs Cursor 对比