企业官网建设流程全解析

1. 为什么“AI-Native SDLC”不是又一个新名词

这两年“AI 原生”这个词被用得太泛了，什么产品都往上面靠。但落到软件研发这条链路上，AI-Native SDLC 其实指向一个非常具体的东西：把 AI 智能体当作研发流程里的一等公民，而不是一个外挂的聊天窗口。传统 SDLC 里，需求、设计、编码、测试、部署、运维是一条人驱动的流水线，AI 顶多在某个环节当个“辅助工具”。而 AI-Native 的做法是，让智能体在整条链路上承担可定义、可审计、可复用的职责，人从“执行者”变成“编排者和审核者”。

我最初接触这套思路，是从 Claude Code 这个工具开始的。它和普通的代码补全插件有本质区别：它能直接读写项目文件、执行终端命令、跑测试、根据报错自我修正，还能通过一个叫CLAUDE.md的约定文件记住项目的上下文和规范。这就意味着，它不再是一个“你问我答”的助手，而是一个能独立完成一个任务闭环的执行单元。当这样的执行单元被嵌入到需求拆解、代码生成、测试补全、文档维护等环节时，SDLC 的形态就变了。

这篇手册面向的是已经在用或准备用 AI 智能体改造研发流程的工程师、技术负责人和 DevOps。不管你是刚听说 Claude Code 想试试水，还是已经在团队里推了一阵子但效果不理想，我都会把踩过的坑、验证过的配置、以及那些文档里不会写的经验摊开讲。核心关键词就几个：AI-Native、SDLC、Claude Code、智能体、CLAUDE.md，后面所有内容都围绕它们展开。

2. 整体设计思路：智能体在研发链路里到底站什么位置

2.1 从“工具调用”到“职责委托”的思维转变

大部分人用 AI 写代码，模式是这样的：打开对话框，描述需求，复制生成的代码，粘贴到编辑器，跑一下，报错了再贴回去问。这个模式的问题在于，上下文是断裂的。AI 不知道你的项目结构、不知道你的代码规范、不知道你之前已经改过哪些文件。每次对话都是从零开始，你花在“解释背景”上的时间可能比写代码还多。

AI-Native SDLC 的第一个设计原则就是上下文持久化。Claude Code 通过CLAUDE.md这个文件来解决这个问题。你可以把它理解成一份“项目交接文档”，里面写清楚：项目是干什么的、目录结构长什么样、用什么技术栈、代码风格有什么约定、哪些文件不能动、测试怎么跑、部署流程是什么。每次 Claude Code 启动时，它会自动读取这个文件，把里面的内容作为系统提示的一部分。这样你就不需要每次重复交代背景，智能体一上来就带着“项目记忆”干活。

这个设计的精妙之处在于，它把“提示工程”从一次性的对话技巧，变成了可版本管理的工程资产。CLAUDE.md可以提交到 Git 仓库，可以随项目演进更新，团队成员共享同一份上下文。这比每个人各自维护一套提示词要可靠得多。

2.2 智能体职责的边界划分

把智能体放进 SDLC 不等于让它什么都干。我的经验是，越是边界清晰、验收标准明确的任务，越适合交给智能体。比如：

• 根据接口定义生成 CRUD 代码
• 为已有函数补单元测试
• 根据报错日志定位问题并给出修复建议
• 把散落的注释整理成 API 文档
• 执行代码格式化和静态检查

反过来，需要跨系统权衡、涉及模糊需求判断、或者后果不可逆的操作，人必须留在回路里。比如数据库 schema 变更、生产环境配置修改、涉及安全边界的逻辑，这些可以让智能体给方案，但执行前必须人工确认。

这个边界划分不是拍脑袋定的，而是根据“错误成本”来的。智能体犯错的成本越低、越容易回滚，就越可以放手让它做。代码生成错了，跑个测试就知道；测试补错了，review 时能发现；但要是它直接把生产库的表删了，那就不是 review 能救回来的。

2.3 为什么选 Claude Code 作为切入点

市面上智能体框架不少，有平台化的（比如各种低代码智能体搭建平台），也有代码化的（比如用 Python 自己写 agent）。Claude Code 的定位比较特殊：它是一个命令行原生的智能体，直接跑在你的终端里，能操作你的文件系统和 shell。这意味着它天然适合研发场景，因为研发工作本来就是在终端和编辑器之间来回切换的。

