企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 沙箱
• 云原生
• 容器运行时
• 零信任

本文讲解 Agent Substrate 仓库内置的agents-md技能（见 .agents/skills/agents-md/SKILL.md），它定义了一套为 AI 代理（Agent）生成或更新AGENTS.md文件的方法论。通过阅读本文，你将掌握如何为项目根目录与各子目录编写高信噪比、低 token 消耗的代理指南，并理解渐进式披露、模块化、决策表、"Don't 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.md（"There must always be an AGENTS.md file in the project root"）。根目录的AGENTS.md应当包含以下五大部分：

而子目录中的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 Commands：make build/make build-images/make build-demos/make test/make e2e/make verify，并注明 E2E 依赖 GCP 集群与已构建镜像。
• Code Style Guidelines：gofmt格式化（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：坦率说明"安全故事还很早期，许多能力缺失"，当前提供的是基于 gVisor（runsc）的工作负载隔离，未来规划见 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）

当参考资料描述的是工作流时，任务必须写成编号步骤。例如：

1. Get the beep from the boop.
2. Then bop it.

编号步骤对代理的意义在于：每一步都是一个可执行、可验证、可单独失败的原子动作，避免代理把多步骤流程压缩成模糊的"一口气做完"。仓库中 .agents/skills/detect-flaky-tests/SKILL.md（Step 1 收集 workflow run ID → Step 2 下载解析日志 → Step 3 基础设施问题分流 → Step 4 聚合统计 → Step 5 创建 issue → Step 6 开修复 PR → Step 7 汇报）正是这一原则在相邻技能文档中的体现。

5. 决策（Decisions）

当代码库中存在多种做法时，使用决策表，例如：

决策表的价值在于把"if/else 式的文字描述"压缩成一眼可扫的矩阵，代理可以按"当前情况命中哪一列"快速选择实现路径。仓库根目录 AGENTS.md 中"新 Go 代码放哪里"的表格就是标准实践：

代理新增代码时，只需对照该表即可确定归属目录，无需理解整个 Go 模块的依赖图。

6. 真实代码示例（Real Code Examples）

如果仓库中有特别好的示例，可以摘录真实代码片段，长度不超过约 10 行，且只应选择最具代表性、值得在未来代码中复用的模式。其目的不是展示代码，而是提高代理的代码复用率，避免每个代理都重复造轮子。示例必须是"真实存在于仓库中的代码"，而非杜撰的伪代码——这也保证了示例与仓库现状永远一致。

7. 领域特定规则（Domain Specific Rules）

可以包含少量简单的领域特定规则，但不要太多，否则代理会陷入"规则过多"的泥潭。技能给出的通用示例是："任何金融计算都必须使用金融专用的数值类型"（"Use a finance-specific numeric type for any financial calculations."）。领域规则应当少而准，每条都能显著影响代码质量，而非罗列琐碎偏好。

8. "Don't vs. Do"：警示必须配方案

在添加"不要做某事"的警告时，必须同时给出正确的做法建议——"Don't do X, do Y instead."。这条原则确保了 AGENTS.md 不只是约束代理，还能教会代理正确路径。仓库中处处可见这种写法：

• 根目录AGENTS.md的提交信息规范："Leave out#1234,Fixes #1234, and GitHub URLs"（Don't），随后立即说明应把上下文写进 PR 描述（Do）。
• hack/tools/AGENTS.md："DO NOT directly edit the go.mod in any of the tools/ subdirectories"（Don't），随即给出正解："Only use the update script"（Do），并给出命令hack/update-tool.sh <tool-name> <version>。
• 根目录AGENTS.md注释规范："Comment the final state of the code, not the path taken to it"（Don't 的变体，隐含正解是描述代码最终状态）。

四、落地要点：在 Agent Substrate 中生成与维护 AGENTS.md

将agents-md技能应用到 Agent Substrate 仓库时，可遵循以下工作流：

1. 确保根目录AGENTS.md存在且准确：对照技能列出的五大部分逐项检查，并以"当前代码状态"为准修正过时内容（技能要求 "Ensure the target AGENTS.md file accurately reflects the current status of the code"）。例如：如果新增了某个cmd/下的二进制，应同步更新 Repository Layout 目录图；如果调整了验证流程，应更新 Build and Test Commands 一节。
2. 按目录下沉高特定性内容：对cmd/、internal/、pkg/、tools/、hack/、manifests/、demos/、benchmarking/等子目录，判断是否有"只对该目录生效、但对全局无意义"的约束（如 hack/tools/AGENTS.md 的"禁止直接编辑 go.mod"），有则下沉为子目录文件。
3. 遵守长度与格式纪律：每个文件控制在约 100–150 行；工作流写成编号步骤；多选一场景用决策表；示例代码不超过约 10 行且必须真实；每条 "Don't" 都配一条 "Do"。
4. 维护引用闭环：把需要展开的细节放进根目录 docs/ 下的文档，AGENTS.md 只保留链接（如 docs/dev/code-layout.md、docs/observability.md），文档过时后及时更新——这正是技能中 References 原则的要求。
5. 注意"生成而非擅自修改"的边界：agents-md技能面向的是"为代理提供准确的仓库地图"，在只读仓库中应用时，应把发现的问题（如缺失的AGENTS.md、过时的命令）作为建议提出，而非直接改写仓库文件。

五、小结

agents-md技能将 AGENTS.md 的编写从"自由发挥的文档写作"收敛为一套可执行、可检查的工程规范：根目录五大部分兜底全局信息，子目录文件承载局部细节；渐进式披露控制篇幅，模块化控制粒度；决策表与编号步骤把知识组织成代理可直接消费的结构；"Don't vs. Do" 与真实代码示例则让规范既约束行为又传授最佳实践。在 Agent Substrate 仓库中，根目录 AGENTS.md 与 hack/tools/AGENTS.md 已经示范了这套规范的完整形态——前者约百行覆盖全局并外链详档，后者仅六行聚焦一个硬性约束，两者配合构成了一套对 AI 代理友好、对维护者低负担的仓库说明书体系。当你在任何 Go 项目中需要让 AI 代理"快速上手且不乱来"时，这套方法论都值得直接复用。

• 人工智能
• AI Agent
• Agent 沙箱
• 云原生
• 容器运行时
• 零信任