The Context Tax of AI Coding: Why Agents Generate Code Fast but Reach Correct Changes Slowly

VInce929 — Wed, 09 Sep 2026 09:22:03 +0000

A three-layer workflow for improving time-to-correct-change in existing repositories.

Coding agents are getting remarkably good at generating code.

Yet in real repositories, code generation is often not the slowest part of the task.

The slow part is reaching the correct change.

Before an agent writes a line, it often has to answer questions such as:

Which business module owns this request?
Which request, data, or event path is actually active?
Is this file current production logic, a test fixture, a legacy implementation, or a similar-but-unrelated feature?
Which callers, contracts, configuration, and validations are relevant to this change?

I call this pre-generation overhead the context tax.

The context tax is not just a token problem. It creates search overhead, larger working context, irrelevant edits, and repair loops.

An agent may produce valid-looking code quickly while still taking a long time to produce a change that is correct for the repository, compatible with its boundaries, and ready for real-environment validation.

I am open-sourcing an experimental methodology called Context-First:

https://github.com/Vince929/context-first-agent-workflows

Its goal is simple:

Reduce the context tax so coding agents reach correct changes faster.

Why I keep using it

Context-First was not designed as a theoretical framework looking for a use case.

It came from a repeated problem in my daily work with coding agents in real existing repositories: writing code was often not the slow part. The slow part was getting the agent to the correct business entry point, providing enough context without flooding it with irrelevant code, avoiding changes to similar-but-unrelated implementations, and reaching a validation environment with the right change.

In my own day-to-day work, this workflow has significantly reduced:

the number of times I need to redirect an agent to the code that actually owns a request;
time spent on broad search and irrelevant context collection;
unrelated refactors caused by unclear business boundaries;
repair loops caused by missed direct dependencies, callers, or validation constraints;
coordination overhead between receiving a request and obtaining a change that can be validated.

The practical result is that I complete routine development work faster and spend substantially less time continuing implementation work outside normal working hours.

This is not a claim that the workflow makes models emit tokens faster. It is a claim about my experience using agents in real repositories: reducing context tax can improve the end-to-end speed from request to a correct, verifiable change.

My working hypothesis is:

If an agent receives the smallest correct context before it generates a change, it is more likely to reach a correct and verifiable result with less search, a smaller change surface, and fewer repair loops.

To make that practical, Context-First separates the problem into three layers.

1. Structure: keep business context local

Inside the existing source root, runtime code is organized around:

<source-root>/
  app/
  modules/
tools/

Where:

modules/ contains user-recognizable business capabilities;
app/ contains application composition and non-business platform capabilities;
tools/ contains non-runtime engineering operations such as migration, maintenance, operations, and generation.

For example, a task-management module might look like this:

modules/
  task-management/
    pages/
    components/
    api/
    state/
    domain/
    model/

When a task asks for a priority filter, an agent should be able to start at:

modules/task-management/

instead of guessing between global folders such as:

components/
services/
models/
store/
utils/

This does not require every language to use the same source-root layout. A frontend project may use src/; Python may use src/<package>/; Java or Kotlin may keep src/main/<language>/.

What is standardized is the first architectural decision after entering the source root:

Is this about how the application runs? Look in app/.
Is this about a business capability? Look in modules/<capability>/.
Is this about migration, maintenance, or operations? Look in tools/.

The structural layer aims to reduce long-term context search cost by keeping the primary context for a business request physically close together.

2. Navigation: create a cold-start index for unfamiliar repositories

Even a well-organized repository is unfamiliar to a new agent.

An agent may not know:

where the project starts;
how modules are named;
which paths are primary;
which platform capabilities affect most changes.

Context-First uses a root PROJECT-MAP.md as a compact semantic index.

It records only high-value facts:

project purpose and runtime shape;
actual entry points;
primary business modules and responsibilities;
a small number of important request, data, or event paths;
platform capabilities that affect many tasks.

For example:

# Task Management Web Project Map

