企业官网建设流程全解析

1. 为什么“AI Native 团队”不是加个 Copilot 就算数

这两年我参与过三个不同规模的团队从传统研发模式往 AI Native 方向迁移，最大的感受是：绝大多数团队对“AI Native”的理解还停留在“给每个人开个 AI 编程助手账号”的阶段。这跟真正的 AI Native 差着十万八千里。AI Native 的核心不是工具替换，而是整个软件开发生命周期（SDLC）的重构——从需求拆解、方案设计、编码实现、测试验证到部署运维，每个环节的输入输出形态、协作方式、质量门禁都要重新设计。

我见过最典型的失败案例：一个二十人的后端团队全员配了 AI 编码工具，三个月后统计发现代码产出量涨了 40%，但线上事故率翻了将近一倍。原因很简单——AI 生成的代码没人认真 review，测试用例还是老一套，CI 流水线也没做针对性调整。工具升级了，流程没升级，结果就是加速了混乱。

所以这篇手册要解决的问题很具体：一个团队到底该怎么系统性地落地 AI Native 开发范式。我会从目录结构约定、Plan Mode 工作流、Agent 编排、并发与安全、到最终的度量体系，把每个环节拆开讲透。适合正在做技术选型的 TL、想推动团队转型的架构师，以及已经在用 AI 工具但感觉“哪里不对”的一线开发者。

2. 项目整体设计与思路拆解

2.1 从 SDLC 视角重新定义 AI Native 的边界

传统 SDLC 的每个阶段在 AI Native 语境下都需要重新回答三个问题：谁来做、做什么、怎么验证。

这个表格不是理论推演，是我在实际项目中反复调整后沉淀下来的。关键洞察在于：AI Native 不是让 AI 替代人，而是让人的角色从“执行者”变成“编排者和审核者”。这意味着团队的能力模型要变——写代码快不再是核心竞争力，定义问题、设计约束、审核产出的能力才是。

2.2 为什么选择 CLAUDE.md 作为团队级约定入口

在对比了多种方案后，我最终选择用CLAUDE.md作为团队 AI 协作的“宪法文件”。原因有三：

第一，它是纯文本、可版本控制的。团队任何成员对 AI 行为的调整都可以通过 PR 来 review，这比在某个 SaaS 平台里改配置要透明得多。第二，它天然支持分层继承。根目录放全局约定，子目录放模块级约定，Agent 读取时会自动合并，这跟微服务的配置管理思路一致。第三，它不绑定特定工具。虽然名字叫 CLAUDE.md，但实际内容可以被任何支持 system prompt 注入的工具消费。

我见过有团队用 Notion 文档来管理 AI 约定，结果三个月后文档和实际代码严重脱节。文本文件放在仓库里，跟代码同生命周期，这是最不容易腐化的方案。

2.3 Plan Mode 的定位：不是聊天，是推演引擎

很多人把 Plan Mode 当成“跟 AI 聊需求”的窗口，这是巨大的误解。Plan Mode 的真正价值在于在动手之前把所有约束条件显式化。

我的做法是：任何非平凡任务（预估超过 2 小时工作量）都必须先走 Plan Mode。输入不是一句“帮我实现 XX 功能”，而是一份结构化的任务描述，包含：目标、约束、验收标准、已知风险、相关代码路径。Plan Mode 输出的是一份可执行的步骤清单，每步都有明确的输入输出和验证方式。

这个流程看起来增加了前期成本，但实测下来，它把返工率降低了至少 60%。因为大部分返工不是因为写错代码，而是因为一开始就没想清楚要写什么。

3. 核心细节解析与实操要点

3.1 CLAUDE.md 的分层结构与编写规范

一个成熟的CLAUDE.md应该包含五个部分，我按优先级排列：

# 项目 AI 协作约定 ## 1. 项目上下文 - 技术栈：TypeScript + Node.js 20 + PostgreSQL 15 - 架构模式：模块化单体，按领域分包 - 代码风格：见 .eslintrc，禁止 any 类型 ## 2. 禁止事项（硬约束） - 禁止引入新的第三方依赖，除非在 PR 中说明理由 - 禁止修改 database/migrations 下的历史文件 - 禁止在业务代码中直接调用外部 HTTP 接口，必须走 gateway 层 ## 3. 推荐模式（软约定） - 新增 API 时参考 src/modules/user/handler.ts 的结构 - 错误处理统一使用 AppError 类 - 测试文件与被测文件同目录，命名 *.spec.ts ## 4. 常用命令 - 启动开发环境：pnpm dev - 运行单测：pnpm test -- <path> - 类型检查：pnpm typecheck ## 5. 领域知识 - 订单状态机定义见 docs/order-state-machine.md - 用户权限模型见 docs/rbac.md

