My biggest coding headache this weekend was managing the docs, specs and plans

Documentation is the code you write when working with LLMs. The Agent is the compiler.

Specs used to be written once and ignored. With LLMs in the loop, they become shared state - drafted, revised, and reconciled by humans and agents every time the system changes.

Developer work in LLM-assisted development increasingly lives upstream of the editor: brainstorming, writing plans, and authoring skills. In practice, most of my time goes into shaping the problem so agents can take it from there—implementing features, generating tests, drafting documentation, and carrying parts of the SDLC forward without constant hand-holding.

That upstream focus produces a growing body of specification: documents that explain not just what the system does, but why it is built the way it is. Every new brainstorming session, plan, or skill tends to spawn new docs and force updates to existing ones—merging overlapping specs, splitting bloated documents into sharper scopes, or retiring plans that no longer match the code. The artifact trail is no longer optional background material; it is part of the delivery pipeline, maintained in a loop between human judgment and agent execution.

I spend less time writing code and more time writing and maintaining docs and specs. That is the real trade in agent-assisted development. Developers are now one degree removed from the implementation: they shape the work, review the output, and keep the surrounding artifacts honest. The discipline that used to go into code, structure, clarity, maintenance, hygiene, has to apply to plans and specifications too.

Tonight's Cleanup

Tonight's commit for a personal Flutter Adaptive Cards project was the 3rd straight requirement/spec/doc only PR request.

I asked the Question

Is there any documentation in @docs that is candidate for being merged?

Resulted in 20 document changes

The good news is that 6 plans and specs have been archived as they were superseded by later work. 15 documents were updated with new content, removed content or updated links.

Video

Too lazy to read that stuff?  Watch the video

Revision History

Created 2026 05