★ FEATURED ARTICLE 我最早用 Claude Code 的时候坦白讲是把一个能读代码的 AI 当成了高级补全工具。让它“改一下这个函数”它确实改了但半天之后我发现它把另一处调用给忘了。后来我才意识到问题不在模型在于我根本没做配置。Claude Code 的默认形态更像一个临时外包每次对话都要重新交代背景而经过完整配置之后它才能变成一支长期磨合的工程团队——有团队手册、有专项专家、有流程门禁、有外部系统接入。这也是这篇指南想解决的核心问题如何把一个 CLI 工具配置成一支能真正交付的 AI 工程团队。文章会沿着环境准备、CLAUDE.md、子代理与 Skills、Hooks 与 MCP、团队协作工作流、实战案例和避坑记录这条路往下走。适合正在用或准备用 Claude Code 落地项目的个人开发者、技术负责人也适合想在公司内部建立统一 AI 工程规范的人。我的所有结论都来自真实项目里的反复试错配置不是玄学是可以复现的东西。1. 为什么说 Claude Code 应该被配置成一支“工程团队”1.1 默认形态下它是一个记忆力很差的外包在没有做任何配置的情况下启动 Claude Code它确实能理解当前仓库的代码、能读文件、能执行命令但每一次新对话都基本从零开始。你告诉它“我们项目里所有接口都用 Result 对象包裹”它这次记住了等你换一个终端窗口或者开了第二个会话它又忘了。上下文窗口再大也扛不住这种反复解释。我印象最深的一次是让 Claude Code 给订单模块加一个查询接口。它在 service 层直接返回了裸数据完全没有经过统一响应包装。代码能跑但和整个项目的规范完全不搭。后来我才发现不是它不听话而是我没有把这些规则写进它的“团队手册”。1.2 团队化配置的四个支点如果你把一个没有配置的 Claude Code 看成一个临时工那配置完之后它应该更接近一支有角色分工的固定团队。我通常会从四个维度去搭建这套体系配置元素对应工程团队角色解决的核心问题CLAUDE.md团队手册/文化规范让 AI 知道项目基因、技术栈、规矩Subagents子代理专项专家让不同任务由不同角色负责减少上下文串味Skills标准化作业流程把高频任务沉淀成可复用的 SOPHooks / MCP质量门禁与外部工具链把流程卡点和外部系统接进 AI 的操作链路这四个支点不是各自孤立的。CLAUDE.md 负责统一认知子代理负责分工Skills 负责把流程固化Hooks 和 MCP 负责把 AI 的行为放到受控的轨道上。少了任何一个这个“团队”都会显得不完整。1.3 配置之前先想清楚交付边界我见过不少团队拿到这个工具之后第一反应是“让它把整个项目都写了”。这个思路会把人坑得很惨。Claude Code 再强它也不清楚你老板的真实意图、客户的隐藏需求、代码上线后的运维约束。配置的目标不是让 AI 替代人而是把重复性、有规则可循的事交给它让人专注在决策和判断上。所以我的习惯是在写任何配置文件之前先列一个“什么交给 AI、什么必须人审”的清单。比如交给 AI脚手架代码、单元测试、接口文档、重构建议、代码风格修复。必须人审数据库迁移方案、权限设计、对外协议变更、架构选型。边界想清楚了后面的配置才能有的放矢。2. 环境准备Node.js、Git 与 CLI 安装里那些容易被忽略的细节2.1 Node.js 版本选型LTS 优先Claude Code 本身是 npm 包所以 Node.js 环境是第一道门槛。很多人在这一步就踩坑系统里装的是 Node 16然后直接npm install -g anthropic-ai/claude-code安装过程报各种依赖错误。原因很简单Claude Code 对 Node.js 版本有要求太老的版本跑不起来。我建议用 nvm 管理 Node 版本尤其是要在一台机器上同时维护多个项目的开发者。安装 nvm 之后执行nvm install 20 nvm use 20 node -v选择 Node 20 LTS 而不是最新的大版本原因是 LTS 版本的生态兼容性最稳Claude Code 的依赖链不容易出问题。项目里如果有其他历史约束也尽量保证 Node 版本不低于 18。2.2 Git 用户级配置AI 提交代码时也要“身份”Claude Code 在读取仓库、生成提交、分析 git diff 时都依赖 Git。如果你当前仓库的用户名和邮箱没有配对它执行git commit时会直接报错或者提交出一个奇怪的作者信息。所以先做一下全局配置git config --global user.name Your Name git config --global user.email youexample.com git config --global core.autocrlf input第三行core.autocrlf input是我在 Windows 环境下特别建议加上的避免 AI 生成的代码提交后出现大量换行符变更。如果你是在 macOS 或 Linux 上这行配置也不会造成副作用。2.3 安装 Claude Code 与登录鉴权安装方式很简单官方推荐直接走 npmnpm install -g anthropic-ai/claude-code安装完成后先验证claude --version如果能看到版本号说明核心程序已经就位。接下来是登录鉴权有两种常见路径首次运行claude按提示进入浏览器登录账号。如果是在 CI 或服务器环境直接设置ANTHROPIC_API_KEY环境变量。我在本地机器上一般用账号登录因为可以共用订阅额度在自动化脚本里则用 API Key方便无交互执行。这里强调一句一定要从官方渠道安装和登录不要从来路不明的脚本或镜像拿包否则你交给它的代码都可能成为别人手里的数据。2.4 验证最小可用配置登录完之后建议先跑一个最小测试claude -p 请输出 hello world-p是非交互模式适合脚本调用。如果它能正常返回结果说明整条链路已经通了。接着可以用claude config list看一下当前生效的配置项确认没有异常。到了这一步环境准备就算结束了。3. CLAUDE.md把项目基因写进 AI 团队手册3.1 一本好的项目手册应该覆盖什么CLAUDE.md 的核心作用是让 Claude Code 在每次进入项目时都能快速获得“与项目有关的公共知识”。它相当于团队手册而不是一本大而全的文档。我通常会在里面写四类内容项目定位与架构这个项目是做什么的前端、后端、服务端如何组织。常用命令启动、测试、构建、 lint 分别是什么使用什么包管理器。代码规范与约束返回值结构、命名风格、目录职责、禁止事项。常见坑比如某些目录不能动某些依赖不要升级某些文件是自动生成。不用担心写得多详细只要把“一个合格同事入职第一天该知道的事”写进去就行。与其让 AI 去猜不如直接告诉它。3.2 全局与项目级手册的加载顺序Claude Code 的 CLAUDE.md 不是只有一个。它支持全局级和项目级甚至子目录级。我个人的理解是~/.claude/CLAUDE.md是全局手册对所有项目生效适合放通用的编码偏好和工作习惯。项目根目录的CLAUDE.md是项目手册放本项目特有的信息。子目录下也可以放 CLAUDE.md当你在子目录里打开 Claude Code 时它会向上查找合并加载。所以我在团队里一般这样分配全局手册维护“我们团队怎么写代码”的通用约定项目手册维护“当前仓库有哪些雷区”。两者合在一起AI 拿到的是完整上下文。3.3 一份可以抄的 CLAUDE.md 模板下面这份是我在某个订单服务项目里实际用过的简化版你可以直接改造成自己的# 项目订单服务order-service ## 技术栈 - TypeScript / Node.js 20 / Fastify / PostgreSQL - 包管理器pnpm ## 常用命令 - pnpm dev 启动本地开发服务 - pnpm test 运行全部测试 - pnpm lint 运行 ESLint - pnpm build 构建产物 ## 代码规范 - 所有接口返回统一使用 ResultT 结构 - service 层禁止直接操作数据库必须走 repository - 错误信息统一从 errors.ts 中引用不要写魔法字符串 - 文件名使用 camelCase组件目录使用 PascalCase ## 禁止事项 - 不要修改 migrations/ 下已执行的迁移文件 - 不要提交 dist/ 和 .env - 不要随意升级 fastify 大版本这份模板并不复杂但很管用。AI 读过之后生成代码的“形状”会立刻变得符合项目风格。3.4 手册也要持续维护CLAUDE.md 最怕的不是写得不好而是写完之后再也不更新。项目架构变了、命令改了、规范升级了手册还在讲旧版本AI 就会按错误信息执行。我的习惯是每次完成一个比较大的需求之后顺手让 Claude Code 自己刷新一下手册。比如claude -p 请根据最近的代码变更检查并更新 CLAUDE.md只更新已经过时的内容这样能保证团队手册跟得上项目演进的节奏。4. 子代理与 Skills给 AI 团队配上专项专家4.1 什么是子代理如果说 CLAUDE.md 让 AI 知道“团队规矩”那子代理就是让不同角色各司其职。Claude Code 支持在.claude/agents目录下放多个 Markdown 文件每个文件定义一个专项角色模型会根据你的需求描述选择合适的子代理来执行任务。一个典型的子代理文件长这样--- name: backend-architect description: 负责后端架构设计、数据模型评审、接口设计。当用户提到数据库、API、服务拆分时使用。 tools: Read, Grep, Glob, Write model: claude-sonnet-4-20250514 --- 你是团队里的后端架构师。你只关注后端设计不负责前端实现。 每次评审时你必须先读取相关代码再给出结论。输出格式如下 1. 现状问题 2. 改进建议 3. 改动范围 4. 风险提示其中description非常关键它决定了模型何时选择这个子代理。写得太宽模型什么任务都丢给它写得太窄它几乎没有出场机会。tools则是它的权限边界不要给子代理配置它用不到的工具。4.2 把代码评审专家落地我团队里最常用的一个子代理就是code-reviewer。它的职责很简单在代码变更之后从侧面挑毛病。它的系统提示词大概是这样的你是资深 code reviewer。你只审查 diff不直接修改代码。 审查时重点关注 - 是否破坏现有接口 - 是否存在类型安全问题 - 是否有明显性能隐患 - 是否偏离项目代码规范 输出格式按严重程度列出问题每个问题给出文件路径和修改建议。实际调用时在 Claude Code 对话里输入code-reviewer然后给它一个指令“请 review 当前分支的 diff ”。它就会以这个专家视角输出评审意见。相比让同一个 Agent 既写代码又做评审这样隔离出来的结果干净得多。4.3 Skills沉淀可复用的操作流程Skills 和子代理不同。子代理更像“角色”Skills 更像“动作”。你可以把一套固定的操作流程写成一个 Skill之后喂给它对应的材料它就知道按步骤执行。在我的.claude/skills目录里有一个create-unit-test的 Skill里面有一份 SKILL.md定义了这个技能的执行步骤先定位被测文件再读取相关依赖然后按项目测试规范生成单测最后运行测试确认通过。这样无论我给 Claude Code 哪个文件只要触发这个技能它都能按统一标准产出测试代码。Skills 的价值在于沉淀。一次调教好的流程团队里所有人、所有项目都能复用不需要每次都重新用对话去教它。4.4 怎么选择子代理、Skills 还是直接 Prompt我的判断标准很简单需要承担一类职责、具备判断力的用子代理。需要执行固定步骤、产出固定格式的用 Skills。临时的一次性任务直接写 Prompt 就好别为每个场景都造配置。配置不是越复杂越好。多一个角色就多一份上下文开销也意味着模型有更多机会选错工具。克制才是这里的主旋律。5. Hooks 与 MCP把质量门禁和外部系统接进流水线5.1 Hooks 是在关键动作上“插门卫”Claude Code 在执行工具调用的时候支持通过 Hooks 在特定事件前后插入命令。我最常用的是PreToolUse也就是在 AI 调用某个工具之前先执行一段检查如果不通过就中断操作。配置文件放在项目的.claude/settings.json里。一个简化的示例{ hooks: { PreToolUse: [ { matcher: Write, hooks: [ { type: command, command: npx eslint $CLAUDE_FILE_PATH } ] } ] } }这个配置的意思是在 Claude Code 准备写文件之前先对目标文件跑一次 ESLint。如果 lint 不过写文件操作就会被拦住。相当于在 AI 的“手”前面装了一根栏杆逼它交付符合规范的结果。不同版本传入的环境变量字段可能略有差异以你当前版本的官方文档为准。5.2 用权限模型给 AI 画行动半径Hooks 能卡流程但真正决定 AI 能碰什么、不能碰什么的是settings.json里的权限规则。我见过最典型的反面案例是把权限全部开到 allowAI 在一次任务中直接改了不该改的文件夹搞得整个工程编译不过。建议在项目里维护一份这样的权限配置语法细节根据版本来{ permissions: { allow: [Read:src/**], ask: [Write:src/**], deny: [Write:secrets/**, Bash:rm -rf *] } }简单来说就是默认能读源码写代码需要确认敏感目录和危险命令直接禁止。AI 需要权限但绝不应该是无限权限。5.3 通过 MCP 接入公司知识库MCP 是 Claude Code 连接外部系统的通道。你可以通过它接入内部文档、数据库、工单、监控系统让 AI 不只是“读代码”还能“查资料”。命令行注册一个 MCP 服务claude mcp add docs --transport stdio -- npx -y your-org/mcp-docs-server执行完之后claude mcp list可以看到已注册的服务。在对话里 Claude Code 就会主动去调用这个 MCP检索相关文档来回答问题。这对我来说是“团队化”非常关键的一步AI 不再依赖我贴文档它可以自己去查。5.4 Hook 太宽也是一种坑给一个项目配了 Write 的 lint hook 之后我遇到过一个问题AI 每次生成测试文件也要跑一遍 lint结果因为测试文件里有些临时写法不通过整个生成任务被反复中断。后来我把 matcher 细化到“只拦 src 目录下的写入”问题立刻消失。所以配置 Hook 和权限的时候范围越小越好。宁可一开始写得窄一点也不要因为“太宽松”和“太严格”两头摇摆。6. 团队协作模式多成员并行、Review 与交接6.1 把需求拆成可并行的子任务一个比较大的需求别让 Claude Code 一口气从头写到底。我对它的工作方式更像带团队先让它读需求、拆任务再把任务分给不同的“工种”去执行。拆任务的时候我会让它输出类似这样的清单任务 A定义数据模型和 repository 层任务 B实现 service 层业务逻辑任务 C补充接口文档和单元测试然后打开两个终端分别用非交互模式并行执行claude -p 完成任务 A边界以 CLAUDE.md 为准这样做的直接好处是可以更快拿到结果更重要的是不同任务之间的上下文不会被互相污染。任务 A 的决策不会因为任务 B 的讨论而走样。6.2 用子代理做 Code Review代码写出来不算完Review 是工程团队的日常。我会让主 Claude 先提交代码然后调用code-reviewer对 diff 做检查再让我自己人工过一遍。实际操作中不必要求子代理把所有问题都找出来它最擅长的是那些“一眼就能看出不符合规范”的问题比如命名、类型、明显逻辑漏洞。真正需要业务判断的还是人。6.3 让 AI 自动生成交接文档任务完成后文档往往是最容易被省略的环节。我的做法是把它变成工作流的一部分claude -p 请根据最近的 git log 和代码变更生成一份简短的变更说明包括做完了什么、有哪些影响点这样做出来的说明可以贴进 commit message 或 PR 描述也可以作为团队同步材料。更进阶的玩法是让 AI 根据变更自动更新 CLAUDE.md 和架构文档让团队手册始终处于最新状态。6.4 团队统一配置怎么分发如果你们团队有好几个人都在用 Claude Code配置就一定要进版本库。我会把.claude/目录包含 agents、skills、settings.json提交到 Git 仓库这样新同事 clone 项目之后所有配置自动就位。但注意.claude/里不要放任何带密钥的东西比如 API Key、个人 token。这些应该放在用户级配置或环境变量里否则一次 git push 就可能泄露。7. 实战工作流让这套配置跑完一个完整需求7.1 场景设定用一个实际场景来验证整套配置现在要在一个已有的 Node.js 仓库里加一个“用户反馈看板”功能需要包含反馈提交、列表查询、按状态筛选三个接口。假设仓库已经搭好了脚手架但没有业务逻辑。7.2 先搭团队手册第一步是创建项目的CLAUDE.md。我写清楚技术栈、接口返回格式、目录职责、测试命令。这个动作我一般不让 AI 代劳因为项目信息需要人来确认AI 只能补充细节。7.3 添加专家角色然后在.claude/agents/下放两个子代理backend-architect负责设计接口和数据模型。code-reviewer负责最后对 diff 做检查。这两步做完基础配置就绪。7.4 让主 Claude 拆解并执行进入交互模式给主 Claude 一个总体指令“根据 CLAUDE.md为反馈看板功能拆解任务并调用 backend-architect 给出数据模型和接口设计方案。”它会先读取项目结构明确要动的文件然后以架构师身份输出方案。确认方案没问题后我再让它按任务列表逐个实现。命令层面没有魔法就是把需求讲清楚然后让它沿着 CLAUDE.md 的规则走。7.5 Review 与收尾实现完成后我执行git add . claude -p 调用 code-reviewer 审查当前 diff给出修改建议根据审查结果让 AI 修改最后跑测试、提交代码。整个流程下来AI 负责了大部分实现和自查我负责确认方向和质量。8. 踩坑记录配置过程中最容易翻车的五个位置8.1 环境变量不生效最无语的是配置了ANTHROPIC_API_KEY但 Claude Code 始终提示未授权。通常是环境变量写进了.env却没有被当前 shell 加载。我在服务器上会先用echo $ANTHROPIC_API_KEY确认变量真的存在再去跑claude。如果是.env文件就手动 source 一次或者直接用direnv管理目录级环境变量省得每次切换项目都踩坑。8.2 CLAUDE.md 写太长吞掉大量上下文CLAUDE.md 内容过多也会带来问题模型每次读取手册都要消耗 token一旦手册超过某个量级反而会影响它在任务里的判断效率。我自己经历过一次项目手册写了上万字结果 AI 在回答简单问题时都要“翻半天手册”效果非常差。现在我会要求 CLAUDE.md 控制在 200 行以内太细的规范放到子代理或 Skills 里按需加载。8.3 子代理的 description 写得过于宽泛如果backend-architect的 description 里写了“当用户提到设计时使用”那模型可能连写一个工具函数都去调用架构师导致输出变得冗长。description 必须写得像触发条件明确到什么情况下用、什么情况下不用。这是需要反复调的地方。8.4 MCP 服务挂起不报错MCP 服务启动慢的时候Claude Code 会一直等表面上看起来像模型卡住了。遇到这种情况别急着重启终端先运行claude mcp list看看服务状态再去检查 MCP 进程的日志。后来我把所有 MCP 服务都改成本地 stdio 的轻量实现稳定性提升明显。8.5 权限配置过严导致频繁打断有一段时间我把写权限全部设成了 ask结果 AI 每写一个文件都要我确认一次效率低到没法用。现在我采用分级策略src下的新增文件可以自动写入删除操作和修改配置类文件需要确认。让 AI 在可接受范围内自治但关键动作仍然过问。最后分享一点个人的体会这套配置不是一天建成的。我从最初只写了一页 CLAUDE.md到慢慢加了子代理、Skills、Hooks 和 MCP整个过程像在带一支团队一步步磨合。最重要的是保持克制——不要让 AI 团队做了太多它不该做的事。把规则写进文档把边界配成权限把流程挂上 Hook剩下的事情它会慢慢给你惊喜。
阅读完成 · 觉得有帮助？
