Agentic Engineering 落地指南：从上下文工程到多 Agent 研发体系

AI 辅助编程已经越过了“补全几行代码”的阶段。现在的问题不再是“AI 能不能写代码”，而是：

• AI 能不能理解真实项目的业务背景？
• 一个需求跨越多次会话时，AI 能不能恢复状态？
• AI 上次踩过的坑，下次能不能自动避开？
• 多个 Agent 能不能像团队成员一样分工协作？
• AI 生成的需求、设计、代码和配置，如何被系统性验证？

这些问题合在一起，指向一个新的工程范式：Agentic Engineering。

它的核心不是提示词技巧，而是把 AI Agent 纳入软件工程体系：用结构化上下文提供事实依据，用文档系统承载长期记忆，用 Skill 和 Subagent 封装专业能力，用门禁和自动化验证控制质量，用 git 让知识资产版本化、可协作、可复用。

1. 从 Vibe Coding 到 Agentic Engineering

Vibe Coding 可以理解为一种“随手和 AI 对话，让 AI 写代码”的工作方式。开发者描述目标，AI 生成代码；报错后把错误贴回去，AI 再修。它能解决很多小任务，但在真实工程里会遇到几个典型问题：

Agentic Engineering 解决的不是“让 AI 更听话”，而是让 AI 有上下文、有记忆、有工具、有验证、有协作边界。

可以用一个简单公式理解：

AI 工程产出质量 = 模型能力 × 上下文质量 × 验证强度

模型能力由平台和模型厂商提供；工程团队真正能控制的是后两项：上下文质量和验证强度。

2. Agentic 是一个光谱，不是开关

“Agentic”不是非黑即白的概念。一个系统让 LLM（大语言模型）参与控制流的程度越高，它就越 Agentic。

flowchart LR
    A[Router<br/>输入分类与路由] --> B[State Machine<br/>多步骤执行与循环判断]
    B --> C[Autonomous Agent<br/>自主规划、工具调用、记忆沉淀]

越往右，工程基础设施越重要。一个只做路由的系统，写几条规则就够了；一个能跨会话执行需求、生成代码、跑测试、沉淀知识的系统，必须具备：

• 上下文索引与检索
• 状态持久化
• 工具调用规范
• 多 Agent 协作机制
• 自动化评审和质量门禁
• 经验沉淀与文档维护

这就是 Agentic Engineering 的工程边界。

3. 核心约束：上下文窗口是 Agent 的认知带宽

传统软件系统的接口是函数签名、协议、数据库表结构。Agent 系统的“接口”更特殊：上下文窗口里的信息组合。

同一个 Agent，在不同上下文下会表现出完全不同的行为：

• 给它完整项目知识，它能按项目规范实现需求；
• 给它空目录和模糊描述，它会猜测甚至编造；
• 给它过多规则，它会遗漏关键约束；
• 给它少量精准规则，它反而稳定。

所以，Agentic Engineering 的第一性问题是：

如何让 Agent 在正确的时刻拿到正确的信息，并且只拿到必要的信息？

这也是很多复杂设计失败的根源。传统的领域驱动设计（Domain-Driven Design，DDD）适合确定性软件系统，但直接套到 Agent 体系上会出问题。DDD 强调边界、接口、聚合、事件；Agent 的行为却是概率性的、上下文驱动的。你无法像约束函数一样约束 Agent，只能通过上下文、工具、验证和反馈环路提高它的可靠性。

4. 文档即记忆：用文件系统承载 Agent 的长期知识

Agent 需要记忆，但不一定需要复杂数据库。最实用的做法是：用 Markdown 文档和目录结构承载长期知识，让人和 AI 读同一份资料。

一个典型目录可以这样设计：

.
├── AGENTS.md
├── context/
│   ├── team/
│   │   ├── INDEX.md
│   │   ├── git-workflow.md
│   │   ├── code-style.md
│   │   └── review-rules.md
│   └── project/
│       ├── project-a/
│       │   ├── INDEX.md
│       │   ├── architecture.md
│       │   ├── domain-model.md
│       │   └── experience/
│       └── project-b/
├── requirements/
│   └── req-001/
│       ├── meta.yaml
│       ├── plan.md
│       ├── process.txt
│       └── notes.md
├── skills/
├── agents/
└── commands/

