Documentation lies.
Not on purpose. It lies because nobody updates it. The wiki says the discount threshold is $100. The code says $75. The wiki was right once. The code is right now.
This has always been a problem. But it used to be a human problem — developers knew to distrust the wiki and read the code instead.
AI agents don’t have that instinct.
Agents Read What You Give Them
When an AI agent picks up a task, it needs context. It needs to know what the system does, how it behaves, what the boundaries are.
Where does it get that context?
If you point it at documentation, it gets a version of truth that may or may not reflect reality. If you point it at the code, it gets implementation details without intent. It can see what the code does but not what it’s supposed to do.
Tests are different.
A well-written test suite is the only artifact that is simultaneously:
- Executable — it runs, so it can’t silently drift from reality
- Intentional — it describes what the system should do, not just what it happens to do
- Current — if it’s wrong, the build breaks
That’s not documentation. That’s a contract.
The Test Suite as Interface
Think about what a test gives an agent:
test("orders over $75 get free shipping")
test("orders at exactly $75 get free shipping")
test("orders under $75 are charged $5.99 shipping")Three lines. An agent now knows the shipping threshold, the boundary behavior, and the fee. No wiki required. No Slack thread archaeology. No “ask Sarah, she knows how that works.”
The test names are the specification. The assertions are the contract. The test data is the edge case documentation.
This is why test naming matters more than most developers think. test_shipping_1 tells an agent nothing. test("orders at exactly $75 get free shipping") tells it everything.
Why This Changes How You Write Tests
If your test suite is the interface for AI agents — and increasingly it is — then test quality isn’t just about catching bugs.
It’s about communication clarity.
A test suite full of test_1, test_2, test_3 is a codebase with no documentation. An agent can run the tests but can’t understand the intent. It can tell you what passes and fails, but not why it matters.
A test suite with scenario-style names, clear arrange-act-assert structure, and boundary cases spelled out? That’s a codebase that an agent can reason about.
The bar isn’t “do my tests pass.”
The bar is “could an agent read my tests and understand my system.”
The Feedback Loop Gets Tighter
Here’s what happens when your test suite is good enough to serve as an agent interface:
- Agent reads test names to understand system behavior
- Agent reads failing tests to understand what needs to change
- Agent makes changes
- Tests run automatically
- Pass → done. Fail → agent reads the failure and iterates.
No human in that loop until the end. The test suite is doing the job that documentation, code review, and tribal knowledge used to do — combined.
That’s not a future scenario. That’s how teams using AI agents are working today.
The Uncomfortable Implication
If your test suite can’t explain your system to an agent, it probably can’t explain your system to a new team member either.
You’ve just been compensating with Slack messages and pairing sessions.
AI agents don’t have that luxury. They get the tests and the code. Nothing else.
Which means the quality of your test suite is now directly proportional to how much value you can extract from AI tooling.
Low-quality tests → agents need constant human guidance → you haven’t automated anything.
High-quality tests → agents self-serve → you’ve built leverage.
The test suite isn’t just a safety net anymore.
It’s the API for the next generation of your team.