Ask HN: Design docs as levers for maintaining technical quality
Recently, I started using Cursor and other tools for my hobby projects, and I realized that it is very easy to get carried away, which directly impacts the code quality. If I don't start with a solution in mind and blindly ask AI to code, it is disastrous (not a surprise, though). As more orgs adopt AI coding tools, I assume that technical quality will become the immediate concern, and design skills will become even more critical.
Even before AI, this was a challenge for me as a developer and as an engineering manager, as funding technical quality is often a balancing act between priorities and people.
I think that a well-thought-out system will lay the foundation for writing good code. If the barrier to entry to write a good design doc is high (currently dependent on developer's craft), people would naturally avoid it and tend to solution on the fly by focusing on the coding part. In contrast, a design doc will slow down that process and get feedback early enough in the cycle that coding becomes relatively more straightforward. A good design doc can even become input to some of these AI coding tools.
I'm thinking of solving this by providing a tool to write better design documents, giving levers to build a better mental model of existing systems, reason, and articulate solutions while inviting healthy discussions. From my experience, I've seen a high variance in the quality of design documents, ranging from great ones to afterthought namesake design documents to show in a promo packet. With this tool, I want to reduce the gap in quality between a senior/staff dev's design doc and a junior dev's design doc. At the same time, it significantly reduces the effort it takes for a staff dev to write a design doc.
I started building the tool, and it looks exciting to me. So far, it can analyze code, offer solutions, provide alternatives, and even draw mermaid diagrams to represent systems. At the same time, I'm worried if I'm over-indexing on something trivial that doesn't address the actual problem of technical quality. I would like to hear from the community about your thoughts on the tool and whether you have used other levers to maintain the technical quality for your team or your organization.