AI coding advice is rediscovering the Agile Manifesto

In a longer article about AI and micromanagement, I wrote about over-specified prompts and context files that grow until they resemble an anxious manager's briefing notes.

One part of that argument kept bothering me afterward. The AI coding advice on LinkedIn had started to sound familiar.

For two years, we've written elaborate markdown files to explain our repositories to AI. Some of that context helps. Keep adding to it, though, and the file becomes another piece of documentation that can drift away from the code it describes.

Our prompts went through a similar phase. We wrote rigid pseudocode, prescribed each mechanical step, and tried to remove every possible decision. It worked for small tasks. As the tools improved, I noticed better results when the prompt explained the user's problem, the relevant constraints, and what a successful result looked like. The model could work out more of the path for itself.

We're probably five minutes away from someone publishing an "AI Coding Manifesto." I can already imagine the themes: code that explains itself, clear user needs, architecture visible in the repository, and tests that show what correct behavior looks like. Maybe there'll be something about names that don't require 200 lines of prose to explain data_final_v2.

These aren't special techniques for talking to a machine. They're old ways of making software easier to understand and change. AI makes the cost of ignoring them unusually visible because it will happily follow stale instructions or reproduce a bad pattern at speed.

The original Agile Manifesto also left room for the items on the right. Detailed instructions and context files can be useful. They become a problem when we use them to compensate for a repository that no longer communicates its own design.

Maybe the AI coding manifesto has already been written. We published it in 2001, and we're slowly finding our way back to it.