How Prompts Become Technical Debt in AI Coding

Technical debt is a familiar problem, and AI cuts both ways: it can help clean up work that was previously too tedious, but it can also make it easy to add more code without understanding it. I want to look at a related idea from Sean Goedecke: prompts themselves can become technical debt.

Project instruction files are one example. I already suspect that the AGENTS.md in the T3 Code repository is outdated and may be causing problems. Like code, instructions can accumulate while the project around them changes; unlike a compile error, the resulting failure may not announce itself.

Goedecke starts with the idea that code carries a maintenance cost. New features require code, but future changes must coexist with what is already there. A sufficiently large system cannot be held in one person’s head, so engineers need ways to navigate and reason about its parts.

I remember an earlier expectation that AI tools would simply load a whole codebase into a growing context window. In practice, approaches that search for relevant files can be more useful. My point is not that one retrieval method always wins, but that a large context window does not automatically give either a person or an agent a reliable understanding of every line.

Prompts come in many forms: AGENTS.md or CLAUDE.md files, nested instructions, skills, tool descriptions and system prompts assembled by an application. T3 Chat, for example, adjusts its system prompt according to selected tools and models. That flexibility also creates configuration that has to be maintained.

A small prompt adjustment can affect how a model behaves. I have seen vendors test different instructions and tool descriptions for individual models. I mention reported performance differences between harnesses, but those numbers depend on the benchmark and configuration; they do not establish that one tool universally improves every model by a fixed percentage.

As one example, I describe a developer spending time testing Gemini prompts before a release to reduce unnecessary tool use. The broader lesson is that getting a model to behave well involves work beyond the model name. System prompts are not magic secrets, but developing and evaluating them can be real engineering.

Changing a workflow can change what the agent sees and how it acts. Adding a skill, plugin or MCP server may expose new instructions or tools, depending on the product and its configuration. Installing everything that sounds interesting can consume context and encourage irrelevant tool use, so I recommend inspecting what is actually enabled.

Goedecke argues against spending excessive time on a bespoke coding setup because prompt tweaks can be model-specific. A new model can interpret a previously useful instruction differently, and the company maintaining an agent may need to retune tool descriptions for that release. I have encountered such changes in my own testing.

That creates a subtle failure mode. A carefully crafted set of instructions can become outdated or even harmful after a model update, yet the agent may still produce plausible results. You might blame the model or the application without noticing that an old customization is influencing the outcome.

I like to start from a minimal setup and add capabilities when I encounter a concrete need. I use the Pi coding agent in a relatively plain configuration partly to see what the underlying model does well or poorly. Its customizability is useful, but I do not treat every available customization as something I must enable.

I compare the amount of context different harnesses may use for instructions and tools. The figures I mention are observations from particular versions and configurations, not universal current token counts. What matters is checking your own setup and understanding the tradeoff between useful guidance and material the agent must process.

Prompt debt can decay quietly. An old instruction can remain syntactically valid while subtly steering the agent in the wrong direction, especially after a model or project changes. Traditional code can also fail silently, but prompt behavior makes regressions particularly difficult to spot without representative evaluations.

I inspect T3 Code’s AGENTS.md and find old language describing the repository as an early work in progress and encouraging sweeping changes. It also describes a Codex-first architecture that I say no longer applies. The broad instruction once served a purpose, but I now suspect it may encourage changes we do not want.

Updating that file properly would mean more than deleting text at random: ideally we would test the revised guidance against real tasks and see whether behavior improves. The team has been busy shipping features, which is exactly how an instruction file can be neglected while the codebase changes around it.

For another project, Lakebed, I describe a different kind of agent file: more of a letter explaining the project’s purpose and desired approach than a directory map. I think explaining why as well as what can be valuable. The challenge is that this remains less deterministic than ordinary code, and failures may be quiet.

Staying on one model might avoid some changes, but Goedecke and I are skeptical that freezing a setup is always practical while models improve quickly. That is a judgment about the current pace and tradeoffs, not a rule that every application must immediately upgrade or that a newer model always wins.

His recommendation for many users is to choose a maintained coding tool and keep custom configuration limited, relying on its maintainers to evaluate prompts as models change. That is also part of the motivation behind T3 Code: provide an interface while using work done by the teams maintaining underlying agent tools.

The practical advice is to avoid unnecessary skills and tools, and keep project instructions focused on concrete facts. Be cautious with generic behavior steering and with pages of model-generated instructions that nobody has reviewed. These are preferences and heuristics, not proof that every long instruction file is harmful.

I prefer to write or review instructions deliberately and remove material that no longer helps. My own global instructions are short, and even those sometimes get in the way. For many projects I start without a project-specific agent file, then add guidance once a recurring need becomes clear.

Audit the Markdown files, system prompts and other instructions supplied to your agents. Check whether they still describe the current project and whether each instruction helps with a real task. My own repository is an example of why this is easy to neglect: the code changed repeatedly while its guidance went untouched.