From First-Run Drop-Off to First Useful Agent Run

查看原文 / View Original 编辑 / Edit

From First-Run Drop-Off to First Useful Agent Run

从首次运行流失到首次有效代理运行

I keep coming back to the same onboarding question: what happens in the first 10 minutes? For agent tools, that window is brutal. A developer opens a repo, starts the agent, asks for a change, and waits to see if the tool understands the project. If the agent guesses the package manager, misses the test path, edits generated files, or asks the developer to explain the repo from scratch, trust drops fast. That isn’t an agent model problem every time. A lot of it is repo readiness. 我一直在思考同一个入职引导问题：最初的 10 分钟会发生什么？对于代理工具（Agent tools）来说，这个窗口期非常残酷。开发者打开一个仓库，启动代理，提出修改请求，然后等待查看工具是否理解该项目。如果代理猜错了包管理器、找错了测试路径、修改了生成文件，或者要求开发者从头解释仓库结构，信任度会迅速下降。这并不总是代理模型本身的问题，很大程度上取决于仓库的准备情况。

The Agentic AI Foundation, hosted by the Linux Foundation, is building an open home for projects like MCP, goose, AGENTS.md, and agentgateway. That work can sound big and infrastructural, but one of the most useful entry points is small: make your repo easier for an agent to understand on the first run. AGENTS.md is the repo-side context. goose is a practical runtime path. Together, they give you a way to move from “the agent is poking around” to “the agent made a useful first pass.” 由 Linux 基金会托管的 Agentic AI Foundation (AAIF) 正在为 MCP、goose、AGENTS.md 和 agentgateway 等项目构建一个开放的家园。这些工作听起来宏大且偏向基础设施，但最实用的切入点之一其实很小：让你的仓库在首次运行时更容易被代理理解。AGENTS.md 提供了仓库层面的上下文，而 goose 则是一条实用的运行时路径。两者结合，让你能够从“代理在乱撞”转变为“代理完成了第一次有效的尝试”。

Start With The First Useful Run

从第一次有效运行开始

Don’t begin by asking, “What should our agent docs say?” Ask this instead: what should a developer be able to ask an agent to do in this repo within 10 minutes? Pick one task. Not the whole system. One useful first run. For example: 不要从“我们的代理文档应该写什么？”开始，而要问：开发者在 10 分钟内应该能要求代理在这个仓库里做什么？挑选一个任务，不要试图涵盖整个系统，只需一个有效的首次运行任务。例如：

  • Find the right entry point for a small bug
  • 为一个小 Bug 找到正确的入口点
  • Add a focused test around an existing function
  • 针对现有函数添加一个有针对性的测试
  • Update a docs page with a known source file nearby
  • 根据附近的已知源文件更新文档页面
  • Explain how a specific package or module is wired
  • 解释某个特定包或模块是如何连接的

That first run gives your AGENTS.md a job. It isn’t a policy dump. It’s the context an agent needs to avoid wasting the developer’s first session. 这次首次运行赋予了 AGENTS.md 一个明确的任务。它不是政策堆砌，而是代理避免浪费开发者首次会话所需的上下文。

Put Repo Truth Where Agents Can Find It

将仓库真相放在代理能找到的地方

AGENTS.md is a simple open format for guiding coding agents, and the project site says it’s already used by over 60k open-source projects: https://agents.md. The reason it works is plain: agents need a predictable place for repo instructions. README files are written for humans. CI files are written for automation. AGENTS.md gives agents the details that usually live in maintainer heads. AGENTS.md 是一种用于引导编码代理的简单开放格式，项目网站显示它已被超过 6 万个开源项目使用：https://agents.md。它有效的原因很简单：代理需要一个可预测的地方来获取仓库指令。README 文件是写给人看的，CI 文件是写给自动化流程看的，而 AGENTS.md 则为代理提供了通常只存在于维护者脑海中的细节。

Your first version should answer: What kind of project is this? Where does source code live? Where do tests live? Which files should agents avoid editing? What style or architecture choices should agents preserve? What should the agent do before claiming a task is done? Keep it short enough that someone would maintain it. Stale agent instructions are worse than missing ones because they create confident mistakes. 你的第一个版本应该回答：这是什么类型的项目？源代码在哪里？测试在哪里？代理应该避免编辑哪些文件？代理应该保留哪些风格或架构选择？代理在声称任务完成前应该做什么？保持简短，以便有人愿意维护它。过时的代理指令比缺失指令更糟糕，因为它们会导致代理自信地犯错。

Write Instructions Like Maintainer Notes

像写维护者笔记一样编写指令

An AGENTS.md file doesn’t need brand language. It needs maintainer notes. Say things like: AGENTS.md 文件不需要品牌化的语言，它需要的是维护者笔记。可以这样写：

# AGENTS.md
## Project Shape
This repo contains a web app and supporting packages. App code lives in `apps/web`. Shared code lives in `packages`.
## Working Rules
Prefer small changes that match nearby patterns. Do not rewrite public APIs unless the task asks for it.
## Tests
When changing behavior, add or update the closest existing test. If you can't run the test locally, say what you inspected and why the test wasn't run.
## Files To Avoid
Do not edit generated files, lockfiles, or vendored code unless the task is specifically about dependency updates.

