DenisSergeevitch/agents-best-practices · 上手攻略

  • 仓库：DenisSergeevitch/agents-best-practices
  • 链接：https://github.com/DenisSergeevitch/agents-best-practices
  • 分类：agent-harness · skill · architecture
  • 作者：Tom
  • 更新：2026-09-20

是什么

一个供应商无关（provider-neutral）的 Agent Skill，用于设计、审计、重构和解释 AI Agent 的控制平面（harness）。它不是运行时框架，而是一套设计方法论和 MVP 蓝图模板，适用于 OpenAI、Anthropic 或任何 OpenAI 兼容 API。核心理念一句话："模型提议动作；harness 负责验证、授权、执行、记录并返回观察结果。"

作者 Denis Sergeevitch 提炼了一套通用 agent 架构原则，覆盖编码、研究、财务、法律、支持、运营、销售、医疗、教育等工作流领域——编码 agent 只是其中一个子域。

解决什么问题

市面上的 agent 示例大多"能跑就行"，缺乏运行时纪律：没有步数预算、没有 schema 校验、没有权限矩阵、长对话后上下文压缩丢失活跃状态、无可观测性。agents-best-practices 的目标是让你在动手写代码之前先有一张合规蓝图，把 harness 设计成"生产就绪"。

核心解决三类问题： 1. 从零设计 agent 时无从下手 → 14 节 MVP 蓝图模板，按图索骥。 2. 现有 agent 脆弱/昂贵/难调试 → 审计清单（运行时级 vs 提示词级故障点分离）。 3. 选型困惑（Direct tool loop / LangChain / LangGraph / SDK） → provider-neutral 原则帮你独立评估。

快速安装

方式 A：通过 Skills（推荐，支持 Codex / Claude Code 等兼容 agent）

npx skills add DenisSergeevitch/agents-best-practices -g

-g 表示全局安装到用户级别，每个项目都能发现该 skill。

方式 B：粘贴 prompt 给 AI agent

Install the agents-best-practices skill for me:
1. Clone https://github.com/DenisSergeevitch/agents-best-practices into my
   user-level skills directory as `agents-best-practices/`.
   - Codex: ~/.codex/skills/
   - Claude Code: ~/.claude/skills/
2. Verify that SKILL.md, icon.jpeg, and the references/ directory are present.
3. Confirm the install path when done.

方式 C：手动 Git clone

# Codex
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
git clone https://github.com/DenisSergeevitch/agents-best-practices.git \
  "${CODEX_HOME:-$HOME/.codex}/skills/agents-best-practices"

# Claude Code（用户级）
mkdir -p "$HOME/.claude/skills"
git clone https://github.com/DenisSergeevitch/agents-best-practices.git \
  "$HOME/.claude/skills/agents-best-practices"

# Claude Code（项目级）
mkdir -p .claude/skills
git clone https://github.com/DenisSergeevitch/agents-best-practices.git \
  .claude/skills/agents-best-practices

⚠️ 注意：Skill 有自更新机制——每次新任务会检查 upstream main commit 与本地安装版本是否一致，若落后则自动用验证过的上游快照。安装后 skill 版本记录在 SKILL.md 的 metadata.version（当前为 1.9.0，⚠️ 此为 2025 年数据，最新版本请以 GitHub 最新 commit 为准）。

核心用法

默认 Agent 循环（任何 provider 通用）

user/task → instruction & context builder → model call → tool/action proposal
→ schema validation → permission decision → execution 或 approval pause
→ structured observation → context update → repeat within budget or finish

触发 Skill 的对话意图（任意一条即激活）

  • build / design / scaffold / specify an agent
  • audit / refactor / improve an existing harness
  • choose between OpenAI / Anthropic / OpenAI-compatible APIs
  • design tools, permissions, guardrails, approval flows, sandboxing
  • add context compaction、memory、retrieval
  • design programmable context / continual refinement / self-refining loops

MVP Blueprint 核心结构（14 节）

关键节选：

1. Objective — 定义 agent 的域、用户画像、输入输出、完成信号。

2. Autonomy Level（自主等级，默认 Level 1/2）

