企业官网建设流程全解析

1. 从"AI辅助"到"AI原生"：团队开发范式的分水岭

大多数团队对AI的使用还停留在"辅助"层面——写代码时开个补全插件，写文档时让模型润色一下，测试时用AI生成几条用例。这种模式的天花板很明显：AI始终是一个外挂工具，人还是流程的中心，所有上下文靠人脑传递，所有决策靠人拍板。而AI Native的核心区别在于，AI不再是工具，而是团队的一等公民——它有自己的工作空间、自己的上下文文件、自己的任务队列，甚至自己的"记忆"。

这个转变听起来抽象，落到工程上其实非常具体。传统SDLC里，需求从产品经理传到开发，开发传到测试，测试传到运维，每一环都有信息损耗。AI Native SDLC要做的事情，是把这条链路上所有可结构化的上下文，沉淀成AI能直接读取和执行的资产。CLAUDE.md这类文件就是典型代表——它不是给人看的文档，而是给Agent看的"项目宪法"，里面写清楚了这个仓库的技术栈、目录约定、代码风格、禁止事项、常用命令。Agent每次启动都会先读它，相当于新员工入职先看员工手册。

我见过太多团队在这一步走偏：把CLAUDE.md写成给领导汇报的PPT，堆满了"赋能""闭环""抓手"这类词，结果Agent读完一脸懵，该干嘛还是干嘛。正确的做法是把它当成一份给一个聪明但完全不了解你项目的工程师看的交接文档——具体、可执行、有边界。比如不要写"遵循良好的代码规范"，而要写"所有新函数必须带类型注解，Python用mypy检查，提交前跑make lint"。

Plan Mode是另一个容易被低估的机制。很多人觉得让AI先出计划再执行是浪费时间，直接让它干活不香吗？实测下来恰恰相反。在Plan Mode下，Agent会先把任务拆解成步骤、列出要改的文件、说明每步的意图，人确认后再执行。这个"确认"环节省下的返工时间，远超多花的那几十秒。尤其是涉及多文件改动的重构任务，没有Plan Mode的Agent就像没有图纸就开工的装修队，干到一半发现水电走错了，拆了重来。

Agent这个概念在AI Native语境下，和传统的"脚本"有本质区别。脚本是确定性的，输入A必然输出B；Agent是有自主决策能力的，它会根据环境反馈调整策略。这就引出了一个关键问题：如何给Agent划定安全边界。一个能自主执行命令、读写文件、调用API的Agent，如果边界没划好，轻则改错文件，重则删库跑路。所以Agent沙箱、权限控制、操作审计这些机制，在AI Native团队里不是可选项，而是基础设施。

2. CLAUDE.md的写法决定了Agent的上限

2.1 为什么这个文件比你想的重要

CLAUDE.md（以及类似的AGENTS.md、.cursorrules等）本质上是Agent的持久化上下文。Agent的上下文窗口是有限的，每次对话能塞进去的信息就那么多。如果项目约定不沉淀成文件，每次都要人在对话里重复交代，既浪费token又容易遗漏。更关键的是，人会在不同会话里给出不一致的指令，导致Agent的行为飘忽不定。

我自己的做法是把CLAUDE.md分成几个固定区块：项目概览、技术栈与版本、目录结构说明、开发命令、代码规范、测试要求、禁止事项、常见陷阱。每个区块都写具体的、可验证的内容。比如"技术栈"部分不写"使用现代前端框架"，而写"React 18 + TypeScript 5.3 + Vite 5，状态管理用Zustand，样式用Tailwind CSS 3.4"。

2.2 一个可复用的CLAUDE.md骨架

下面是我在多个项目里迭代出来的结构，你可以直接拿去改：

