AI Agent Engineering · Week 12
12-02|企业 AI Agent 应该交付哪些东西
把代码、架构、测试、安全、部署、演示和交接材料组合成可运行、可验收、可维护的交付包。
一个在线 Demo 不能代表完整交付
企业接手系统时会问:代码在哪里,怎样启动,使用什么数据,权限怎样控制,失败如何恢复,哪组测试证明它可用,谁维护知识库,哪些功能仍是 Mock。只有演示视频或聊天截图,无法回答这些问题。
最终交付包
Agent 项目 · 在线/本地 Demo · GitHub Repository · README
系统架构图 · Workflow · Tools · API/MCP · 数据与知识库设计
权限与安全设计 · Eval/Reliability Report · Security Report
部署说明 · Config/Secret 清单 · Monitoring · Rollback · Runbook
Demo Script · 截图/视频 · Enterprise Case Study
README 是入口:解释业务问题、能力边界、架构、快速启动、测试命令、演示账号、已知限制和文档索引。详细设计可以拆分,但入口必须让新接手者知道从哪里开始,以及哪些前置资源需要另行申请。
证据如何串起来
Requirement ID
↓
Architecture Decision + Owner
↓
Implementation Version
↓
Test Case + Trace + Audit
↓
Report + Acceptance Sign-off
↓
Runbook + Change History
“系统支持安全退款”需要具体证据:需求编号、退款 State Machine、Approval Contract、对象级授权测试、重复执行测试、Security Report 和部署版本。截图可以帮助展示,但不能代替可重复测试和机器可读结果。
交接时明确四种状态
已经实现,并通过列明环境和版本的测试
流程可演示,业务系统或数据为模拟
架构和接口已定义,尚未完成实现
当前版本明确不承担,说明原因和后续条件
作品集描述同样遵守事实边界。可以写“我设计了退款 Workflow、Tool Contract 与安全测试;使用 Codex 协助实现;在 Mock 数据集上通过 49 个用例”。如果没有连接真实 Shopify、没有生产流量和正式安全评审,就明确写出这些限制。
Failure Lab
交付一个能跑的仓库就结束
为什么诱人: 源代码是最具体的成果,开发者也最熟悉。
为什么失败: 客户无法判断配置、数据、风险、验收状态和故障处理责任。
更合理设计: 代码与架构、测试证据、部署、Runbook、限制和交接清单一起交付。
报告里只放成功截图
为什么诱人: 页面简洁,演示效果好。
为什么失败: 截图缺少输入、版本、断言和失败边界,无法重复验证。
更合理设计: 截图用于沟通;Case Result、Trace、Report 和版本记录用于验收。
隐藏 Mock 与未完成功能
为什么诱人: 项目看起来更接近商业成品。
为什么失败: 客户会基于错误前提评估风险,后续交接也会立即暴露差距。
更合理设计: 使用状态标签明确 Implemented、Mock、Designed 和 Out of Scope。
实践:执行 Delivery Package Audit
对照 10 项最终交付物,逐项记录路径、版本、Owner、完成状态、验证方法和已知限制。让一个不了解项目的人只看 README 与文档索引,尝试启动 Demo、运行测试、定位一次失败并找到回滚步骤。
Acceptance Criteria
- ☐ Repository 与 README 能解释问题、边界、架构、启动、测试和文档入口。
- ☐ 架构图覆盖 Workflow、Tools、API/MCP、数据、RAG、权限和部署。
- ☐ Reliability 与 Security 报告可追溯到 Case、Trace 和版本。
- ☐ 部署说明包含 Config、Secret、数据、Health、Monitor 和 Rollback。
- ☐ Demo Script 同时展示成功、失败、审批和越权拒绝。
- ☐ Enterprise Case Study 记录需求、判断、实现、证据、结果和限制。
- ☐ 每项能力标明 Implemented、Mock、Designed 或 Out of Scope。
- ☐ 文档说明个人设计、Codex 协助与实际测试范围。
主动回忆
- 为什么 README 应该成为交付入口?
- 截图和可重复测试分别承担什么作用?
- 一个功能要怎样从需求追溯到验收证据?
- 准确披露 Mock 和限制为什么会增强可信度?
下一课进行 Final Challenge:独立完成需求判断、架构、测试、部署与交付说明。
延伸阅读 / Sources
核查日期:2026-10-18。
- GitHub Docs:About the repository README file。用于核对 README 的项目入口与可见范围。
- OpenAI API:Evaluation best practices。用于核对任务标准、持续评估和人工校准证据。
- NIST:AI Risk Management Framework。用于核对风险、责任、测量与治理材料。
长期有效的原理: 企业交付需要可运行资产、可追溯证据、运行责任和限制说明。当前实现方式: 文档工具与部署平台会变化,交付索引和状态声明应长期维护。