Post

The primary artifact you need during design for agent-first development is a list of invariants. "Here's what absolutely must be true about the final result." This will often include a mix of concerns and will often include specific API contracts, specific test scenarios and expected outcomes, etc.

I haven't really found "spec-driven development" where the spec is a gigantic long document to be very useful. The spec begins to rot the moment it's written, and the codebase is the actual source of truth.

But maintaining a list of invariants makes it easy to put a verification loop at the end of an implementation cycle, and is also something that is easiest for a human team to align on.

I'm experimenting with design docs whose primary tab is just "here's the list of agreed upon invariants" that I might use an LLM to assist me in writing but I carefully review and edit every line to make sure I agree.

Then the secondary tab is a fully LLM-owned detailed design based on the invariants + codebase investigation. If I find something wrong in the design, I can update the invariants and redo the design.

You do have to be careful -- you can't put anything in the invariants that you don't actually mean is invariant, or you'll wake up to twisted code contorted around a false assumption.