# 项目名称 ## 项目概览 一句话说明这个项目是干什么的，目标用户是谁。 ## 技术栈 - 语言与版本：Python 3.11 - 框架：FastAPI 0.110 - 数据库：PostgreSQL 16 + SQLAlchemy 2.0 - 测试：pytest + httpx - 包管理：uv ## 目录结构 - `src/api/`：路由层，只做参数校验和响应组装 - `src/services/`：业务逻辑层，所有核心逻辑写在这里 - `src/models/`：SQLAlchemy模型 - `tests/`：测试文件，与src结构镜像 ## 常用命令 - 安装依赖：`uv sync` - 启动开发服务：`uv run uvicorn src.main:app --reload` - 跑测试：`uv run pytest -xvs` - 类型检查：`uv run mypy src/` - 格式化：`uv run ruff format .` ## 代码规范 - 所有函数必须有类型注解 - 禁止在路由层写业务逻辑 - 数据库操作必须通过service层 - 异常统一用自定义的AppError体系 ## 禁止事项 - 不要修改`alembic/versions/`下的历史迁移文件 - 不要在代码里硬编码密钥，用环境变量 - 不要跳过测试直接提交 ## 常见陷阱 - 本地开发连的是docker里的PG，端口5433不是5432 - 修改模型后必须生成迁移：`uv run alembic revision --autogenerate -m "描述"`

这个骨架的关键在于可执行性。Agent读完就知道该跑什么命令、该把代码放哪、什么不能碰。我实测下来，有了这份文件，Agent首次生成代码的可用率能从大概四成提到七成以上。

2.3 维护CLAUDE.md的节奏

很多人写完CLAUDE.md就扔那不管了，结果项目演进半年，文件里写的命令早就失效了。我的习惯是把它纳入代码评审——每次PR如果引入了新的约定、新的命令、新的目录，必须同步更新CLAUDE.md。这跟维护README是一个道理，但优先级更高，因为README是给人看的，CLAUDE.md是给Agent看的，Agent不会像人一样"猜"你的意图。

还有一个技巧：把CLAUDE.md拆成主文件和子目录文件。根目录放全局约定，各个子模块目录放该模块特有的说明。Agent在处理某个模块的任务时，会优先读取该模块的说明文件，这样上下文更聚焦，token利用效率更高。

3. Plan Mode不是可选项：任务拆解的质量决定交付质量

3.1 Plan Mode到底在做什么

Plan Mode的本质是强制Agent先做任务分解，再执行。在没有Plan Mode的情况下，你给Agent一个"给用户模块加个导出功能"的任务，它可能直接就开始改代码了，改到一半发现需要先加个依赖，加完依赖发现数据库要加字段，加完字段发现前端要改接口……整个过程像打地鼠，改一处崩一处。

Plan Mode下，Agent会先输出一份计划：要改哪些文件、每个文件改什么、按什么顺序改、有没有依赖关系、有没有风险点。人看完这份计划，可以提前发现"哎这个方案会影响另一个模块"或者"这个顺序不对，应该先改数据库"，直接在计划阶段纠正，而不是等代码写完再返工。

3.2 一份好的Plan长什么样

我拿一个真实任务举例：给一个FastAPI项目加"用户头像上传"功能。Agent在Plan Mode下输出的计划应该是这样的：

## 任务计划：用户头像上传 ### 步骤1：数据库变更 - 修改 `src/models/user.py`，给User模型加 `avatar_url` 字段（String, nullable） - 生成迁移文件：`uv run alembic revision --autogenerate -m "add avatar_url to user"` ### 步骤2：存储层 - 新增 `src/services/storage.py`，封装对象存储的上传逻辑 - 需要新增依赖：`boto3`（或项目已有的存储SDK） - 配置项：从环境变量读取 `STORAGE_BUCKET`、`STORAGE_REGION` ### 步骤3：业务逻辑 - 修改 `src/services/user.py`，新增 `update_avatar(user_id, file)` 方法 - 校验文件类型（只允许jpg/png）、大小（限制2MB） ### 步骤4：API层 - 修改 `src/api/user.py`，新增 `POST /users/{user_id}/avatar` 路由 - 接收multipart/form-data，调用service层方法 ### 步骤5：测试 - 新增 `tests/services/test_storage.py` - 新增 `tests/api/test_user_avatar.py` - 用mock替换真实存储调用 ### 风险点 - 对象存储的凭证管理需要确认现有方案 - 文件大小限制需要和产品确认具体数值

