企业官网建设流程全解析

做架构设计的时候，最怕什么？最怕面对一个空目录无从下手。我在过去半年里，用Claude Code把大量重复性的架构规划、模块拆分和代码生成工作交给了AI，实测下来，效率提升是实打实的，踩过的坑也不少。这一篇是光子AI实战系列第五章的上半部分，主要聚焦两件事：怎么让Claude Code帮你做项目架构设计，以及怎么用它稳定地产出能跑的代码。适合已经把Claude Code跑通、准备在真实项目里落地的开发者，也适合想给团队定一套AI编码规范的Tech Lead参考。

先给你吃颗定心丸：Claude Code不是那种只会吐建议的聊天框，它是个能直接读你磁盘代码、执行命令、批量改文件的命令行编程智能体。这种"能动手"的属性，决定了它特别适合干架构落地和代码生成。但工具再强，用法不对照样翻车。这篇文章不写官方文档里那种干巴巴的介绍，只讲我在真实微服务项目里怎么拆架构、怎么喂需求、怎么验收生成代码，顺便把那些常规教程不会写的教训一并交底。

1. 项目架构设计：先想清楚，再让AI动手

1.1 为什么架构设计环节最适合引入Claude Code

很多人有个误区，觉得架构设计是"人类高级思维活动"，AI干不了。这话一半对一半不对。AI确实不具备你对业务全局的洞察力，但架构设计的落地步骤其实高度结构化：定边界、拆模块、理依赖、约定接口规范、排出目录结构。这些步骤一旦你对业务想明白了，剩下的填充工作极为繁琐，而且特别容易因为"太熟了"而马虎。

Claude Code在这种场景下的优势一句话概括：它能站在项目全貌上看问题，而不是盯着某一个文件抠细节。你给它一个仓库，它能递归理解目录结构、阅读关键文件、梳理模块间的依赖关系，然后基于整个代码库来回答问题。这就是它跟普通对话式AI最本质的差异——普通AI只能基于你粘贴的片段给建议，Claude Code能自己去看代码。实测中，它对中大型项目（几万到几十万行代码）的理解能力完全够用，不需要你手动把每个文件都贴给它。

另一个优势是执行链路完整。架构设计通常牵扯到大量"改一处动全身"的操作：新建目录、移动文件、统一修改引用路径。人工做这些事繁琐且容易漏，Claude Code可以一口气执行完，中间遇到失败还能自己分析报错、修正重试。我经常跟团队说，把Claude Code当成一个"自带勘察能力的施工队"，你负责画图纸，它负责按图施工。

1.2 先写架构上下文文档，再让AI干活

直接上来就甩一句"给我设计一个微服务架构"，Claude Code大概率会给你一套"正确但没用"的方案——通用模板谁都会写，问题是它不知道你的真实约束。我自己的血泪教训：早期用AI做架构，经常拿到一套很标准的DDD分层，但落到项目里就是水土不服，因为技术栈、团队习惯、部署方式全是变量。

后来我沉淀了一套做法：在动手前，先写一份《架构上下文文档》，把AI需要知道的关键约束一次性喂给它。这份文档不需要很长，但必须包含五类信息：

• 项目目标与边界：这个系统解决什么问题，哪些功能明确不做
• 技术栈约束：语言、框架、数据库、消息队列、部署方式，越具体越好
• 模块划分倾向：哪些业务领域需要独立成模块，允许依赖的方向
• 代码规范要求：命名风格、分层约定、接口风格、异常处理偏好
• 刚性与柔性约束：哪些是死规矩（比如"禁止循环依赖"），哪些可以灵活

写完之后，不是让AI直接生成代码，而是先让它基于这份上下文输出一版架构设计说明。我来审，审完再让它动手。这一步叫"先对齐认知，再分配任务"。你会发现，给了上下文之后，AI产出的架构方案质量完全是另一个量级——它不再是空泛的八股文，而是贴着你的项目情况给出的具体决策。