这套结构把 Agent 的记忆拆成三层。

flowchart TB
    subgraph L[长期记忆：按需检索]
        C[context/<br/>团队规范、项目知识、经验文档]
        S[skills/<br/>可复用能力包]
        R[requirements/<br/>历史需求产物]
    end

    subgraph O[溢出区：跨会话存档]
        P[process.txt<br/>进度与阻塞]
        N[notes.md<br/>过程笔记]
        PL[plan.md<br/>计划与决策]
    end

    subgraph W[工作记忆：运行时上下文]
        X[当前对话上下文]
    end

    L --> W
    W --> O
    O --> W

这种设计有几个具体好处：

“文档即记忆”的关键价值在于知识一致性。如果人看 Wiki，AI 看向量库，早晚会出现版本漂移；如果人和 AI 都读仓库里的 Markdown 文件，知识更新只需要合一次 PR。

还有一个常被忽略的优势：高频使用会对抗文档腐化。传统文档写完没人看，很快过期；当 Agent 每天都依赖这些文档执行任务时，文档一过时，AI 行为就会出错，开发者会立刻发现并修正。

5. AGENTS.md 不应该变成巨型规则书

很多团队刚开始会把所有规则都塞进 AGENTS.md：

你要遵守 Git 规范……
你要遵守代码风格……
你要会写需求文档……
你要会做详细设计……
你要会代码审查……
你要会操作测试平台……

短期看很方便，长期会让上下文腐烂。规则越多，Agent 越难判断哪条最重要。更好的做法是让 AGENTS.md 退化成入口索引：

# 项目角色

你是本项目的研发协作者，需要基于仓库内文档和工具完成需求分析、方案设计、代码实现、测试验证和知识沉淀。

# 工作原则

- 先检索项目上下文，再生成结论
- 不确定的信息必须标注待确认
- 文档输出需要先给关键确认点，再生成完整内容
- 不在受保护分支直接提交

# 知识入口

- 团队规范：context/team/INDEX.md
- 项目知识：context/project/INDEX.md
- 需求状态：requirements/{id}/meta.yaml
- 工具能力：skills/、agents/、commands/

# 常用命令

- /requirement:new
- /requirement:continue
- /requirement:next
- /code-review
- /knowledge:extract-experience

它不负责承载全部知识，只负责告诉 Agent：你是谁、原则是什么、知识在哪里、工具怎么进场。

6. 从场景路由到工具设计：推送规则不如按需拉取

一种常见设计是“场景路由”：先让 Agent 判断当前任务属于需求定义、代码探索、方案设计还是代码审查，再加载对应规则。

flowchart LR
    U[用户意图] --> R[场景识别]
    R --> S[加载场景规则集]
    S --> A[主 Agent 执行任务]

这个设计早期有效，但场景变多后容易崩。真实需求经常横跨多个场景：

我在做需求定义，顺便看看已有代码实现，再根据现状调整方案。

此时 Agent 可能连续加载“需求定义”“代码探索”“方案设计”三套规则，主上下文被规则占满，任务本身反而被挤出去。

更稳定的方式是工具设计：

flowchart LR
    U[用户意图] --> P[平台根据描述匹配工具]
    P --> T[调用 Command / Skill / Subagent]
    T --> K[工具内部按需加载领域知识]
    K --> A[返回摘要或结果]

两种模式的区别很明显：

工具设计的本质是：把能力固化到 Command、Skill、Subagent、Hook、MCP 等平台扩展点里，而不是让 Agent 每次都在运行时猜流程。

7. 三层能力：Command、Skill、Subagent

Agentic Engineering 里的工具可以分三层。

7.1 Command：只做入口，不写业务流程

Command 不应该复制完整流程，它只做两件事：

1. 预检；
2. 委托给 Skill 或 Agent。