这份计划的价值在于，它把"一个功能"拆成了"五个可独立验证的步骤"，每一步都有明确的产出物。人审计划的时候，可以快速判断：存储方案用现有的还是新引入？大小限制合不合理？测试覆盖够不够？这些问题在计划阶段解决，成本是分钟级；等代码写完再发现，成本是小时级。

3.3 什么任务适合Plan Mode

不是所有任务都需要Plan Mode。改个typo、调个日志级别，直接干就行。我的判断标准是：涉及三个以上文件，或者涉及数据库/接口/依赖变更的任务，必须走Plan Mode。这类任务的共同特点是"牵一发动全身"，计划阶段多花两分钟，执行阶段省半小时。

还有一个经验：Plan Mode下不要一次给太大的任务。你给Agent一个"重构整个认证模块"的任务，它出的计划会非常粗，因为细节太多它顾不过来。正确的做法是把大任务切成小任务，每个小任务单独走Plan Mode。比如"重构认证模块"可以切成"把session认证换成JWT""把密码哈希从bcrypt换成argon2""加refresh token机制"三个独立任务。

4. Agent的边界设计：能干什么和不能干什么

4.1 Agent沙箱的必要性

Agent沙箱这个词听起来很重，其实核心就一件事：限制Agent能触碰的资源范围。一个没有沙箱的Agent，理论上可以读写你机器上的任何文件、执行任何命令、访问任何网络。这在开发环境可能还好，在生产环境就是灾难。

沙箱的实现层次有好几种。最轻的是文件系统层面的限制，比如让Agent只能在一个指定的工作目录里操作，出了这个目录就拒绝。中等的是进程层面的限制，用容器把Agent跑起来，限制它能用的CPU、内存、网络。最重的是权限层面的限制，Agent的每个操作都要经过一个策略引擎审批，比如"读文件可以，写文件需要确认，执行shell命令需要白名单"。

我自己的实践是分环境处理：本地开发用文件系统限制就够了，Agent只能碰项目目录；CI环境用容器隔离，Agent跑在一次性容器里，跑完就销毁；生产环境基本不让Agent直接操作，只让它生成变更建议，由人来执行。

4.2 权限白名单的具体设计

Agent能执行shell命令这件事，风险最大。我的做法是维护一个命令白名单，只有白名单里的命令允许直接执行，其他命令需要人工确认。白名单大概长这样：

这个白名单不是一成不变的，随着项目演进会调整。关键是默认拒绝，显式允许，而不是反过来。

4.3 Agent记忆的管理

Agent记忆是个双刃剑。好的记忆让Agent越用越懂你的项目，坏的记忆让Agent把过时的、错误的经验一直带下去。我的做法是把记忆分成两类：项目级记忆和会话级记忆。

项目级记忆就是CLAUDE.md这类文件，是持久的、经过评审的、可信的。会话级记忆是Agent在单次任务中积累的上下文，任务结束就丢弃。两者之间有一个"晋升"机制：如果某个会话级的经验被证明是通用的、有价值的，就把它沉淀到项目级记忆里。

具体操作上，我会在任务结束后问Agent："这次任务里有没有什么经验值得记到CLAUDE.md里？"Agent会给出几条建议，我筛选后手动加进去。这个习惯坚持下来，CLAUDE.md会越来越厚，但每一条都是实战验证过的。

5. 多Agent协作：什么时候需要，怎么编排

5.1 单Agent的天花板

单Agent做任务，上下文窗口是硬约束。一个复杂任务涉及的文件、日志、文档加起来可能几十万字，塞不进一个上下文窗口。这时候要么做摘要（丢信息），要么分多次对话（丢上下文连贯性）。多Agent协作就是为了解决这个问题：把任务拆给多个Agent，每个Agent负责一块，各自维护自己的上下文。

但多Agent不是银弹。我见过不少团队一上来就搞多Agent，结果协调开销比任务本身还大。判断标准很简单：如果单Agent加Plan Mode能搞定，就不要上多Agent。多Agent适合的场景是任务天然可并行、且各子任务之间耦合度低。比如"给十个微服务各加一个健康检查接口"，这种任务十个Agent并行做，比一个Agent串行做快得多。

5.2 编排模式的选择

多Agent编排有几种常见模式，各有适用场景：

