@pvlvtr:晚上有点无聊,就把 AGENTS.md 和配套配置整理了一下发到 gh 上。里面混合了 ponytail、……

X AI KOLs Timeline 工具

摘要

作者分享了一个开源的 AGENTS.md 仓库,提供了一套实用的工程框架,包括规则、工作流和工具,旨在让 AI 编程助手更具可预测性、可验证性和可追溯性,并针对国产快速模型进行了优化。

晚上有点无聊,就把 AGENTS.md 和配套配置整理了一下发到 gh 上。内容混合了 ponytail、Karpaty、我的工具箱、Radio-T 的一些想法,还有其他各种零碎的东西。由 Gemini、DeepSeek、Claude 和 ChatGPT 一起协作完成。针对国产快速模型进行了优化。
查看原文
查看缓存全文

缓存时间: 2026/11/21 12:21

晚上有点无聊,所以我整理了一下 AGENTS.md 和配套的配置,然后发布到了 GitHub 上。这是 ponytail、Karpaty、我的工具链、Radio-T 的一些想法,以及各种零散内容的混合体。由 Gemini、DeepSeek、Claude 和 ChatGPT 一起拼出来的。针对国产轻量级模型做了优化。

— # pavelveter/AGENTS.md Source: https://github.com/pavelveter/AGENTS.md # AGENTS.md

面向 AI 编码代理的工程规范。没有玄学、没有幻觉、没有范围蔓延。

把它做得更狠。做得更好。做得更快。做得更强。

但首先,确保它真的能跑。小的 diff。真实的测试。诚实的报告。一点点偏执是特性,不是缺陷。 License: MIT AI Agents Engineering


这是什么?

一个面向 AI 辅助软件开发的实用工程框架。不是又一堆魔法提示词合集。不是一本 400 页的关于工作未来的大部头宣言。更不是邀请某个大模型因为发现了“改进机会“就重写半个代码库的请柬。

本仓库包含一套模块化的规则、工作流和工具,旨在让 AI 编码代理更可预测、更高效、更可问责。核心思想:AI 代理应该像工程师一样运作,而不是一个拥有 root 权限、热情洋溢的自动补全工具。

本系统聚焦于:

  • 上下文工程 —— 检索相关知识,而不是把所有东西都塞给模型。
  • 智能体工作流 —— 委派任务时明确范围、边界和恢复路径。
  • 验证优先开发 —— 代码在被测试之前只是一个假设。
  • 根因调试 —— 复现、排查、修复、验证。
  • 规格驱动开发 —— 在实现复杂变更之前先确定预期行为。
  • 安全与可靠性 —— 认真对待输入边界、密钥、权限和故障模式。
  • 工具效率 —— 使用现有工具、标准接口和可组合的工作流。
  • 持久化知识 —— 跨会话、跨代理保留架构上下文。

目标很简单:让 AI 辅助开发更加可预测、可复现、可维护、可衡量。

工程哲学

1. 上下文是一种工程资源

更多的上下文并不自动意味着更好的推理。加载相关文档,检查实际代码库,检索架构知识,避免把 token 浪费在无关信息上。上下文应该是精心筛选的,而不是一股脑倾倒的。

2. 自主性需要边界

一个没有约束的自主代理只是一个产生技术债务的高速工厂。明确定义:

  • 任务范围。
  • 允许的变更。
  • 必须保持的现有行为。
  • 验证要求。
  • 恢复策略。

给代理足够的自由去解决问题,但不要给它太多自由去发明新问题。

3. 验证胜过自信

命令执行成功不一定是正确性的证明。

  • 测试应该验证行为。
  • 构建应该使用实际的项目配置。
  • 安全假设应该被检查。
  • 失败路径应该被考虑。
  • 未经验证的断言绝不应被当作事实呈现。

“在我的推理里能跑“不是一个合格的测试结果。

4. 根因优于创可贴

先复现。追踪执行路径。找出真正的原因。不要为了消除一个失败的检查就压制错误、削弱测试、随意加重试,或者引入 fallback 行为。

5. 优先使用可组合的工具

使用标准的 CLI 工作流、MCP 集成、现有包和原生平台能力。避免重新发明已经存在的功能。只有当现有方案不适用时才编写自定义代码 —— 而不是因为再写一个实现让人感觉很有产出。

6. 人类掌握决策权

代理可以调查、实现、测试、评审和提议架构。但正确性、安全性和架构决策的责任必须始终明确。人类仍然是工程师。模型是一个能力很强、偶尔过于自信的协作者。