例如 /requirement:new 可以这样设计：

# /requirement:new

用途：启动一个新需求。

执行要求：
1. 检查当前分支是否允许创建需求分支。
2. 检查 requirements/ 下是否已有同名需求。
3. 委托 managing-requirement-lifecycle Skill 执行新需求初始化流程。

禁止：
- 不在命令内展开完整需求流程。
- 不复制需求文档模板。
- 不直接生成详细设计。

这样 /requirement:new、/requirement:continue、/requirement:next 可以共享同一个 managing-requirement-lifecycle Skill。规则改一处即可，不需要同步修改多个命令文件。

7.2 Skill：封装知识，不写死脚本

Skill 是专业知识包，不是固定脚本。它告诉 Agent 这个领域有哪些约束、模板、参考资料和校验方式，但不要把每一步都写死。

推荐结构：

skills/config-gen-engine/
├── SKILL.md
├── reference/
│   ├── field-spec.md
│   ├── enum-types.md
│   ├── config-structure.md
│   ├── when-syntax.md
│   └── db-tables.md
├── templates/
│   ├── lottery.json
│   ├── task-activity.json
│   └── checkin.json
├── examples/
│   └── production-samples.md
└── scripts/
    └── validate.go

关键约束：

• SKILL.md 保持短小，只写触发条件、流程概览、资源索引；
• 详细知识放到 reference/、templates/、examples/；
• 所有资源从 SKILL.md 一跳可达，不做深层嵌套；
• 确定性操作用脚本，不让 LLM 自由发挥。

7.3 Subagent：隔离大输出和复杂探索

如果任务会产生大量中间输出，就不要放在主对话里执行。代码审查、上下文收集、需求质量评审、文档批量更新都适合用 Subagent。

Subagent 的硬约束可以这样定：

常见分类：

选型逻辑可以固化成一棵决策树：

flowchart TD
    A[任务是否会产生大量输出<br/>或需要多轮独立探索?]
    A -->|是| B[使用 Subagent<br/>隔离上下文]
    A -->|否| C[是否需要领域知识<br/>或多步工作流?]
    C -->|是| D[使用 Skill<br/>按需加载知识]
    C -->|否| E[是否高频且固定?]
    E -->|是| F[使用 Command<br/>快捷触发]
    E -->|否| G[不用工具化<br/>写在规范或直接对话]

8. 需求全生命周期：让 AI 按工程流程工作

一个成熟的 Agentic Engineering 体系，应覆盖需求从提出到交付的完整链路。可以设计 8 个阶段：

flowchart LR
    A[1 需求初始化] --> B[2 需求定义]
    B --> C[3 概要设计]
    C --> D[4 详细设计]
    D --> E[5 开发计划]
    E --> F[6 编码实现]
    F --> G[7 代码审查]
    G --> H[8 测试验收]

配套命令：

每个需求有自己的状态目录：

requirements/req-001/
├── meta.yaml      # 阶段、项目、服务、分支等元信息
├── plan.md        # 当前计划
├── process.txt    # 进度日志
├── notes.md       # 过程笔记和待沉淀经验
├── requirement.md # 需求文档
├── design.md      # 设计文档
└── review.md      # 评审结果

8.1 上下文自动搜索：先查事实，再生成内容

AI 最危险的错误不是明显写错，而是“看起来合理但没有来源”。需求文档里出现一个不存在的接口、设计方案里引用一条虚构规则，后续阶段都会被误导。

解决方式是：任何文档生成前，先收集项目上下文。

flowchart TB
    A[启动需求/设计任务] --> B[读取项目 INDEX.md]
    B --> C[定位强相关文档]
    C --> D[读取团队规范]
    D --> E[读取模板和历史经验]
    E --> F[生成关键确认点]
    F --> G[用户确认后生成正式文档]

信息写入文档时，只允许三种状态：

禁止出现第四种状态：没有来源，但看起来合理，所以直接写入。

8.2 渐进式输出：先确认关键点，再写长文档

