企业官网建设流程全解析

1. 为什么需要给 AI Agent 配一套工程工作流

1.1 从“能聊”到“能干”的鸿沟

大多数人接触 AI Agent 的第一印象，是它能流畅地回答问题、写代码片段、做总结。但真正把它放进一个实际项目里，问题马上就来了：它记不住上下文、不知道项目规范、每次都要重新解释需求、生成的东西风格飘忽不定。这不是模型能力不够，而是缺少一套工程工作流来约束和引导它。

所谓“Skills”，本质上就是给 AI Agent 预置的一套可复用、可组合的能力模块。你可以把它理解成给一个新入职的工程师配的“上岗手册 + 工具箱 + 检查清单”。没有这套东西，Agent 就像一个聪明但完全不了解项目背景的外包人员，每次交付都要你从头 review 到尾。

我最初做这件事的动机很朴素：受够了每次开新对话都要把项目结构、代码规范、命名约定重新粘贴一遍。后来发现，真正的问题不是“重复输入”，而是Agent 缺少稳定的行为边界。它会自由发挥，而自由发挥在工程场景里往往意味着不可控。

1.2 这套工作流到底解决什么问题

把 Skills 拆开来看，它解决的是四类核心问题：

• 上下文一致性：Agent 在不同会话、不同任务中，对同一项目的理解保持一致，不会这次用驼峰命名、下次用下划线。
• 任务可分解：复杂需求能被拆成标准化的子任务，每个子任务有明确的输入输出和验收标准。
• 质量可兜底：通过预置的检查规则和模板，让 Agent 的输出在“及格线”之上，减少人工返工。
• 能力可积累：每次踩过的坑、总结的规范，都能沉淀成新的 Skill，下次自动生效。

这四点听起来像套话，但落到实操里，每一条都对应着具体的文件结构、提示词模板和调用逻辑。后面我会逐个拆开讲。

1.3 适合谁来参考这套方案

这套东西不是给“只想让 AI 写个周报”的人准备的。它适合以下几类场景：

• 你正在用 AI Agent 辅助开发一个有一定规模的项目，代码文件超过几十个。
• 你需要 Agent 反复执行同类任务，比如生成 API 文档、写单元测试、做代码审查。
• 你团队里有多个人都在用 Agent，但输出风格和质量参差不齐。
• 你想把某些重复性的工程决策固化下来，不想每次都靠人脑记忆。

如果你只是偶尔用 AI 查个语法，那这套工作流可能显得过重。但只要你的项目进入“持续迭代”阶段，它带来的收益会迅速超过搭建成本。

2. Skills 的核心设计思路与模块拆解

2.1 整体架构：三层结构

我最终落地的方案是三层结构，从下到上分别是：

这三层不是随便分的。基础规范层解决“不能做什么”，任务模板层解决“怎么做”，检查校验层解决“做完怎么验”。很多人的 Agent 工作流只有中间一层，结果就是 Agent 知道大概要干什么，但不知道边界在哪、也不知道做到什么程度算合格。

2.2 为什么选择“文件驱动”而不是“纯提示词”

一开始我也试过把所有规则塞进一个超长的系统提示词里。实测下来，超过一定长度后，模型对中间部分的规则遵循度会明显下降。而且每次改一条规则，都要动整个提示词，维护成本极高。

后来改成文件驱动：每个 Skill 是一个独立的 Markdown 或 YAML 文件，Agent 在需要时按需读取。这样做有几个好处：

• 可组合：不同任务加载不同的 Skill 文件，不会互相干扰。
• 可版本管理：每个 Skill 文件都能进 Git，改动有记录。
• 可测试：可以单独验证某个 Skill 是否生效，而不是黑盒调试。
• 可复用：同一个 Skill 能跨项目、跨会话使用。

提示：文件驱动的前提是你的 Agent 框架支持“按需读取文件”或“工具调用”。如果只支持单轮对话，那这套方案需要做适配。

2.3 核心模块清单

我目前维护的 Skill 模块大概有这些，按使用频率排序：

1. 项目结构说明：告诉 Agent 每个目录放什么、哪些文件不能动。
2. 代码风格规范：命名、缩进、注释、导入顺序。
3. 任务执行模板：新增功能、修复缺陷、重构、写文档。
4. 测试生成规则：测试文件位置、命名、覆盖要求。
5. 提交信息规范：提交格式、关联任务编号。
6. 依赖管理规则：新增依赖的审批流程、版本锁定策略。
7. 日志与错误处理：日志级别、错误码、异常捕获范围。
8. 输出格式检查：返回结果的 Markdown 结构、代码块标注。

每个模块都是独立文件，Agent 根据当前任务类型决定加载哪些。比如让它写测试，就加载“测试生成规则”+“代码风格规范”+“项目结构说明”。

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

3.1 基础规范层怎么写才有效