Notice what’s missing: fake certainty. Don’t say “run the full test suite” unless that’s realistic. Don’t list commands you haven’t checked. Don’t tell the agent to use a package manager you don’t use. Your agent instructions should be as true as your README. 注意这里缺少了什么：虚假的确定性。除非现实可行，否则不要说“运行完整测试套件”。不要列出你没验证过的命令。不要告诉代理使用你根本不用的包管理器。你的代理指令应该像你的 README 一样真实。

Design The Goose Path

设计 Goose 路径

goose is an open-source AI agent runtime under AAIF. Its project page describes it as an agent that can install, execute, edit, and test with any LLM: https://aaif.io/projects/goose. For onboarding, think of goose as the first-run path you can test against your repo instructions. A good first-run path has three pieces: A clear starting task, A repo-level AGENTS.md, A visible stopping point. goose 是 AAIF 下的一个开源 AI 代理运行时。其项目页面将其描述为一个可以使用任何 LLM 进行安装、执行、编辑和测试的代理：https://aaif.io/projects/goose。对于入职引导，可以将 goose 视为你可以用来测试仓库指令的“首次运行路径”。一个好的首次运行路径包含三个部分：一个清晰的起始任务、一个仓库级的 AGENTS.md、以及一个可见的停止点。

The stopping point matters. If the agent changes code, how does the developer know whether it did the right thing? Maybe the agent should point to the files it changed. Maybe it should explain the test it would run. Maybe it should stop before touching a migration, generated file, or public API. That belongs in AGENTS.md. 停止点很重要。如果代理修改了代码，开发者如何知道它做得对不对？也许代理应该指出它修改的文件，也许它应该解释它将要运行的测试，也许它应该在触碰数据库迁移、生成文件或公共 API 之前停止。这些都应该写在 AGENTS.md 中。

Make The Agent Ask Better Questions

让代理提出更好的问题

A useful agent doesn’t need to know everything. It needs to know when to stop guessing. Add guidance for uncertainty: 一个有用的代理不需要知道所有事情，它只需要知道什么时候该停止猜测。为不确定性添加指导：

## When Unsure
If the requested change touches auth, billing, data deletion, or production configuration, ask before editing. If there are multiple plausible implementations, describe the tradeoff and choose the smallest local change unless the user tells you otherwise.

Why does that help? Because first-run drop-off often comes from surprise. The agent edits the wrong layer, takes a broad refactor path, or treats a risky area like ordinary code. Good instructions narrow the blast radius. 为什么这有帮助？因为首次运行的流失往往源于“意外”。代理修改了错误的层级、进行了大范围的重构，或者将高风险区域当作普通代码处理。良好的指令可以缩小“爆炸半径”。

Treat Docs As Product Surface

将文档视为产品界面

Developer onboarding isn’t separate from product. The docs shape what users try, where they get stuck, and whether they come back. For agent-ready repos, AGENTS.md is part of that product surface. So review it the same way you’d review a quickstart: Is the first task obvious? Are repo boundaries named? Are setup assumptions current? Are risky areas called out? Can a new contributor tell what “done” means? 开发者入职引导与产品本身密不可分。文档决定了用户尝试什么、在哪里卡住以及是否会回来。对于支持代理的仓库，AGENTS.md 是产品界面的一部分。因此，请像审查快速入门指南一样审查它：第一个任务是否显而易见？仓库边界是否明确？设置假设是否是最新的？风险区域是否被标注？新的贡献者能否理解什么是“完成”？

This is where AAIF’s open ecosystem angle becomes practical. If agent tools are going to work across projects, maintainers need shared conventions that don’t depend on one vendor, one editor, or one model. AGENTS.md gives repos a portable instruction layer. goose gives developers an open way to run agent workflows against it. Small file. Real leverage. 这就是 AAIF 开放生态系统角度变得务实的地方。如果代理工具要在各个项目中发挥作用，维护者就需要不依赖于特定供应商、编辑器或模型的共享约定。AGENTS.md 为仓库提供了一个可移植的指令层，goose 为开发者提供了一种运行代理工作流的开放方式。文件虽小，杠杆效应巨大。

A Practical Checklist

实用清单

Use this before you point an agent at your repo: 在将代理指向你的仓库之前，请使用此清单：

  • Pick one first-run task a new developer would value.
  • 挑选一个新开发者会重视的首次运行任务。
  • Add or update AGENTS.md with project shape, test expectations, and files to avoid.
  • 添加或更新 AGENTS.md，包含项目结构、测试预期和应避免的文件。
  • Remove commands you haven’t verified.
  • 删除你未验证过的命令。
  • Tell the agent how to behave around risky code paths.
  • 告诉代理在处理高风险代码路径时该如何表现。
  • Run the first task through goose or your agent runtime of choice.
  • 通过 goose 或你选择的代理运行时运行第一个任务。
  • Edit AGENTS.md based on where the agent guessed wrong. Repeat until the first.
  • 根据代理猜错的地方编辑 AGENTS.md。重复此过程，直到首次运行顺畅。
← 返回新闻列表 / Back to news list