如果你是第一次听说 Claude Code可能会觉得它不过是又一个“AI 写代码工具”但如果你已经用过一两周大概率会和我有一样的感受——它不是帮你写代码的它是接手整个项目的。所谓“接手项目”不是说你扔一句“帮我做个系统”它就全部搞定而是它具备一个 Senior 工程师的工作方式自己读代码、自己查报错、自己改文件、自己跑测试出现问题时还会告诉你它改了哪里、为什么这么改。这一期宝典我把它定位成“深度实战”目标就一件事把 Claude Code 从一个会写代码的助手调教成能拆解需求、设计架构、统筹落地的 AI 高级架构师。适合已经装好工具、会基本对话的人继续往下钻也适合正在评估“要不要把它引入团队工作流”的人提前看看天花板在哪里。1. 进阶之前先把认知拉齐Claude Code 到底是什么样的“AI 架构师”1.1 从“对话补全”到“自治执行”的本质跃迁很多朋友第一次接触 AI 编程是从 IDE 里的自动补全开始的。光标停下来模型给你补后面几行你删掉一个函数它再给你补一个新的。这种模式有一个天然天花板模型只看见你光标附近的几百行它不知道这个模块被谁调用也不知道测试为什么挂了。所以它只能“补”不能“设计”。Claude Code 的做法完全不一样。它跑在终端里不是一个插件而是一个 Agent。它把“写代码”这件事拆成一个循环先理解你给的目标再判断自己缺什么信息然后调用工具去拿这些信息——读文件、搜目录、跑命令、查报错——拿到之后继续理解和修改直到任务完成或者它主动向你汇报风险。我用一个生活化的类比来解释传统补全工具像打字员的联想输入你写到哪里它帮到哪里Claude Code 更像一位刚入职的高级工程师你给它一份模糊的需求文档它会自己进代码库翻资料、搭环境、写实现、跑测试做完之后把变更清单放在你桌上。这个“自己能主动拿信息”的能力是它能做架构师的根本前提。技术层面这个循环有一个约定俗成的说法叫 Agent Loop也就是“思考 → 工具调用 → 观察结果 → 再思考”。Claude Code 每执行一个动作都会停下来评估效果而不是一口气把答案念完。这意味着它能处理真实工程里最常见的状况某个接口根本不存在、依赖没装、测试挂了。它会在循环里自我纠正这才是能用来做项目的关键。1.2 这一期要构建的四种核心能力理解了它的运行方式再说清楚我们要练哪四种能力。很多人拿到 Claude Code 只是“会问”但离“会用”差得很远。我总结为四个台阶正好对应高级架构师的日常职责。第一个是需求澄清能力。高级工程师接需求第一反应是追问边界给谁用、什么量级、哪些必须、哪些可后置。Claude Code 天然支持这种“多轮澄清”但你得主动让它这样做默认情况下它更倾向于取巧——直接开工。第二个是架构拆解能力。把一个大目标拆成若干可独立验证的阶段。这个能力看似简单实际上决定了 AI 产出的代码是否可维护。你让它一口气做完整项目它就会写出一坨能跑但不负责任的代码你让它分阶段做每一阶段有明确验收标准它就会表现出架构师的一面。第三个是多文件工程能力。真实项目是几十上百个文件交错在一起的Claude Code 能跨文件搜索、修改、保持风格一致。这里的难点不是它能读多少文件而是你如何让它知道“哪部分重要”以及“改动边界在哪里”。第四个是验收与重构能力。AI 写完代码之后你要让它自己审自己写测试、跑测试、发现坏味道、出重构计划。我见过很多人把 Claude Code 当一次性生成器用生成完就跑这是最浪费的用法。让它进入“代码评审模式”才是调教出架构师感觉的分水岭。这四个能力不是孤立技巧而是递进的先澄清再拆解然后并行推进最后验收迭代。后面的实战案例全部围绕这条主线展开。2. 环境与工作台把 Claude Code 调成顺手的高级工程师2.1 安装、登录与基本工作模式先说安装。如果你用的是 Node.js 环境一条命令就能搞定npm install -g anthropic-ai/claude-code安装完成后在任意项目目录下执行claude就会进入交互模式。启动之后它会问你登录方式一般两种一种是订阅账号直接授权登录另一种是 API Key。个人开发者建议用订阅账号跑长任务的时候更轻松如果已经买了 API那就用ANTHROPIC_AUTH_TOKEN环境变量注入别写死在项目文件里。我之前有个朋友装完 Claude Code 之后第一反应是“这不就是个黑乎乎的终端聊天框吗”转头又回到 IDE 里去了。其实完全可以在 VS Code 里用打开终端快捷键通常是 Ctrl直接执行claude它和编辑器可以共享工作区写代码、看报错、跑测试都在同一个窗口里完成体验上和“AI 坐到你的工位旁边”非常接近。VS Code 官方也出过 Claude Code 扩展本质上是把这个终端会话嵌进编辑器侧边栏按自己习惯选一种就行。第一次启动后我强烈建议做两件事。第一件在项目根目录建一个CLAUDE.md这是项目的“交接文档”后面单独讲。第二件用/config看一眼权限模式默认情况下 Claude Code 会在写文件和跑命令前征求你的允许刚上手时先别全部放开等熟悉了它改文件的风格再考虑进入更自由的模式。2.2 环境变量、权限控制与第三方模型接入这里要聊几个工程上非常关键的点。首先是环境变量。Claude Code 原生走 Anthropic API但环境变量是留了口的ANTHROPIC_BASE_URL可以指向任何兼容 Anthropic 接口的服务商ANTHROPIC_AUTH_TOKEN对应你的鉴权信息。也就是说如果你想接入 DeepSeek、Moonshot 这类第三方大模型思路就是开一个兼容接口然后export ANTHROPIC_BASE_URLhttps://your-compatible-api.example.com export ANTHROPIC_AUTH_TOKENyour-token claude启动之后 Claude Code 就会用这个模型作为底层大脑。我的建议是尝鲜可以但核心项目的上下文管理、工具调用稳定性还是优先用官方模型第三方模型更多用来省成本。注意这个兼容端点必须是你自己或厂商合法提供的别拿一些来路不明的代理去跑项目数据落到谁手里你都控制不了。权限控制是另一个不能跳过的话题。默认交互模式下Claude Code 每写一个文件、每执行一条 shell 命令都会弹一次确认。对新手这是保护但做大型重构时会很烦。你可以提前划定允许范围比如允许它读src/和tests/但deploy/、secrets/目录必须每次确认允许跑npm test但禁止执行任何删除命令。这些都是通过/permissions管理的也可以用--permission-mode启动参数直接指定。日常会话有几个命令我几乎每天都在用/resume恢复上次中断的会话/cost看当前会话花了多少钱防止跑着跑着账单吓人/compact可以压缩历史上下文释放窗口空间。这些命令不复杂但能在关键时刻救你一命。2.3 让 Claude Code 记住项目背景CLAUDE.md 的正确写法CLAUDE.md 是 Claude Code 里我最喜欢的设计没有之一。它的作用很简单每次新开会话时Claude Code 会自动读这个文件作为项目的“长期记忆”。很多人的问题就出在“没有写它”导致每次会话 AI 都像个第一天入职的新人什么都要你重新交代。CLAUDE.md 应该写哪些内容我总结了一份模板# 项目交接说明 ## 技术栈 - 前端React 18 TypeScript Vite - 后端Node.jsExpress PostgreSQL - 测试Vitest ## 目录约定 - src/modules/ 按业务域组织 - tests/ 与 src/ 目录结构一一对应 ## 常用命令 - npm run dev 启动开发环境 - npm test 运行全部测试 - npm run lint 代码检查 ## 关键约束 - 数据库变更必须走 migration不允许直接改表结构 - 所有对外接口必须有参数校验和错误码 - 不要在生产环境执行 eslint --fix只改自己需要的代码 ## 待办备注 - 用户模块重构方案尚未评审不要自行实施关键不是格式漂亮而是让 AI 在“动手之前就知道边界”。尤其要写清楚“不要做什么”这比“要做什么”更能避免它瞎改。我试过把这段约束写成“不要在生产环境执行 eslint --fix只改自己需要的代码”后它乱改无关文件的比例明显下降。关于 skills新版本里.claude/skills/目录可以放自定义技能包。每个技能包本质上是一个文件夹里面至少有一个SKILL.md描述文件告诉 Claude Code 这个技能什么时候触发、怎么用。如果你在 GitHub 上看到别人分享的 skills手动安装的步骤非常简单把整个文件夹下载下来放进.claude/skills/下一次会话它就能感知到。不需要编译、不需要注册这就是个“说明书”机制。3. 深度实战样例从需求到上线让 Claude Code 当总架构师3.1 实战目标与初始需求理论说太多没意思我们直接上一场实战。为了贴近真实场景我把目标设定为一个常见的中小型项目给一个内部团队做一套“图书借阅管理 API”。初始需求非常简单就三句话支持图书录入、查询、借出、归还能记录每本书的借阅历史预留后续扩展为多个业务线共用的能力。你拿这个需求直接扔给 Claude Code它大概率会立刻开写然后交给你一堆带着 TODO 的代码。这不是它笨而是你没给它“当架构师”的空间。高级架构师拿到需求的第一反应一定不是写代码而是把需求变成方案。所以第一轮要逼它做方案评审而不是写代码。3.2 第一轮需求澄清与方案评审这是我常用的开场提示词你可以直接复制你现在是一位有 10 年经验的软件架构师。请先不要写任何代码。我需要你 针对“图书借阅管理 API”做需求澄清和方案评审。 请依次完成 1. 列出你看到的需求中不明确的地方必须给出至少 5 个问题 2. 对每个问题给出你的推荐默认值 3. 基于默认值输出技术选型建议说明理由 4. 输出一个分阶段实现计划每个阶段必须有可验证的产出。 注意不确定的信息不要猜测统一标注为 [待确认]。这段提示词里最值钱的其实是最后一句“不确定的信息不要猜测统一标注为 [待确认]”。大模型天生倾向于自信地编造你不立这个规矩它就会把假设当事实写进方案。加了这句之后它会明显收敛把“需要你拍板”的地方圈出来。我实际跑过一次它给出的澄清问题包括是否需要多租户隔离图书的唯一标识是 ISBN 还是系统内部 ID借阅周期是否有上限是否需要预约功能并发借出同一本书怎么处理这些正好是架构师应该关心的点。然后它会给出默认值比如“先按单租户设计但数据模型预留 tenant_id 字段”这种答案直接可作为后续设计输入。方案评审环节我建议你额外加一个约束“技术选型需要给出 2 个备选方案和取舍逻辑”。这样它就不会随便挑一个流行框架应付你而是真的按“团队维护成本、生态成熟度、部署复杂度”来对比。比如它会对比 SQLite 和 PostgreSQL并指出先用 SQLite 快速跑通、后期迁 PostgreSQL 的迁移成本这种“演进式架构”的思路正是架构师的核心思维。3.3 第二轮分阶段实现与验收方案确认后不要让 Claude Code 一口气实现全部功能而是让它按照计划中的第一阶段执行。我的经验是阶段越细交付质量越高。可以这样切入开始实施第一阶段。本阶段目标搭建项目骨架 完成图书数据模型 实现 图书录入与查询接口。 要求 - 只做本阶段内容不要越过边界 - 每个接口都要有参数校验和统一的错误响应结构 - 写完核心代码后自动补充对应的单元测试 - 完成后运行测试并汇报哪些通过、哪些失败。注意这里我故意加了两条“制度性”要求参数校验和测试。如果不加Claude Code 写出来的接口往往连错误码都没有前端对接时直接抓瞎。加了之后它生成的基础代码质量会上一大截。执行过程中你可能看到它频繁地读文件、查目录这就是 agent 在收集信息。如果是大型项目建议先/compact或者新开会话把第一阶段的上下文压缩一下。我常用的做法是每完成一个阶段把“当前进度摘要”写回CLAUDE.md然后/resume或新开会话继续下一阶段。这样 AI 永远带着准确的进度记忆而不是在一坨历史对话里翻找。验收时我会检查三样东西第一测试是否真实覆盖了核心逻辑而不是只跑了个空壳第二接口错误场景是否被处理比如借一本不存在的书会返回什么第三代码风格和既有约定是否一致。这三样过关这一阶段就算真正完成再让它进下一阶段。3.4 第三轮重构与扩展性验证很多教程到这里就结束了但“AI 高级架构师”真正的价值在最后一轮让 AI 自己评审自己的代码并给出重构计划。这一步能让项目从“能跑”进化到“值得维护”。评审提示词我建议这样写请对当前代码进行一次独立代码评审不要修改任何文件。 从以下四个维度输出问题清单 1. 扩展性未来增加多租户时哪些设计会成为阻碍 2. 错误处理哪些异常路径缺失或处理不当 3. 安全性是否存在注入、未授权访问等风险 4. 可测试性哪些模块难以独立测试为什么 对每个问题给出严重等级CRITICAL / MAJOR / MINOR并搭配重构建议。 最后输出一份重构计划按优先级排序明确每步的验证方式。让 AI 审自己的代码听起来像是“让球员给自己当裁判”但实际上很有用。因为它刚写完代码所有上下文都在脑子里能发现真实的耦合和坏味道。我拿到它的评审结果后通常会人工再过滤一遍重点看 MAJOR 以上等级的问题MINOR 的问题让它顺带修掉即可。重构的时候要给它严格的边界否则它会顺手重写整个系统。我的做法是让它的重构计划变成“可勾选的清单”一次只动一步每步都跑一遍测试。比如先抽出一个借阅服务的独立接口测过再重构数据访问层。这种“小步快跑”的做法和人类团队里的重构纪律完全一致也是防止 AI 把整个项目改坏的最有效手段。经过这三轮你已经能看到 Claude Code 不再是一个“写代码机器”而是一个有自己工作计划、会主动暴露风险、并且能自己验收的工程师。这个过程就是本期标题里“打造 AI 高级架构师”的真正含义。4. 高手常用的四个进阶武器Skills、MCP、并行任务、自动化约定4.1 Skills给 Claude Code 装上专用工具包上一节说过.claude/skills/的安装方式这里展开讲一下它的价值。Skills 本质上是把“某个特定场景的最佳实践”打包成说明书让 Claude Code 遇到对应场景时自动按你的规矩办事。它和 Prompt 最大的区别是Prompt 每次都要你敲一遍Skills 是存储在项目里的以后每次会话它都会主动加载。比如我给自己团队写过一个“Code Review”技能包结构大概是这样.claude/skills/code-review/ ├── SKILL.md └── templates/ └── review_report.mdSKILL.md里写明触发条件“当用户要求审查代码或执行 code review 时使用本技能”然后列出评审维度、输出格式、注意项。这样只要我在对话里说“帮我看看这个模块”它就会自动按技能包里的规范输出结构化的评审报告而不是随机应变地给一堆感想。想从 GitHub 手动安装别人分享的 skills步骤很简单把技能文件夹下载到项目的.claude/skills/下确保里面有一个完整的SKILL.md然后重启对话或用/skills命令确认它已经被识别。装完你会发现Claude Code 的不同项目之间完全可以形成“个性化差异”这个项目它像个严谨的审查员那个项目它像个快速原型工具全靠技能包控制。4.2 MCP把外部接口接进对话里MCPModel Context Protocol是另一个改变使用深度的能力。你可以把它理解成 Claude Code 的“USB 接口”不同服务通过这个协议插进来AI 就能直接读写外部数据源。比如你想让它直接查询本地 PostgreSQL 数据库、操作 GitHub 仓库、搜索公司内部文档都可以通过 MCP 服务器实现。社区里已经有不少现成的 server用 npx 就能启动例如文件系统、数据库、浏览器自动化等场景都有现成方案。实战层面我踩过一个坑不要一股脑接一堆 MCP 工具。每接入一个都会占用上下文窗口也会增加 AI“做多余动作”的概率。接一两个真正高频的工具就好比如“项目任务管理”或“内部知识库”其他靠文件读写基本够用。另外MCP 工具的权限边界要比 shell 命令更谨慎来历不明的 server 不要随便接尤其是那些声称“一键自动化”的授权给它等于把终端钥匙交出去。4.3 并行任务与长任务管理真实项目里最耗时的不是写代码而是“等 AI 写代码”。尤其是大型代码库重构、多模块需求分析这类任务单线程一次做一个任务太慢。Claude Code 支持把任务拆开并行处理思路有点像 MapReduce大任务拆成多个小任务分头执行最后把结果汇总。在一个大型代码库扫描场景里我做过一次测试把“分析所有 service 模块的耦合度”拆成按目录分片的多个任务每个任务单独跑一个会话然后把结论合并。整体耗时几乎降了一半。注意拆任务的时候每片之间的依赖要尽量小否则汇总时还得来回对齐反而更慢。长任务管理上我的习惯是“写进度文件”。每完成一个重要阶段让 Claude Code 把决策摘要写进docs/decisions.md或CLAUDE.md。这样无论会话被压缩、中断还是换机器项目的关键上下文都能保留下来。别依赖/resume找历史对话它只能恢复一个会话恢复不了“项目记忆”。4.4 用权限白名单和 hooks 固化团队约定最后一个进阶武器比较低调但工程价值很高权限模式的精细化和 hooks 自动化。先把 Claude Code 开发阶段高频的命令比如npm test、git diff加入白名单减少确认步骤再把危险操作rm -rf、drop table设为每次询问。这套组合下来配合效率和安全兼得。hooks 是更进阶的玩法。它可以定义“在某个事件发生后自动执行脚本”比如在每次 Claude Code 修改完代码后自动跑一次 lint或者在 git commit 前自动格式化。配置方式不复杂在settings.json里声明事件和命令即可。我用得最多的场景是让 Claude Code 完成代码修改后自动运行测试并在测试失败时自动修复一轮再报告最终情况。这个循环极大减少了“人在旁边盯测试输出”的时间。你可以按自己团队的约定扩展比如“提交前禁止生成调试日志”“release 分支禁止直接 push”。这套机制做完你的 Claude Code 使用体验会从“一个人工智能助手”变成“一个小型自动化工程团队”。5. 翻车实录我踩过的坑和排查清单5.1 高频问题速查表用 Claude Code 用了几个月我整理了一份自己的踩坑清单这里直接分享出来现象根本原因解决办法做一半上下文爆了后面开始胡言乱语对话历史太长上下文窗口被占满/compact压缩历史或新开会话并带上 CLAUDE.md改完了 A 文件顺手把无关的 B 文件也改了没给改动边界初始提示词太开放在提示词里明确“只修改与本阶段相关的文件”反复修同一个 bug越修越离谱它丢掉了早期的关键报错信息中断当前循环新开会话把原始报错和最小复现步骤贴进去生成的接口没有错误处理你没在需求里要求错误处理统一在 CLAUDE.md 里声明“所有对外接口必须有校验和错误码”跑的测试全是空壳根本没有断言它用“看起来在写测试”来糊弄验收时抽查是否有真实断言或要求“测试必须 fail 一个真实场景”对话中途卡死命令执行超时任务太大单轮跑不完拆小步骤用阶段式推进避免一次让它做太多这个表里的问题有一个共同点大部分不是 AI 能力问题而是使用习惯问题。Claude Code 的默认行为是“尽量满足你”你没给边界它就会自由发挥所以约束写清楚比换更强的模型更有效。5.2 一个容易被忽略的关键允许它说“不知道”很多人用 AI 编程时最烦的一点是它明明不知道某个库的 API还一本正经地编造。Claude Code 这个现象要少一些因为它可以先搜索代码或文档再回答但依然存在。尤其是在接第三方模型时幻觉问题会更明显。我养成的习惯是在关键任务提示词里明确写一句“遇到不确定的内容输出 UNKNOWN禁止猜测。”比如让它对接一个我没给文档的内部系统就要求它“先检查项目里是否有相关接口定义若没有则标记 UNKNOWN 并说明需要什么信息不得编写虚构的调用代码”。这句话能拦住大量无意义的“假代码”。真实架构师接需求时最忌讳的风气是“不懂装懂”AI 也是一样。另一个相关的技巧如果 Claude Code 输出了一段看起来很合理、但你不确定它对不对的代码直接让它“用 100 字以内解释你这条实现的依据并列出不确定的假设”。它会把自己推理链条中模糊的地方暴露出来方便你快速判断要不要采信。5.3 成本与效率控制心得最后聊一下钱的问题。Claude Code 跑得快、产出高但如果控制不好token 消耗也会很可观。我自己统计过几次完整闭环项目一次从需求澄清到第一版实现基本会消耗几百万 token 的量级折合人民币几百元。这个成本听上去不低但对比一个初级开发蹲两周的工资依然便宜到可以忽略。真正要防的是“无效消耗”。我的三个省钱习惯先把需求拆清楚再动手让 AI 少做无用功这是最省钱的方式每次只做一个小阶段完成就验收不要让它长时间挂机自动迭代长项目尽量用/compact而不是无限加长上下文因为上下文越长单价越贵而且效果反而会下降。如果你只是日常写个小工具CLI 模式下一天可能几块钱放心用如果是企业级长任务建议设定--max-turns限制最大循环轮数防止它陷入“疯狂自我修复”的无限循环。这个参数我一开始没注意某次让它自动调一个 CSS 兼容性问题它连续改了十一轮还没停最后我强制中断花掉的 tokens 已经够吃一顿饭了。我个人现在最深的体会是Claude Code 的上限不是由模型决定的而是由使用者决定的。你把 CLAUDE.md 写得越认真把任务拆得越细致把边界说得越清楚它反馈给你的代码质量就越接近一个真正带过大型项目的高级工程师。如果你也想让它变成你的“AI 高级架构师”别急着让它写代码先从写一份诚实的项目交接文档开始。最后补一句实操建议每周挑一个下午让 Claude Code 把最近一周你写的所有核心模块做一轮独立评审别带预设答案去读报告——它的视角和你不一样往往能指出你在项目里“舍不得删的那坨代码”。这个习惯坚持一个月你对它能力边界的判断会比读十篇教程都准。