等级 描述 适用场景
Level 0 仅回答，无副作用 检索/摘要
Level 1 起草（人类执行所有变更） 默认起步
Level 2 审批门控动作（建议默认） 大多数业务 agent
Level 3 策略边界内自动执行 低风险操作，强日志
Level 4 跨检查点长期自主目标 仅在 harness 稳定后启用

3. Core Agentic Loop — provider-neutral 的模型→工具→观察循环，含预算和终止条件。

4. Tool Registry — 最小化 typed tools，按风险分级（read_private_data / draft_external_message / approval_gate 等）。

5. Context & Memory — 持久化状态在 prompt 外；自动压缩时需再水化（rehydrate）活跃状态而非仅聊天历史。

场景用例（直接复制使用）

You have a domain and need the smallest useful production-safe agent harness.

Build an agent for account renewal risk. It should read CRM,
support tickets, and usage data, then draft renewal actions.

→ Agent responds with Level 2 审批门控 MVP blueprint，
  含完整 core loop、minimal tools 和 launch gate。

审计已有 Agent 的修复顺序

1. Add loop budgets and termination reasons.
2. Store plan, approvals, todos, and artifacts outside the prompt.
3. Make compaction rehydrate active state, not chat history.
4. Add evals for injection, missing tool result, timeout, and budget exhaustion.

典型适用场景

  1. 从零构建业务 Agent（CRM 更新机器人、财务对账、法律合同审查）：先出 MVP 蓝图再写代码，避免后期重构。
  2. 审计现有 brittle Agent：区分运行时级 vs 提示词级问题，对症下药。
  3. 多 Provider 评估：用 provider-neutral 原则对比 OpenAI / Anthropic / 开源模型，不被 SDK 绑架。
  4. 安全与合规设计：工具风险分级、权限矩阵、approval gate、prompt injection 处理——作为架构设计的前置检查清单。
  5. 编码 Agent 专用：配合 references/coding-agents.md，区分 MVP（draft+verify+explain）vs 成熟期（merge+deploy+own production）。

坑与注意

⚠️ Skill 版本滞后风险：安装的 skill 是快照，不保证是最新。⚠️ 每次任务前需检查 upstream commit（SKILL.md 写了明确步骤），版本号 1.9.0 为历史记录，当前最新 commit hash 请以 GitHub 为准。

⚠️ 不能替代运行时框架：它只提供设计图，不提供执行引擎。你仍需选 LangChain / LangGraph / Direct loop 等作为 runtime。

⚠️ 自更新不覆盖本地修改：若安装目录有本地变更，skill 自更新会跳过而非覆盖，避免丢失定制，但需手动同步上游。

⚠️ Level 3/4 门槛高：长时自主运行需要成熟的 harness，文档建议"仅在 base harness 可靠后"才启用。

⚠️ Skill 覆盖范围极广：容易在对话中频繁触发，建议明确任务边界再调用，否则 skill 会用大量架构术语回应。

与同类对比

项目 类型 LLM in loop 适用场景 许可证
DenisSergeevitch/agents-best-practices 设计方法论/Skill — 从零设计/审计/选型 ⚠️ 未在 README 明确声明
LangChain / LangGraph 应用框架 ✅ 快速原型 MIT/Apache 2.0
CrewAI / AutoGen 多 Agent 编排 ✅ 多 Agent 协作场景 Apache 2.0
Raw direct tool loop 极简运行时 ✅ 追求控制的极客 —

核心差异：agents-best-practices 不运行代码，它产出一套设计决策。搭配 direct tool loop 使用效果最佳——用它想清楚架构，再用 LangChain/LangGraph 或手写 loop 实现。

一句话推荐结论

如果你需要在写代码之前先把 Agent 的 harness 设计想清楚，而不是照着 LangChain 教程直接开撸，这个 Skill（及其 MVP Blueprint）是目前最系统的 provider-neutral 参考；上手门槛低，深度够用，适合团队在做 Agent 架构设计时的第一站。

数据来源：GitHub README、SKILL.md、references/mvp-agent-blueprint.md（均为 2025 年快照，⚠️ 版本号与 commit 请以 upstream 最新为准）