这里还有个很多人忽略的技巧：架构上下文文档写好后，放到项目根目录命名为CLAUDE.md。Claude Code有个机制，每次会话启动和关键操作前会自动读取这个文件，相当于你给AI配了一个"项目背景记忆"。以后不管谁在项目里启动Claude Code，它都会自动知道这些约束，不用每次重新解释。如果你团队里有多个项目，可以在各自仓库里都放一份，实测下来能大幅减少AI"忘事"和"自作主张"的情况。

1.3 把架构决策拆成AI能执行的阶段性任务

架构设计最忌讳一次让AI干太多。我见过不少朋友让Claude Code"设计并实现整个系统"，结果AI跑着跑着就走样了，要么模块风格前后不一，要么中间某一步失败后开始乱改无关文件。原因是目标太宏大，AI没有"分段完成"的约束，容易放飞。

正确的姿势是把架构落地拆成阶段性的原子任务。比如做一个微服务模块，我会拆成四步：

1. 基于架构上下文文档，输出目录结构和核心模块职责说明
2. 按确认后的目录结构，先建空骨架（不写业务逻辑，只建文件和接口签名）
3. 逐模块填充业务代码，每次只处理一个模块
4. 全程跑测试和编译，验证骨架没有被破坏

每个阶段之间，我都要停下来看一眼，确认无误再放行。听起来好像把AI当成"实习生"在用，没错，就是要用管理实习生的心态来管理AI：目标明确、边界清晰、分步验收。这样看起来多花了几次交互的时间，但整体返工率低得多，算总账其实是快的。

关于拆分的颗粒度，我的经验是：每个任务的范围控制在"一次能交代清楚、AI能独立完成resume"的程度。什么叫能独立完成？就是这个任务失败后，AI不需要问你任何问题就能自己重试。如果一个问题反复出现，说明任务拆分得还是太粗，继续往小里拆。

2. 代码生成的核心细节：从需求到可运行代码

2.1 需求的"三明治"写法

很多人让AI生成代码，直接把产品需求说明书贴过去，或者更省事，丢一句"帮我写个用户登录功能"。代码生成的第一步不是写代码，而是翻译需求——把业务需求翻译成AI能准确理解的技术任务。这个翻译过程做得越到位，生成代码的质量越高。

我用下来最有效的需求描述结构，叫"三明治"写法：顶层放目标与验收标准，中间放关键业务规则与数据约束，底层放技术实现要求。三层结构配合使用，比一堆自然语言描述要清晰得多。

举一个真实例子。我需要一个订单模块的仓储层代码，需求是这样写的：

• 目标与验收：实现OrderRepository接口及MyBatis实现，支持分页查询、按状态统计、批量插入，所有方法必须有单元测试覆盖，测试使用内存数据库
• 业务规则：订单状态枚举包含PENDING、PAID、SHIPPED、COMPLETED、CANCELLED；分页默认每页20条，最大100条；批量插入单次不超过500条
• 技术约束：使用Spring Boot 3.x、MyBatis-Plus、Java 17；禁止在Repository层写业务判断；日期字段统一使用LocalDateTime；方法命名遵循现有代码风格

你有没有发现，这个需求描述里几乎没有一句废话，全都是AI可以直接落地的信息。特别是"技术约束"里的"禁止在Repository层写业务判断"，这种显式负向约束极其重要。AI生成代码时默认倾向是"求全"，你如果不告诉它某些事情不要做，它往往会给你加一堆看似贴心实则越权的逻辑。

填写需求描述时还有一个切入点容易被忽略：约定"不要做的事"。比如"不要生成多余注释"、"不要引入新依赖"、"不要改其他模块的文件"。AI默认不会主动遵守这些，你说一次它记得住一整轮会话，但新开会话就得重新交代。这也是我前面强调CLAUDE.md的原因——把这些约定写进项目级配置，AI每次都会自动读到。

2.2 生成代码的验收清单

代码生成出来不等于能用。我给自己定了一套验收清单，每次AI生成完代码，我照着清单过一遍，基本能筛掉八成的问题：

