人工智能AI AgentAgent 沙箱云原生容器运行时零信任【免费下载链接】substrateAgent Substrate: the core system项目地址https://gitcode.com/GitHub_Trending/substrate7/substrate点击查看免费下载本文讲解 Agent Substrate 仓库内置的agents-md技能见 .agents/skills/agents-md/SKILL.md它定义了一套为 AI 代理Agent生成或更新AGENTS.md文件的方法论。通过阅读本文你将掌握如何为项目根目录与各子目录编写高信噪比、低 token 消耗的代理指南并理解渐进式披露、模块化、决策表、Dont vs. Do 等核心原则在真实仓库中的落地方式。文中所有示例均取自 Agent Substrate 仓库现有的AGENTS.md文件与配套文档可直接对照查阅。一、AGENTS.md 是什么让代理理解仓库的驾驶手册AGENTS.md是项目面向 AI 编程代理如 Claude、Codex 等的说明文件作用是让代理在进入仓库时快速理解这个项目是做什么的、代码放在哪里、如何构建、如何测试、遵循什么风格约定。与面向人类读者的 README 不同AGENTS.md的读者是 Agent因此它的首要设计目标是用最少的 token 传递最准确的上下文并引导代理在需要深入时按需阅读更详细的参考文档。在 Agent Substrate 仓库中根目录的 AGENTS.md 就是一个完整范例它开篇即用两句话定义了系统的核心定位构建在 Kubernetes 之上的、通过将大量actor映射到少量就绪worker上以实现高密度复用的系统并立即给出开发必读入口README.md、CONTRIBUTING.md让代理在 10 秒内建立正确的项目心智模型。二、核心要求根目录必须存在且至少包含五大部分技能文件明确了一条硬性规则项目根目录必须始终存在一个AGENTS.mdThere must always be an AGENTS.md file in the project root。根目录的AGENTS.md应当包含以下五大部分章节作用Project overview项目概述一句话讲清系统定位与核心机制帮助代理判断问题是否属于本项目范畴Build and test commands构建与测试命令给出可直接执行的标准命令避免代理靠猜Code style guidelines代码风格指南明确格式化、头注释、提交信息等硬性约定Testing instructions测试指令规定新代码必须带测试等红线与验证流程Security considerations安全注意事项列出当前的安全能力边界与必须遵守的最佳实践而子目录中的AGENTS.md可以且应该更精简、更贴合该子目录AGENTS.md files in subfolders may be even more concise and specific to those subfolders。对照根目录 AGENTS.md可以看到五个部分逐一落地Project overview说明 Agent Substrate 是基于 Kubernetes 的 actor/worker 映射系统并指出开发请先读README.md和CONTRIBUTING.md集群与 GCP 资源部署见hack/install-ate.sh与tools/setup-gcp。Repository Layout用一张代码块目录图 一张新 Go 代码放哪的决策表让代理快速定位cmd/、internal/、pkg/、docs/、hack/、manifests/、demos/、benchmarking/、tools/各目录的职责并指向 docs/dev/code-layout.md 获取完整说明。Build and Test Commandsmake build/make build-images/make build-demos/make test/make e2e/make verify并注明 E2E 依赖 GCP 集群与已构建镜像。Code Style Guidelinesgofmt格式化make fmt、版权头模板hack/boilerplate/、小粒度 PR、go mod tidy保持go.mod干净、注释简洁且描述最终状态、美式英语拼写golangci-lint的misspell会检查locale: US。Testing Instructions新代码必须配测试、不得破坏既有测试、提审前先跑make verify、真实基础设施 E2E 需先按hack/ate-dev-env.sh.example与go run ./tools/setup-gcp bootstrap准备集群。Security Considerations坦率说明安全故事还很早期许多能力缺失当前提供的是基于 gVisorrunsc的工作负载隔离未来规划见 docs/roadmap.md。值得注意的是根目录AGENTS.md还额外包含了Commit Messages与Metrics两节——前者约定提交信息要自解释、不写 issue/PR 编号后者说明指标注册表位于 docs/metrics/registry/指标变更需遵循 docs/dev/best-practices/metrics.md 并运行hack/verify/metrics.sh基数规则见 docs/metrics/substrate.yaml。这说明技能列出的五部分是最低要求仓库完全可以按需扩充但必须保持精简。三、最大化代理性能七大写作原则技能文件的第二节 Maximize AGENTS.md Performance 给出了七条具体原则这是整个技能的方法论核心1. 渐进式披露Progressive Disclosure每个 AGENTS.md 应当简短全文约 100–150 行并按需链接到仓库内少量聚焦的参考文档。原则是根文件只给地图细节交给被链接的文档代理需要时才点进去读。这既节省了 token也避免了根文件与详细文档维护不同步。仓库中的落地案例根目录AGENTS.md约 96 行恰好在 100–150 行的推荐区间内并把仓库布局的完整说明full rationale and per-directory details外链到 docs/dev/code-layout.md把指标规则的补充说明外链到 docs/observability.md。2. 模块化Modularity每个文件夹最多只能有一个AGENTS.md但可以在任意文件夹创建它。与其把高度具体的建议都堆在根文件里不如把高度特定领域的建议下沉到最相关的子目录。这正是渐进式披露的空间维度根文件讲全局子目录讲局部。仓库中的落地案例hack/tools/AGENTS.md 全文仅 6 行只讲一件事——更新工具必须用hack/update-tool.sh tool-name version禁止直接编辑任何tools/子目录下的go.mod。这是一个子目录文件比根文件更精简、更聚焦的教科书式示例代理一旦要改动tools/下的工具立刻就能读到这条关键约束而无需翻阅整个仓库的规范。3. 参考资料References当某份本可以帮到你的文档缺失时把参考文档补充到项目根目录的docs/文件夹中当这些文档过时后再更新它们。这条原则把 AGENTS.md 的维护与文档体系绑定在一起AGENTS.md 是索引docs/是正文两者需要同步演进。Agent Substrate 仓库根目录 docs/ 下正是这样组织的——设计文档与开发者指南如 docs/dev/code-layout.md、docs/architecture.md、docs/observability.md各自独立成文供 AGENTS.md 按需引用。4. 工作流Workflows当参考资料描述的是工作流时任务必须写成编号步骤。例如Get the beep from the boop.Then bop it.编号步骤对代理的意义在于每一步都是一个可执行、可验证、可单独失败的原子动作避免代理把多步骤流程压缩成模糊的一口气做完。仓库中 .agents/skills/detect-flaky-tests/SKILL.mdStep 1 收集 workflow run ID → Step 2 下载解析日志 → Step 3 基础设施问题分流 → Step 4 聚合统计 → Step 5 创建 issue → Step 6 开修复 PR → Step 7 汇报正是这一原则在相邻技能文档中的体现。5. 决策Decisions当代码库中存在多种做法时使用决策表例如QuestionBoopBopIs foo a bar baz?✅Is foo a quux?✅决策表的价值在于把if/else 式的文字描述压缩成一眼可扫的矩阵代理可以按当前情况命中哪一列快速选择实现路径。仓库根目录 AGENTS.md 中新 Go 代码放哪里的表格就是标准实践SituationLocationOnly used by one binarycmd/binary/internal/pkgShared across binaries, not for external importinternal/pkgPublic API for external consumerspkg/pkgPublic proto (control-plane gRPC API)pkg/proto/nameInternal proto (atelet / ateom)internal/proto/nameDev/CI scriptshack/Standalone Go dev/CI toolstools/namewith its owngo.mod代理新增代码时只需对照该表即可确定归属目录无需理解整个 Go 模块的依赖图。6. 真实代码示例Real Code Examples如果仓库中有特别好的示例可以摘录真实代码片段长度不超过约 10 行且只应选择最具代表性、值得在未来代码中复用的模式。其目的不是展示代码而是提高代理的代码复用率避免每个代理都重复造轮子。示例必须是真实存在于仓库中的代码而非杜撰的伪代码——这也保证了示例与仓库现状永远一致。7. 领域特定规则Domain Specific Rules可以包含少量简单的领域特定规则但不要太多否则代理会陷入规则过多的泥潭。技能给出的通用示例是任何金融计算都必须使用金融专用的数值类型Use a finance-specific numeric type for any financial calculations.。领域规则应当少而准每条都能显著影响代码质量而非罗列琐碎偏好。8. Dont vs. Do警示必须配方案在添加不要做某事的警告时必须同时给出正确的做法建议——Dont do X, do Y instead.。这条原则确保了 AGENTS.md 不只是约束代理还能教会代理正确路径。仓库中处处可见这种写法根目录AGENTS.md的提交信息规范Leave out#1234,Fixes #1234, and GitHub URLsDont随后立即说明应把上下文写进 PR 描述Do。hack/tools/AGENTS.mdDO NOT directly edit the go.mod in any of the tools/ subdirectoriesDont随即给出正解Only use the update scriptDo并给出命令hack/update-tool.sh tool-name version。根目录AGENTS.md注释规范Comment the final state of the code, not the path taken to itDont 的变体隐含正解是描述代码最终状态。四、落地要点在 Agent Substrate 中生成与维护 AGENTS.md将agents-md技能应用到 Agent Substrate 仓库时可遵循以下工作流确保根目录AGENTS.md存在且准确对照技能列出的五大部分逐项检查并以当前代码状态为准修正过时内容技能要求 Ensure the target AGENTS.md file accurately reflects the current status of the code。例如如果新增了某个cmd/下的二进制应同步更新 Repository Layout 目录图如果调整了验证流程应更新 Build and Test Commands 一节。按目录下沉高特定性内容对cmd/、internal/、pkg/、tools/、hack/、manifests/、demos/、benchmarking/等子目录判断是否有只对该目录生效、但对全局无意义的约束如 hack/tools/AGENTS.md 的禁止直接编辑 go.mod有则下沉为子目录文件。遵守长度与格式纪律每个文件控制在约 100–150 行工作流写成编号步骤多选一场景用决策表示例代码不超过约 10 行且必须真实每条 Dont 都配一条 Do。维护引用闭环把需要展开的细节放进根目录 docs/ 下的文档AGENTS.md 只保留链接如 docs/dev/code-layout.md、docs/observability.md文档过时后及时更新——这正是技能中 References 原则的要求。注意生成而非擅自修改的边界agents-md技能面向的是为代理提供准确的仓库地图在只读仓库中应用时应把发现的问题如缺失的AGENTS.md、过时的命令作为建议提出而非直接改写仓库文件。五、小结agents-md技能将 AGENTS.md 的编写从自由发挥的文档写作收敛为一套可执行、可检查的工程规范根目录五大部分兜底全局信息子目录文件承载局部细节渐进式披露控制篇幅模块化控制粒度决策表与编号步骤把知识组织成代理可直接消费的结构Dont vs. Do 与真实代码示例则让规范既约束行为又传授最佳实践。在 Agent Substrate 仓库中根目录 AGENTS.md 与 hack/tools/AGENTS.md 已经示范了这套规范的完整形态——前者约百行覆盖全局并外链详档后者仅六行聚焦一个硬性约束两者配合构成了一套对 AI 代理友好、对维护者低负担的仓库说明书体系。当你在任何 Go 项目中需要让 AI 代理快速上手且不乱来时这套方法论都值得直接复用。赞分享人工智能AI AgentAgent 沙箱云原生容器运行时零信任【免费下载链接】substrateAgent Substrate: the core system项目地址https://gitcode.com/GitHub_Trending/substrate7/substrate点击查看免费下载相关推荐Nango 文档编写规范面向 AI Agent 的 Docs 维护指南docs/AGENTS.md 全解析Nango 文档编写规范面向 AI Agent 的 Docs 维护指南docs/AGENTS.md 全解析 本篇指南系统拆解 Nango 开源仓库中 do后端API网关AI 应用JupyterLab 仓库 AGENTS.md 指南面向 AI Agent 的代码库开发规范与最佳实践JupyterLab 仓库 AGENTS.md 指南面向 AI Agent 的代码库开发规范与最佳实践 导读 本文围绕 JupyterLab 仓库根目录的 A前端后端数据科学开发工具解读 ccusage 仓库的 AGENTS.md面向 AI Agent 的代码库路由与治理规范解读 ccusage 仓库的 AGENTS.md面向 AI Agent 的代码库路由与治理规范 导读 AGENTS.md 是 ccusage 项目为 AI 编AI 应用CLI开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
