我上周查看 GitHub 时，一个不到两周的仓库已经达到了 1,000 颗星，这个名字很简单：它是由 Denis Sergeevich 创建的，叫做“Agent Best Practices”。
2026 年，仍然有很多团队把模型当作一个万能的管家，让它决定一切，做一切，希望它不要搞砸，我自己也曾踩过这个坑。
去年，我为一位从事外贸工作的朋友做了一个客服智能体，这个要求看起来很简单，客户询问运费，智能体查数据库后回复，如果客户想更改地址，智能体就改地址，我构建了 LangGraph 的一个版本，在生产的第一周内，40% 的地址更改请求失败，要么是改了错误的字段，要么是界面根本没动，有两次，客户的订单状态直接变为“已取消”。
经过两周的调试，我最终确定问题在于根本不应该允许模型直接与数据库交互，这就是 Agent Best Practices 仓库的真正目的。
描述一组运行时规则，模型只负责提出建议，实际执行这个操作的部件称为约束层，该工具负责验证、批准、执行、记录并提供反馈，每个步骤都有明确的责任范围。
像我这样的小团队在踩到坑之前不会意识到这个问题，今年 2 月，OpenAI 发表了一篇名为《Harness Engineering》的文章，解释了他们如何使用 Codex 在内部编写产品代码， 3 名工程师，7 个 Codex 实例，3 个月内 1,500 个 PR，不到 100 万行代码，核心方法论就一句话，人类负责掌舵，智能体负责划船。
Anthropic 去年 12 月发布了一篇类似的文章，“构建有效的智能体"，视角更简单，简单的可配置模式比复杂的框架更好，避免使用允许你直接使用 API 执行此操作的框架。
你是否注意到，OpenAI 和 Anthropic 这两家领先的人工智能公司在智能体问题上有着令人惊讶的一致共识：不要赋予模型太多权力或依赖提示来确保运行时的严谨性？
Agent Best Practices 整体结构如下所示，底层是一个与提供商无关的智能体循环，用户输入进入上下文构建器，构建者组装上下文并将其提供给模型，该模型返回工具调用建议并执行架构验证，如果验证通过了权限检查，则在实际执行之前会通过权限检查，执行后，返回结构化观察结果，进入下一个循环，直到预算用完或任务完成。
在这个仓库中，工具根据风险进行分类，读取工具可以独立运行，草稿工具可以独立生成但必须标记，外部提交、部署、破坏性操作、财务操作和特权操作必须经过审批流程，每个工具都需要狭窄的类型定义、强大的模式验证和结构化的返回值，特别强调不得公开诸如 execute_anything、write_database 和 send_message 等通用工具。
我的客服智能体就犯了这个错误，我直接把 write_order 接口交给了模型，如果模型想要改变地址，可以改变地址，如果模型想更改你的状态，它可以更改你的状态，如果出现问题，没留日志。
另一个例子是上下文管理，这个仓库花了很多篇幅来解释压缩方法，如果智能体跑很久，上下文肯定会溢出，常见的做法是截断或压缩，但强调在压缩时必须保持活跃的工作状态，当前审批、运行计划、加载的规则和修改的文件不会丢失，如果批准记录丢失，模型将无法得知压缩后的位置，这可能会导致重复操作。
还有工具权限领域，这就提出了一个我认为特别重要的概念，叫做渐进式披露，不要一次向模型公开所有功能，首先输入名称和描述，然后在使用模型时加载详细的工作流程，原因很简单，智能体的上下文窗口是有限的，塞入太多东西不仅浪费代币，而且还会影响模型决策的质量。
Vercel 创建的 Skills 框架将这一想法变为现实， npx Skill add 命令安装在一行中，执行时，只有任务匹配才会激活相应技能的所有内容，该框架目前拥有超过 19000 颗星，可见业界确实需要这种标准化的扩展机制。
说到技能，Agent Best Practices 本身就是 Agent Skills，这遵循 agentskills.io、SKILL.md 条目文件以及 references 目录中的 16 个参考文档的规范，智能体启动时只读名称和描述，仅当用户谈论与智能体架构相关的问题时，才会加载完整的 SKILL.md 和相关参考。
设计本身实践了它所倡导的原则，保持简单并能够按需加载，但是，这个仓库不仅仅是最佳实践的集合，因为它具有三种特定用途，每种用途都有不同的输入和输出。
一是生成 MVP 蓝图，指定业务领域直接有助于制定最小可行的智能体设计计划，包括循环结构、工具注册表、权限矩阵、情境策略、规划模型、评估计划和在线路径，我认为这对于想要使用智能体但不知道从哪里开始的团队特别有用。
二是对现有架构进行审计，我已经有一个正在跑的智能体，但总是会出现问题，这对于逐层检查是否存在循环预算限制、压缩中是否存在状态丢失、工具的结果是否与不可靠的数据混合以及是否存在事件跟踪非常有用，很多人顺序搞反了，先用智能体，他们首先创建提示，然后添加工具，然后考虑添加保护措施，审计模式能帮你找出欠了什么债。
三是工具和权限的设计，有许多外部系统可供连接，包括 Slack、Linear、Google Drive 和内部 API，如何设计工具边界和权限级别，建议按风险分类，单独阅读，标记草稿，批准写入操作，不要使用通用接口。
这三种用法涵盖了从 0 到 1、1 到稳定、稳定到可扩展的整个智能体流程，然而，仓库并非没有争议。
GitHub Issues 上有人正在讨论 SKILL.md 和参考目录之间的重复内容， SKILL.md 记录了使其独立的核心原则，并且参考书目中还有更详细的扩展，双方经常谈论同样的事情，作者目前的态度是 SKILL.md 应该能够独立运行，并且重复是故意的，我理解这种权衡，但对于想要阅读更多内容的人来说似乎有点麻烦。
一些安全问题是无法避免的，正如 HN 上有人指出的，当前的技能生态系统实际上拉取的是 HEAD 版本的 GitHub 仓库，没有任何版本锁定或签名验证，经过扫描周围环境，他们发现了 59 个高危技能，其中包含经过 Base64 混淆的恶意代码，以及 335 个可以执行任意 shell 命令的技能。
这与早期 npm 的混乱非常相似，环境问题出现后，供应链安全并不总是得到认真考虑， Agent 最佳实践本身是 MIT 协议的干净仓库，但如果 Agent 技能分配模型不解决信任问题，则很难在企业级场景中实现大规模采用。
回到仓库本身，我不认为它的核心价值是 16 个引用，这些建议可以在 OpenAI 和 Anthropic 的官方文档中找到，真正的价值在于从“运行一个模型提案工具”的核心洞察出发，衍生出一套完整的自洽的运行时架构，此外，每个规则都是约束层级别的强制约束，而不是单独的提示技术。
当前的智能体生态有点像 2014 年的容器市场，虽然每个人都刚刚意识到 Docker 的潜力，但 Kubernetes 还没有到来， CrewAI 拥有超过 50,000 颗星，LangGraph 拥有超过 30,000 颗星，OpenAI Agents SDK 拥有超过 20,000 颗星，每个公司都在推广自己的抽象层。
Agent Best Practices 选择了一条不同的道路，它不依赖于运行时、模型提供程序或编排框架，它只是定义了该字段，这种姿势可能不会让你成为明星框架，但它会比其他框架持续更长时间。
纪律是一件事，所以无论你如何改变你的框架，你都必须有纪律，设置做智能体的第一步不是选框架，而是绘制权限矩阵，哪些运营模型可以自主运行，哪些需要手动确认，哪些根本不应该暴露给模型，当你绘制这个矩阵并选择工具和框架时，你会得到完全不同的方向感。
如果你也做 agent 相关的工作，即使你没有安装这个技能，花 20 分钟阅读它的 SKILL.md 和 mvp-agent-blueprint.md 可能比阅读一周的框架教程更有用。