和平台化智能体相比，Claude Code 的优势是离代码近。平台化智能体往往需要你把代码上传或者通过 API 交互，中间隔了一层；而 Claude Code 直接在你本地项目目录里工作，读写文件、执行命令都是原生的。和纯 Python 框架相比，它的优势是开箱即用，不需要自己搭一套 agent loop、工具调用、上下文管理的脚手架。

当然它也有局限，比如对非代码类任务的支持不如通用智能体平台，对多模态输入的处理也有限。但对于 SDLC 这个场景，它的能力覆盖已经足够了。

3. 核心细节解析：CLAUDE.md 与智能体配置的实操要点

3.1 CLAUDE.md 到底该写什么

很多人第一次创建CLAUDE.md时不知道写什么，要么写得太简略（等于没写），要么写得太啰嗦（智能体抓不住重点）。我的建议是把它当成一份给新入职同事的 onboarding 文档来写，但更精炼。具体包含以下几块：

项目概述：一两句话说明项目是做什么的、服务哪些用户、核心功能是什么。这部分帮助智能体理解业务语境，避免生成脱离实际的代码。

技术栈与版本：列出语言、框架、数据库、中间件及其版本。版本很重要，因为不同版本的 API 可能有差异，写清楚能避免智能体生成过时的写法。

目录结构说明：用树形结构列出主要目录和关键文件的作用。不需要列全，但核心模块要覆盖。

代码规范：命名约定、缩进风格、注释要求、错误处理模式、日志规范等。这部分越具体越好，比如“所有异步函数必须用 try-catch 包裹并记录 error 级别日志”就比“注意错误处理”有用得多。

常用命令：安装依赖、启动开发服务、跑测试、构建、部署的命令。智能体需要知道怎么验证自己的改动。

禁区与注意事项：哪些文件不能改、哪些操作需要人工确认、哪些依赖不能引入。这是安全边界。

一个实际的CLAUDE.md片段长这样：

# 项目概述 这是一个面向中小企业的订单管理系统后端，基于 FastAPI + PostgreSQL。 # 技术栈 - Python 3.11 - FastAPI 0.104 - SQLAlchemy 2.0 (async) - PostgreSQL 15 - pytest + pytest-asyncio # 目录结构 - app/api/ 路由层，按业务模块分文件 - app/models/ SQLAlchemy 模型 - app/services/ 业务逻辑 - app/core/ 配置、数据库连接、依赖注入 - tests/ 测试文件，与 app 目录结构镜像 # 代码规范 - 所有路由函数必须声明 response_model - 数据库操作必须在 service 层，路由层不直接碰 session - 异常统一用 app.core.exceptions 里定义的异常类 - 日志用 structlog，禁止 print # 常用命令 - 安装依赖: poetry install - 启动开发: uvicorn app.main:app --reload - 跑测试: pytest -v - 格式化: ruff format . # 禁区 - 不要修改 alembic/versions/ 下的已有迁移文件 - 不要直接操作生产数据库 - 新增依赖前必须先问我

这份文件不需要一次写完美，可以在使用过程中逐步补充。每次发现智能体犯了重复性错误，就把对应的规则加进去。它本质上是一个持续迭代的约束集。

3.2 智能体权限与安全配置

Claude Code 默认会请求文件读写和命令执行权限。在个人项目里这没什么问题，但在团队或生产相关环境里，必须做权限收敛。我的做法是：

第一层，目录级隔离。只在项目目录下启动 Claude Code，不要在家目录或根目录启动。这样它的文件操作范围天然被限制在项目内。

第二层，命令白名单。Claude Code 支持配置允许执行的命令列表。把rm -rf、DROP TABLE、git push --force这类危险命令排除在外。具体配置方式因版本而异，但思路是只放行读操作和安全的写操作（如跑测试、格式化、构建）。

第三层，敏感文件排除。在CLAUDE.md里明确写出哪些文件不能被读取或修改，比如.env、密钥文件、生产配置。虽然这不是强制机制，但能降低智能体误操作的概率。

第四层，人工确认关键操作。对于数据库迁移、依赖变更、部署脚本执行这类操作，配置成需要人工确认后才执行。Claude Code 本身有交互确认机制，不要图省事全部跳过。