• 编译与测试：在提交前先跑完整构建和测试，确保没有红
• 依赖检查：有没有引入多余的第三方库，版本是否与项目现有依赖冲突
• 风格一致性：命名风格、目录位置、注解用法是否与周边代码一致
• 边界处理：空值、超限、并发场景有没有处理，还是直接裸奔
• 安全性：SQL拼接、权限校验、敏感信息是否硬编码
• 不可疑修改：AI有没有顺手改了与任务无关的文件

这里我要说一个非常实用的检查方法：让AI自己说明改动了哪些文件、每个文件改了什么。Claude Code本身支持追踪项目状态和差异对比，你在它完成任务后可以直接问它"列出本次修改的所有文件及变更原因"。AI能说清楚的部分通常没问题，最怕的是它支支吾吾说不清为什么要改某个文件——那种改动大概率是多余的，直接回退。

另外，千万别迷信AI生成的单元测试。我并不是说AI不会写测试，而是它写的测试容易"只测快乐路径"。我自己踩过这种坑：AI生成的测试把正常流程测得很全，覆盖率数字也好看，但边界条件一个都没有。解决方案是验收清单里加一条"必须包含至少一个异常路径测试用例"。你可以在需求描述里直接写明要几个成功用例、几个失败用例，AI会更听话。

2.3 大段代码一次生成，还是分批生成

对于比较大的功能模块，分批生成永远优于一次生成。原因很简单：AI的注意力窗口是有限的，一次交代的事情越多，每件事分到的"注意力"越少，生成质量和一致性就越差。我实测下来，一次性让AI生成一个完整的CRUD模块（Controller到Mapper全链路），前几个文件质量还行，越到后面越容易偷懒，甚至出现接口签名对不上、重复代码之类的问题。

分批生成的做法是：按依赖顺序切分，先生成底层再生成上层。比如做Web服务模块，先让AI生成领域模型和仓储接口，验收通过后，再生成持久层实现，然后是Service层，最后才是Controller层。每一层在上层生成前都要标注清楚"下一层依赖的接口已经存在，不要重复定义"。这样既控制了单次任务的复杂度，又保证了层与层之间的衔接。

这里顺带说一个提升准确率的小技巧：给AI提供"参考实现"。如果项目里已经有一个模块的代码风格是你满意的，告诉AI"参考user-service模块的UserController，按同样的风格实现order-service模块"。AI对模仿风格的完成度相当高，比用语言描述"请你把风格写得优雅一点"靠谱一万倍。

3. 实操过程：一个微服务模块从0到1的完整拆解

3.1 环境准备与模型接入

在进入实操之前，先把环境说清楚。Claude Code目前以命令行工具和桌面版两种形态分发，日常使用建议直接装CLI版本，配合VS Code插件能获得比较顺手的编码体验。安装方式不复杂，在终端执行官方安装命令即可，Windows、macOS、Linux都支持。装完之后可以在终端里输入claude唤起交互界面。

平时我不建议在终端交互框里碎碎念式地聊天，效率太低。更高效的方式是在系统终端里直接执行非交互式命令，比如：

claude "基于现有代码风格，实现用户模块的仓储层，要求包含分页方法"

像这样把任务作为参数直接传入，Claude Code会用默认配置和项目上下文处理任务，处理完直接返回结果。这种方式在自动化脚本和批处理场景里特别省事。

关于模型配置，Claude Code默认连接Anthropic官方的Claude系列模型，但如果你的团队有成本考量或者统一使用其他模型供应商的需求，也可以通过API兼容方式接入第三方大模型。社区里有不少工具专门做模型配置管理和切换，比如cc-switch这类配置管理工具，可以在不同模型供应商之间一键切换，把DeepSeek、Qwen、GLM等模型接入Claude Code。切换前务必确认你选的模型具备足够的工具调用能力和长上下文处理能力，否则会遇到指令不执行或者跑到一半断片的问题。

我自己的建议是：如果做的是严肃的架构设计和代码生成工作，优先选推理能力最强的模型；如果是简单重构、批量改命名这种机械任务，用成本更低的模型也没问题。按任务类型匹配模型，才是合理的成本策略。

3.2 让AI搭建项目骨架

现在开始实操。假设我们要用Claude Code生成一个新的微服务模块payment-service，技术栈是Spring Boot 3 + MyBatis-Plus + PostgreSQL，放到现有多模块Maven工程里。

