logoalt Hacker News

mrwh • today at 2:09 PM • 2 replies • view on HN

An AI design doc has all the outward appearances of a -- good! excellent sometimes! -- preAI design doc, in my experience. But it also has no reason to exist. There's no social aspect, since no one has gone through the process of actually understanding the systems involved, there's no meaningful way to review it ("why do things this way?" "Because it said to do things this way"). And it's not needed for the implementation either, for which the original prompt, whatever it was, suffices. By industrialising the output of a process, we forget why it was necessary to go to the trouble in creating it by hand in the first place. Perhaps that's ultimately how things advance, and right now we're in the absurd middle, treating proofs of work like the work itself.


Replies

techmunky • today at 5:05 PM

If you're using your LLMs to create the product A - Z then sure these docs don't matter. But assuming you or a team is driving the product and engineering architecture then these docs do matter. I still build out docs because they are a reviewable source of truth, a reliable historical knowledge sink, and because I still know how my product works.

mceachen • today at 3:38 PM

> it also has no reason to exist.

I despised having to produce design documents for software projects 20 years ago (the last time I had to do it as a software engineer). I wanted to jump straight to coding. I begrudgingly found that, much like research papers, it's a forcing function in really understanding the problem space.

Over the last year, I've found that, at least for nontrivial things, if my agent makes a terse (under 300 line) technical design doc that describes their research and their tasks, it can highlight any disconnects between what I asked and the agent's interpretation. It also serves as context to ramp up cross-model reviews, and as historical reference material when I have to Chesterson's fence something later. I wrote up more about this here: https://photostructure.com/coding/claude-code-tpp/

➕ show 1 reply