注意：权限配置不是一劳永逸的。每次项目结构或部署流程有变化，都要回头检查权限设置是否还合适。我见过因为新增了一个部署脚本但忘了加白名单，导致智能体执行了预期外操作的案例。

3.3 上下文窗口管理与任务拆分

Claude Code 的上下文窗口是有限的，虽然具体大小随版本变化，但不要把整个代码库一次性塞给它。正确的做法是按任务拆分上下文。

比如你要让它实现一个新接口，不要让它“读整个项目然后加个接口”，而是明确告诉它：参考app/api/orders.py的风格，在app/api/users.py里加一个GET /users/{id}/orders接口，数据模型参考app/models/order.py。这样它只需要读几个相关文件，上下文利用率高，生成质量也稳定。

对于大任务，拆成多个小任务串行执行。每个小任务完成后，让智能体总结一下改了什么，作为下一个任务的输入。这样既控制了上下文长度，又保留了任务间的连贯性。

我常用的一个模式是“三步法”：

1. 探索阶段：让智能体读相关文件，输出它对现状的理解和改动计划。这一步不写代码，只做分析。
2. 执行阶段：确认计划后，让它按计划改代码。改完让它自己跑测试。
3. 验证阶段：人工 review 改动，跑一遍完整测试，确认无误后提交。

这个模式的好处是，在写代码之前先对齐理解，避免它按错误的理解写了一堆然后全部返工。

4. 实操过程：从零搭建一条 AI-Native 研发流水线

4.1 环境准备与 Claude Code 安装

Claude Code 的安装方式根据操作系统不同有差异。在 macOS 和 Linux 上，通常通过 npm 全局安装：

npm install -g @anthropic-ai/claude-code

Windows 上建议在 WSL2 里安装，原生 Windows 的支持虽然有了，但终端体验和文件系统性能还是 WSL 更顺。安装完成后，在项目根目录执行claude命令即可启动。

首次启动需要配置 API 访问。如果你用的是官方服务，按提示登录即可。如果想接入第三方模型或本地模型（比如通过 LM Studio 跑的模型），需要配置对应的 API endpoint 和 key。这部分配置因版本而异，核心是找到配置文件（通常在~/.claude/目录下），设置base_url和api_key。

VS Code 用户可以直接在集成终端里跑 Claude Code，也可以装对应的扩展。扩展的好处是能在编辑器内直接看到智能体的文件改动 diff，review 更方便。

提示：如果你在配置过程中遇到“组织已禁用订阅访问”之类的提示，通常是账号权限或订阅状态的问题，检查一下账号所属组织是否限制了 API 访问。这类问题在团队账号里比较常见，个人账号一般不会遇到。

4.2 第一个智能体任务：让 Claude Code 读懂你的项目

安装完成后，不要急着让它写代码。第一步是让它读懂项目。在项目根目录启动 Claude Code，然后给它一个探索指令：

请阅读项目根目录下的 CLAUDE.md，然后浏览 app/ 目录下的主要文件， 用一段话总结这个项目的架构和主要模块职责。

这个指令的目的是验证两件事：一是CLAUDE.md是否被正确读取，二是智能体对项目结构的理解是否准确。如果它的总结有偏差，说明CLAUDE.md写得不够清楚，需要补充。

接下来可以让它做一个小的、可验证的任务，比如：

请找出 app/services/ 下所有没有单元测试覆盖的函数，列出来。

这个任务只读不写，风险为零，但能让你观察它的文件检索和分析能力。如果它能准确列出，说明基本配置没问题。

4.3 代码生成任务的完整流程

假设我们要新增一个“用户订单统计”接口。完整流程如下：

第一步，定义接口契约。在CLAUDE.md或直接在指令里写清楚：路径、方法、请求参数、响应结构、错误码。比如：

新增接口 GET /users/{user_id}/order-stats 响应: { "total_orders": int, "total_amount": float, "last_order_at": datetime } 错误: 用户不存在返回 404

第二步，让智能体探索相关代码。指令：

请阅读 app/api/users.py、app/services/user_service.py、app/models/order.py， 理解现有的路由风格、service 层写法和模型定义，然后给出这个新接口的实现计划。

第三步，review 计划并确认。智能体会输出一个计划，比如“在 user_service.py 加一个 get_order_stats 方法，在 users.py 加路由，复用现有的 get_user_or_404 依赖”。你确认没问题后，让它执行。