仓库结构

本仓库由一个小型核心模块和若干支撑模块组成,支撑模块仅在需要时加载。

文件职责
AGENTS.md核心规则:使命、范围、安全决策、编辑前检查、技术栈检测、Ponytail Ladder、Bug 修复、测试、恢复、工具、按需文档、完成清单和报告格式。
debug.md根因调试。先复现。不要掩盖错误或削弱测试。
deps.md依赖规则、包管理命令,以及添加或升级包之前的安全检查。
benchs/evals.md规则变更的测试场景和评分。
git.md分支安全、diff 检查、暂存纪律和提交信息规范。
refactor.md不改变行为的结构性重构。
review.md报告发布前的合理性检查:范围、遗漏、正确性和诚实性。
sdd.md面向功能、API、Schema 和架构变更的规格驱动流程。
security.md输入边界、注入防御、密钥卫生和认证/网络规则。
testing.md行为测试、真实边界、干净的测试数据、不稳定测试规则和技术栈测试命令。
tools.md搜索顺序(fff、codebase-memory-mcp、rg)和命令规则。
stacks/按技术栈划分的指令,仅在相关时加载。

按技术栈划分的规则

  • stacks/go.md
  • stacks/node.md
  • stacks/python.md
  • stacks/web.md

核心文档定义规则。支撑文件提供细节。修个错别字没必要加载整本规则手册。我们有更重要的事要做。


工具链

这套配置结合了 AI 工具、CLI 实用程序、语言工具链和持久化的代码库上下文。有些工具对工作流至关重要;有些是可选的加速器。

AI 与代理基础设施

