Agentic Engineering

Agentic
Engineering

Created By技术开发部 · 马里奥
2024.10.25 / SIMON WILLISON

鹈鹕骑自行车
为什么选它？

Simon Willison 公开分享了一项非正式 LLM 测试。他用同一句提示词测试了 OpenAI、Anthropic、Google 和 Meta 的 16 个模型。

后面会用它演示怎样写验收标准、验证结果和组织项目文件。

原文 · Pelicans on a bicycle ↗

原始提示词

Generate an SVG of a pelican riding a bicycle

生成一幅鹈鹕骑自行车的 SVG 矢量图。

让语言模型写代码，再看渲染结果

Willison 喜欢鹈鹕，也猜测训练数据中不太可能已有同题 SVG。浏览器把模型写出的代码渲染成图，可以直观看出车架几何、脚踏位置，以及鹈鹕和自行车是否组合得合理。

AGENTIC AI FOUNDATION

AAIF

开放 Agent 生态的中立治理层Linux Foundation 旗下 · 2025.12.09 成立推动开源项目与开放标准透明、协作地被采用
AGENTIC AI FOUNDATION

AAIF 的职责

为开放的 Agent 标准和开源项目提供厂商中立的协作平台。

AAIF 成立公告 ↗

推动标准化

支持开放协议和格式，让 Agent 能连接外部工具与数据、互相通信，并复用项目指引与专业能力。

治理开源项目

为 Agent 框架和协议提供长期、中立的治理机制，降低对单一厂商的依赖。

建设行业生态

汇聚 OpenAI、Anthropic、Google、Microsoft 等企业与开源社区，推动 Agent 产品、工具和基础设施互操作。

FOUNDING CONTRIBUTIONS / 2025.12.09

The Founding
Three

三个创始贡献项目，分别覆盖连接协议、Agent 运行时与项目指导。

ANTHROPICFOUNDING PROJECT

Model Context Protocol

连接 AI 模型、工具、数据与应用的开放协议。

BLOCKFOUNDING PROJECT

goose

本地优先、开源可扩展的 AI Agent 框架。

OPENAIFOUNDING PROJECT

AGENTS.md

为 Coding Agent 提供一致项目指导的简单开放格式。

10 OPEN PROJECTS / AAIF

Project
Landscape

从工具接入与 Agent 协作，到运行、隔离与训练。

AAIF 官方项目清单 ↗
Agent RouterGrowth

基础设施 管理应用访问模型与 MCP 工具的路由和权限。

Agent SkillsImpact

能力扩展 用开放格式封装可复用的 Agent 专业能力。

Agent2Agent (A2A)Growth

Agent 通信 规范不同 Agent 之间的通信与任务协作。

agentgatewayGrowth

基础设施 为 Agent、模型与 MCP 提供安全的流量网关。

AGENTS.mdImpact

开发规范 向 Coding Agent 提供项目指令与上下文。

gooseImpact

Agent 运行时 开源、可扩展，支持多种模型。

MCPImpact

工具协议 规范 AI 应用与外部工具及数据的连接。

Open ResponsesImpact

API 规范 提供可跨模型供应商使用的通用接口格式。

OpenEnvGrowth

模型训练 为 Agent 的强化学习后训练提供环境接口。

OpenSandboxSandbox

执行环境 为 Agent 提供隔离的执行沙箱。

圆点标记创始项目。中文标签按技术用途归类，英文标签表示项目阶段。
MODEL API PROTOCOLS / 接口对比

Model API
Protocols

从数据结构到流式事件，理解三种模型接口设计。

OPENAI API

Chat Completions

DATA
messages
TOOLS
tool_calls
THINKING
依赖模型及扩展字段
STREAM
SSE · choices.delta
BEST FOR
通用聊天、兼容接入
OPENAI API

Responses

DATA
input / output
类型化 Items
TOOLS
独立工具调用输出项
THINKING
专门的推理输出结构
STREAM
SSE · 类型化事件
BEST FOR
复杂 Agent 工作流
ANTHROPIC API

Messages

DATA
messages / content
TOOLS
tool_use 内容块
THINKING
Thinking 内容块
STREAM
SSE · 内容块事件
BEST FOR
Claude 原生能力
AGENTS.MD / 重点辨析

More Than
a File

同一个名称，既指 AAIF 旗下的开放项目，也指你仓库中的具体文件。

OPEN PROJECT / AAIF · IMPACT

AGENTS.md

跨仓库、跨工具的共同约定
  • 开放格式与参考文档
  • 独立仓库、维护与社区治理
  • 跨 Coding Agent 的生态采用