第一步，先把架构上下文文档建好。我在项目根目录创建一个CLAUDE.md，写上这个模块的技术栈、目录约定、命名规范和"不能动其他模块"的约束。接着启动Claude Code，给它下达搭建骨架的任务：

在当前Maven多模块工程中新建payment-service模块，严格遵循项目根目录CLAUDE.md中的约定。 需要完成的内容： 1. 创建标准Maven目录结构和pom.xml，继承父工程的依赖管理，不要引入新依赖 2. 创建包结构：controller / service / repository / entity / dto / common 3. 在entity中定义Payment实体，字段包括：id、orderId、amount、status、channel、transactionNo、createTime、updateTime 4. 在repository中定义PaymentMapper接口，继承BaseMapper 5. 生成一套基础配置类，支持后续接入PostgreSQL 只搭骨架，不要实现具体业务逻辑。

这一步的关键词是"只搭骨架，不要实现具体业务逻辑"。如果你不明确说这句，AI会在建骨架的同时给你写一堆推断出来的业务代码，而这些代码90%都不符合你的真实需求，白白增加审查负担。

AI执行完成后，我会让它列一下生成的文件清单，对照需求逐一检查目录结构和pom依赖。实测中这一步翻车率最高的地方是pom.xml——AI偶尔会给子模块引一些父工程里根本不存在的依赖版本，编译直接挂。遇到这类问题不用慌，让它读取父pom的依赖管理配置，照着改。

3.3 逐层填充业务代码

骨架确认无误后，进入逐层填充阶段。我会继续分三步走，每步一次交互。

第一步生成领域模型和持久层。下一轮任务描述我写成这样：

基于payment-service的骨架，实现entity和repository层： 1. 为Payment实体补充MyBatis-Plus注解，表名映射为payment 2. 实现PaymentMapper接口，增加自定义分页查询方法selectPageByStatus，支持按状态分页，返回IPage<Payment> 3. 为repository层编写单元测试，使用H2内存数据库，覆盖插入、分页查询和按订单号查询三个用例

这一层生成的代码技术含量不高，但细节陷阱多，最容易出问题的点就是MyBatis-Plus的注解和分页插件配置。所以检查时我会特别关注：主键生成策略、自动填充字段（createTime/updateTime）、逻辑删除字段有没有配置正确。

第二步生成Service层，任务描述补充业务约束：

实现PaymentService及其实现类，包含以下方法： 1. createPayment：创建支付单，状态初始为PENDING；金额必须大于0；同一订单号不允许重复创建 2. markPaid：将支付单标记为PAID，只允许PENDING状态流转，否则抛业务异常 3. queryPageByStatus：调用仓储层分页方法，对入参做基础校验 禁止在Service层拼接SQL或操作Entity之外的数据库对象。业务异常统一使用BizException，错误码定义在common模块中。

这里我的经验是，Service层的需求描述一定要包含业务规则和异常约定，否则AI会在异常处理上自由发挥，动不动就抛RuntimeException，或者干脆吞掉异常。给定了BizException后，它生成的处理逻辑就规矩多了。

第三步生成Controller层：

在payment-service中实现PaymentController，提供以下REST接口： 1. POST /api/v1/payments 创建支付单，入参为CreatePaymentRequest，出参为PaymentResponse 2. POST /api/v1/payments/{id}/paid 标记支付完成 3. GET /api/v1/payments 分页查询，入参为pageNo、pageSize、status 统一返回结构使用Result<T>包装，遵循common模块中已有的ApiResponse约定。参数校验使用Jakarta Validation注解。

每生成完一层，我都会先让AI跑一遍该模块的测试，再进入下一层。三层全部完成后，跑一次全量编译和测试，确认没有破坏其他模块。到这步为止，一个微服务模块的代码生成闭环就完整走完了。

3.4 验证与收尾：让AI自己检查自己

代码全部生成后，还有一道收尾工序：整体审查。我会让Claude Code以"资深架构师"的视角对刚才生成的代码做一次全面评审，明确指出潜在问题并给出修改建议，类似这样：

