@pvlvtr:晚上有点无聊,就把 AGENTS.md 和配套配置整理了一下发到 gh 上。里面混合了 ponytail、……
摘要
作者分享了一个开源的 AGENTS.md 仓库,提供了一套实用的工程框架,包括规则、工作流和工具,旨在让 AI 编程助手更具可预测性、可验证性和可追溯性,并针对国产快速模型进行了优化。
查看缓存全文
缓存时间: 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.mdstacks/node.mdstacks/python.mdstacks/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-lockfilepnpm runpnpm exec <command>pnpm -r run <script>
保留 pnpm-lock.yaml。不要偷偷切换到 npm 或 Yarn。
搜索策略
首选搜索工作流:
fff—— 发现相关文件和内容。codebase-memory-mcp—— 检索架构和符号上下文。rg—— 验证精确定义、引用和调用点。
智能地使用可用工具。如果首选工具缺失,就使用合理的替代品。不要为了逃避敲 rg 而花掉半个任务的时间去安装一个搜索工具。
运行环境
本仓库反映的是一个真实的工作环境,而不是一个想象中的通用开发者工作站。
主要环境
| 组件 | 配置 |
|---|---|
| 操作系统 | macOS |
| Shell | Zsh |
| 终端 | Kitty |
| 编辑器 | Vim |
| Python | uv |
| 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。如果要将这套配置适配到其他运行时:
- 替换 OpenCode 特定的配置路径。
- 配置目标运行时以加载
AGENTS.md。 - 将全局指令移动到相应的代理目录。
- 重新配置 MCP 服务器和工具权限。
- 更新运行时特定的命令、钩子和集成。
- 保留项目级别的工程规则。
可能的替代方案:
- Claude Code (https://docs.anthropic.com/en/docs/claude-code/overview)
- Codex (https://developers.openai.com/codex/)
- Cursor (https://docs.cursor.com/)
工程规则的单一事实来源,胜过五份微妙不兼容的副本。
如何使用
- 将
AGENTS.md及支撑的 Markdown 文件复制到你的项目中。 - 保留目录结构。
- 配置你的编码代理以发现并加载这些指令。
- 对照实际项目检查按技术栈划分的规则。
- 运行一个小任务,观察代理行为。
- 根据观察到的失败调整规则,而不是基于理论偏好。
系统应该随着代码库和工具一起演进。不要仅仅因为某条规则听起来很聪明就添加它。添加它是因为它能防止一类真实的错误。
评估与持续改进
指令也是软件。它们可能过时、自相矛盾、过度限制,或者干脆无效。使用 benchs/evals.md 来评估代理规则的变更。有用的评估场景包括:
- 代理在编辑之前是否会检查现有的变更?
- 它是否会保留不相关的用户修改?
- 它是否会在尝试修复之前先复现 Bug?
- 它是否会避免不必要的依赖?
- 它是否会选择正确的包管理器?
- 它是否会运行有意义的测试?
- 它是否会诚实报告跳过的检查?
- 它是否会避免扩大任务范围?
- 它是否能在操作失败后安全恢复?
一条在 Markdown 里看起来不错但不改变任何代理行为的规则,只是文档装饰。
报告格式
每个完成的任务都应产出一份简洁的、基于证据的报告。标准结构:
| 部分 | 含义 |
|---|---|
| STATUS | 当前已验证的状态。 |
| ACTION | 做了什么或必须做什么。 |
| RESULT | 观察到的结果。 |
| VERIFICATION | 证据和已执行的检查。 |
| RISK | 残留的风险或局限。 |
| NEXT ACTION | 如有需要的后续行动。 |
最后附上一份 Decisions 列表,记录重要的实现选择及其理由。不要隐藏失败的测试。不要假装跳过的检查通过了。在什么都没验证的时候不要说“一切看起来都很好“。
设计原则
- 小的变更更容易评审。
- 显式的假设更容易被质疑。
- 可复现的工作流更容易被信任。
- 模块化的指令更容易维护。
- 好的默认值减少不必要的决策。
- 真实的验证胜过自信的语言。
- 工程纪律比模型热情更重要。
最后一条规则:
永远不要把生成代码和解决问题混为一谈。
前者很容易。后者才是工作。
License
MIT
相似文章
@reach_vb: 一个好(定期更新)的 AGENTS md 就是你所需要的一切,你还可以在项目级别自定义指令与全局…
该推文强调,一个定期更新的 AGENTS.md 文件可以用来定制 AI 代理行为,无需构建自定义工具,特别是像 GPT 5.6 这样的指令跟随模型。
本文系统梳理了AI Agent架构与工程实践,涵盖控制流、上下文工程、工具设计、记忆、多Agent组织、评测、追踪和安全,基于OpenClaw实现展开,强调Harness(测试验证基础设施)对系统稳定性的关键作用。
本文系统梳理了AI Agent架构与工程实践,涵盖控制流、上下文工程、工具设计、记忆、多Agent组织、评测、追踪和安全,基于OpenClaw实现展开,强调Harness(测试验证基础设施)对系统稳定性的关键作用。
@chasen_liao: https://x.com/chasen_liao/status/2077219202608545835
本文探讨了提示词工程升级为Agent工程的趋势,强调通过AGENTS.md等结构化上下文管理AI代理,并分享了一套最小闭环的工作流方法论。
@billtheinvestor:开发系统最极致高效的Agents.md,没有之一: # AGENTS.md ## 核心原则 - 选择最简单的实现,完全满足当前需求……
一位开发者分享了一份全面的 Agents.md 模板,其中包含使用 AI 智能体构建和维护交易系统的核心原则,涵盖策略开发、工程标准和范围纪律。
@jasonzhou1993: https://x.com/jasonzhou1993/status/2075179471951614381
作者分享了运行AI代理循环一个月后的实际经验,强调了循环契约、状态和日志的重要性,以使代理实现自主和可靠。