> A React web application for reviewing and assigning operational tasks.

## Module navigation

| Path | Responsibility | Main entry point / key dependency |
| --- | --- | --- |
| `src/app/routes/` | Route composition and access guards | `AppRoutes.tsx` |
| `src/modules/task-management/` | Task list, filters, assignment, and review flow | `pages/TaskListPage.tsx` |
| `src/app/platform/http/` | Shared HTTP client and request error normalization | `client.ts` |

## Primary request / data paths

1. `browser entry -> app routes -> task-management page -> task API -> backend`

A project map is not an architecture encyclopedia or a file inventory.

It answers one question:

What should the agent read first?

After that, source code, types, call graphs, and runtime behavior remain the implementation truth. The map only reduces the scope of the first search.

The navigation layer aims to reduce cold-start time before an agent finds the first relevant files.

3. Execution: let people decide and agents do deterministic work

Agents should not silently make product, compatibility, or module-boundary decisions.

In Context-First, humans decide:

business goals and acceptance criteria;
architectural boundaries and compatibility policy;
release risk and real-environment acceptance;
which changes may expand and which must remain local.

Agents execute:

locating the target implementation and direct dependencies;
reading necessary interfaces, types, callers, and configuration;
implementing the smallest correct change in the smallest real context;
repairing failures based on real build, runtime, or test evidence;
clearly handing off change scope, compatibility impact, and validation steps.

A typical local task looks like this:

human provides goal and constraints
  -> agent reads the target module and direct dependencies
  -> agent implements the smallest correct change
  -> human validates in the real target environment
  -> if a real failure occurs, agent makes a targeted repair

The point is not to make agents do less work. It is to prevent them from making uncertain decisions that belong to people.

When work involves module migration, directory redesign, public-contract changes, or extensive import movement, it should switch to a different mode:

analyze facts
  -> propose a reviewable migration plan
  -> obtain explicit approval for boundaries and trade-offs
  -> implement consistently

The execution layer aims to reduce unrelated edits, repair loops, and validation noise after the correct context has been found.

What this methodology aims to improve

Context-First does not claim to make models emit tokens faster.

It aims to improve time-to-correct-change: the time from receiving a request to producing a correct, verifiable change.

Useful signals include:

time from task receipt to the first relevant implementation file;
number of files and directories read before the first edit;
clarification rounds about business boundaries or compatibility;
changed files and directories per task;
validation failures caused by missed direct dependencies;
total time from request to correct change;
repair and rework loops;
maintainer feedback on whether a change remained local and reviewable.

These measurements do not automatically prove that one structure is always better. Benefits will vary by team, language, repository shape, agent tool, and task type.

But they move the conversation away from folder-name preference and toward a more concrete question:

Which code structure, navigation method, and collaboration protocol help agents reach correct changes faster?

An experiment, not a universal answer

Context-First does not argue that every repository should undergo a large directory migration.

It does not argue that business modules are always better than technical layers.

Some systems genuinely require broad global context before a safe change is possible. Some teams are organized around platform or infrastructure boundaries rather than business capabilities. Some tasks are bottlenecked by external dependencies, test environments, or release workflows rather than code navigation.

So this repository does not present one personal experience as a universal benchmark.

It provides:

three installable agent skills;
a PROJECT-MAP.md template;
the app + modules + tools structure method;
a synthetic before/after example;
a protocol for sanitized case studies and measurements;
GitHub Discussions for methodology questions, evidence, and counterexamples.

GitHub repository:

https://github.com/Vince929/context-first-agent-workflows

Counterexamples, agent adapters, cross-language case studies, and discussion about context tax and time-to-correct-change are welcome.

I am especially interested in questions such as:

Which systems truly require broad global context before agents can safely make changes?
When do business modules create more complexity instead of less?
Can a short, human-maintained PROJECT-MAP.md remain trustworthy over time?
Which measurements capture productivity without rewarding unsafe or incomplete changes?

Those cases and counterexamples will determine what Context-First should eventually become.