基础规范层最容易犯的错误是写得太“人性化”。比如“请尽量使用有意义的变量名”——这种表述对 Agent 来说等于没说。有效的规范必须是可判定的。

我现在的写法是这样的：

naming: variables: snake_case classes: PascalCase constants: UPPER_SNAKE_CASE private_methods: _leading_underscore max_length: 32 forbidden: [data, info, temp, obj]

注意最后那个forbidden列表。这是我从实际踩坑里总结出来的：Agent 特别喜欢用data、info、temp这种万能词，导致代码可读性极差。明确禁掉之后，它被迫去想更具体的名字。

另一个关键是给出正反例。纯规则不够，Agent 需要看到“什么算对、什么算错”。比如：

正确：user_profile = fetch_user_profile(user_id) 错误：data = get_data(id)

正反例不用多，每个规则配一组就够。但一定要有，否则 Agent 会按自己的理解自由发挥。

3.2 任务模板层的设计技巧

任务模板层是使用频率最高的部分。我的设计原则是：每个模板必须包含输入、步骤、输出、验收四个部分。

以“新增功能”模板为例：

## 任务：新增功能 ### 输入 - 功能描述 - 涉及的文件范围 - 是否需要新增依赖 ### 步骤 1. 阅读相关文件，确认现有实现 2. 列出改动清单，等待确认 3. 按清单逐个修改 4. 补充或更新测试 5. 更新相关文档 ### 输出 - 改动文件列表 - 测试运行结果 - 需要人工确认的点 ### 验收 - 所有测试通过 - 无新增 lint 错误 - 改动范围不超过输入指定范围

这里最关键的是第 2 步“等待确认”。早期版本没有这一步，Agent 会一口气改十几个文件，改完才发现方向错了。加上确认环节后，返工率大幅下降。

注意：确认环节会增加交互轮次，适合复杂任务。简单任务可以跳过，但要在模板里明确标注“简单任务可省略确认”。

3.3 检查校验层的落地方式

检查校验层最容易被忽略，但它决定了整套工作流的下限。我的做法是把检查项分成“硬性”和“软性”两类。

硬性检查是必须通过的，比如：

• 语法错误为零
• 测试覆盖率不低于阈值
• 无未使用的导入
• 无硬编码的敏感信息

软性检查是提醒性质的，比如：

• 函数长度建议不超过 50 行
• 注释覆盖率建议不低于 30%
• 圈复杂度建议不超过 10

硬性检查可以直接用工具跑，Agent 只需要读取结果。软性检查需要 Agent 自己判断，所以要在 Skill 文件里写清楚判断标准。

我实测下来，硬性检查用工具做比让 Agent 做更可靠。Agent 适合做软性判断，比如“这个函数名是否准确描述了它的行为”。分工明确之后，整体效率提升明显。

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

4.1 从零搭建一套最小可用工作流

如果你现在就想动手，我建议从最小可用版本开始。不要一上来就搞十几个模块，先跑通一个闭环。

第一步：确定你的 Agent 框架支持什么

不同框架对 Skill 的支持方式不同。有的支持工具调用，有的支持文件读取，有的只能靠系统提示词。先确认你的框架能力，再决定 Skill 的存储形式。

第二步：写第一个 Skill 文件

从“项目结构说明”开始。这个文件最简单，也最基础。内容大概是这样：

# 项目结构 ## 目录说明 - src/：源代码 - tests/：测试文件，与 src/ 结构镜像 - docs/：文档 - scripts/：辅助脚本 ## 禁止修改 - config/production.yaml - migrations/ 下的历史文件 ## 新增文件规则 - 源代码放 src/ 对应子目录 - 测试文件放 tests/ 对应子目录 - 临时文件放 tmp/，不提交

第三步：接入 Agent

在你的 Agent 初始化逻辑里，加入读取 Skill 文件的步骤。伪代码大概是这样：

def load_skills(task_type): base = read_file("skills/project_structure.md") if task_type == "test": base += read_file("skills/test_rules.md") elif task_type == "feature": base += read_file("skills/feature_template.md") return base

第四步：跑一个真实任务验证

找一个你本来就要做的任务，比如“给某个函数补测试”。观察 Agent 的输出是否符合 Skill 里的规范。不符合的地方，就是你需要补充或修改 Skill 的地方。

4.2 参数选择与阈值设定

工作流里涉及不少阈值，比如测试覆盖率、函数长度、注释比例。这些数字不是拍脑袋定的，我一般按这个逻辑来：

• 测试覆盖率：新项目从 60% 起步，稳定后提到 80%。老项目先看现状，设定“不低于当前值”即可。
• 函数长度：软性建议 50 行。超过 50 行的函数，Agent 需要主动提示“建议拆分”。
• 注释比例：不设硬性指标，但要求“每个公开函数必须有文档注释”。
• 圈复杂度：软性建议 10。超过时 Agent 需要说明原因。