第四步，执行并自测。指令：

按计划实现，完成后跑 pytest tests/test_users.py，如果有失败请修复。

第五步，人工验证。看 diff，跑完整测试，确认无误后提交。

这个流程走下来，一个简单接口从定义到完成大概五到十分钟，其中大部分时间花在 review 上。相比手写，效率提升是明显的，但review 环节不能省。智能体生成的代码在风格一致性和边界处理上偶尔会有疏漏，比如忘了处理空列表、忘了加类型注解，这些都要在 review 时抓出来。

4.4 测试补全与文档维护的自动化

测试补全是智能体最擅长的任务之一。指令可以很直接：

请为 app/services/order_service.py 里的 calculate_total 函数补单元测试， 覆盖正常情况、空订单、折扣边界三种场景，测试文件放在 tests/services/test_order_service.py。

智能体会读原函数、理解逻辑、生成测试、跑一遍确认通过。如果测试失败，它会根据报错调整。这个过程基本不需要人工干预，除非函数逻辑本身有歧义。

文档维护也是类似。让智能体扫描所有路由函数，提取 docstring 和类型注解，生成 OpenAPI 格式的文档草稿。或者让它对比代码和现有文档，找出不一致的地方并修正。这类任务的特点是规则明确、验收标准清晰，非常适合交给智能体。

4.5 把智能体接入 CI 流水线

更进一步的做法是把 Claude Code 接入 CI。比如在 PR 创建时，自动触发一个智能体任务：检查新增代码是否有对应的测试、是否符合CLAUDE.md里的规范、是否有明显的安全问题。检查结果作为 PR 评论发出来。

这个做法的价值在于把规范检查从人工 review 里剥离出来。人工 review 应该关注逻辑正确性和设计合理性，而格式、测试覆盖、命名规范这些机械性检查交给智能体。这样 review 效率会高很多。

具体实现方式取决于你的 CI 平台。核心思路是在 CI 脚本里调用 Claude Code 的非交互模式（通常通过--print或类似参数），把检查指令和文件路径传进去，捕获输出并格式化。

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

5.1 智能体“不听话”怎么办

最常见的问题是智能体没有按CLAUDE.md里的规范执行。比如你写了“所有路由必须声明 response_model”，但它生成的路由就是没加。原因通常有两个：一是CLAUDE.md里的规则太多，它没抓住重点；二是规则表述不够具体，它理解有偏差。

解决办法是把规则写得更具体、更靠前。把最重要的规则放在CLAUDE.md的开头，用加粗或列表突出。对于经常被忽略的规则，可以在指令里再强调一遍。比如：

注意：所有新增路由必须声明 response_model，这是硬性要求。

另一个技巧是给正例和反例。与其写“注意错误处理”，不如写：

错误处理统一用 app.core.exceptions 里的异常类。 正确示例：raise UserNotFoundError(user_id) 错误示例：raise HTTPException(status_code=404, detail="not found")

这样智能体有明确的参照，执行准确率会高很多。

5.2 上下文丢失与任务漂移

长任务执行到后面，智能体可能会“忘记”前面的约定，开始生成不符合规范的代码。这是上下文窗口被占满后的典型症状。解决办法是主动管理上下文：

• 每个任务完成后，让它输出一个简短总结，然后开新会话执行下一个任务，把总结作为新会话的输入。
• 对于特别长的任务，分阶段执行，每个阶段结束后人工确认再继续。
• 定期用/clear或类似命令清空上下文，重新加载CLAUDE.md。

我自己的习惯是，一个任务不超过三次交互。如果三次还没搞定，说明任务拆得不够细，或者指令不够明确，停下来重新拆。

5.3 生成代码的“幻觉”问题

智能体有时会引用不存在的函数、导入不存在的模块、或者调用不存在的 API。这在依赖版本不明确时尤其常见。排查方法是让它自己验证：

请检查你刚才生成的代码，确认所有 import 的模块和调用的函数在项目中真实存在。 如果有不存在的，请修正。

这个自检指令能抓出大部分幻觉问题。另外，在CLAUDE.md里写清楚依赖版本，也能减少这类问题。

5.4 常见问题速查表

5.5 几个踩过的坑

