1. 开工之前：Claude Code 是什么，我们团队怎么用它1.1 一个终端里的全能“结对程序员”Claude Code 是当前热度很高的命令行 AI 编程助手，直接跑在终端里，通过自然语言对话完成读代码、改文件、执行命令、跑测试、提交 commit 这一整个闭环。和常见的“聊天窗里粘代码”不同，它拥有真实的工作目录访问权限，能从头到尾跟踪一个任务的上下文，而不是把代码复制进对话里让 AI 猜。我用它小半年，最大的感受是：它更像一个可以随时喊来结对的老同事，而不是一个“高级补全插件”。你给它一个目标，它会自己打开相关文件、定位问题点、修改实现、运行验证、再回来汇报结果。这个过程中你不需要事无巨细地指挥每一行怎么改，但你可以随时叫停、提问、纠正方向。我们团队是中型的全栈研发团队，代码库规模不大不小，但历史包袱不少：老模块、混合技术栈、缺少统一注释的地方到处都是。引入 Claude Code 之后，我们最早的目标其实很朴素——减少重复劳动，让日常开发里“查半天才能动手”的时间大幅缩短。后来才发现，真正让它值回票价的是把团队规范和上下文喂给它之后，它几乎变成了对项目最熟的“虚拟老员工”，新人和老手用它的效率差被明显拉平了。如果你还没试过这类终端 AI Agent，这篇总结建议从头看，尤其第二章的 CLAUDE.md 配置，是后续一切技巧的地基。如果你已经用它写过几个小任务，可以重点看第三、四章，那部分涉及上下文控制、hooks 自动化和 headless 模式，都属于“直接照抄就能提效”的清单。1.2 团队用下来收益最大的三类场景我们并没有把所有编码工作都交给 AI，只把收益最高、风险可控的三类场景沉淀成了团队固定流程。第一类是老代码探索与依赖梳理。接手一个不熟悉的模块时，过去需要人肉读目录结构、翻 entrypoint、追调用链，耗时经常以小时计。现在直接让 Claude Code 沿着调用链追踪数据流，把“这个功能从接口到落库经过了哪些层、哪些地方有副作用”梳理成一份带引用路径的说明，我只需要复核结论。实测下来，单个模块的理解成本普遍从半天压缩到一小时左右，而且它给出的文件引用路径可以直接点击核对，不会出现“看起来很有道理但实际是编的”这种情况。第二类是跨文件批量修改。传统 IDE 的重构工具擅长单文件级改名、提取函数，但遇到“把某类异常处理统一换成新的错误码体系”这种横跨十几个文件的连锁改动，手工操作很容易漏。Claude Code 的优势在于它能基于全局搜索的结果先生成完整改动计划，再逐个文件落实，最后靠测试兜底。我们团队的大多数机械性迁移、格式统一、日志规范改造都走这个路径。第三类是代码评审与检查的补充视角。它会从命名一致性、测试覆盖盲区、边界情况处理等维度提出建议，虽然不能完全替代人工评审的架构判断，但能有效兜住低级遗漏。后面第四章我还会展开讲 subagent 的评审用法，比单会话硬问的效果好一个量级。2. 让 AI 懂项目：两个把“记忆”做好的技巧2.1 技巧一：CLAUDE.md 是项目的长期记忆，越早建越划算Claude Code 每次启动都会自动读取项目根目录下的 CLAUDE.md，以及用户全局目录下的 ~/.claude/CLAUDE.md，把里面的内容当作默认的项目认知。这个文件就是它的“长期记忆”，作用相当于一份同时写给新人和 AI 看的项目说明书。我用过之后最大的建议是：这个文件不是文档，是约束条件和判断依据。不要写空话，要写“看完之后能直接按它的标准做事”的内容。我们团队的 CLAUDE.md 固定包含五块：# 项目概述 一句话说明系统定位、核心用户、主仓库结构。 # 技术栈与命令 - 包管理器：pnpm - 本地启动：pnpm dev - 测试：pnpm test（重要：改完代码必须跑相关测试） - Lint：pnpm lint # 代码规范 - 目录职责：src/components 无业务逻辑，src/api 只做请求封装 - 命名规则：组件用 PascalCase，工具函数用 camelCase - 错误处理：禁止吞异常，所有 catch 块必须有日志输出 # 易错点 - 支付模块的金额单位是分，不是元，后端返回也是分 - 配置中心修改后需重启才生效，不要手动改运行中的内存值 # 当前进行中的事项（保持更新） - feature/user-notification 分支正在重构通知中心，涉及 3 个文件首次可以从执行claude后输入/init开始，它会自动扫描代码库生成初始版本，但自动生成的只有骨架，真正有价值的内容要靠团队自己补。我们团队现在的做法是：任何人在工作中发现“如果 AI 不知道这个背景，一定会做错的事”，就顺手补进 CLAUDE.md，每周 review 一次合并提炼。另外我们还约定，每次完成一个重要迭代，要在“当前进行中的事项”里更新状态，否则 AI 会拿着过时的上下文开始工作。这里有几个踩过的坑。第一个是文件不能太长，超过两百行之后，AI 对其中任意一条的敏感度会明显下降，出现“明明写了却没按着做”的情况。解决办法是只保留不可从代码推断的信息，像“语言版本是 TypeScript 5”这种从 package.json 一眼可见的就不写。第二个坑是每条规则要写成可被验证的结论，不要写“注意代码质量”这种无法判断的废话，要写“组件内超过三层的嵌套条件必须提取函数”。第三个坑是全局 CLAUDE.md 和项目 CLAUDE.md 不要内容冲突，全局的我们只放通用规范，项目相关的全部放项目级文件里。2.2 技巧二：权限规则一次配好，把“你确定吗”消灭在源头Claude Code 在执行命令前会做权限判断，默认策略是遇到命令先询问你。这个机制安全上没毛病，但用起来非常打断节奏：每跑一次测试弹一次确认，改成增量编译又弹一次，一会儿工夫耐心就没了。更麻烦的是，频繁弹出的确认框会导致操作者麻木，真正危险的命令也可能顺手就点了允许。所以第二件值得做的事就是维护.claude/settings.json，把团队里常见的、低风险的命令一次性配置成自动放行。我们的配置模板大概是这样的：{ "permissions": { "allow": [ "ls", "cat", "pwd", "git status", "git diff", "git log", "pnpm test", "pnpm lint", "pnpm build", "curl -I*" ], "deny": [ "rm -rf *", "git push --force", "chmod -R 777", "dropdb*" ], "ask": [ "git commit -m *", "git push *", "pnpm install" ] } }配置的逻辑很清晰：allow是白名单，命中就直接执行不询问；deny是硬性禁止，命中直接拒绝；ask是黑名单之外需要人工确认的命令。重点说一下为什么git commit和git push我们放在ask而不是allow。提交信息往往需要结合代码内容判断，让它闷头执行未必符合团队规范，而且 push 属于对外影响操作，保留一道人工确认是成本极低的保险。配置权限之前，我的建议是先在默认的 ask 模式下正常用两三天，把弹窗内容收集一下，然后在配置里把高频低风险命令固化进allow。千万不要一上来就把所有命令全放行，尤其是删除、强制推送、生产环境操作这类命令，一旦 AI 误触发可能造成不可逆损失。团队里如果有人提出新命令要放行，我们要求由配置维护人统一审核后合入，避免每个人的配置文件风格五花八门。3. 控制对话质量：三个管好上下文的技巧3.1 技巧三：自定义 slash command，把团队套路沉淀成命令Claude Code 支持把一些反复使用的提示词封装成自定义命令，放在~/.claude/commands/目录下，一个 Markdown 文件就是一个命令，文件名就是触发词。执行时输入/命令名，文件内容就会作为提示词前缀注入。我们团队的~/.claude/commands/下面维护了大概六个命令，使用频率最高的是代码评审和修复重构。比如cr.md：你是一名严格的高级代码评审者。请按以下流程评审用户提供的 diff 或指定文件： 1. 先梳理改动目标与关联模块 2. 检查：命名、边界条件、错误处理、测试覆盖 3. 指出问题时应给出文件与行号，并说明严重程度 4. 最后输出问题清单，按阻塞/建议两级分类 不要输出修改后的完整代码，只输出评审意见。这个文件执行的效果是：输入/cr后，AI 会立刻按照预设的评审流程输出结构化的意见，而不是泛泛地“整体不错”。我们过去在人工评审里发现新人容易漏边界条件，把这个要求固化进命令模板之后，评审判定的准度明显稳定了。另一个推荐固化的命令是/context，用于快速加载完成一个任务前必须了解的代码约定和链路信息。一个好的自定义命令应该做到“不同的人用，效果一致”。如果团队里有人发现某个提示词的封装效果特别好，就把它提取成命令文件放进共享目录，这样每个人都在使用团队验证过的最佳实践，而不是各自和 AI 随机对话。需要注意 commands 目录里的 md 文件顶部可以加 YAML front-matter 描述参数，但这个对普通团队不是必须，先保持纯 Markdown 更简单。3.2 技巧四：用 @ 引用让 AI 只看该看的文件Claude Code 的上下文窗口虽然很大，但“大”不等于“应该塞满”。上下文越长，AI 对关键细节的注意力越分散，反应速度也越慢。实际使用中最容易被忽略的效率杠杆是精确控制它“看到什么”。在对话中使用@路径可以直接把指定文件内容附加到上下文中。比如只讨论权限校验逻辑时，直接@src/middleware/auth.ts，而不是扔一句“看看这个项目里有没有权限校验问题”。后者会让 AI 自己选文件，它选的文件不一定是你关心的，还容易读入一堆无关内容稀释重点。团队里的高阶玩法是组合引用。例如处理“登录接口超时”问题，一次对话同时引用@src/router/login.ts、@src/services/auth.ts、@src/config/timeout.ts三个文件，加上一句话说明现象，AI 基本能直接定位到问题链路，不需要你先把代码粘出来。我还见过同事把git diff的输出贴给 AI 做增量代码问题排查，效果比让它读整个仓库源码好很多。关于大型代码库，一个省钱的诀窍是先让它读目录结构和入口文件，再决定要不要深入某个文件。直接丢一整包源码给它，它会消耗大量 token 在无关内容上。我一般会先给@README.md或让 AI 跑tree -L 2输出目录结构，确认范围后再精确引用。这个习惯帮助我们省下的 token 费用相当可观。3.3 技巧五：大任务拆小步，每步都有验收标准这是团队里最重要的工作纪律，没有之一。Claude Code 擅长执行定义清晰的独立任务，但如果任务描述是“完成用户模块的重构”，它的表现会立刻下滑——不是能力不够，而是缺少中间反馈和验收机制，AI 只能按自己对全局的理解一路走到底，走到坑里才发现方向偏了。我们的做法是把大任务拆成“回合”。每个回合包含四件事：目标、边界、验证方式、完成定义。举一个真实的迁移任务例子，我们需要把某个老模块的日志依赖全部替换为团队统一封装的新日志库，一共涉及 8 个文件：第一回合：先让它基于全局搜索输出完整的改动清单，包括每个文件的依赖位置和估时，人确认清单无误后再动手。第二回合：只改基础工具类和公共函数层，改完跑一遍相应单测，确认无回归。第三回合：再改业务调用层，同样的方式逐层递进，每层都有明确的验证步骤。拆分的核心原因是限制失败影响半径。如果一次让它改完 8 个文件，其中某个文件的迁移方式有问题，回滚范围很大，排查成本也高。如果按层推进，最多回滚一层，而且每一层都有测试兜底，发现问题的时点会早得多。实际执行中我还会要求它在每个回合结束输出“变更摘要 + 验证结果”，这样即使中间会话中断，下一个新会话也能通过摘要快速接上。这个小技巧也直接影响了成本。失败重跑的范围从一整个大任务缩小到一个小回合，token 浪费量降下来了，团队对它的信任度也提升了。如果你的团队刚接入这类工具，第一条纪律我建议就定这个：任务可以大，但交付必须是一小步一小步来。4. 自动化与流水线：三个把 AI 嵌入工作流的技巧4.1 技巧六：hooks 配置把检查与格式化变成条件反射Claude Code 提供了 hooks 机制，可以在特定事件点自动执行脚本。我们团队用得最狠的是PostToolUse和PreToolUse，分别在 AI 执行完命令之后和执行命令之前触发。这相当于把团队的工程纪律从“靠人提醒”升级成了“自动发生”。举例来说，我们要求所有提交代码前必须通过 lint。传统流程是靠开发者自觉，后来改成了在.claude/settings.json里配置：{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "pnpm exec eslint $CLAUDE_FILE_PATH --fix" } ] } ] } }这段配置的效果是：AI 每次写完文件，立刻对修改的文件跑一次 eslint 并自动修复。过去人工流程里“改完代码忘记跑 lint”的毛病在这里被直接堵住了，因为格式化变成工具链的默认行为，而不是人的习惯。Notification钩子在耗时任务结束时推送通知，长任务可以放心挂后台不用盯着。配置 hooks 有一条原则：只挂确定性强的命令。像测试这种结果依赖运行环境、偶尔有 flaky 的命令，不要强制挂在每次写文件后，否则会频繁打断 AI 的流，反噬效率。格式化、静态检查这类确定性强的操作最合适，而测试验证我们建议放在每轮任务的验证阶段由 AI 主动执行，而不是每次写入都触发。刚配置 hooks 时建议先不开--force自动修复，只记录问题。观察一段时间确认不会误改后，再打开自动修复。我们的 eslint --fix 策略就是先只报警了两天，确认修复稳定才改成自动模式。这个渐进策略帮助团队减少了对“自动改代码”这件事的恐惧感。4.2 技巧七：subagent 并行评审，让代码质量有第二双眼睛Claude Code 的任务机制可以把一个任务拆给多个子 agent 并行处理。最常用的场景是评审：主 agent 完成代码修改后，派生一个 subagent 专门从测试覆盖的角度检查，再派生一个从安全边界角度检查，两个视角互不干扰，最后把意见汇总回来。具体使用方式是在对话中描述清楚评审角度，比如“用一个独立的 subagent 检查这个 diff 的异常分支是否有遗漏，输出具体文件和行号”。主 agent 就会并行启动多个子任务，等待全部完成后整合结果。对一次跨 5 个文件的改动做全量 code review，过去人工需要大半个小时，现在 AI 并行评审几分钟就能给出问题清单，我只需要花少量时间核实结论。这个用法解决了一个单会话评审的天然缺陷：主 agent 在长上下文里容易“证实偏差”——它刚写完代码，倾向于认为自己的实现没问题，让它自己审自己容易走过场。独立 subagent 没有参与实现阶段，看待代码的角度是全新的，更容易找出矛盾点。我们的复盘中还发现，并行 2-3 个子 agent 的成本不一定比顺序逐个评审高，因为并行能让模型在一次调用周期内同时处理多个方向，整体延迟反而更低。但从质量和可维护性角度，不要一次派太多，超过三个子 agent 后意见之间容易相互污染，最后的汇总结果反而难读。4.3 技巧八：headless 模式接 CI，做定时巡检自动修Claude Code 支持 headless 模式：不开启交互界面，直接使用claude -p "提示词"执行一次性任务。这个模式是接自动化流水线的关键入口。我们团队用它做定期巡检，让 AI 自动扫描代码库中的技术债，并尝试修复。举两个落地场景。第一个是依赖升级后的自动修复：每次升级依赖版本后，跑一个 headless 任务让 AI 逐个修复版本升级带来的 API 不兼容编译错误。之前这个工作往往要开发花半天手工修，现在一条命令让它根据编译错误提示逐个文件修，大部分能自动完成。第二个是定期清理：每两周让 AI 检查一次仓库里的 TODO、FIXME 和 debugger 残留，输出清单并处理掉过期的注释。实际命令大概是这样：claude -p "扫描 src 目录中所有 FIXME 注释，输出文件路径和上下文，按严重程度排序，并尝试修复其中由简单重构可解决的问题" --max-turns 50--max-turns是必须有的护栏，防止 headless 任务在无人监督时陷入死循环。另一个重要护栏是分支隔离：headless 任务永远在专用分支上跑，AI 修完代码后由自动化流水线创建合并请求，走到人工审批环节，禁止直接推到主分支。第一次跑 headless 时，一定要先设计一个“不会产生不可回滚影响”的任务，观察几轮后习惯它的行为边界，再逐步增加任务风险等级。我们团队实测的收益是：原本要半天的人工升级处理时间，压缩到 20 分钟左右的 AI 自动修复加人工复核，而且因为每次都从编译错误出发修，修复结果比人手盲改更一致。5. 成本与纪律：两个控制预算和稳定性的技巧5.1 技巧九：成本可控三板斧，别让好工具变成账单炸弹Claude Code 使用成本随调用量线性增长，团队接入后如果不加以控制，账单会涨得比效率还快。我们摸索出的成本控制三板斧是：任务分级用模型、限制最大轮数、定期压缩上下文。第一板斧是任务分级用模型。理解需求、写复杂业务逻辑、设计 API 这类认知密集型任务用能力最强的模型；批量格式化、注释翻译、简单正则替换这类机械任务就切换到更快更便宜的模型。Claude Code 支持按任务用--model指定模型，我们团队的默认约定是：重任务不省，轻任务不浪费。第二板斧是限制最大轮数。每次执行带--max-turns，根据任务复杂度预估需要执行的步骤数，限制在一个合理区间。这个参数的作用不仅是防死循环，还会强迫 AI 在限制内尽快收敛，不会无止境地在边缘问题上纠缠。比如简单的单文件修复给 10 轮就够，跨模块重构给 30-50 轮，不让它无限发散。第三板斧是上下文压缩。长任务跑完一部分后及时/compact把历史精简成摘要，避免后续步骤继续背负越来越庞大的上下文。上下文越长，成本和延迟都越高，但有效信息密度反而下降。我们统计过，一次正常的跨文件改造，在每完成一个模块后做一次压缩，相比一次性从头跑到尾，总消耗能降低三成左右，响应速度也有明显改观。还建议开一个共享的用量统计，每周看一下各成员的使用量和成本分布，不是为了监控个人，而是发现异常模式，比如某个成员成本异常高，大概率是上下文管理上有优化空间，可以直接把第三章的技巧分享给他。5.2 技巧十：及时压缩与果断重开，会话健康比什么都重要最后一个技巧是关于会话卫生。Claude Code 的对话历史就像人的工作记忆，越长越疲惫。如果你发现同一个会话里的 AI 开始表现得不对劲，比如反复确认已经确认过的事、无端修改无关代码、或者答非所问，基本不是模型坏掉了，而是它的上下文已经乱得像一团毛线。健康的处理方式是分层治理。会话变长但方向还是对的，就执行/compact压缩历史，让 AI 在精简后的摘要上继续工作。会话方向一开始就错了，或者需求已经变了，别犹豫，果断/clear重开，把当前状态和遗留问题写进笔记再重新开始。很多新手会粘着一个会话从头干到底，这不是坚持，是给自己挖坑。我们团队的约定是：每个功能任务采用“多会话递进”模式。第一个会话负责探索和方案设计，结束时把关键结论写入 CLAUDE.md；第二个会话负责落地编码，因为上下文从 CLAUDE.md 加载，不需要重讲背景；第三个会话做评审和收尾。每次会话都轻装上阵，效果远好于一个超长会话一口气讲完所有事。这个习惯还有一个隐藏好处：会话历史是团队的知识资产。散落在一个超长会话里的决策过程很难被复用，但分阶段会话的结论可以通过 CLAUDE.md 沉淀下来，变成团队长期积累的一部分。我们后来能快速让新成员上手项目，很大程度归功于这样沉淀下来的量化文档，而不只是 AI 本身的能力。5.3 团队协作约定：配置入库、代码过审、密钥不外传最后补充几条团队级的协作纪律，它们不属于技巧，但决定了前面所有技巧能不能长期稳定发挥作用。第一，所有配置文件进版本库。CLAUDE.md、settings.json、commands 目录都纳入代码仓库管理，任何人对配置的修改都要走合并请求流程。这样既能统一大家的使用基线，也便于回滚错误配置。团队新成员克隆仓库后就拿到了全套最佳实践，不需要口头传教。第二，AI 写的代码同样要走评审。我们内部有一条硬性约定：AI 直接提交的代码不允许绕过 code review 合入主干。AI 可能反复犯同一个逻辑错误，尤其在自己写的代码里自我评审时容易失灵，人工评审是最后一道防线。第三，密钥和敏感信息严禁进入对话。绝对不要把数据库密码、云服务密钥、个人凭证粘贴进 prompt，也不要让 AI 读取包含敏感信息的配置文件。它的上下文可能被记录用于调试，一旦泄露就是安全事故。我们的做法是敏感配置一律从环境变量读取，Claude Code 的工作目录里只放不含秘密的示例文件，从源头避免这些问题。这几点不是技术问题，是流程设计。AI 工具带来的效率增益越明显，越需要明确它产生的代码和修改如何进入团队的正式交付体系，否则效率和风险会一起增长。以上十条是我们验证过、正在稳定使用的实践集合。如果你刚开始用这类工具，别试图一次全上，先挑团队当前最痛的场景选两三条跑起来，稳定后再逐步扩展，节奏稳比效果好更要紧。
1. 开工之前：Claude Code 是什么，我们团队怎么用它1.1 一个终端里的全能“结对程序员”Claude Code 是当前热度很高的命令行 AI 编程助手，直接跑在终端里，通过自然语言对话完成读代码、改文件、执行命令、跑测试、提交 commit 这一整个闭环。和常见的“聊天窗里粘代码”不同，它拥有真实的工作目录访问权限，能从头到尾跟踪一个任务的上下文，而不是把代码复制进对话里让 AI 猜。我用它小半年，最大的感受是：它更像一个可以随时喊来结对的老同事，而不是一个“高级补全插件”。你给它一个目标，它会自己打开相关文件、定位问题点、修改实现、运行验证、再回来汇报结果。这个过程中你不需要事无巨细地指挥每一行怎么改，但你可以随时叫停、提问、纠正方向。我们团队是中型的全栈研发团队，代码库规模不大不小，但历史包袱不少：老模块、混合技术栈、缺少统一注释的地方到处都是。引入 Claude Code 之后，我们最早的目标其实很朴素——减少重复劳动，让日常开发里“查半天才能动手”的时间大幅缩短。后来才发现，真正让它值回票价的是把团队规范和上下文喂给它之后，它几乎变成了对项目最熟的“虚拟老员工”，新人和老手用它的效率差被明显拉平了。如果你还没试过这类终端 AI Agent，这篇总结建议从头看，尤其第二章的 CLAUDE.md 配置，是后续一切技巧的地基。如果你已经用它写过几个小任务，可以重点看第三、四章，那部分涉及上下文控制、hooks 自动化和 headless 模式，都属于“直接照抄就能提效”的清单。1.2 团队用下来收益最大的三类场景我们并没有把所有编码工作都交给 AI，只把收益最高、风险可控的三类场景沉淀成了团队固定流程。第一类是老代码探索与依赖梳理。接手一个不熟悉的模块时，过去需要人肉读目录结构、翻 entrypoint、追调用链，耗时经常以小时计。现在直接让 Claude Code 沿着调用链追踪数据流，把“这个功能从接口到落库经过了哪些层、哪些地方有副作用”梳理成一份带引用路径的说明，我只需要复核结论。实测下来，单个模块的理解成本普遍从半天压缩到一小时左右，而且它给出的文件引用路径可以直接点击核对，不会出现“看起来很有道理但实际是编的”这种情况。第二类是跨文件批量修改。传统 IDE 的重构工具擅长单文件级改名、提取函数，但遇到“把某类异常处理统一换成新的错误码体系”这种横跨十几个文件的连锁改动，手工操作很容易漏。Claude Code 的优势在于它能基于全局搜索的结果先生成完整改动计划，再逐个文件落实，最后靠测试兜底。我们团队的大多数机械性迁移、格式统一、日志规范改造都走这个路径。第三类是代码评审与检查的补充视角。它会从命名一致性、测试覆盖盲区、边界情况处理等维度提出建议，虽然不能完全替代人工评审的架构判断，但能有效兜住低级遗漏。后面第四章我还会展开讲 subagent 的评审用法，比单会话硬问的效果好一个量级。2. 让 AI 懂项目：两个把“记忆”做好的技巧2.1 技巧一：CLAUDE.md 是项目的长期记忆，越早建越划算Claude Code 每次启动都会自动读取项目根目录下的 CLAUDE.md，以及用户全局目录下的 ~/.claude/CLAUDE.md，把里面的内容当作默认的项目认知。这个文件就是它的“长期记忆”，作用相当于一份同时写给新人和 AI 看的项目说明书。我用过之后最大的建议是：这个文件不是文档，是约束条件和判断依据。不要写空话，要写“看完之后能直接按它的标准做事”的内容。我们团队的 CLAUDE.md 固定包含五块：# 项目概述 一句话说明系统定位、核心用户、主仓库结构。 # 技术栈与命令 - 包管理器：pnpm - 本地启动：pnpm dev - 测试：pnpm test（重要：改完代码必须跑相关测试） - Lint：pnpm lint # 代码规范 - 目录职责：src/components 无业务逻辑，src/api 只做请求封装 - 命名规则：组件用 PascalCase，工具函数用 camelCase - 错误处理：禁止吞异常，所有 catch 块必须有日志输出 # 易错点 - 支付模块的金额单位是分，不是元，后端返回也是分 - 配置中心修改后需重启才生效，不要手动改运行中的内存值 # 当前进行中的事项（保持更新） - feature/user-notification 分支正在重构通知中心，涉及 3 个文件首次可以从执行claude后输入/init开始，它会自动扫描代码库生成初始版本，但自动生成的只有骨架，真正有价值的内容要靠团队自己补。我们团队现在的做法是：任何人在工作中发现“如果 AI 不知道这个背景，一定会做错的事”，就顺手补进 CLAUDE.md，每周 review 一次合并提炼。另外我们还约定，每次完成一个重要迭代，要在“当前进行中的事项”里更新状态，否则 AI 会拿着过时的上下文开始工作。这里有几个踩过的坑。第一个是文件不能太长，超过两百行之后，AI 对其中任意一条的敏感度会明显下降，出现“明明写了却没按着做”的情况。解决办法是只保留不可从代码推断的信息，像“语言版本是 TypeScript 5”这种从 package.json 一眼可见的就不写。第二个坑是每条规则要写成可被验证的结论，不要写“注意代码质量”这种无法判断的废话，要写“组件内超过三层的嵌套条件必须提取函数”。第三个坑是全局 CLAUDE.md 和项目 CLAUDE.md 不要内容冲突，全局的我们只放通用规范，项目相关的全部放项目级文件里。2.2 技巧二：权限规则一次配好，把“你确定吗”消灭在源头Claude Code 在执行命令前会做权限判断，默认策略是遇到命令先询问你。这个机制安全上没毛病，但用起来非常打断节奏：每跑一次测试弹一次确认，改成增量编译又弹一次，一会儿工夫耐心就没了。更麻烦的是，频繁弹出的确认框会导致操作者麻木，真正危险的命令也可能顺手就点了允许。所以第二件值得做的事就是维护.claude/settings.json，把团队里常见的、低风险的命令一次性配置成自动放行。我们的配置模板大概是这样的：{ "permissions": { "allow": [ "ls", "cat", "pwd", "git status", "git diff", "git log", "pnpm test", "pnpm lint", "pnpm build", "curl -I*" ], "deny": [ "rm -rf *", "git push --force", "chmod -R 777", "dropdb*" ], "ask": [ "git commit -m *", "git push *", "pnpm install" ] } }配置的逻辑很清晰：allow是白名单，命中就直接执行不询问；deny是硬性禁止，命中直接拒绝；ask是黑名单之外需要人工确认的命令。重点说一下为什么git commit和git push我们放在ask而不是allow。提交信息往往需要结合代码内容判断，让它闷头执行未必符合团队规范，而且 push 属于对外影响操作，保留一道人工确认是成本极低的保险。配置权限之前，我的建议是先在默认的 ask 模式下正常用两三天，把弹窗内容收集一下，然后在配置里把高频低风险命令固化进allow。千万不要一上来就把所有命令全放行，尤其是删除、强制推送、生产环境操作这类命令，一旦 AI 误触发可能造成不可逆损失。团队里如果有人提出新命令要放行，我们要求由配置维护人统一审核后合入，避免每个人的配置文件风格五花八门。3. 控制对话质量：三个管好上下文的技巧3.1 技巧三：自定义 slash command，把团队套路沉淀成命令Claude Code 支持把一些反复使用的提示词封装成自定义命令，放在~/.claude/commands/目录下，一个 Markdown 文件就是一个命令，文件名就是触发词。执行时输入/命令名，文件内容就会作为提示词前缀注入。我们团队的~/.claude/commands/下面维护了大概六个命令，使用频率最高的是代码评审和修复重构。比如cr.md：你是一名严格的高级代码评审者。请按以下流程评审用户提供的 diff 或指定文件： 1. 先梳理改动目标与关联模块 2. 检查：命名、边界条件、错误处理、测试覆盖 3. 指出问题时应给出文件与行号，并说明严重程度 4. 最后输出问题清单，按阻塞/建议两级分类 不要输出修改后的完整代码，只输出评审意见。这个文件执行的效果是：输入/cr后，AI 会立刻按照预设的评审流程输出结构化的意见，而不是泛泛地“整体不错”。我们过去在人工评审里发现新人容易漏边界条件，把这个要求固化进命令模板之后，评审判定的准度明显稳定了。另一个推荐固化的命令是/context，用于快速加载完成一个任务前必须了解的代码约定和链路信息。一个好的自定义命令应该做到“不同的人用，效果一致”。如果团队里有人发现某个提示词的封装效果特别好，就把它提取成命令文件放进共享目录，这样每个人都在使用团队验证过的最佳实践，而不是各自和 AI 随机对话。需要注意 commands 目录里的 md 文件顶部可以加 YAML front-matter 描述参数，但这个对普通团队不是必须，先保持纯 Markdown 更简单。3.2 技巧四：用 @ 引用让 AI 只看该看的文件Claude Code 的上下文窗口虽然很大，但“大”不等于“应该塞满”。上下文越长，AI 对关键细节的注意力越分散，反应速度也越慢。实际使用中最容易被忽略的效率杠杆是精确控制它“看到什么”。在对话中使用@路径可以直接把指定文件内容附加到上下文中。比如只讨论权限校验逻辑时，直接@src/middleware/auth.ts，而不是扔一句“看看这个项目里有没有权限校验问题”。后者会让 AI 自己选文件，它选的文件不一定是你关心的，还容易读入一堆无关内容稀释重点。团队里的高阶玩法是组合引用。例如处理“登录接口超时”问题，一次对话同时引用@src/router/login.ts、@src/services/auth.ts、@src/config/timeout.ts三个文件，加上一句话说明现象，AI 基本能直接定位到问题链路，不需要你先把代码粘出来。我还见过同事把git diff的输出贴给 AI 做增量代码问题排查，效果比让它读整个仓库源码好很多。关于大型代码库，一个省钱的诀窍是先让它读目录结构和入口文件，再决定要不要深入某个文件。直接丢一整包源码给它，它会消耗大量 token 在无关内容上。我一般会先给@README.md或让 AI 跑tree -L 2输出目录结构，确认范围后再精确引用。这个习惯帮助我们省下的 token 费用相当可观。3.3 技巧五：大任务拆小步，每步都有验收标准这是团队里最重要的工作纪律，没有之一。Claude Code 擅长执行定义清晰的独立任务，但如果任务描述是“完成用户模块的重构”，它的表现会立刻下滑——不是能力不够，而是缺少中间反馈和验收机制，AI 只能按自己对全局的理解一路走到底，走到坑里才发现方向偏了。我们的做法是把大任务拆成“回合”。每个回合包含四件事：目标、边界、验证方式、完成定义。举一个真实的迁移任务例子，我们需要把某个老模块的日志依赖全部替换为团队统一封装的新日志库，一共涉及 8 个文件：第一回合：先让它基于全局搜索输出完整的改动清单，包括每个文件的依赖位置和估时，人确认清单无误后再动手。第二回合：只改基础工具类和公共函数层，改完跑一遍相应单测，确认无回归。第三回合：再改业务调用层，同样的方式逐层递进，每层都有明确的验证步骤。拆分的核心原因是限制失败影响半径。如果一次让它改完 8 个文件，其中某个文件的迁移方式有问题，回滚范围很大，排查成本也高。如果按层推进，最多回滚一层，而且每一层都有测试兜底，发现问题的时点会早得多。实际执行中我还会要求它在每个回合结束输出“变更摘要 + 验证结果”，这样即使中间会话中断，下一个新会话也能通过摘要快速接上。这个小技巧也直接影响了成本。失败重跑的范围从一整个大任务缩小到一个小回合，token 浪费量降下来了，团队对它的信任度也提升了。如果你的团队刚接入这类工具，第一条纪律我建议就定这个：任务可以大，但交付必须是一小步一小步来。4. 自动化与流水线：三个把 AI 嵌入工作流的技巧4.1 技巧六：hooks 配置把检查与格式化变成条件反射Claude Code 提供了 hooks 机制，可以在特定事件点自动执行脚本。我们团队用得最狠的是PostToolUse和PreToolUse，分别在 AI 执行完命令之后和执行命令之前触发。这相当于把团队的工程纪律从“靠人提醒”升级成了“自动发生”。举例来说，我们要求所有提交代码前必须通过 lint。传统流程是靠开发者自觉，后来改成了在.claude/settings.json里配置：{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "pnpm exec eslint $CLAUDE_FILE_PATH --fix" } ] } ] } }这段配置的效果是：AI 每次写完文件，立刻对修改的文件跑一次 eslint 并自动修复。过去人工流程里“改完代码忘记跑 lint”的毛病在这里被直接堵住了，因为格式化变成工具链的默认行为，而不是人的习惯。Notification钩子在耗时任务结束时推送通知，长任务可以放心挂后台不用盯着。配置 hooks 有一条原则：只挂确定性强的命令。像测试这种结果依赖运行环境、偶尔有 flaky 的命令，不要强制挂在每次写文件后，否则会频繁打断 AI 的流，反噬效率。格式化、静态检查这类确定性强的操作最合适，而测试验证我们建议放在每轮任务的验证阶段由 AI 主动执行，而不是每次写入都触发。刚配置 hooks 时建议先不开--force自动修复，只记录问题。观察一段时间确认不会误改后，再打开自动修复。我们的 eslint --fix 策略就是先只报警了两天，确认修复稳定才改成自动模式。这个渐进策略帮助团队减少了对“自动改代码”这件事的恐惧感。4.2 技巧七：subagent 并行评审，让代码质量有第二双眼睛Claude Code 的任务机制可以把一个任务拆给多个子 agent 并行处理。最常用的场景是评审：主 agent 完成代码修改后，派生一个 subagent 专门从测试覆盖的角度检查，再派生一个从安全边界角度检查，两个视角互不干扰，最后把意见汇总回来。具体使用方式是在对话中描述清楚评审角度，比如“用一个独立的 subagent 检查这个 diff 的异常分支是否有遗漏，输出具体文件和行号”。主 agent 就会并行启动多个子任务，等待全部完成后整合结果。对一次跨 5 个文件的改动做全量 code review，过去人工需要大半个小时，现在 AI 并行评审几分钟就能给出问题清单，我只需要花少量时间核实结论。这个用法解决了一个单会话评审的天然缺陷：主 agent 在长上下文里容易“证实偏差”——它刚写完代码，倾向于认为自己的实现没问题，让它自己审自己容易走过场。独立 subagent 没有参与实现阶段，看待代码的角度是全新的，更容易找出矛盾点。我们的复盘中还发现，并行 2-3 个子 agent 的成本不一定比顺序逐个评审高，因为并行能让模型在一次调用周期内同时处理多个方向，整体延迟反而更低。但从质量和可维护性角度，不要一次派太多，超过三个子 agent 后意见之间容易相互污染，最后的汇总结果反而难读。4.3 技巧八：headless 模式接 CI，做定时巡检自动修Claude Code 支持 headless 模式：不开启交互界面，直接使用claude -p "提示词"执行一次性任务。这个模式是接自动化流水线的关键入口。我们团队用它做定期巡检，让 AI 自动扫描代码库中的技术债，并尝试修复。举两个落地场景。第一个是依赖升级后的自动修复：每次升级依赖版本后，跑一个 headless 任务让 AI 逐个修复版本升级带来的 API 不兼容编译错误。之前这个工作往往要开发花半天手工修，现在一条命令让它根据编译错误提示逐个文件修，大部分能自动完成。第二个是定期清理：每两周让 AI 检查一次仓库里的 TODO、FIXME 和 debugger 残留，输出清单并处理掉过期的注释。实际命令大概是这样：claude -p "扫描 src 目录中所有 FIXME 注释，输出文件路径和上下文，按严重程度排序，并尝试修复其中由简单重构可解决的问题" --max-turns 50--max-turns是必须有的护栏，防止 headless 任务在无人监督时陷入死循环。另一个重要护栏是分支隔离：headless 任务永远在专用分支上跑，AI 修完代码后由自动化流水线创建合并请求，走到人工审批环节，禁止直接推到主分支。第一次跑 headless 时，一定要先设计一个“不会产生不可回滚影响”的任务，观察几轮后习惯它的行为边界，再逐步增加任务风险等级。我们团队实测的收益是：原本要半天的人工升级处理时间，压缩到 20 分钟左右的 AI 自动修复加人工复核，而且因为每次都从编译错误出发修，修复结果比人手盲改更一致。5. 成本与纪律：两个控制预算和稳定性的技巧5.1 技巧九：成本可控三板斧，别让好工具变成账单炸弹Claude Code 使用成本随调用量线性增长，团队接入后如果不加以控制，账单会涨得比效率还快。我们摸索出的成本控制三板斧是：任务分级用模型、限制最大轮数、定期压缩上下文。第一板斧是任务分级用模型。理解需求、写复杂业务逻辑、设计 API 这类认知密集型任务用能力最强的模型；批量格式化、注释翻译、简单正则替换这类机械任务就切换到更快更便宜的模型。Claude Code 支持按任务用--model指定模型，我们团队的默认约定是：重任务不省，轻任务不浪费。第二板斧是限制最大轮数。每次执行带--max-turns，根据任务复杂度预估需要执行的步骤数，限制在一个合理区间。这个参数的作用不仅是防死循环，还会强迫 AI 在限制内尽快收敛，不会无止境地在边缘问题上纠缠。比如简单的单文件修复给 10 轮就够，跨模块重构给 30-50 轮，不让它无限发散。第三板斧是上下文压缩。长任务跑完一部分后及时/compact把历史精简成摘要，避免后续步骤继续背负越来越庞大的上下文。上下文越长，成本和延迟都越高，但有效信息密度反而下降。我们统计过，一次正常的跨文件改造，在每完成一个模块后做一次压缩，相比一次性从头跑到尾，总消耗能降低三成左右，响应速度也有明显改观。还建议开一个共享的用量统计，每周看一下各成员的使用量和成本分布，不是为了监控个人，而是发现异常模式，比如某个成员成本异常高，大概率是上下文管理上有优化空间，可以直接把第三章的技巧分享给他。5.2 技巧十：及时压缩与果断重开，会话健康比什么都重要最后一个技巧是关于会话卫生。Claude Code 的对话历史就像人的工作记忆，越长越疲惫。如果你发现同一个会话里的 AI 开始表现得不对劲，比如反复确认已经确认过的事、无端修改无关代码、或者答非所问，基本不是模型坏掉了，而是它的上下文已经乱得像一团毛线。健康的处理方式是分层治理。会话变长但方向还是对的，就执行/compact压缩历史，让 AI 在精简后的摘要上继续工作。会话方向一开始就错了，或者需求已经变了，别犹豫，果断/clear重开，把当前状态和遗留问题写进笔记再重新开始。很多新手会粘着一个会话从头干到底，这不是坚持，是给自己挖坑。我们团队的约定是：每个功能任务采用“多会话递进”模式。第一个会话负责探索和方案设计，结束时把关键结论写入 CLAUDE.md；第二个会话负责落地编码，因为上下文从 CLAUDE.md 加载，不需要重讲背景；第三个会话做评审和收尾。每次会话都轻装上阵，效果远好于一个超长会话一口气讲完所有事。这个习惯还有一个隐藏好处：会话历史是团队的知识资产。散落在一个超长会话里的决策过程很难被复用，但分阶段会话的结论可以通过 CLAUDE.md 沉淀下来，变成团队长期积累的一部分。我们后来能快速让新成员上手项目，很大程度归功于这样沉淀下来的量化文档，而不只是 AI 本身的能力。5.3 团队协作约定：配置入库、代码过审、密钥不外传最后补充几条团队级的协作纪律，它们不属于技巧，但决定了前面所有技巧能不能长期稳定发挥作用。第一，所有配置文件进版本库。CLAUDE.md、settings.json、commands 目录都纳入代码仓库管理，任何人对配置的修改都要走合并请求流程。这样既能统一大家的使用基线，也便于回滚错误配置。团队新成员克隆仓库后就拿到了全套最佳实践，不需要口头传教。第二，AI 写的代码同样要走评审。我们内部有一条硬性约定：AI 直接提交的代码不允许绕过 code review 合入主干。AI 可能反复犯同一个逻辑错误，尤其在自己写的代码里自我评审时容易失灵，人工评审是最后一道防线。第三，密钥和敏感信息严禁进入对话。绝对不要把数据库密码、云服务密钥、个人凭证粘贴进 prompt，也不要让 AI 读取包含敏感信息的配置文件。它的上下文可能被记录用于调试，一旦泄露就是安全事故。我们的做法是敏感配置一律从环境变量读取，Claude Code 的工作目录里只放不含秘密的示例文件，从源头避免这些问题。这几点不是技术问题，是流程设计。AI 工具带来的效率增益越明显，越需要明确它产生的代码和修改如何进入团队的正式交付体系，否则效率和风险会一起增长。以上十条是我们验证过、正在稳定使用的实践集合。如果你刚开始用这类工具，别试图一次全上，先挑团队当前最痛的场景选两三条跑起来，稳定后再逐步扩展，节奏稳比效果好更要紧。