主管模式：一个主管Agent负责任务分解和结果汇总，多个工作Agent负责执行。适合任务可以清晰分解、子任务之间独立性强的场景。主管Agent的prompt要写清楚"你负责分解任务，不要自己执行"。

流水线模式：Agent按顺序排列，前一个的输出是后一个的输入。适合有明确阶段划分的任务，比如"需求分析→设计→编码→测试"。每个Agent专注自己那一环，prompt可以写得很专。

对等模式：多个Agent平级，通过共享的工作区协作。适合探索性任务，比如"调研三个技术方案并给出对比"。每个Agent调研一个方案，最后汇总。

我自己的项目里用得最多的是主管模式，因为它最可控。主管Agent的prompt大概长这样：

你是一个任务协调者。你的职责是： 1. 把用户的任务分解成3-5个子任务 2. 为每个子任务生成一个工作Agent的prompt 3. 收集工作Agent的结果并汇总 4. 如果子任务之间有依赖，调整执行顺序 你不需要自己执行任何子任务，只负责协调。

5.3 Agent之间的通信协议

多Agent协作最容易出问题的地方是通信。Agent A的输出格式Agent B读不懂，或者Agent A以为自己在汇报，Agent B以为自己在接收指令。解决办法是定义统一的消息格式。我的做法是用JSON schema约束Agent之间的消息：

{ "from": "agent_name", "to": "agent_name", "type": "task_assignment | result_report | question | answer", "payload": { "task_id": "uuid", "content": "...", "artifacts": ["file_path_1", "file_path_2"], "status": "pending | in_progress | done | failed" } }

这个格式看起来简单，但能避免大量沟通歧义。每个Agent的prompt里都写清楚"你发送消息必须符合这个格式，接收消息时按这个格式解析"。

6. 落地过程中踩过的坑和应对

6.1 Agent执行中断的排查思路

agent execution terminated due to error这个报错，我踩过不下十次。原因五花八门，但排查路径可以标准化：

第一步，看Agent的最后一条输出。如果它停在某个命令执行后，大概率是那个命令失败了。第二步，看命令的退出码和stderr。第三步，如果命令本身没问题，看是不是上下文超限了——Agent的上下文窗口满了，它会静默截断，然后行为变得奇怪。第四步，看是不是权限问题——Agent试图访问沙箱外的资源被拒绝了。

我遇到最多的是上下文超限。解决办法是把大任务拆小，或者把不必要的信息从上下文里剔除。比如Agent读了一个巨大的日志文件，把上下文撑爆了，这时候应该让它先grep出关键行，而不是读全文。

6.2 Agent"自作主张"的预防

Agent有时候会做一些你没让它做的事，比如顺手重构了一个它觉得"不优雅"的函数，或者删了一个它觉得"没用"的文件。这种自作主张在开发环境可能只是烦人，在生产环境就是事故。

预防措施有三层。第一层是prompt约束，在CLAUDE.md里明确写"只做被要求的事，不要顺手改其他代码"。第二层是Plan Mode，让Agent先说要做什么，你确认了再执行。第三层是操作审计，Agent的每个写操作都记日志，事后可以追溯。

我自己的习惯是，对Agent的写操作保持"最小惊讶原则"——如果Agent要改的文件不在我预期的范围内，我会先问它为什么。这个习惯帮我拦下过好几次"Agent觉得这个文件该删"的情况。

6.3 Token成本的控制

Agent跑起来token消耗是很快的。一个复杂任务，Agent读文件、思考、执行、读结果、再思考，来回几轮，几十万token就没了。控制成本有几个实用技巧：

• 精简上下文：CLAUDE.md不要写废话，只写Agent真正需要的信息。我见过有人把整个API文档贴进去，几万字，Agent每次启动都读一遍，纯浪费。
• 用grep代替全文读取：让Agent先grep定位，再读具体行，而不是读整个文件。
• 缓存常用信息：有些信息Agent每次都要用，比如数据库schema，可以做成一个精简的摘要文件，而不是让它每次去读模型定义。
• 设置token预算：在Agent的配置里设一个单任务token上限，超了就停下来让人介入，避免一个任务烧掉一天的额度。

6.4 Agent Skill的沉淀

