I do not like writing specs (the implementation plans that are fed to the LLM we use). Luckily for me Claude is doing most of the writing. My job revolves mostly around arguing with Claude until it generates a Markdown file I like.

After I like the Markdown file, I commit it hoping the other human that reads it, likes it too. Because why else would you commit it?

After the other human likes the spec, I can apply it, which results in a bunch of generated code. I have to check if the code actually works and meets my standards. Then I send it off to review, again.

Hopefully everyone likes it on the first try. At that point we can push it to the main branch and archive the spec so it becomes 'canon'.

If that is not the case, the other humans will ask Claude to review the code, while I ask Claude to read the comments, and respond to them either by applying the changes or rejecting the feedback.

It just doesn't make sense to me. The specs generated this way are generally incredibly difficult to read. Even when asking to write the specs in plain English, I can't read those documents without becoming tired.

What then?

I do not know. But keeping a decision log or an ADR makes more sense to me. That seems to be the goal anyway, keeping track of decisions.

This log has the real decisions, it has no fluff. Your code already tells you WHAT; the log holds WHY.

But to be honest, I am still figuring out this whole AI-assisted development thing.