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.

The

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:

• Find the right entry point for a small 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.

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: .

1. Pick one first-run task a new developer would value.


2. Add or update AGENTS.md with project shape, test expectations, and files to avoid.


3. Remove commands you haven't verified.


4. Tell the agent how to behave around risky code paths.


5. Run the first task through goose or your agent runtime of choice.


6. Edit AGENTS.md based on where the agent guessed wrong.


7. Repeat until the first run produces something you would review seriously.

The goal isn't to make the agent perfect. The goal is to make the first session legible.

A 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.