agents.md · agentsmd/agents.md · MIT
LOCAL FILE / YOUR REPOSITORY

AGENTS.md

某个项目自己的工程说明书
  • 安装、运行与测试命令
  • 代码风格、边界与安全约束
  • 目录约定与协作要求
project/AGENTS.md
项目定义共同语言；文件记录你的项目规则。
你创建的 AGENTS.md 文件，是对这个开放项目所推广格式的具体采用。
project/AGENTS.md

AGENTS.md

Agent 的工作手册规定工作方式、项目指引和约束
CUSTOM EXTENSION / 自定义架构知识

Architecture
& Decisions

既描述系统如何组成，也保留重要决策为什么发生。

docs/architecture.md

architecture.md

系统设计蓝图

描述系统架构、技术栈与模块边界。

docs/adr/

adr/

架构决策档案

记录重要技术决策及其原因。

docs/memory.md

memory.md

项目的经验库保存经过验证、值得长期复用的知识
CUSTOM EXTENSION / 自定义扩展
specs/001-pelican-on-bike/worklog.md

worklog.md

已经做了什么记录执行进度和验证结果。例：SVG 结构检查通过，待确认缩小后能否辨认。
CUSTOM EXTENSION / 自定义扩展
DEVELOPMENT PARADIGM / 开发范式

SDD

Spec-Driven Development规范驱动开发
SPEC-DRIVEN DEVELOPMENT

SDD 的
思想演进

谈到 SDD 的来源，可以分别追溯理论基础、术语的学术用法、AI 时代的思想倡导和工具实践。

  1. 早期理论基础 · Tony Hoare ↗

    霍尔逻辑用「前置条件、程序、后置条件」描述程序行为，为形式化验证提供方法。

  2. 名称的早期明确学术使用 · Ostroff、Makalsky、Paige ↗

    三人在《Agile Specification-Driven Development》中明确使用 SDD 一词，将测试驱动开发与契约式设计结合。

  3. AI 时代的思想倡导 · Sean Grove ↗

    在《The New Code》中倡导以规格作为意图的来源（Spec-as-Source），用它指导 AI 生成代码和验证结果。

  4. AI SDD 的早期工具实践 · AWS Kiro 团队 ↗

    Kiro 将需求、设计和任务组织成可审阅的文档，由 Coding Agent 按任务实施。

  5. 开源工作流 · GitHub Spec Kit 团队 ↗

    Den Delimarsky 介绍开源工具 Spec Kit，让不同 Coding Agent 都能按规格、计划和任务推进实现。

.specify/memory/constitution.md

constitution.md

项目的宪法定义不可轻易违反的工程原则
SPEC KIT STANDARD / 标准产物
specs/001-pelican-on-bike/spec.md

spec.md

要做什么交付独立 SVG：能看出鹈鹕正在骑车，缩小后仍能辨认长喙和两个车轮。
SPEC KIT STANDARD / 标准产物
specs/001-pelican-on-bike/plan.md

plan.md

准备怎么做用 viewBox 管理缩放，将车轮、车架和鹈鹕分组，用矢量图形绘制。
SPEC KIT STANDARD / 标准产物
specs/001-pelican-on-bike/tasks.md

tasks.md

具体做哪些事绘制车架和车轮 → 补齐鹈鹕与骑行姿势 → 做结构检查与缩放验收。
SPEC KIT STANDARD / 标准产物
CONTEXT → CODE → CONTINUITY

The Continuity
Loop

从理解项目到验证结果，再把经验带回下一次会话。

01
AGENTS.md加载项目指引、工作方式与协作约束
02
architecture.md + adr/ + memory.md自定义扩展：恢复架构、技术决策与长期经验
03
constitution.md → spec.md → plan.md → tasks.mdSpec Kit 标准产物：从工程原则到规格、计划与任务
04
src/ + tests/ + worklog.md执行开发、验证结果；worklog.md 记录交接，属于自定义扩展
经验与验证结果回流 memory.md / worklog.md，让下一次会话继续而非重来。
DOCUMENT MAP / 初版目录

Project
Filesystem

一套目录，连接项目知识、工程规范与交付过程。

project/
├─ AGENTS.md
│
├─ docs/
│  ├─ architecture.md
│  ├─ memory.md
│  └─ adr/
│
├─ .specify/
│  └─ memory/
│     └─ constitution.md
│
├─ specs/
│  └─ 001-pelican-on-bike/
│     ├─ spec.md
│     ├─ plan.md
│     ├─ tasks.md
│     └─ worklog.md  # 自定义扩展
│
├─ src/
└─ tests/
目录设计复盘

