Claude Code 出来半年多我从最初拿它当高级补全工具到后来真正把它当架构师用中间踩了不少坑也总结出一套还算稳定的打法。第 1 期聊过基础安装和日常提效这期我想认真讲讲怎么把 Claude Code 从帮你写代码的助手升级成能帮你做技术决策的 AI 高级架构师。很多人用 AI 编程工具停留在给我写个函数这个报错怎么解决的层面这当然有价值但你只是在用它的手没用上它的脑。真正把 Claude Code 用出架构师水平核心在于三件事让它理解你的项目全局、让它参与技术方案设计、让它独立执行完整的工程链路。这篇文章会围绕这三个点把我在实际项目里验证过的做法、提示词和避坑经验全部摊开来讲。内容会比较长适合已经装好 Claude Code、写过几个小项目、想往深度方向突破的人。如果你还没安装环境建议先看第 1 期把基础补上再回来看这篇。1. 为什么说 Claude Code 能当架构师三种 AI 编程工具的段位差异先聊一个基础但很多人没想透的问题影响 Claude Code 到底能做多难的事。市面上 AI 编程工具看着很多但按能力层级其实能分成三档理解这三档差异你就明白为什么有些工具只能写函数而 Claude Code 能做到架构师级别。第一档是补全型工具。像早期的代码补全插件基于当前光标位置和上下文预测你下一行要写什么。它们的问题在于只有局部视野看不到整个项目的结构更别提理解业务逻辑。你让它写一个全局状态管理的方案它只能给你拼凑一段看起来像模像样的代码但和项目里其他模块的耦合关系它根本不知道。第二档是对话型工具。ChatGPT、Copilot Chat 这类能针对你贴出来的代码片段做解释、修改能力上限取决于你给它多少上下文。问题在于上下文是你手动喂的它永远只看到你展示给它的那一小块世界而且很多工具不能直接操作你的文件系统它给了方案还得你自己去改。第三档是代理型工具。Claude Code 属于这一档它能直接读取项目目录结构、搜索代码、打开文件、执行终端命令、运行测试、提交 commit也就是说它拥有的是整个项目的全仓视野并且拥有执行能力而不只是对话能力。这个差异是根本性的。我做过一个对比实验让对话型工具和一个代理型工具各自给一个遗留项目加日志追踪功能。对话型工具只能根据我贴出来的几个文件来回修改而 Claude Code 直接顺着调用链把入口、中间层、数据库访问层全部读了一遍然后自己定位到最合适的埋点位置改了 6 个文件跑通测试全程我只说了两句话。但这里必须说清楚拥有能力不等于自动具备架构师水平。我的真实体验是Claude Code 默认状态下更像一个执行速度快、但只对当前任务负责的高级开发工程师你要通过工作方式、提示词设计、流程约定才能把它调教成架构师。下面几章就是具体方法论。2. 展开实战的底座环境准备、模型接入与配置规范在谈工作流之前先把环境这层打扎实。很多进阶玩法能不能落地取决于你有没有给它配一个稳定可靠的运行底座。我见过不少人在这一步偷懒后面全崩。2.1 安装方式的取舍Claude Code 官方推荐 npm 安装这是全平台通用的方式前提是你的机器上有 Node.js 18 以上版本。装完直接在终端运行claude就能进入交互界面。如果还没装一条命令的事npm install -g anthropic-ai/claude-codeWindows 用户需要稍微注意一下Claude Code 在 Windows 上的终端能力是受限的很多依赖 shell 的复杂操作没法跑。我的建议是 Windows 上装完就尽量配合 WSL 用把项目放在 Linux 子系统里操作能少踩很多坑。如果你用 VS Code可以直接装官方扩展在编辑器里调起 Claude Code好处是看到代码上下文更直观。但我个人还是更习惯独立的终端窗口因为 Claude Code 执行终端命令时会输出大量过程信息独立窗口看更清楚不会被编辑器面板的空间限制影响。2.2 模型接入的三种方式和我的推荐Claude Code 的模型接入有三条路径很多人搞混订阅登录有 Claude 订阅账号就能直接登录适合日常高频使用不用自己管理 Key但每天调用量有配额限制。API Key 直连从控制台申请 Anthropic API Key写入环境变量ANTHROPIC_API_KEY即可。这种方式按量计费灵活性强适合重度使用。接入本地或第三方模型Claude Code 支持通过重定向 Base URL 接第三方服务。我一直用 LM Studio 拉本地模型做离线调试再切换到云端跑正式任务这样既能保护敏感代码又能省点云上费用。安装完 LM Studio 后在设置里启动本地服务然后export ANTHROPIC_BASE_URLhttp://localhost:1234/v1这里有个容易被忽略的细节Claude Code 的底层接口依赖特定参数格式不是所有本地模型都能完整兼容。实测下来接本地模型时任务复杂度要降低预期写写脚本、修修 bug 可以做大型重构就明显力不从心。所以我的建议是本地模型用于日常小改和隐私敏感实验重大项目还是走官方接口。2.3 权限模式防止 Claude Code 乱来高级用法里最容易被忽略的是权限配置这决定了你敢不敢让它自动跑命令。默认情况下Claude Code 执行每个终端命令前都会征求你的同意这在初期很安全但你也发现效率太低——查个文件列表也要问你一遍。我的做法是用--permission-mode参数和配置文件做分级授权。对只读命令直接放行对写操作保持确认对不可逆命令比如删库、强制推送绝对拦截。配置文件里可以这样设置claude --permission-mode acceptEdits还可以用settings.json里的permissions.allow和permissions.deny列表做细粒度控制。比如允许git add/commit/push但禁止rm -rf{ permissions: { allow: [git status, git add ., git commit -m *, git push], deny: [rm -rf, git push --force, drop database*] } }这一步不要嫌烦它组的就是你的安全底线。Claude Code 执行能力越强你越需要一个可控的边界否则高级架构师分分钟变成高危拆迁队。3. 架构师级工作流设计文档驱动、任务拆解与多 Agent 协作环境搞定了下面进入正题。这一章讲的是我目前用得最顺的架构师级工作流核心就一句话把 Claude Code 当成一个需要你管理的高级工程师团队而不是一个什么都会的万能回答机。3.1 设计文档先行让 AI 在写代码前先把方案讲清楚我犯过的最大错误是拿到需求直接让 Claude Code 写代码。它写出来的东西跑得通但架构一团糟——所有逻辑堆在一个文件里模块边界模糊扩展基本靠复制粘贴。后来调整的顺序是先让它出设计文档评审通过后才允许写码。比如我想做一个带用户系统的博客平台我的第一步提示词是这样的你是这个项目的技术架构师。在动手写任何代码之前请先输出一份技术设计文档包含 1. 系统模块划分和职责边界 2. 数据库表结构和关键字段设计 3. 核心 API 路由设计 4. 关键业务逻辑的技术方案认证、权限、缓存等 5. 可能的技术风险点 不要写代码只要文档。这一步的效果出奇地好。Claude Code 会花不少 token 去思考全局产出的文档质量经常能和你团队里的中级架构师打个平手尤其在模块划分和数据库设计上给出的方案往往比我第一反应想到的更规范。我拿到文档会先自己过一遍把不对的地方、不符合现有项目习惯的地方标注出来然后让它按批注修订。设计文档驱动还有一个隐性好处它降低了后续代码实现的跑偏概率。有了全局方案Claude Code 后面写代码时不会东一榔头西一棒子而是遵循自己在文档里定下的边界和约定代码结构一致性明显提升。3.2 大任务拆解把做一个系统变成做一系列子任务架构师和普通开发的一个重要差异是能不能把一个庞大的需求拆成有序、可验证的小任务。Claude Code 虽然能一次性处理大需求但它的上下文窗口和注意力都有上限一个复杂系统的代码若让它一口气写完后期必然出问题而且一出就是连锁问题你很难定位是哪一块的逻辑造成整体崩坏。我的做法是要求 Claude Code 把整个项目分解成任务清单存成文件然后逐项执行。提示词大概长这样请把整个项目拆成开发任务清单每个任务需要包含 - 任务名称 - 依赖的前置任务 - 需要的输入文件与输出文件 - 验收标准怎么判定这个任务算完成 - 预估工作量 用表格形式输出最后保存到一个 TASKS.md 文件里。拆完任务以后我每次只让它做当前的一个任务做完跑测试、确认没有问题再进入下一个。这个过程看起来很慢但你回头看整体进度会发现它比让 AI 一口气堆完然后你花三天修 bug 要快得多。高频后也就发现拆解任务的过程本身就是和 Claude Code 对齐认知的过程相当于在设计阶段就完成了隐性需求澄清。它对任务的理解越一致后面写出来的东西就越少返工。3.3 多 Agent 协作Claude Code 的多角色并行机制Claude Code 比较新的版本支持多 Agent 协作你可以同时运行多个独立的 Claude Code 会话分别在不同目录、不同分支处理不同模块通过共享文件和 git 分支做交互。我用过一个很有意思的三 Agent 架构一个负责前端界面一个负责后端 API一个负责数据库与部署脚本。它们三个在各自的分支上互不干扰我这个总指挥只需要定期把它们各自的状态合并、处理代码冲突、做联调验收。多 Agent 的威力来自并行但风险也来自并行——最大的问题就是如果两个 Agent 不理解全局边界会做出互相矛盾的模块接口。所以我在启动多 Agent 之前一定先让一个架构 Agent把接口约定文档写死在开始并行开发之前请先定义好前后端接口契约包括 - 所有 API 的路径、方法、请求响应格式 - 数据模型在前后端的字段命名约定 - 错误码规范 - 状态管理的数据流方向 输出为 API_CONTRACT.md供所有开发会话共同遵守。这个接口契约相当于给了每个并行 Agent 一个共同宪法。一旦定下来你基本可以放手让它们各自跑最后合并时冲突会很少。3.4 用验收标准兜底让 AI 自己给自己打分架构师不仅管拆任务还要管验收。如果你只是让 Claude Code做完了给我看它通常会回复已完成但实际效果怎么样它自己也没跑过。我的习惯是每个任务都必须带验收步骤而且验收要尽可能自动化。比如让它实现一个用户注册接口验收标准就是启动测试服务用 curl 发三次不同参数的请求验证通过与否再写一个针对边界条件的自动化测试跑完给我结果。这样一个任务完成时它自己已经做了一轮自测而不是交给你来做质量把关。Claude Code 执行验证类的命令时强烈建议你把这一步加进权限白名单否则它会频繁停下来等你点确认效率根本起不来。4. 从零实战一个完整系统团队知识库的全流程复现方法论讲了那么多落实到具体项目上是什么体验我拿一个真实做过的小项目当案例完整的流程拆给你看。项目是一个内部团队知识库需求包括 Markdown 文档管理、全文搜索、按标签分类、简单的用户权限。难度不算高但涉及前端、后端、数据库、搜索索引多个模块用来演示架构师级实战很合适。4.1 一句话需求到技术选型我的第一步就是让它做技术选型。这里有个反直觉的要点你没有必要自己做选型但你要有能力判定它的选型是否合理。我给的提示词会包含项目背景和约束条件我们要做一个团队内部知识库主要功能是 Markdown 文档的增删改查、全文搜索、标签管理、简单的多用户权限。团队熟悉 JavaScript 技术栈部署环境要求简单预算有限不希望引入太重的基础设施。请给出一套技术选型方案包括前端框架、后端框架、数据库、搜索方案的推荐说明理由并指出备选方案。Claude Code 给出的方案是前端 React Vite后端 Node.js Express数据库 SQLite全文搜索用 SQLite 的 FTS5 扩展。理由是这套组合部署最简单单机就能跑数据量在十万篇文档内完全够用不需要为了看起来高级而引入 Elasticsearch 这种重组件。这个方案理性且克制我认可了。这里也体现出我用它当架构师的一个原则它说的技术选型未必是市面上最先进的但往往是最契合你给定约束条件的只要逻辑链条清晰就可以采用。4.2 设计评审与代码生成的衔接选型确定后进入前面提到的设计文档环节。我让它产出数据结构、API 设计和模块边界。这里有个值得强调的经验在设计阶段尽量要求它同时给出反例比如让它在设计表结构时说明为什么 token 字段不放在 users 表里这类问题。这个操作能让它主动暴露潜在设计陷阱比让它光给出方案更有价值。评审通过后我按 3.2 节的方法让 Claude Code 自己拆任务。它拆出来的任务大致是这样的清单任务一搭项目脚手架Vite Express SQLite 初始化任务二数据库迁移脚本和基础表创建任务三文档 CRUD API Markdown 渲染任务四FTS5 全文搜索接口任务五用户认证与权限中间件任务六前端文档编辑页面任务七前端搜索结果页与标签筛选任务八联调与端到端测试每个任务都写了验收标准和依赖关系。整个开发过程中我只做了一件事盯着它一个个跑完任务每个任务结束时要求它运行自测命令给出测试输出截图或关键结果。整个项目从零到能跑大概花了一个下午其中大部分时间是在等它执行命令。4.3 代码审查环节让 AI 当自己的 Code Reviewer系统跑通之后先别急着庆祝。架构师级的项目要过的一关是代码质量。我让 Claude Code 对自己的产出做一轮代码审查请以资深代码评审员的视角审查当前项目里所有核心模块的代码重点关注 1. 有没有明显的逻辑漏洞 2. 错误处理是否到位 3. 是否有不安全或低效的写法 4. 是否存在重复代码和可以抽象的地方 按问题描述 - 所在文件 - 影响程度 - 修复建议的格式输出然后在获得我的确认后再修改。这一轮查出来的问题还挺有价值发现一个用户输入没做 XSS 过滤的漏洞、一个全文搜索在空查询时会导致全表扫描的性能隐患、两处重复的日期格式化逻辑。它能做代码评审这件事本身不算新奇但胜在它看得全因为它记得整个项目是自己写的能跨文件比对一致性和潜在风险。这个优势是人工 review 做不到的。5. 高级实战中的常见坑我替你踩过的那些雷最后分享一些高段位实战中一定会遇到的坑。这些坑都很隐蔽网上的教程基本不会写但实际项目里它们能让你浪费大半天。5.1 上下文长度是硬边界大项目里的失忆问题Claude Code 的记忆不是无限的。当项目文件越来越多每次对话携带的上下文越来越长到了一定程度它就开始顾此失彼——前面定好的接口约定写到后面突然换了一种命名方式早期代码里定义好的常量后期函数里直接拿魔法数字硬写。我的解法是三层重要约定必须写进文件比如项目根目录的AGENTS.md而不是只放在对话里项目级约定AGENTS.md - API 响应格式统一为 { success, data, error } - 日期字段一律返回 ISO 8601 格式字符串 - 禁止在业务逻辑中直接使用 SQL 语句必须走 Repository 层 - 错误处理统一走 errorHandler 中间件每个大阶段开始时主动让 Claude Code读一遍关键文件把约定复习一遍超长任务分段执行做完一段开一个新会话把上一阶段的设计文档、任务清单、验收报告作为新会话的输入。这种外置记忆的思路是 AI 编程时间越久越重要的核心竞争力。5.2 它看起来很自信但会在小问题上连续错Claude Code 有个让人抓狂的特点它的大局观很强但会在细节上连续犯低级错误而且如果你不加约束它会用同样的错误模式反复覆盖自己的修复。比如我遇到过让它改一个日期格式化函数它连改四次每一次都是同一个 bug只是用不同的写法重新犯了一遍。应对这个问题的关键是用测试把错误钉死。只要存在一个测试用例能暴露问题就不依赖它自己想明白直接让它跑测试、看失败信息、再修。用测试说话效率远高于在对话里反复纠正。5.3 终端命令的越权风险权限配置别省有一次我让它优化一个数据迁移脚本它在执行前检查时发现脚本里有一条DROP TABLE IF EXISTS temp_import觉得这个表不存在可以顺手加进去差点把一张生产环境的临时表删了。所幸我配置了 deny 列表拦住了DROP开头的命令。这个经历让我更加坚持权限分级允许范围只覆盖你真正需要的操作其他的一律手工确认。别嫌烦真出事故的时候你就知道这条有多重要。5.4 本地模型接入的适配细节如果你按 2.2 节说的接 LM Studio 本地模型有几个细节提前告诉你免得卡住本地模型的上下文长度通常远小于 Claude 官方模型复杂任务会提示上下文超限你不要硬让它做拆碎了再做LM Studio 的 API 格式和 Anthropic 的接口存在差异Claude Code 会通过兼容层做转换但不是所有模型都能很好支持工具调用功能实测部分模型会听不到终端命令返回值表现为它执行完命令后自言自语你可以观察它是否在根据命令输出调整下一步行动本地模型跑设计文档生成这种纯文本任务表现不错跑修改代码并验证这种需要工具闭环的任务就费劲。按任务类型分流把能用本地模型扛的扛下来把复杂的留给云端。这些是我自己实践中的配置实测结论不同版本可能有所不同如果你发现行为不一样优先检查模型参数和 Claude Code 版本很多时候是模型对工具调用的兼容性差异替换模型大概率能解决。6. 从高效工具到真正的架构师最后几个习惯建议文章聊到这里方法论和实操案例都给了最后我想说一点更软性但很重要的经验。Claude Code 的定位是代理型 AI它已经从单纯的代码生成工具进化为可以参与工程决策的协作者。但你需要清醒认识到它做不了一个真正的架构师的全部工作。真正的架构师要背锅——上线出问题、业务方改需求、团队产能不足这些决策它替你扛不了。它擅长的是在你给出明确约束时给出高质量的技术方案并快速执行但最终的决策权和责任永远在你手里。我在团队里使用它的个人经验是把它当高速高产的方案执行者来用重要决策我拍板格式和细节它补齐全局设计我评审局部实现交它处理验收标准我来定测试执行让它跑。这样配合下来我的角色从写代码的人变成了设定方向、校验结果的人人均产出确实提升了一大截但也不是没有任何代价——你需要花时间学会管理 AI而不是依赖 AI。最后分享一个小习惯每次项目结束后我会让 Claude Code 把这次实战里踩过的问题、用过的有效提示词、总结出的项目规范追加到AGENTS.md里。这个文件是你的AI 团队记忆库半年之后你再开新项目它带着这些经验直接起飞少犯反复犯的错。工具本身只会越来越强但你能不能把它用出架构师的水平最终取决于你自己是否愿意在设计、评审、复盘这些非编码动作上下功夫。