这个结构的精髓在于硬约束和软约定分开。硬约束是 Agent 绝对不能违反的，软约定是“最好这样做但可以商量”。我踩过的坑是：早期把所有规则都写成硬约束，结果 Agent 遇到边界情况时直接卡死，反而降低了效率。

提示：CLAUDE.md不要超过 200 行。超过这个长度，Agent 的遵循率会明显下降。长内容应该拆到子目录的CLAUDE.md里，或者放到docs/下用引用方式链接。

3.2 Plan Mode 的输入模板与输出校验

我团队现在用的 Plan Mode 输入模板是这样的：

## 任务目标 实现用户订单的批量导出功能，支持 CSV 和 Excel 两种格式。 ## 约束条件 - 单次导出上限 10000 条 - 导出任务异步执行，通过 WebSocket 通知进度 - 复用现有的 export 模块，不新建 ## 验收标准 - 10000 条数据导出耗时 < 30s - 导出过程中用户可取消 - 失败时保留部分结果并给出明确错误 ## 已知风险 - 大数据量可能导致内存溢出 - WebSocket 连接可能中断 ## 相关代码 - src/modules/export/ - src/modules/order/service.ts

Plan Mode 输出的步骤清单，我会用三个标准校验：每步是否可独立验证、是否有明确的回滚点、是否覆盖了所有已知风险。任何一条不满足，就打回去重新规划。

3.3 Agent 编排：从单 Agent 到多 Agent 的临界点

什么时候该从单 Agent 升级到多 Agent？我的经验判断标准是：当任务需要同时满足三个以上正交约束时。

比如“实现一个 API 接口”是单 Agent 任务。“实现一个 API 接口，同时保证性能、安全、可观测性，并且要写文档和测试”就是多 Agent 任务。因为性能优化、安全审计、文档生成、测试编写这四个方向的关注点差异太大，单个 Agent 的上下文窗口和注意力会被稀释。

我常用的多 Agent 编排模式是“主从式”：

orchestrator: role: 任务分解与结果汇总 model: 高推理能力模型 workers: - name: coder role: 代码实现 constraints: [遵循 CLAUDE.md, 不修改测试文件] - name: tester role: 测试编写与执行 constraints: [只读业务代码, 可写测试文件] - name: reviewer role: 代码审查 constraints: [只读, 输出审查报告]

关键设计是worker 之间的权限隔离。coder 不能改测试，tester 不能改业务代码，reviewer 只能读。这样即使某个 Agent 出错，也不会污染其他环节的产出。

3.4 Agent 并发控制与资源隔离

“AI Agent 怎么扛并发”是最近被问得最多的问题。我的答案可能有点反直觉：大部分团队根本不需要高并发 Agent，需要的是任务队列。

Agent 的并发瓶颈不在模型调用，而在上下文管理和状态同步。我实测过，同一时刻跑 10 个 Agent 处理不同任务，上下文切换的开销会让整体吞吐量下降 40% 以上。更合理的做法是：用任务队列串行化大部分任务，只对真正独立的子任务开并发。

具体实现上，我用的是“信号量 + 优先级队列”的组合：

class AgentScheduler { private semaphore: Semaphore; private queue: PriorityQueue<Task>; async submit(task: Task): Promise<Result> { await this.semaphore.acquire(); try { return await this.execute(task); } finally { this.semaphore.release(); } } }

信号量大小设置为 CPU 核心数的 1.5 倍，这是我在多个项目里试出来的经验值。太高会导致上下文切换频繁，太低会浪费资源。

4. 实操过程与核心环节实现

4.1 从零搭建 AI Native 开发环境的完整步骤

假设你是一个 5-10 人团队的 TL，现在要从零开始搭建 AI Native 开发环境。以下是我验证过的步骤：

第一步：仓库结构改造。在项目根目录创建CLAUDE.md，在docs/下创建ai-context/目录，存放领域知识文档。这一步的关键是不要一次性写完所有文档，先写最核心的 20%，剩下的在实际使用中逐步补充。

第二步：工具链选型。我的推荐组合是：编辑器侧用支持 Agent 模式的工具，CI 侧用可编程的 Agent 框架，本地用 CLI 工具做快速验证。三者共享同一份CLAUDE.md，保证行为一致。

