software engineering / system design / technical design docs / career / claude code / cursor
Technical Design Doc Template: The 8 Sections I Write Without AI
How I write a technical design document the old-school way, before any AI touches it. If you are a computer science student or a new grad who leans on Cursor and Claude Code without reading much of the code, this is the part of the job that keeps you employed at a big tech company.
First, I make sure I understand what the task actually is, in plain words rather than jargon; if I cannot explain it to my 13-year-old niece with a metaphor, I do not understand it yet. Second, I work out the trade-offs, such as performance against maintainability, and whether the design should be a synchronous process or an async one with workers. Third, and most important, I learn the technologies my company already uses, because a design built on BigQuery at a Snowflake company makes no sense. Then I copy a teammate's existing design doc template exactly: problem statement, goals and non-goals, high-level architecture, technologies, low-level design, considered alternatives, privacy and security, and the rollout plan. Finally I read it over, check that it solves the right problem, and make sure I have two or three real alternatives before picking the best one.
Transcript
0:00So I made over $400,000 right after I graduated and here's how I learned how to create strong
0:04technical design documents.
0:06And if you're a computer science student who wants to learn how to actually navigate
0:09big tech, particularly if you use tools like Cursor and Claude Code, and you're not really
0:14focusing on reading all the code all that much, then please stop and save this video.
0:19Otherwise, you're going to get fired for your first job out of college.
0:23Step 1, I make sure I understand what the task actually is. Not in terms of technical jargon, but what are we actually doing?
0:30Like if I can't explain what we're doing using metaphors to my 13 year old niece, then I have no idea what the task actually is.
0:37Once I understand what the task actually is, then I can understand what trade-offs
0:41am I likely to make, right? Do I want the code to be extremely performant? Do I want
0:46the code to be highly maintainable? What are the trade-offs I'm going to make?
0:49That helps me decide, you know, what the design should look like. It is going to
0:53be a synchronous process, an async process with some workers. I need to
0:57understand the actual requirements so I can build the best system I can.
1:01Number three, and this is most important,
1:03I need to make sure I understand the technologies
1:05that my company is actually using, right?
1:07I mean, if I go out and design something using BigQuery
1:10when a company is using Snowflake,
1:11that's not gonna make any sense, right?
1:13So I need to make sure I understand
1:14the specific technologies my company is using
1:17to solve some of the most common engineering challenges
1:19that I'm going to encounter.
1:20Then, and only then, will I copy-paste everything in the Claude Code and tell it to create a technical design document.
1:25I'm just kidding, so what I'm going to do is take a template of someone else's existing technical design document, then I'm going to try to copy that template exactly.
1:32Usually these documents are formatted with the first part being a problem statement, the second part being a list of goals and non-goals.
1:38The next part being a high-level architecture.
1:40The next part being what technologies I plan to use.
1:43Then things such as the low-level design, the considered alternatives, any privacy and security recommendations, the rollout plan,
1:49And again, almost all of this should exist within some template that your company is giving you.
1:54If there's no template, that's kind of weird.
1:56I guess you can Google it, but like, I'd be very shocked if you don't have a template.
2:00Afterwards, I read it over, understand it, and then I try to make sure, did I really implement the right solution?
2:05Did I really propose the thing I need to do?
2:07Are any of my considered alternatives better?
2:09I want at least two to three considered alternatives, and to really think about which one is best for what I'm trying to accomplish.
2:17Now this is the old school way of creating a technical design document without AI. Let me know if you want a part 2 where I can explain how to create it with AI.
Join the conversation
Loading conversation…