{"slug": "from-first-run-drop-off-to-first-useful-agent-run", "title": "From First-Run Drop-Off to First Useful Agent Run", "summary": "The Agentic AI Foundation (AAIF), hosted by the Linux Foundation, is promoting AGENTS.md and goose to improve first-run agent experiences. AGENTS.md provides a predictable place for repo instructions, helping agents avoid common pitfalls like guessing package managers or editing generated files. The project claims over 60k open-source projects already use AGENTS.md.", "body_md": "I keep coming back to the same onboarding question: what happens in the first 10 minutes?\n\nFor 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.\n\nThat isn't an agent model problem every time. A lot of it is repo readiness.\n\nThe [Agentic AI Foundation](https://aaif.io), 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.\n\nAGENTS.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.\"\n\nDon't begin by asking, \"What should our agent docs say?\"\n\nAsk this instead: what should a developer be able to ask an agent to do in this repo within 10 minutes?\n\nPick one task. Not the whole system. One useful first run.\n\nFor example:\n\nThat 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.\n\nAGENTS.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](https://agents.md).\n\nThe 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.\n\nYour first version should answer:\n\nKeep it short enough that someone would maintain it. Stale agent instructions are worse than missing ones because they create confident mistakes.\n\nAn AGENTS.md file doesn't need brand language. It needs maintainer notes.\n\nSay things like:\n\n```\n# AGENTS.md\n\n## Project Shape\n\nThis repo contains a web app and supporting packages. App code lives in `apps/web`. Shared code lives in `packages`.\n\n## Working Rules\n\nPrefer small changes that match nearby patterns. Do not rewrite public APIs unless the task asks for it.\n\n## Tests\n\nWhen 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.\n\n## Files To Avoid\n\nDo not edit generated files, lockfiles, or vendored code unless the task is specifically about dependency updates.\n```\n\nNotice what's missing: fake certainty.\n\nDon'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.\n\ngoose 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](https://aaif.io/projects/goose).\n\nFor onboarding, think of goose as the first-run path you can test against your repo instructions.\n\nA good first-run path has three pieces:\n\nThe 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.\n\nThat belongs in AGENTS.md.\n\nA useful agent doesn't need to know everything. It needs to know when to stop guessing.\n\nAdd guidance for uncertainty:\n\n```\n## When Unsure\n\nIf the requested change touches auth, billing, data deletion, or production configuration, ask before editing.\n\nIf there are multiple plausible implementations, describe the tradeoff and choose the smallest local change unless the user tells you otherwise.\n```\n\nWhy 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.\n\nGood instructions narrow the blast radius.\n\nDeveloper onboarding isn't separate from product. The docs shape what users try, where they get stuck, and whether they come back.\n\nFor agent-ready repos, AGENTS.md is part of that product surface. So review it the same way you'd review a quickstart:\n\nThis 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.\n\nSmall file. Real leverage.\n\nUse this before you point an agent at your repo:\n\nThe goal isn't to make the agent perfect. The goal is to make the first session legible.\n\nA developer should be able to open the repo, start the agent, ask for one scoped task, and understand the result without becoming the repo tour guide.", "url": "https://wpnews.pro/news/from-first-run-drop-off-to-first-useful-agent-run", "canonical_source": "https://dev.to/bengreenberg/from-first-run-drop-off-to-first-useful-agent-run-mde", "published_at": "2026-07-16 22:16:16+00:00", "updated_at": "2026-07-16 22:35:06.436663+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools"], "entities": ["Agentic AI Foundation", "Linux Foundation", "AGENTS.md", "goose", "MCP", "agentgateway"], "alternates": {"html": "https://wpnews.pro/news/from-first-run-drop-off-to-first-useful-agent-run", "markdown": "https://wpnews.pro/news/from-first-run-drop-off-to-first-useful-agent-run.md", "text": "https://wpnews.pro/news/from-first-run-drop-off-to-first-useful-agent-run.txt", "jsonld": "https://wpnews.pro/news/from-first-run-drop-off-to-first-useful-agent-run.jsonld"}}