AI 生成长文档很快，人审查长文档很慢。如果一次性输出几千字，人的审查很容易变成“扫一眼通过”。

文档类任务应该分两段：

1. 输出 3 到 5 条关键确认点；
2. 用户确认方向后，再生成完整文档。

需求定义阶段的关键确认点可以包括：

• 已找到的项目上下文；
• 无法确认的信息；
• 需要用户决策的边界；
• 可能影响方案的技术约束；
• 建议采用的文档结构。

这样人的注意力集中在最重要的判断上，而不是被长文档淹没。

8.3 质量评审：固定维度 + 项目动态维度

需求评审不能只靠模板。固定维度提供基线，项目上下文提供动态检查项。

评审结论需要量化：

这让评审从“感觉差不多”变成可复现的工程判断。

9. 多 Agent 代码审查：并行专项检查 + 汇总裁决

代码审查天然适合多 Agent 并行。每个 checker 只关注一个维度，最后由汇总 Agent 合并结果。

flowchart TB
    A[/code-review] --> B[预检<br/>识别需求、仓库、增量变更]
    B --> C1[设计一致性检查]
    B --> C2[安全检查]
    B --> C3[并发检查]
    B --> C4[复杂度检查]
    B --> C5[错误处理检查]
    B --> C6[测试覆盖检查]
    B --> C7[规范检查]
    C1 --> D[汇总报告]
    C2 --> D
    C3 --> D
    C4 --> D
    C5 --> D
    C6 --> D
    C7 --> D

专项 checker 可以使用轻量模型，综合判断使用更强模型：

这种模式的优势不是“AI 代替人 Review”，而是把大量低级和重复检查前置。人类 reviewer 可以把精力放在架构取舍、业务语义和复杂风险上。

10. 知识闭环：每个需求都应该增加团队记忆

Agentic Engineering 的复利来自知识闭环：

flowchart LR
    A[需求开发] --> B[产生新知识和踩坑经验]
    B --> C[记录到 notes.md]
    C --> D[验收后整理到 context/]
    D --> E[后续需求自动复用]
    E --> A

记录粒度不要过细，也不要过粗。

一个简单记录模板就够用：

## 经验记录

场景：AI 在实现活动配置生成时写错日期格式。

错误：使用了 `2026-01-01`。

原因：项目运行时使用 Go 的 `time.ParseInLocation("2006:01:02")`，要求格式为 `2026:01:01`。

修正：在 field-spec.md 中补充日期格式规则，并加入生成前自检清单。

复用范围：所有活动配置生成任务。

重点不是文档写得多漂亮，而是让下一次 Agent 能避开同一个坑。

11. 业务落地案例：运营活动配置生成

运营活动配置是一个很适合 Agentic Engineering 的场景。它有明确流程、强领域知识、多个外部系统、很多可验证步骤。

人工流程通常包括：

flowchart LR
    A[需求分析<br/>确认玩法模板和历史活动] --> B[商品创建<br/>雅典娜平台]
    B --> C[活动创建<br/>雅典娜平台]
    C --> D[玩法规则配置<br/>Apollo 控制台]
    D --> E[验证与上线]

痛点很具体：

这个场景可以被改造成一个端到端 Skill：config-gen-engine。

11.1 Ralph Loop：让 Agent 自主迭代到完成

Ralph Loop 的核心是：Agent 完成一轮任务后，如果没有达到完成条件，Stop Hook 阻止退出，把同一条任务重新注入。Agent 通过文件系统读取上一轮状态，继续推进。

flowchart TB
    A[用户下达任务] --> B[Agent 执行当前步骤]
    B --> C[写入 state.json / 日志 / 产物]
    C --> D{是否输出完成标记?}
    D -->|否| E[Stop Hook 阻止退出<br/>重新注入原任务]
    E --> B
    D -->|是| F[允许结束]

这种机制适合多步骤、跨系统、需要重试的任务。状态不依赖长对话，而是写在文件里：

{
  "current_phase": "s4-config-gen",
  "finished_steps": ["s1-requirement", "s2-goods", "s3-activity"],
  "retry_count": 2,
  "last_error": "goods_id should be string, got number"
}