工具用途
OpenCode (https://opencode.ai/)主力 AI 编码环境。代理执行、模型选择、工具和 MCP 集成。
MCP (https://modelcontextprotocol.io/)连接模型与外部工具和上下文资源的标准接口。
codebase-memory-mcp (https://github.com/DeusData/codebase-memory-mcp)持久化的代码库知识、符号关系和架构上下文。

开发者工具

工具用途
fff (https://github.com/magnusmalm/fff-cli)快速文件发现和内容搜索。
ripgrep (https://github.com/BurntSushi/ripgrep)精确的源代码搜索和引用发现。
RTK (https://github.com/rtk-ai/rtk)压缩命令输出,减少噪音和 LLM 上下文消耗。
Git (https://git-scm.com/)版本控制、diff 检查、变更隔离和恢复。

语言工具链

工具用途
Go (https://go.dev/)编译型系统软件、CLI 工具、并发、测试和性能导向的工具开发。
Python (https://www.python.org/)AI/ML 开发、自动化、原型验证和后端工具。
uv (https://docs.astral.sh/uv/)Python 环境、依赖管理和项目执行。
Node.js (https://nodejs.org/)JavaScript 和 TypeScript 运行时及开发生态。
pnpm (https://pnpm.io/)快速包管理、可复现安装、工作区和 monorepo 工作流。

为什么选择这些工具?

codebase-memory-mcp

架构知识应该在上下文重置后仍然存活。在盲目探索文件之前,使用持久化的代码库上下文来理解关系、符号和项目结构。

fff + ripgrep

快速发现和精确搜索。有专门的搜索工具就用,但绝不要让缺少某个工具阻碍进度。标准 shell 工具完全够用。

RTK

终端输出会消耗上下文。减少噪音意味着有更多空间留给真正的推理、相关源代码和测试结果。

Go

在添加依赖之前优先使用标准工具链:

  • go build ./...
  • go test ./...
  • go test -race ./...
  • go vet ./...
  • gofmt -d .

Python + uv

保持环境可复现,依赖管理显式化。优先使用 uv run、uv sync 和项目现有配置,而不是临时的全局安装。

Node.js + pnpm

使用项目声明的包管理器。

  • pnpm install --frozen-lockfile
  • pnpm run
  • pnpm exec <command>
  • pnpm -r run <script>

保留 pnpm-lock.yaml。不要偷偷切换到 npm 或 Yarn。


搜索策略

首选搜索工作流:

  1. fff —— 发现相关文件和内容。
  2. codebase-memory-mcp —— 检索架构和符号上下文。
  3. rg —— 验证精确定义、引用和调用点。

智能地使用可用工具。如果首选工具缺失,就使用合理的替代品。不要为了逃避敲 rg 而花掉半个任务的时间去安装一个搜索工具。


运行环境

本仓库反映的是一个真实的工作环境,而不是一个想象中的通用开发者工作站。

主要环境

组件配置
操作系统macOS
ShellZsh
终端Kitty
编辑器Vim
Pythonuv
Node.js 包管理器pnpm
系统语言Go
AI 编码运行时OpenCode
上下文集成MCP
版本控制Git

OpenCode 配置

当前配置使用 OpenCode 特定的路径:

用途路径
全局配置~/.config/opencode/opencode.json
全局代理定义~/.config/opencode/agents/
项目代理定义.opencode/agents/
项目配置opencode.json 或 .opencode/opencode.json

有用的文档:

  • OpenCode (https://opencode.ai/docs/)
  • 配置 (https://opencode.ai/docs/config/)
  • Agents (https://opencode.ai/docs/agents/)
  • MCP 服务器 (https://opencode.ai/docs/mcp-servers/)

这些路径是有意为之的。它们描述了这套配置开发和使用时的实际环境。

使用其他代理运行时

核心工程规则并不绑定于 OpenCode。如果要将这套配置适配到其他运行时:

  1. 替换 OpenCode 特定的配置路径。
  2. 配置目标运行时以加载 AGENTS.md。
  3. 将全局指令移动到相应的代理目录。
  4. 重新配置 MCP 服务器和工具权限。
  5. 更新运行时特定的命令、钩子和集成。
  6. 保留项目级别的工程规则。

可能的替代方案:

  • Claude Code (https://docs.anthropic.com/en/docs/claude-code/overview)
  • Codex (https://developers.openai.com/codex/)
  • Cursor (https://docs.cursor.com/)

工程规则的单一事实来源,胜过五份微妙不兼容的副本。


如何使用

  1. 将 AGENTS.md 及支撑的 Markdown 文件复制到你的项目中。
  2. 保留目录结构。
  3. 配置你的编码代理以发现并加载这些指令。
  4. 对照实际项目检查按技术栈划分的规则。
  5. 运行一个小任务,观察代理行为。
  6. 根据观察到的失败调整规则,而不是基于理论偏好。

系统应该随着代码库和工具一起演进。不要仅仅因为某条规则听起来很聪明就添加它。添加它是因为它能防止一类真实的错误。


评估与持续改进

指令也是软件。它们可能过时、自相矛盾、过度限制,或者干脆无效。使用 benchs/evals.md 来评估代理规则的变更。有用的评估场景包括:

  • 代理在编辑之前是否会检查现有的变更?
  • 它是否会保留不相关的用户修改?
  • 它是否会在尝试修复之前先复现 Bug?
  • 它是否会避免不必要的依赖?
  • 它是否会选择正确的包管理器?
  • 它是否会运行有意义的测试?
  • 它是否会诚实报告跳过的检查?
  • 它是否会避免扩大任务范围?
  • 它是否能在操作失败后安全恢复?

一条在 Markdown 里看起来不错但不改变任何代理行为的规则,只是文档装饰。


报告格式

每个完成的任务都应产出一份简洁的、基于证据的报告。标准结构:

部分含义
STATUS当前已验证的状态。
ACTION做了什么或必须做什么。
RESULT观察到的结果。
VERIFICATION证据和已执行的检查。
RISK残留的风险或局限。
NEXT ACTION如有需要的后续行动。

最后附上一份 Decisions 列表,记录重要的实现选择及其理由。不要隐藏失败的测试。不要假装跳过的检查通过了。在什么都没验证的时候不要说“一切看起来都很好“。


设计原则

  • 小的变更更容易评审。
  • 显式的假设更容易被质疑。
  • 可复现的工作流更容易被信任。
  • 模块化的指令更容易维护。
  • 好的默认值减少不必要的决策。
  • 真实的验证胜过自信的语言。
  • 工程纪律比模型热情更重要。

最后一条规则:

永远不要把生成代码和解决问题混为一谈。

前者很容易。后者才是工作。


License

MIT

相似文章

本文系统梳理了AI Agent架构与工程实践,涵盖控制流、上下文工程、工具设计、记忆、多Agent组织、评测、追踪和安全,基于OpenClaw实现展开,强调Harness(测试验证基础设施)对系统稳定性的关键作用。

X AI KOLs

本文系统梳理了AI Agent架构与工程实践,涵盖控制流、上下文工程、工具设计、记忆、多Agent组织、评测、追踪和安全,基于OpenClaw实现展开,强调Harness(测试验证基础设施)对系统稳定性的关键作用。