Context Engineering Is Just File Naming

A new job title showed up in my feed last week. Context engineer.

I clicked. Twice. Three articles, all definitional. None of them showed code. Every definition was a paraphrase of “name things well.”

Then I opened my own repo and grepped for utils.py. Eleven hits. Six folders deep, in a project I have shipped to production. The same project where I had spent two hours that morning fighting an agent that kept loading the wrong helper file.

The fix took thirty seconds. I renamed the file.

The pitch checks out

Context engineering is the discipline of shaping what a language model reads when it touches your codebase: filenames, folder structure, function signatures, prompts, retrieval rules. Done well, the model picks the right code on the first try and you write fewer follow-up prompts. Done poorly, you spend paragraphs compensating for a vague filename.

The current pitch goes further. This is a new discipline, the story says, deserving a new role. Curate the files, structure the prompts, build the retrieval system, manage the embeddings. Each claim is accurate. None of them describes a new problem.

You have been doing this since you wrote your first config file. Every time you renamed helpers.js to payment-validation.js, you were context engineering. Every time you split a 400-line file into three named pieces, you were context engineering. The audience was always the next developer reading the file. Now there is one more reader.

The actual job

A senior engineer joining a codebase does three things in the first week. They read the folder structure. They read the most-named-things in the imports. They follow the breadcrumb from filename to function to line.

Agents do the same thing. The retrieval layer in your agent loop is grep with extra steps. It pulls files whose names match the task. It pulls functions whose docstrings match the intent. It pulls comments that say what the code does.

If your filenames are vague, the retrieval is vague. If your function names lie about what the function does, the agent loads the wrong one. If your folder names group code by file type instead of by concern, the agent loads models/ and gets nothing useful.

The skill we have been failing to enforce for thirty years became load-bearing the day a probabilistic reader joined the loop.

Three things I renamed last month

api.py became payment-webhook-handler.py. The agent stopped loading it for unrelated payment questions. One rename, one less failure mode.

utils/ got deleted. The five files inside moved next to the code that called them, with names that said what they did. format-currency.py, parse-iso-date.py, redact-pii.py. The agent now loads them only when the task mentions currency, dates, or PII.

A 600-line process.py split into four files. validate-input.py, dedupe-rows.py, enrich-from-cache.py, write-to-warehouse.py. The agent stopped trying to read the whole pipeline to answer questions about a single step.

Call it context engineering if the buzzword helps. The work is renaming.

Where the model has to guess

Walk your repo right now. Count the files named utils.py, helpers.js, common.go, lib/, services/, manager/. Count functions named process, handle, run, execute, do.

Each one is a place where the model has to guess. Each one is a place where you have to write a longer prompt to compensate. Each one is a paragraph you will never have to write again if you rename it now.

The reason context engineering feels hard is that you are trying to solve at retrieval time what should have been solved at naming time. You cannot grep your way out of a vague folder structure. You cannot embedding-search your way out of process(). The model is asking the same question the senior engineer asks in week one. The answer was always going to be: name things by what they do, not by what they are.

The role that already existed

There is a real version of context engineering. Chunking strategy, embedding choice, retrieval rerankers, evaluation harnesses. That work is real and hard.

Most of what gets called context engineering this month is the rename you skipped in the original PR.

A context engineer is a developer who finally names things.

What is the file in your codebase that the agent keeps loading wrong?