11.2 从自然语言到可运行配置

用户输入：

创建一个任务活动，用户完成签到任务后发放 10 积分奖励，活动时间为 3 月 1 日到 3 月 31 日。

Agent 执行 10 步：

flowchart LR
    S1[S1 需求解析] --> S2[S2 商品创建]
    S2 --> S3[S3 活动创建]
    S3 --> S4[S4 配置生成]
    S4 --> S5[S5 Go 校验]
    S5 --> S6[S6 DB 写入]
    S6 --> S7[S7 API 验证]
    S7 --> S8[S8 前端验证]
    S8 --> S9[S9 玩法引擎测试]
    S9 --> S10[S10 经验沉淀]

    S5 -.失败重试.-> S4
    S7 -.失败重试.-> S4
    S8 -.失败重试.-> S4
    S9 -.失败重试.-> S4

相比人工流程，AI 流程多了几层自动化验证：

11.3 领域知识决定配置质量

让 LLM 生成 JSON 不难，难的是生成能在运行时正确执行的配置。典型坑包括：

所以 Skill 必须带完整知识库：

config-gen-engine/
├── SKILL.md
├── reference/
│   ├── field-spec.md
│   ├── enum-types.md
│   ├── config-structure.md
│   ├── when-syntax.md
│   ├── db-tables.md
│   └── athena-mcp-tools.md
├── templates/
│   ├── lottery.json
│   ├── task-activity.json
│   └── checkin.json
├── examples/
│   └── production-samples.md
└── scripts/
    └── validate.go

这里体现了 Skill 的价值：模型负责理解自然语言和组合信息，知识库负责提供精确约束，脚本负责确定性校验。

11.4 三层验证：不要相信生成即正确

配置生成需要分层验证：

flowchart TB
    A[生成配置 JSON] --> B[L1 结构校验<br/>JSON + Go 反序列化]
    B --> C[L2 业务一致性校验<br/>字段关联、ID、枚举、日期]
    C --> D[L3 运行时验证<br/>API、前端、玩法引擎]
    D --> E[通过后写入经验]
    B -.失败.-> A
    C -.失败.-> A
    D -.失败.-> A

不同层能发现的问题不同：

每次发现新错误，都应加入自检清单。这样下一次错误会在更早阶段被拦住。

11.5 Playwright：让 Agent 真的看页面

Playwright 是浏览器自动化框架。Agent 可以通过可访问性树读取页面结构，找到按钮、输入框、表格和弹窗，再执行点击、输入、截图等动作。

前端验证流程可以这样设计：

sequenceDiagram
    participant Agent
    participant Browser as Playwright 浏览器
    participant Page as 雅典娜页面
    participant API as 本地后端/API

    Agent->>Browser: 打开页面
    Browser->>Page: 加载管理台
    Agent->>Browser: snapshot 获取可访问性树
    Agent->>Browser: 点击登录/搜索/详情
    Browser->>API: 请求商品和活动数据
    API-->>Browser: 返回本地实验数据
    Agent->>Browser: 断言字段与截图留证

如果前端页面请求默认打到远程测试环境，而 Agent 写入的是本地数据，可以用 Whistle 代理做进程级隔离：