对payment-service模块做一次代码评审，重点检查： 1. 接口设计是否符合RESTful规范 2. 是否有潜在的空指针、并发问题 3. 事务边界设置是否合理 4. 与common模块的既有约定是否一致 输出问题清单，按严重程度排序，并给出修改建议。特别关注可能会导致线上故障的问题。

这一步的价值在于AI站在"审查者"位置时和站在"生成者"位置时的表现完全不同，生成的毛病它能盯出来不少。拿到问题清单后，我逐条决定接受还是拒绝修改，然后让它执行修复。这一环节也是我跟团队推荐"AI编码双人模式"的核心原因：一个AI负责写，另一个AI负责挑刺，质量比自己一个人闷头写要高出一截。

4. 常见问题与排查技巧实录

4.1 上下文与Token管理

用Claude Code做大型项目的架构设计和代码生成，绕不开一个核心问题：上下文长度。Claude系列模型的上下文窗口很大（最新版本甚至支持百万token级别），但不是说窗口大就万事大吉——上下文越长，模型对关键信息的注意力就越容易被稀释，响应速度也会变慢，费用更是水涨船高。

我的处理策略有三个层次。第一层是"只读必要的"，在开始任务前，明确告诉AI它需要关注哪些目录，不需要阅读哪些目录（比如生成代码时可以忽略test目录、前端代码等）。Claude Code支持把某些目录排除在读取范围之外，这跟人类看代码"先看主干再看枝叶"是一个道理。

第二层是"善用CLAUDE.md"，把项目约束写进去而不是每次都塞给AI。第三层是"及时开新会话"：一个任务域完成后，开启新会话继续下一个任务域，避免旧的历史对话污染新任务的判断。如果发现AI开始"忘记"较早之前交代的约束，或者回答变迟钝，说明该清理上下文了。

还有一个跟触发条件相关的常见现象：当你在一个大项目的根目录运行Claude Code时，它默认会把整个项目结构纳入视野。几万文件的项目光扫描目录就消耗掉大量token。遇到这种情况，可以对AI明确指定一个子目录范围来操作，比如"围绕modules/order目录展开任务，其他目录仅作参考，不要遍历读取"。这个操作对降低Token消耗的效果立竿见影。

4.2 生成质量不达标的排查思路

AI生成代码质量不达标，很多人第一反应是"换个更强的模型"或者是"这工具不行啊"，其实大多数情况下问题出在输入侧。按照我的排查顺序，一步一步来：

先看任务描述是否足够具体。出现幻觉——比如调用了不存在的库函数、编造了Spring不存在的注解——多半是因为你给的约束太少，AI只能靠"想象中的最佳实践"去猜。这时候别急着骂AI，返回去把技术栈、版本号、现有代码风格全部交代清楚，再让它重新生成。

再看任务范围是否过大。生成的代码前后矛盾、接口签名对不上，八成是任务里塞了太多文件，AI顾此失彼。拆小任务重试。

最后看参考信息是否给足。AI频繁询问同一个业务概念，说明你的需求里缺了背景信息，补上对应的业务规则描述，绝大部分问题都能解决。极少情况下，任务描述、参考都给足了，AI还是反复出错，那就是模型能力的瓶颈，换更强的模型或换推理模式试试。

下面这个表格是我整理的常見问题速查，照着排查能省下大量试错时间：

4.3 成本控制与授权管理

日常使用Claude Code的成本问题，团队管理者问得最多。坦白讲，重度使用AI编码确实会产生费用，但远没有一些人想象的那么夸张。控制费用的手段倒也不复杂：按任务类型匹配模型、严格控制上下文读取范围、及时清理长会话。再配合用cc-switch这类配置管理工具在多个模型供应商之间按需切换，成本能够压到团队可接受的范围。

另外一个容易被忽略的方面是授权管理。Claude Code的核心功能之一是可以直接执行终端命令、修改文件系统——这既是它高效的原因，也是潜在的风险点。在团队环境里，不同的项目、不同的任务应该配置不同的命令权限。比如运行测试、代码格式化这类低风险命令可以放行，而删除文件、修改全局配置这类高风险操作必须经过人工确认。Claude Code的命令权限是支持分级的，建议在项目配置里设置白名单机制，把AI的行为关在笼子里干活。