这些数字都可以在 Skill 文件里配置，方便不同项目调整。关键是不要设一个你自己都达不到的标准，否则 Agent 会频繁触发警告，反而降低效率。

4.3 一次完整的任务执行记录

我拿最近一次“新增一个数据导出功能”来举例，完整走一遍流程。

任务输入：在现有报表模块里增加 CSV 导出功能。

加载的 Skills：

• 项目结构说明
• 代码风格规范
• 新增功能模板
• 测试生成规则

执行过程：

1. Agent 先读取报表模块现有代码，列出涉及的文件：report_generator.py、report_models.py、tests/test_report_generator.py。
2. 列出改动清单：新增export_csv方法、新增测试、更新文档。等待我确认。
3. 我确认后，Agent 开始修改。过程中它主动提示：“检测到report_generator.py已有 320 行，新增方法后建议拆分。”
4. 我同意拆分，Agent 把导出逻辑放到新文件report_exporter.py。
5. 生成测试，运行通过。
6. 输出改动列表和测试结果。

结果：整个过程交互 4 轮，改动 4 个文件，测试全部通过。如果没有工作流，这个任务大概需要我手动改 3 个文件、写 2 个测试，来回至少 8 轮对话。

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

5.1 Agent 不遵守 Skill 规则怎么办

这是最常见的问题。排查顺序如下：

我踩过最坑的一次是：两个 Skill 文件里都定义了命名规则，但一个用驼峰一个用下划线。Agent 每次随机选一个，导致输出风格飘忽。后来加了“基础规范层优先级最高”的规则才解决。

5.2 Skill 文件维护成本太高怎么办

一开始我每个项目都单独维护一套 Skill，后来发现 80% 的内容是通用的。现在的做法是：

• 通用 Skill：放在公共目录，所有项目共享。
• 项目 Skill：只放项目特有的内容，比如目录结构、特殊依赖。
• 覆盖机制：项目 Skill 可以覆盖通用 Skill 的同名规则。

这样维护量大幅下降。通用部分改一次，所有项目生效。

5.3 如何判断一个 Skill 是否值得沉淀

不是所有经验都值得写成 Skill。我的判断标准是：

• 重复出现：同类问题出现过至少 3 次。
• 可判定：能用明确的规则描述，不依赖主观判断。
• 有收益：沉淀后能减少至少 30% 的返工或沟通成本。

不满足这三条的，先记在笔记里，等满足条件再沉淀。否则 Skill 文件会越来越臃肿，反而拖慢 Agent。

5.4 多 Agent 协作时的 Skill 同步

如果你同时用多个 Agent（比如一个写代码、一个做审查），Skill 需要同步。我的做法是：

• 所有 Agent 读取同一套 Skill 文件。
• 审查 Agent 额外加载“检查校验层”。
• 写代码 Agent 额外加载“任务模板层”。

这样两边对规范的理解一致，审查结果才有意义。否则写代码的按一套规则，审查的按另一套规则，永远吵不出结果。

6. 进阶扩展与个人经验

6.1 把 Skill 和 CI 打通

Skill 里的硬性检查，其实和 CI 里的 lint、test 是重叠的。我现在的做法是：CI 跑工具检查，Agent 跑软性检查。两边结果汇总到同一个报告里。

这样做的好处是，Agent 不需要重复实现工具已经能做好的事，专注于它擅长的部分。比如语法错误交给编译器，Agent 只负责判断“这个函数名是否准确”。

6.2 用 Skill 做知识沉淀

除了工程规范，我还把一些领域知识写成了 Skill。比如“这个项目的业务术语表”、“常见错误码含义”、“历史遗留问题的背景说明”。Agent 在回答相关问题时，会先读取这些 Skill，避免说出外行话。

这部分的价值在长期项目中特别明显。新人入职要花几周才能搞清楚的背景，Agent 加载 Skill 后立刻就能理解。

6.3 我个人的几条经验

第一，不要追求一次写完美。Skill 是迭代出来的，先写个粗糙版本跑起来，遇到问题再补。我第一版 Skill 只有 20 行，现在有 800 多行，都是踩坑踩出来的。

第二，规则要少而精。与其写 50 条模糊的规则，不如写 10 条明确的。Agent 对规则的遵循度是有限的，规则越多，每条被遵循的概率越低。

第三，定期清理。每季度 review 一次 Skill 文件，删掉过时的、合并重复的、补充新踩的坑。不清理的话，半年后你自己都不想看。

第四，让 Agent 参与维护。我有时候会让 Agent 自己 review Skill 文件，指出矛盾或模糊的地方。它经常能发现我自己没注意到的问题。

这套工作流跑了大半年，最大的感受是：AI Agent 的能力上限很高，但下限取决于你给它配的工程约束。Skills 就是那个把下限抬起来的东西。它不会让 Agent 变得更聪明，但会让它的输出更稳定、更可控、更接近一个靠谱工程师的水平。