Agent Skill是指把一类任务的执行方法固化下来，让Agent下次遇到同类任务可以直接调用。比如"给一个API加新端点"这个任务，涉及改路由、改service、加测试、更新文档，步骤是固定的。把这个流程写成一个skill文件，Agent下次遇到"加端点"的任务，直接按skill执行，不用重新规划。

Skill的写法没有统一标准，我的做法是用markdown写清楚：适用场景、前置条件、执行步骤、验证方法、常见问题。放在项目的.agent/skills/目录下，CLAUDE.md里引用一下。这样Agent在处理任务时，会先查有没有对应的skill，有就直接用，没有才自己规划。

这个机制的价值在于把人的经验固化成Agent的能力。团队里资深工程师知道"加端点要记得更新OpenAPI文档"，新人可能不知道，Agent也不知道。但把这个经验写成skill，Agent就知道了，新人通过Agent也间接知道了。

7. 从零搭建AI Native工作流的实操路径

7.1 第一周：把CLAUDE.md写起来

不要一上来就搞复杂的Agent编排。第一周就做一件事：给现有项目写一份CLAUDE.md。内容按我前面给的骨架来，重点是技术栈、命令、目录结构、禁止事项这四块。写完让Agent跑一个简单任务试试，比如"给某个函数加个参数校验"，看它能不能按你的约定来。根据Agent的表现迭代CLAUDE.md，把Agent做错的地方补进去。

这一周的目标是让Agent"懂你的项目"。判断标准是：Agent生成的代码，你不需要大改就能用。

7.2 第二周：引入Plan Mode

第二周开始，所有涉及多文件的任务都走Plan Mode。一开始你可能会觉得慢，但坚持一周，你会发现返工率明显下降。这一周的重点是练习审计划——Agent出的计划，你要能快速判断哪里有问题。常见的计划问题包括：步骤顺序不对、遗漏了测试、风险点没识别出来。审多了你就有感觉了。

这一周还要开始建立命令白名单。把Agent常用的命令列出来，分类成"直接允许"和"需要确认"。这个白名单会随着使用不断调整。

7.3 第三周：沉淀Skill

第三周开始，把重复出现的任务模式沉淀成Skill。判断标准是：如果一类任务你让Agent做了三次以上，就该写Skill了。Skill不用写得很完美，先写个初版，用的时候发现哪里不对再改。Skill的价值在于复用，写得越多，Agent能独立处理的任务就越多。

这一周还要开始做操作审计。Agent的写操作记日志，每周review一次，看有没有异常操作。这个习惯能帮你及早发现Agent的行为偏差。

7.4 第四周：多Agent试点

如果前三周跑得顺，第四周可以试点多Agent。选一个天然可并行的任务，比如"给五个模块各加一个日志埋点"，用主管模式跑一次。重点观察：主管Agent的任务分解合不合理、工作Agent之间的通信有没有歧义、汇总结果的质量如何。根据观察结果调整编排策略。

如果前三周跑得不顺，第四周不要急着上多Agent，继续打磨单Agent的工作流。多Agent是放大器，单Agent的问题在多Agent里会被放大，不会自动消失。

7.5 持续迭代的节奏

AI Native工作流不是搭完就完事的，它需要持续迭代。我的节奏是：每周花半小时review Agent的表现，把新的经验补进CLAUDE.md或Skill；每月花两小时做一次全面review，看有没有结构性的问题需要调整；每季度重新评估一次工具链，看有没有新的工具值得引入。

这个节奏听起来不重，但坚持下来效果很明显。我自己的项目跑了半年，Agent首次生成代码的可用率从四成提到了八成以上，返工率降了一半多。这些数字不是靠某个神奇的工具，而是靠持续的小迭代积累出来的。

最后分享一个我自己的体会：AI Native落地最大的障碍不是技术，是习惯。人习惯了"自己动手"，很难信任Agent去干活。但一旦你跨过那个信任门槛，把重复性的、模式化的任务交给Agent，你会发现自己能腾出大量时间做真正需要人判断的事——架构设计、技术选型、和产品吵架。这才是AI Native的真正价值：不是让AI替代人，而是让人做人该做的事。