flowchart LR
    B[Playwright 浏览器] --> W[Whistle 代理<br/>127.0.0.1:8899]
    W -->|/athena/plat/*| L[本地后端<br/>127.0.0.1:8002]
    W -->|HTML/CSS/JS| R[远程测试环境前端]

这样 Agent 看到的是“真实前端页面 + 本地实验数据”，不会污染公共测试环境。

12. 团队落地：从个人工具到团队知识网络

Agentic Engineering 的团队落地不是强推工具，而是让知识流转方式发生变化。

12.1 clone 替代培训

如果能力都在一个仓库里，团队成员 clone 后就获得：

• AGENTS.md 入口规则；
• context 目录中的团队和项目知识；
• Command、Skill、Subagent 定义；
• 需求目录结构；
• 代码审查门禁；
• 知识沉淀流程。

新人不需要理解全部内部机制，只需要从一个命令开始：

/requirement:new

最小上手路径：

复杂度不应该暴露给新人。22 个 Agent、几十个 Skill 都可以藏在命令背后。

12.2 知识维护要制度化，但不要变成负担

context/ 是团队公共资产，需要轻量 Review：

不值得永久沉淀的信息不要写进 context/：

如果维护文档比写代码还累，通常说明粒度太细了。

13. 快速开始：从一个仓库骨架起步

不需要从零设计整套体系。可以复制一个已有骨架，清空业务上下文，只保留工程能力。

# 删除业务知识
rm -rf context/project/*
rm -rf requirements/*

# 保留工程骨架
# AGENTS.md
# context/team/
# commands/
# skills/
# agents/

然后做三件事：

13.1 修改入口身份

# AGENTS.md

你是当前项目的研发协作者。

你需要：
- 先检索 context/ 中的项目知识；
- 不确定的信息必须标注待确认；
- 按需求生命周期推进任务；
- 代码变更后执行审查和测试；
- 需求结束后沉淀经验。

13.2 用真实需求启动知识积累

/requirement:new

让 Agent 在真实项目里完成需求定义、代码探索、设计草稿和笔记记录。即使只完成一个小需求，也会产生第一批项目上下文。

13.3 发现重复场景后再工具化

不要一开始就创建大量 Skill。满足这些条件时再封装：

14. 常见坑

14.1 规范膨胀

每次 AI 犯错都加规则，最后会让规则膨胀。规则过多时，Agent 反而更容易忽略关键约束。

处理方式：

• 高频错误写入 Skill；
• 偶发错误记录到 notes；
• 极端边界放到 reference，不进入主上下文；
• 定期删除长期未触发的规则。

14.2 缺少量化指标

工具多不代表体系好。需要记录：

不需要复杂平台，定期脚本统计就足够。

14.3 过度相信 AI 输出

规范、知识库、多 Agent 审查都只能降低风险，不能把 AI 输出变成终稿。人仍然要负责：

• 业务判断；
• 架构取舍；
• 安全边界；
• 上线风险；
• 最终质量。

AI 输出默认是草稿，工程责任仍在人。

15. Token 利用率会成为新的工程指标

Agent 消耗 token 执行任务，就像机器消耗电力完成生产。未来团队的软件产能不只取决于工程师数量，也取决于能否高效调度 token。

但消耗 token 不等于高产出。低质量使用方式会浪费大量 token：

• 不给上下文，让 AI 反复猜；
• 不沉淀经验，让同一错误反复出现；
• 不做验证，把错误留到后期；
• 把全部规则塞进上下文，导致 Agent 走神。

Agentic Engineering 追求的是 token 利用率：

真正的竞争力不是“用了多少 AI”，而是每个 token 转化成了多少正确、可交付、可复用的工程产出。

16. 多 Agent 协作不是越多越好

多 Agent 很强，尤其适合并行执行：

• 多维代码审查；
• 批量测试；
• 文档批量更新；
• 大规模代码库扫描；
• 独立子任务并行实现。

但不是所有场景都需要模拟完整软件团队。需求分析、架构决策、方案取舍这类任务高度依赖连续上下文和统一判断，过早拆成多个角色会带来交接损耗。

更务实的原则是：

地基是上下文，不是 Agent 数量。一个人加一个懂项目上下文的 Agent，往往比一群没有共享记忆的 Agent 更可靠。

17. 参考资料

• Andrej Karpathy：Vibe Coding / Agentic Engineering 相关讨论
• Harrison Chase：What is an AI Agent?
• Anthropic：Building Effective AI Agents
• Anthropic：Effective Context Engineering for AI Agents
• OpenAI：Harness Engineering
• Geoffrey Huntley：Ralph Wiggum Technique
• everything-claude-code：Claude Code 配置实践
• Nicholas Carlini：Building a C compiler with a team of agents
• BMAD-METHOD：多角色 Agent 软件工程工作流