保持 Agentic AI 简单：AGENTS.md + Agent Skills + 规格驱动的实用工作流

原文来源：Keep Agentic AI Simple: A Practical Workflow — 用 AGENTS.md、Agent Skills 和规格驱动开发三个基础工具，让 AI 编码 Agent 稳定地产出高质量代码，而不需要复杂的提示词技巧。

很多开发者对 AI 编码 Agent 的印象是两极的：要么觉得是"vibe coding"——把项目丢给 AI 然后祈祷，要么觉得需要搭一套复杂的提示词工程体系。Tim Deschryver 这位 .NET/Angular 生态的老牌开发者给出了第三条路：保持简单，用三个基础文件加一个合理流程，就能让 Agent 从零重写整个项目。

他的实验项目是一个 ASP.NET API + Angular 前端的应用，由 Aspire 编排。过去一个月，他让 AI Agent 把整个项目从头重写了一遍，结果"速度提升惊人，代码质量不错——不是完美，但足够好"。他的定位很明确：AI 是车队里的"超级副将"（domestique），他本人是主将——主将决定战略和方向，副将负责出力。

第一步：AGENTS.md，让每个 Agent 都懂你的项目

AGENTS.md 是当前 AI 编码工具的事实标准上下文文件。它会被自动包含进 Agent 的每一次请求中，所以最适合放三类内容：通用指导原则、项目结构说明、Agent 可以使用的命令。

不同工具叫法不同——GitHub Copilot 里叫 instructions.md，Claude 里叫 CLAUDE.md——但 Tim 的做法是统一用 AGENTS.md 这个标准命名，用符号链接（symlink）让不兼容的工具也能读到同一份文件。这样切换工具时不用改任何指令。

他的 AGENTS.md 里包含：技术栈、构建/测试/lint 命令、编码风格和约定、应用的总体流程。有个细节值得抄作业：把数据库结构用 mermaid 语法画成图放进 AGENTS.md——大图人类看着费劲，但对 Agent 理解数据模型、定位改哪里非常有帮助。

文件要经常维护：引入新概念后让 Agent 在同一会话内更新 AGENTS.md，把反复出现的错误也记进去，相当于给 Agent 建一份"踩坑手册"。

第二步：Agent Skills，按需加载的知识库

Skills 和 AGENTS.md 的关键区别在于：AGENTS.md 每次都进上下文，Skills 只有相关时才被加载。这让上下文窗口保持精简，输出质量更高。Skills 本质上是 markdown 文件（也可以带脚本），教 Agent 特定工具或技术的知识。

Tim 用了不少现成的 skill：官方 Angular skill 教 Agent 最新的 Angular 特性（比如他项目里用的全部 Signal API）、.NET 官方 skills 提供 Entity Framework 的最佳实践，还有 pnpm、NuGet、Aspire 以及文档生成类的 skill。

最有价值的操作是他自己创建了两个 skill：

1. 设计系统 skill：记录项目的整体风格（颜色、字体）和可用组件。没有它，Agent 生成的 UI 代码经常偏离设计方向，导致界面不一致；有了它，界面质量稳定提升。他特别指出这对 Codex 模型尤其必要，Claude 相对好一些。
2. 端点模板 skill：因为大多数 API 端点实现方式相同，他把已有端点作为示例生成"端点模板"skill，后续生成的端点自动与现有代码保持一致。

Skill 的获取很方便：npx skills add dotnet/skills 就能安装，社区仓库在 skills.sh 可以搜索，也可以用 Anthropic 的 skill-creator 自动生成自己的 skill。

有意思的是他明确不用 MCP server："几个月前 MCP 被大力宣传，但它会撑爆 Agent 的上下文窗口，导致输出质量下降。"大部分 MCP server 能做的事，用 skill 或 CLI 工具（Playwright CLI、GitHub CLI 等）都能替代。

第三步：规格驱动开发，大功能先写文档

这是整个工作流里最关键的一环。Tim 用 OpenSpec 做规格驱动开发：用几句话告诉它想要什么，它会生成三个文件：

• proposal.md：功能分析——摘要、做什么、为什么、范围（含不做什么）、成功标准
• design.md：技术设计——涉及的区域、API 端点、Angular 组件、数据模型和实施细节
• tasks.md：分步实施计划——按顺序排列的任务清单

不满意就再补一两个提示词修改，或者直接手改生成的文件。这套文档随代码一起提交，成为代码库的一部分。

为什么规格这么重要？Tim 的观察很直接：没有规格时，Agent 经常漏掉微妙细节，或者实现方式不符合预期，导致要多轮返工。有了规格，Agent 和人类在动手前就对"要建什么、为什么建"达成一致。他把这比作 Les Orchard 说的"15 分钟瀑布"——用很短的结构化规划期换取后续顺畅的编码。

大功能走规格流程，小改动和 bugfix 就直接提示 Agent 修改，不必走完整套。

完整工作流长什么样

Tim 的日常流程：

1. 用 OpenSpec 的 propose skill 生成实施计划
2. 计划成形后让编码 Agent 按步骤实现
3. 功能完成后从功能角度测试，深度 review 关键代码路径——他把 AI 生成的 UI 组件当第三方依赖对待，只看公开 API 不看内部实现
4. 满意后用 git 和 GitHub skills 提交代码、开 PR
5. Agent 干活的同时，他去 review 代码、生成新计划、更新文档或者去跑个步

关于工具选型，他的结论是：模型之间差异已经不大（Claude 在纯设计类任务上略好），工具（harness）层也在变薄，Copilot、Codex、Claude、OpenCode 的差别主要是偏好问题。他个人倾向 OpenCode，因为能在同一个工具里切换不同模型，避免厂商锁定。

实操建议

如果你也想上手，他的建议是从最小配置开始：默认编码 Agent 先用起来，当发现 Agent 反复犯同一个错误时，再引入对应的机制——先加 AGENTS.md，再加 Agent Skills，最后上规格。

配合符号链接让不同工具共享同一套 AGENTS.md 和 skills（./claude/skills、./agents/skills 目录都指向同一份），既避免了重复维护，也方便以后换工具。

最后一句他引用的观点值得记住："不要做害怕 AI 的开发者，要做把它当成最新系统去学习的开发者。" AI 不是银弹，只有在人类主导方向时才能更快交付——但你得先上车，这套工作流就是一张低门槛的入场券。