Our agent debugged for 20 minutes because of wrong assumptions.

I watched our coding agent spin its wheels for 20 minutes trying to debug a test failure. It had all the right tools — it could run tests, read logs, edit files. But it kept making the same logical error: assuming the test framework worked like a different one.

The problem wasn't intelligence. It was assumptions.

Most agents operate like they're working with generic APIs and universal patterns. But your codebase has opinions. Your test framework has quirks. Your deployment pipeline has that one weird step everyone knows about but nobody documents.

Here's what fixed it: assumption documentation.

I created a file called ASSUMPTIONS.md in our repo root:

## Test Framework Assumptions
- Tests run with pytest, not unittest
- Test files must start with test_ or they're ignored
- Fixtures are defined in conftest.py, not inline
- Database tests need @pytest.mark.db decorator

## Deployment Assumptions  
- Staging deploys automatically on PR merge
- Production requires manual approval
- Environment variables are set in .env.production
- Health checks hit /api/health, not /health

## Code Style Assumptions
- We use black for formatting (it's in pre-commit)
- Import order: stdlib, third-party, local
- Type hints are required for public functions
- Docstrings follow Google style

The difference was immediate. Instead of the agent discovering our pytest setup through trial and error, it knew upfront. Instead of assuming standard REST patterns, it knew our API quirks.

Key insight: Your agent doesn't need to be smarter. It needs to be informed about your specific context.

But here's the thing — assumptions change. That health check endpoint? We moved it last month. The deployment process? We added a security scan step.

So I added assumption validation to our agent's startup routine:

When starting a coding session:
1. Read ASSUMPTIONS.md
2. Verify 3 random assumptions
3. Flag any that seem outdated
4. Ask human to confirm or update

Now when our agent starts a session, it might say: "I'm assuming tests run with pytest, but I see some unittest imports in the recent commits. Should I update the assumptions file?"

This prevents assumption rot — that silent drift where your documentation becomes fiction.

The pattern works beyond coding. Our support agent has assumptions about our refund policy, our sales agent has assumptions about pricing tiers, our content agent has assumptions about our brand voice.

Three assumptions every agent needs documented:

• Tool behavior — How your specific tools actually work (not how they're supposed to work)
• Business rules — The policies and constraints that govern decisions
• Context quirks — The weird stuff that's obvious to humans but invisible to agents

The magic happens when your agent stops guessing and starts knowing. It's the difference between an intern figuring things out and a team member who knows how things work here.

Document your assumptions. Validate them regularly. Watch your agent stop reinventing your wheel every conversation.