Context is an infrastructure problem

How you feed context to your agents determines whether they work or hallucinate. Not the model. Not the prompt. The context.

Three reads, three directories, one query

An agent needs to deactivate a user. It reads the schema in the models folder. Now it needs the connection string from the credentials folder. Now it needs to know that the team uses soft deletes and that the status column has an enum constraint, which lives in a conventions folder.

Three reads. Three unrelated directories. One query. And most of what it loaded from each folder was noise.

This is what happens when context is organized for humans, not agents. Humans accumulate knowledge over weeks. Agents start cold every time.

If the context is wrong or unreachable, your agent fails the same way it fails when a database connection is misconfigured. It doesn’t try harder. It guesses.

Context is not documentation you write and forget in a wiki. It’s infrastructure your system depends on to function.

How you structure that context matters more than what’s in it.

The folder structure trap

If you’re a developer, your instinct is to organize knowledge the way you organize code. Separate by type, one folder per concern. Credentials in one place, integration docs in another, conventions somewhere else.

That instinct is right for code. It’s wrong for agent context.

It works for humans because they already have context in their head. A senior developer doesn’t need the conventions file open to remember that the team never hard-deletes rows. They just know. When they need a detail they forgot, they know exactly where to search.

An agent doesn’t know any of that.

It burns context window on irrelevant information, or it skips the search and guesses. Guessing means using a connection string from the wrong environment. It means calling an API endpoint that was deprecated two months ago. It means inserting a row without knowing the column has an enum constraint.

Consider deactivating a user across three systems: updating the database, canceling their Stripe subscription, sending a Slack notification. With co-located context, the agent reads three files: database-users.md, stripe.md, slack.md. Every token it loads is relevant to the task.

With type-organized context, it opens the credentials folder and gets connection strings for every integration, not just the three it needs. It opens the conventions folder and gets rules for every domain. The signal-to-noise ratio drops with every file.

Organizing knowledge by type was designed for humans navigating code with an IDE and accumulated knowledge. Agents have neither.

Co-locate by integration

One file per integration. Everything the agent needs, in one place.

Instead of this:

context/
  credentials/
    database.md
    stripe.md
    slack.md
  models/
    users.md
    payments.md
  conventions/
    queries.md
    messaging.md

Do this:

context/
  database-users.md
  stripe.md
  slack.md
  auth.md

Where each file contains everything the agent needs to work with that integration:

# Database: Users

## Connection
- PostgreSQL 15, hosted on RDS
- Connection string: stored in DATABASE_URL env var
- Connection pool: max 20, timeout 5s

## Schema
- Table: users
- Columns: id (uuid), email (varchar unique), name (varchar),
  status (enum: active, inactive, suspended),
  created_at (timestamp), updated_at (timestamp)
- Indexes: (email) unique, (status), (created_at)

## Conventions
- Soft deletes only: set status to 'inactive', never DELETE FROM
- Default order: created_at DESC
- Use parameterized queries, never string interpolation
- Always check status != 'suspended' before allowing actions

## Gotchas
- The status column is a PostgreSQL enum. You cannot pass
  a plain string, use: WHERE status = 'active'::user_status
- updated_at is not auto-managed. Always set it explicitly
  on UPDATE queries
- The email column has a unique constraint at the DB level.
  Handle duplicate errors gracefully, don't check-then-insert
- The phone column exists but is unreliable. Migration to a
  separate contacts table is planned for Q2. Do not read from
  or write to phone in new code

Connection details, schema, conventions, gotchas. One file. The agent reads it once and writes correct queries on the first try. No navigation. No assembly. When it needs to send a Slack notification instead, it reads slack.md and gets everything about Slack in one place.

Each file is a self-contained briefing. One read, ready to act.

Yes, co-location means duplication. The soft-delete convention appears in every database file. The Stripe API version appears in every payment file. That’s the price of retrieval speed. Same trade-off as denormalizing a database: you trade storage efficiency for query performance. For agents, fast retrieval wins.

The maintenance cost is real. Treat context files like config: review them in PRs, update them when conventions change, flag files that haven’t been touched in 90 days. If a soft-delete policy changes, you update five files instead of one. Small price. The alternative is an agent that silently uses stale conventions because it loaded the wrong file or never found the right one.

Finding the right file

Co-location puts everything in one place. The agent still needs to find that place.

Clear naming helps. database-users.md and stripe-payments.md let the agent pick the right file from a directory listing alone.

An index file helps more. One file at the root of your context directory, one line per context file, a short description of what it covers. The agent reads the index, follows the relevant link, lands on the right file. Two reads total.

There’s already a convention for this: llms.txt. It’s a simple text file that acts as a table of contents for AI agents. You place it at the root of your project, list your context files with one-line descriptions, and any agent that knows the convention can orient itself immediately. Think of it as a sitemap.xml, but for agents instead of search engines.

If you outgrow those, co-location makes vector search better too. Each chunk is self-contained context for one integration instead of fragments scattered across folders that need reassembly.

Treat it like infrastructure

If context is load-bearing, treat it that way. Version-control your context files. Review changes in PRs. When you change a convention or deprecate an endpoint, updating the relevant context file should be part of the same changeset. Not a follow-up task. Not a wiki edit you’ll get to later. Part of the work.

When documentation is wrong, nothing breaks. When infrastructure is wrong, everything breaks.

When a convention changes and the context file still says the old thing, your agent will follow the old convention. Silently. Confidently. On every task until someone notices.

When your agent would break without a context file, that file is infrastructure. Treat it that way.