第三步：建立 Plan Mode 工作流。在团队内推行“非平凡任务必须先 Plan”的规则。初期会有阻力，因为大家觉得慢。我的做法是先在一个试点项目上跑两周，用数据说话——返工率、review 轮次、缺陷密度这三个指标会证明一切。

第四步：Agent 编排落地。从单 Agent 开始，遇到瓶颈再拆多 Agent。不要一上来就搞复杂的多 Agent 系统，那是给自己找麻烦。

第五步：度量体系建立。这一步最容易被忽略，但最重要。没有度量就没有改进。

4.2 关键配置：CLAUDE.md 与 Agent 的联动

CLAUDE.md写好了不代表 Agent 会遵守。我踩过的坑是：文档写得很漂亮，但 Agent 实际执行时完全无视。原因是没有在 Agent 的 system prompt 里显式引用。

正确的做法是在 Agent 初始化时，把CLAUDE.md的内容注入到 system prompt 的最前面，并且加上明确的指令：

你是一个遵循项目约定的开发 Agent。 以下内容是你的行为准则，任何情况下都不得违反： <project-conventions> {CLAUDE.md 内容} </project-conventions> 在执行任何任务前，先确认你的方案是否符合上述约定。 如果任务要求与约定冲突，停止执行并报告冲突。

这个“冲突时停止”的指令非常关键。早期我没加这条，Agent 遇到冲突时会自作主张，产生大量需要返工的代码。

4.3 一个完整任务的端到端实录

我拿最近做的一个真实任务来演示：给订单模块增加“批量取消”功能。

Plan 阶段：输入结构化任务描述，Plan Mode 输出 7 个步骤，包括：定义 API 契约、实现 service 层、添加权限校验、编写测试、更新文档、添加监控埋点、灰度发布方案。我 review 后发现缺少“并发取消时的幂等性处理”，打回补充。

实现阶段：coder Agent 按步骤实现，每完成一步自动运行相关测试。tester Agent 并行编写边界测试用例。reviewer Agent 在 coder 完成后立即审查，输出问题清单。

验证阶段：所有测试通过后，reviewer 的审查报告显示有 3 个中等问题，其中一个是“批量取消时未处理部分失败的情况”。coder Agent 根据报告修复，重新走测试。

部署阶段：灰度发布，监控埋点显示取消成功率 99.97%，无异常。

整个任务从 Plan 到上线用了 4 小时，其中人工介入时间约 40 分钟，主要是 review Plan 和审查报告。对比传统模式，效率提升约 3 倍。

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

5.1 Agent 执行中断与沙盒问题排查

“Agent execution terminated due to error”和“显示更新 agent 沙盒”是高频问题。我的排查顺序是：

我遇到最多的是上下文窗口超限。Agent 处理长任务时，早期对话会被截断，导致它“忘记”了之前的约定。解决方案是在关键节点主动做上下文摘要，把重要信息压缩后重新注入。

5.2 Agent 安全：那些文档不会告诉你的坑

Agent 安全不只是“别让它删库”这么简单。我总结了三类真实踩过的坑：

第一类：隐式权限提升。Agent 在执行任务时，可能会调用一些它“认为需要”的工具，而这些工具的实际权限超出了任务范围。比如让它改一个配置文件，它可能顺手改了相关的环境变量。解决方案是最小权限原则 + 操作审计。

第二类：上下文污染。多 Agent 协作时，一个 Agent 的错误输出可能被另一个 Agent 当成事实。我遇到过 reviewer Agent 把 coder 的错误注释当成“项目约定”来遵循。解决方案是Agent 间通信走结构化格式，禁止自由文本传递。

第三类：提示注入。如果 Agent 会读取外部内容（比如用户输入、网页），恶意内容可能劫持 Agent 行为。解决方案是对外部内容做隔离标记，Agent 处理时明确区分“指令”和“数据”。

注意：Agent 安全没有银弹。我的经验是建立“三层防御”：输入过滤、执行沙盒、输出审查。任何一层发现问题都立即中断。

5.3 性能调优：让 Agent 跑得更快更稳

Agent 性能调优的核心是减少无效的上下文加载。我做过一个实验：同一个任务，加载完整代码库上下文 vs 只加载相关文件上下文，后者速度快 3 倍，准确率还更高。

具体做法是：在CLAUDE.md里定义“上下文加载规则”，告诉 Agent 什么任务该加载哪些目录。比如“修改 API 时只加载 src/modules/ / 和 src/shared/”。这个规则让 Agent 的启动时间从平均 15 秒降到 4 秒。

另一个技巧是缓存常用上下文。对于频繁执行的任务类型（比如写测试、改配置），把相关上下文预先向量化存储，Agent 需要时直接检索，避免每次重新读取文件。