我自己的习惯是：代码提交前手动检查differences，跑完整测试，绝不直接信任AI生成的"提交信息"和"变更摘要"。"信任但验证"这句话放到人身上适用，放到AI身上更适用。

5. 进阶玩法：让Claude Code成为项目里的"长期成员"

5.1 把常用任务沉淀为Skill技能包

用得久了你会发现，很多任务模式是重复的。比如"为新模块生成标准骨架""做一次代码评审""生成数据库迁移脚本"，这些任务的输入输出模式高度固定。与其每次重新描述一遍，不如沉淀成可复用的技能包，也就是Claude Code里的Skill机制。

Skill本质上是把一套提示词、检查清单和执行流程做成可复用的配置，放在项目级或用户级目录里。项目里的其他开发者遇到同类任务时，直接调用对应的Skill，就能获得一致的执行标准和输出格式。这带给团队的价值非常大：它让AI编码的规范不再取决于某个人会不会写提示词，而是沉淀成了团队资产，相当于把架构师的判断标准固化到了工具链里。

我目前最常用的几个Skill包括：新模块脚手架生成、代码变更审查、数据库迁移脚本生成、异常处理规范检查。每个Skill都是边用边迭代的——用完一次发现输出里有个共性问题，就把对应的校验规则追加进去。迭代两三轮之后，产出质量稳定得惊人。

5.2 与IDE深度集成，用熟悉的方式驱动AI

如果你的日常开发主要在VS Code里进行，可以考虑把Claude Code以插件形式集成到IDE环境中。IDE插件跟纯命令行体验最大的区别是：你能直接看到AI修改了哪些文件、diff视图并排呈现，而且可以选中某段代码单独让它重构或解释，交互更贴近日常开发流。

集成后的典型使用流是这样的：在代码编辑器中定位到要改造的类，右键告诉AI"重构这个方法，减少嵌套层级"，它改完之后你在diff面板逐行确认，合适就保留，不合适一键回退。整个过程不用离开编辑器，特别适合代码重构和局部代码生成这类高频轻任务。

我个人的使用习惯是两者配合：命令行负责跑大数据量的架构生成和自动化任务，IDE插件负责日常编码过程中的小步重构。如果你所在的团队对"AI流程"有统一要求，建议在项目文档里写清楚两种使用方式的分工，避免每个开发者各用各的，规范就乱掉了。

5.3 在团队里推广AI编码的几条经验

最后聊聊团队推广的事。我自己带过几个团队引入Claude Code做代码生成，踩过一些管理上的坑，总结几条经验供你参考。

第一条，先固化规范，再放开使用。不要一上来就让全团队自由使用——AI编码的产出质量高度依赖约束和上下文，没有统一规范的情况下，每个开发者喂给AI的信息参差不齐，生成代码的质量也参差不齐。先把CLAUDE.md、Skill技能包、命令权限这些基础设施搭好，再让团队上手，效率会高很多。

第二条，把AI生成的代码纳入正常的代码评审流程。AI写的代码跟人写的代码一视同仁，该走Review走Review，该跑测试跑测试。唯一区别是评审人可以多问一句"这段逻辑的判定条件来自哪里"，这在AI生成的代码里特别值得关注——AI经常会在你没明说的地方替你做了决定。

第三条，留一条"人工兜底"的保留地。涉及核心支付、权限、数据迁移这类高风险模块，我的底线是：AI可以生成初稿，但必须由人逐行审查签字确认，绝不因为AI生成速度快就直接合入主分支。这不是对AI不信任，而是对线上稳定性的敬畏。

我个人在实际操作中的体会是：Claude Code的价值不在"替你写代码"，而在"把你从重复劳动里解放出来，让你有精力盯真正需要判断力的事情"。架构设计请它搭架子、写模板、检查一致性，你负责定方向、守边界、审核心逻辑，这种分工模式，越用越顺手。下一章我会拆解Claude Code在代码重构和遗留系统改造里的实战套路，到时候接着聊。