两个 Memory
存的是什么？

project/
├─ docs/
│  └─ memory.md
└─ .specify/
   └─ memory/
      └─ constitution.md

命名歧义

docs/memory.md 存长期经验，.specify/memory/ 在这个例子中存放 Spec Kit 的工程治理规则。

概念层级混在一起

constitution.md 定义团队必须遵守的规则。长期经验则帮助团队复用已经验证过的做法。

维护成本随文档增加

随着 AGENTS.md、ADR 和架构说明增加，开发者和 Agent 都需要知道新知识该放哪里、以哪份记录为准。

SPEC KIT / 工具约定

Spec Kit 的
治理规则

目录设计要区分工具依赖的路径和团队维护知识的方式。

Spec Kit 官方文档 ↗

正式路径

Spec Kit 将项目治理原则保存在 .specify/memory/constitution.md。

运行时读取

根据官方文档，plan、tasks 和 analyze 每次运行时从该路径读取当前规则。

工具目录的边界

这里的 memory/ 可理解为 Spec Kit 保存持久项目约束的位置。通用 Agent 记忆和团队知识库可以各自设计。

方案一 / 继续使用 SPEC KIT

保留工具路径
按职责归档

保留 Constitution 的正式路径。把 docs/memory.md 中仍有用的经验按主题迁入 docs/knowledge/，更新引用后停用旧文件。

架构决策放在 docs/adr/，功能进度和交接继续写在对应的 worklog.md。

project/
├─ AGENTS.md
├─ .specify/
│  └─ memory/
│     └─ constitution.md
├─ docs/
│  ├─ architecture.md
│  ├─ adr/
│  │  ├─ 0001-xxx.md
│  │  └─ 0002-xxx.md
│  └─ knowledge/ # 按需建立
│     ├─ known-issues.md
│     └─ lessons-learned.md
├─ specs/
│  └─ 001-pelican-on-bike/
│     ├─ spec.md
│     ├─ plan.md
│     ├─ tasks.md
│     └─ worklog.md
├─ src/
└─ tests/
鹈鹕骑自行车 / AGENTIC ENGINEERING 教学练习

从一句提示词，到可验收的交付

Willison 的原题用于比较模型输出。下面是本课基于原题设计的工程练习，加入了动画要求、验收标准和反馈流程。

01 · Prompt Coding

用原始提示词生成第一版 SVG，打开看看鹈鹕和自行车是否容易辨认。

02 · Spec-Driven Development

在 spec.md 写清验收标准：鹈鹕有长喙和喙囊，车架连着两个轮子，动画中双脚始终跟随脚踏。

03 · Harness Engineering

让 Agent 生成 SVG 后自动渲染，截取踩踏的关键帧，把结构检查结果和截图交回 Agent 修改。

04 · Verification

自动检查 SVG 能否解析、有无外部资源。人工查看车架连接、缩小后的可辨识度，以及脚踏与双腿是否同步。

鹈鹕骑自行车 SVG / 项目文件示例

交付一张 SVG
文件怎么放？

鹈鹕骑自行车 白色长喙鹈鹕骑着青色自行车，双腿交替踩踏，车轮转动，路面向后流动。

规则、设计记录、任务进度和成品各有存放位置。Agent 从 AGENTS.md 找到它们。

目录职责与示例
.specify/治理规则。例：SVG 必须自包含，变更须通过结构检查。
docs/长期维护的技术知识。例：用 ADR 记录选择原生矢量图形的原因，把可复用的缩放排查经验归入 knowledge/。
specs/本功能的规格、计划、任务和进度。例：在 spec.md 写清验收标准，在 worklog.md 记录待确认的缩放效果。
src/、tests/交付与验证。例：src/pelican.svg 和检查 SVG 能否解析、有无外部资源的测试。
方案二 / 自研 HARNESS

治理规则
由谁维护？

如果 Harness 自己负责加载治理规则，可以用 docs/governance.md 作为项目内的规则入口。

多仓库共用规则时，可以由中央配置仓库发布版本，Harness 按项目加载。项目记录采用的版本，便于追溯。

project/
├─ AGENTS.md
├─ docs/
│  ├─ governance.md
│  ├─ architecture.md
│  ├─ adr/
│  └─ knowledge/
├─ specs/
├─ src/
└─ tests/
文档设计检查

文档服务于
工程交付

Agentic Engineering 不应演变成 Markdown Engineering。