6. 度量体系：怎么知道你的 AI Native 转型成功了

6.1 四个核心指标

我用的度量体系只有四个指标，但每个都经过精心设计：

指标一：AI 产出采纳率。AI 生成的代码/文档被最终采纳的比例。这个指标反映 AI 输出的质量。健康值应该在 60%-80% 之间。太低说明 AI 能力不足或约定不清，太高反而要警惕——可能人工 review 形同虚设。

指标二：返工率。任务完成后因为质量问题需要重新处理的比例。AI Native 团队的返工率应该比传统团队低 30% 以上。如果没降反升，说明流程有问题。

指标三：人工介入时长占比。人工在任务中花费的时间占总时长的比例。这个指标反映自动化程度。我的目标是降到 20% 以下，目前团队稳定在 25% 左右。

指标四：缺陷逃逸率。上线后发现的缺陷占总缺陷的比例。AI Native 不应该降低这个指标，反而应该通过更严格的测试来降低它。

6.2 度量数据的采集与可视化

度量数据必须自动采集，手动统计的数据没人会坚持。我的做法是在 Agent 框架里埋点，每次任务执行自动记录上述指标，汇总到看板。

看板不需要复杂，一张表格加趋势图就够了。关键是每周 review 一次，发现异常立即排查。我见过太多团队建了看板但没人看，最后变成摆设。

7. 团队协作模式的调整

7.1 角色重新定义

AI Native 团队里，传统角色需要重新定义：

• 初级开发者：从“写代码”转向“审核代码 + 补充测试”。这个转变对很多人来说是痛苦的，因为审核比编写更考验判断力。
• 高级开发者：从“写核心代码”转向“设计约束 + 处理边界情况”。核心代码交给 Agent，人负责定义“什么不能做”。
• TL/架构师：从“技术决策”转向“流程设计 + 度量优化”。技术决策可以借助 Plan Mode 推演，流程设计才是真正的价值所在。

7.2 代码审查的新范式

AI Native 的代码审查跟传统审查有本质区别。传统审查关注“代码写得对不对”，AI Native 审查关注“AI 的理解对不对”。

我的做法是：审查时先看 Agent 的 Plan，再看实现。如果 Plan 就有问题，实现再漂亮也没用。审查清单也变了：

• Agent 是否遵循了CLAUDE.md的所有硬约束
• 边界情况是否被覆盖
• 是否有“看起来对但实际有隐患”的模式
• 测试是否真正验证了行为，而不只是覆盖率

7.3 知识沉淀的新方式

传统团队靠文档和口口相传沉淀知识，AI Native 团队靠可执行的约定。CLAUDE.md就是最好的知识载体——它既是文档，又是 Agent 的行为准则，还是新人的入门指南。

我的经验是：每次踩坑后，第一时间把教训写进CLAUDE.md。比如“批量操作必须考虑幂等性”这条，就是一次线上事故后加进去的。这样知识不会流失，而且立即生效。

8. 我踩过的三个大坑

第一个坑是过早追求全自动化。早期我想让 Agent 端到端完成所有任务，结果质量完全失控。后来调整为“关键节点人工介入”，质量才稳定下来。AI Native 不是无人化，人机协作的边界设计才是核心。

第二个坑是忽视上下文管理。有段时间 Agent 表现时好时坏，排查很久才发现是上下文加载策略有问题。不同任务加载了不相关的上下文，导致 Agent 注意力被稀释。后来做了精细化的上下文规则，表现才稳定。

第三个坑是度量体系建得太晚。前三个月靠感觉判断效果，走了不少弯路。后来建立度量体系后，才发现很多“感觉良好”的改进其实没有效果，而一些被忽视的环节才是真正的瓶颈。

这三个坑的共同教训是：AI Native 转型是系统工程，不能靠单点突破。工具、流程、约定、度量，缺一不可。

9. 后续可以这样扩展

如果你已经跑通了基础流程，下一步可以考虑这几个方向：一是把 Agent 能力扩展到运维侧，做自动化的故障诊断和修复；二是建立跨团队的约定共享机制，让CLAUDE.md的最佳实践在组织内流动；三是探索 Agent 的自我改进——让 Agent 根据历史执行数据自动优化自己的行为准则。

我个人最看好的方向是第三个。目前已经在试点：让 Agent 分析自己的失败案例，自动生成CLAUDE.md的补充条款。初步效果不错，但还需要更多数据验证。这个方向如果跑通，AI Native 团队就真正具备了自我进化的能力。