logoalt Hacker News

GeneralMayhemtoday at 3:31 PM1 replyview on HN

Not OP, but I think they're way more essential with AI doing a lot of the coding. The biggest thing that AI, even the frontier models, is not great at is staying on topic and actually finishing a project with reasonable priorities instead of ratholing on insignificant details or claiming it's "finished" when it's half done.

The most important thing that a good design doc does is specify what's in and out of scope. The second most important thing is to precisely define common vocabulary - what are the important concepts in the problem you're solving, and how should they relate to each other? All of that information serves to ground the day-to-day work in what's important. I find myself starting every Claude session with "read this doc and get familiar with the world, then we'll get to work on a part of it".

(The same is true when working with humans, especially but not limited to junior engineers who aren't used to managing a project longer than a week or two. AI coding agents just never grow out of that phase.)


Replies

luc_today at 4:27 PM

For an entire project? Yes I agree. For a feature or a submodule? I think when you work with claude to develop a plan, it's generally pretty good.

I guess my question stems from being rigid how a design doc should be defined, argued over, and then executed by humans. I think some of the details simply don't matter, and if they do, they often can be changed relatively quickly in order to adhere to the new requirement.

Try the claude-mem plugin.