按实际用途决定文档数量。已有可靠的持久化记忆系统时，复用它保存和检索长期经验。需要随仓库维护的知识再按主题写入 docs/knowledge/。

每类知识有一个权威来源

同一条规则由一处维护，其他文档引用它。

Agent 按任务读取上下文

通过 AGENTS.md 找到当前任务需要的规格、架构或决策。

长期知识和临时状态分开

进度、阻塞和交接写在 worklog.md。值得复用的经验经验证后再归档。

关键规则有可执行的检查

用测试验证行为，用 Lint 检查代码约束，由 CI 在合并前执行这些检查。

规则设计 / 职责与读取机制

两份文件，谁在什么时候读？

两份文件都能写项目规范。2026 年 5 月，Spec Kit 社区讨论了同时维护它们是否违反 DRY。可以从谁读取、何时读取来决定怎么分工。

维度AGENTS.mdconstitution.md
定位Agent 的操作指令入口项目工程治理原则
主要读取方Codex 等支持该文件的 Coding AgentSpec Kit 的工作流命令
典型内容仓库上下文、工作步骤、命令和工具用法架构原则、质量门槛和设计约束
加载方式由 Agent 按自身规则发现并读取plan、tasks、analyze 在运行时读取
适用范围仓库里的日常编码任务，包括 SDDSDD 及显式引用它的其他流程
重复风险复制治理条款后需要同步更新复制 Agent 操作细节后也容易失步
社区讨论 #2476 ↗ · Codex 读取规则 ↗ · Spec Kit 运行时读取 ↗
鹈鹕骑自行车 SVG / 单一事实来源（SSOT）

质量门槛写一处，操作说明引用它

以 SVG 交付为例，治理文件定义合并条件，操作文件说明 Agent 如何验证。

constitution.md · 质量原则

## Quality Principles

- SVG 必须自包含，变更须通过自动化结构检查。
- 未通过必要测试的变更不得合并。

AGENTS.md · 操作步骤

## Development Workflow

- 修改 SVG 前，阅读
  .specify/memory/constitution.md 的质量原则。
- 运行本示例仓库的 npm run test:svg。
- 按 spec.md 检查原尺寸和缩小后的画面。
- 在 worklog.md 记录结果及未完成项。
鹈鹕骑自行车 SVG / 冲突演练

一份要求测试
一份允许跳过

如果 Constitution 要求 SVG 变更通过结构检查，而 AGENTS.md 写着「只改图形可以跳过测试」，两条规则就会冲突。

明确规则归属

团队约定由 Constitution 定义 SVG 的质量门槛，操作说明引用这条规则并给出验证步骤。

发现冲突就报告

暂停受影响的操作，指出文件和条款，请规则负责人确认。修正冲突说明后，再继续执行和验证。

由 CI 执行可验证的门槛

把 SVG 解析和外部资源检查设为合并前的必需检查。鹈鹕是否像在骑车，仍按规格进行人工验收。

选型 / 按工作流决定文件数量

一份还是两份？看工作流依赖

操作和治理的区分是一种维护约定。小项目可以把两类内容放在同一个文件的不同章节。

方案 A · 只用 AGENTS.md

适合不依赖 Spec Kit 的普通 Coding Agent 项目或轻量 SDD。把工程原则和操作步骤集中维护。

# AGENTS.md

## 工程原则
## 操作步骤与命令

方案 B · 同时保留两份

适合正式使用 Spec Kit 的团队。Constitution 保存治理原则，AGENTS.md 提供操作说明和文件索引。

project/
├─ AGENTS.md
├─ .specify/
│  └─ memory/
│     └─ constitution.md
└─ docs/
   ├─ architecture.md
   └─ adr/
HARNESS / 按任务加载

任务决定
加载哪些文档

文件名不决定指令优先级。普通 Codex 会话需要用到治理原则时，通过 AGENTS.md 的明确指引或 Harness 加载 Constitution。

团队需要约定规则由谁维护、何时加载、冲突如何处理，以及哪些检查必须由机器执行。

AGENTS.md · 工作入口

进入仓库时读取操作指引，再按任务定位所需文件。

constitution.md · 治理策略

设计、实现或审查涉及工程约束的变更时，加载适用条款。

architecture.md · 架构知识

任务涉及模块边界或系统交互时，读取当前架构，必要时查相关 ADR。

spec.md、plan.md、tasks.md · 工作流产物

进入具体功能时，按阶段读取需求、设计和待执行任务。

AGENTIC ENGINEERING

THANKS

感谢聆听 · 欢迎交流

技术开发部 · 马里奥

SLIDE INDEX