What an AI Agent Should Find in a New Component
A four-question test for whether the component explains itself
If you want an AI agent to become useful fast in an unfamiliar component, do not start with a bigger prompt. Start with a component that explains itself.
When an agent lands in `shipping-quotes`, it should be able to answer four questions quickly:
- What does this component own?
- How do I work here?
- How do I verify a change?
- Where does the tricky context live?
If the component cannot answer those questions locally, the agent reads too much, touches too much, and asks too many basic questions. Ownership is fuzzy. The right commands are tribal knowledge. The important context lives in a slide deck, a spreadsheet, or somebody’s memory. So the agent wanders.
That is not always a model problem. Often, it is a component problem.
This is also a different problem from feedback after the edit. Before an agent can verify its own work, it has to orient itself in the component.
What does this component own?
An agent works best when it can reason locally.
That means the component should have a clear boundary, a small blast radius, and obvious contracts. In `shipping-quotes`, the agent should be able to tell what this component owns, what it depends on, and what it should not touch. It should know whether this component computes carrier quotes, consumes package and destination data, applies zone rules, or also owns checkout totals. Those are different jobs. A good boundary makes that visible in the interfaces, the file layout, and the local docs.
This matters more than context-window size. Even with a huge context window, a tangled component is still hard to change. The problem is not only how much code the agent can read. The problem is how much uncertainty the component creates. If every small edit may break three adjacent systems, the cost of acting goes up fast.
The first test is simple: can the agent make a local change without dragging half the repo into scope?
How do I work here?
Once the boundary is clear, the local path should be obvious.
If I drop an agent into `shipping-quotes`, I want it to find a short local guide. That might be `AGENTS.md`, `CLAUDE.md`, or a tight `README`. The name matters less than the job. The file should say what this component owns, which invariants matter, which commands to run, where the tests live, and what not to edit casually.
The component should also expose one obvious way to work. There should be one obvious command to run the local flow, one obvious command to exercise the tests, and one obvious place to look when something fails. If the repo offers four test commands, three half-working scripts, and two undocumented setup paths, the agent spends its first half hour on archaeology.
Good output belongs here too. When something breaks, the error should narrow the problem. “Missing carrier rate for zone” is useful. “Package dimensions exceed supported service limits” is useful. A stack trace with no domain signal is not. Legible components produce legible failures.
How do I verify a change?
Before an agent can fix a component, it needs a fast way to learn what the component does.
That is why tests matter so much. They do not only verify the change after the edit. They orient the agent before the edit. A strong suite shows what inputs matter, which edge cases the team cares about, and how wide the surface really is.
In `shipping-quotes`, a small suite might reveal the expected output for a domestic order, what happens to oversized packages, how missing carrier rates fail, and which rounding rules matter. In five minutes, that tells the agent more than a long design doc full of abstractions.
If a component is hard to understand, the fix is often not more prose. It is better tests. A good test file is both a guardrail and a map.
Where does the tricky context live?
The hard part of a component is often not the syntax. It is the domain logic.
That context should live where the agent can read it: in or near the component. Examples, fixtures, schemas, expected outputs, notes on invariants, and short explanations of weird cases all help. They are discoverable, versioned, searchable, and easy for an agent to inspect.
If the meaning of `shipping-quotes` lives in a slide deck, a spreadsheet, or somebody’s memory, the agent starts blind. The operator then has to shuttle basic context into the prompt by hand. That is slow, fragile, and easy to get wrong.
This does not mean every component needs a Markdown essay. It means the important context should exist in agent-readable form and sit beside the work. A canonical fixture is better than a paragraph. A sample output is better than a vague comment. A short glossary beside the code is better than a forgotten deck.
The standard to aim for
A good operator should be able to drop an agent into `shipping-quotes` without writing a custom tour guide every time.
The agent should find a clear boundary, one local path, tests that teach the terrain, and context that lives beside the code. If it cannot, a bigger prompt will not solve the underlying problem. The component is still illegible.
That is the standard I care about. Not whether an agent can eventually muddle through, but whether it can land in an unfamiliar component and become useful fast.
If you want better work from agents, stop treating the prompt as the only interface. The component is an interface too.