坑一：在项目根目录之外启动。有一次我在家目录启动 Claude Code，让它改一个项目文件，结果它把路径搞错了，在错误的位置创建了文件。后来我养成习惯，永远在项目根目录启动，并且在CLAUDE.md里写明项目根路径。

坑二：一次性给太多任务。早期我试过让它“把整个模块重构一遍”，结果它改到一半上下文满了，后面的改动质量急剧下降，还引入了几个 bug。后来改成一次只做一个函数或一个文件，质量稳定多了。

坑三：忽略 review。有次赶时间，智能体生成的代码没仔细看就提交了，结果它把一个边界条件写反了，测试没覆盖到，上线后才发现。从那以后，再简单的改动也要过一遍 diff，这是底线。

坑四：CLAUDE.md 长期不更新。项目演进后，CLAUDE.md里的目录结构和命令都过时了，智能体按旧信息操作，频繁出错。现在我把更新CLAUDE.md作为每次迭代的固定动作，和更新文档同等对待。

6. 智能体行为审计与效果度量

6.1 为什么要做审计

当智能体在研发流程里承担越来越多职责时，可追溯性就变得重要了。出了问题要能回答：这个改动是谁（哪个智能体、哪个版本）做的、基于什么指令、参考了哪些文件。这不是不信任智能体，而是工程管理的基本要求。

Claude Code 本身会记录会话历史，但默认存在本地。团队使用时，建议把关键任务的会话记录归档，至少保留指令和最终 diff。这样出问题时能快速定位。

6.2 效果度量的几个指标

我用来衡量智能体在 SDLC 中效果的核心指标有三个：

任务完成率：智能体独立完成（无需人工修正）的任务占比。这个指标反映的是指令质量和CLAUDE.md的完善程度。初期可能只有 40% 左右，随着上下文文件完善和任务拆分熟练，能到 70% 以上。

返工率：智能体生成的代码在 review 时被打回重改的比例。这个指标反映的是生成质量。返工率高说明指令不够具体，或者任务难度超出了智能体能力边界。

时间节省比：完成同一类任务，用智能体 vs 纯手工的时间比。这个指标因任务类型差异很大。测试补全和文档生成通常能省 60% 以上时间，复杂业务逻辑实现可能只省 20% 到 30%。

这些指标不需要精确统计，粗略记录就能发现趋势。关键是持续观察，及时调整。如果某个指标恶化，说明流程或配置有问题，要停下来排查。

6.3 智能体行为的边界与风险控制

智能体再能干，也有能力边界。我的原则是三不做：

• 不可逆的操作不做：删数据、改生产配置、强制推送，这些必须人工执行。
• 涉及安全边界的逻辑不做：认证、授权、加密相关的代码，智能体可以给建议，但最终实现要人工把关。
• 跨系统协调不做：需要同时改多个仓库、多个服务的任务，智能体容易顾此失彼，拆成单系统任务分别处理。

这三条不是对智能体能力的否定，而是对错误成本的理性评估。智能体犯错的概率不低，关键是让错误发生在可回滚、可发现的环节。

7. 从单点工具到研发范式：一些个人体会

我用了大半年 Claude Code 之后，最大的感受不是“效率提升了多少”，而是工作方式变了。以前写代码是“想清楚每一步然后敲出来”，现在是“描述清楚目标然后 review 结果”。这个转变需要适应，因为 review 别人的代码（哪怕是智能体生成的）和写自己的代码，用的是不同的脑力。

另一个体会是，CLAUDE.md的质量直接决定了智能体的上限。我见过很多人抱怨智能体不好用，一看他们的CLAUDE.md，要么没有，要么就三行字。这就像招了个新人但不给他任何交接文档，然后怪他干不好活。把CLAUDE.md写好、维护好，是 AI-Native SDLC 里投入产出比最高的一件事。

最后分享一个小技巧：让智能体自己维护CLAUDE.md。每次它犯了重复性错误，你可以让它把对应的规则补充进去。比如：

你刚才生成的代码没有加类型注解，请把“所有函数必须加类型注解”这条规则 补充到 CLAUDE.md 的代码规范部分。

这样CLAUDE.md会随着使用越来越完善，智能体的表现也会越来越稳定。这个正反馈循环一旦转起来，整个研发流程的自动化程度会自然提升。