Caveat: This is how I operate at a big tech company. This would look different at a startup and vastly different if I was just building by myself. At a large company there is definitely a coordination tax you need to pay, and that seeps into how you build.
1. Build a Mental Model - Understand
I usually spend the first couple of days just building context. I use an LLM to explore the codebases this might touch, read the PRDs, and understand how the project fits into the existing ecosystem. The goal is to build a strong mental model of what is already there and how well it is working. From there, I start figuring out which services we can extend, what might need to be new, and reaching out to the owners of the services that we might be extending.
I will then write a couple of different design docs for the proposal. One high-level doc for the business that focuses on the why, and one low-level doc for the engineering team that focuses on the how.
2. High-Level Doc - Align
For the high-level doc, the audience is generally very senior engineers/PMs, directors, and VPs. They are either technical or used to be technical, but the common denominator is that they have a million things on their plate. You are communicating the what and the why, so the core idea needs to be memorable.
Historically, this might have been a detailed powerpoint or a concise Google Doc. What I have been doing lately is writing everything in markdown and then having an LLM convert it into an HTML/CSS/JS presentation. The front of each slide stays high level, but clicking it reveals a back side with underlying details.
Definitely have an LLM make the architecture and sequence diagrams. If something is confusing, make the diagram interactive. LLMs are really good at this. If I really need management buy-in, I would prototype a demo that shows what the final result could look/feel like and link to it.
3. Low-Level Doc - De-Risk
For the low-level doc, the audience is whoever will be doing the implementation. Historically this meant engineering teammates, but these days it means agents too. Since people can use LLMs to ask what something means, I generally keep this doc pretty technical. If part of a feature is ambiguous or hard to reverse, I will usually include a few options and do a spike on each one before deciding which direction to commit to. This doc will be full of pseudocode snippets and links to the services and files that the implementation will touch.
By the end of the document, there should be a very clear answer for how we will address each of the "whys" from the high-level doc, what metrics we will use to measure the success of the rollout, and how the project will be released in stages that build on top of each other.
For key architecture decisions, I usually evaluate the options across a few dimensions:
- Scalability: What happens at 10–100x the current load? What happens if 40 engineers are contributing instead of 4?
- Reversibility: How painful will it be to change this decision later?
- Ownership: Who is actually going to own and operate this system? Do they have the bandwidth and track record to maintain it well?
- Ability to reuse existing interfaces: Can we reuse something that already exists, or are we introducing a new boundary?
- Verifiability: How easy is it to prove that this system is working correctly? Can we test it, observe it, and quickly tell when something is wrong?
- Cost: What does this cost us now? What will it cost us as we scale?
Some examples of this might be:
- "Should we spin up a starrocks instance or reuse our existing postgres instance?"
- "Does this existing microservice meet our TPS and latency standards, or should we build our own service for this functionality?"
- "Is there an MCP an agent can use to read data from this analytics warehouse?"
4. Execute in Stages - Execute
Generally I like to build towards a final solution and not just one shot it, even though it is tempting to do that with AI. I think you should still deliver something in stepping stones, or else it might turn into a skunkworks project that is always 2 weeks from being done.
There is some version of the project you can ship in 2 weeks, another in 2 months, and another in 6 months. Build towards those. Every two weeks you should be at a point where you have something worth demoing.
5. Shipping Means More Than Releasing to Prod - Validate & Iterate
Something isn't shipped when it is released to prod. It needs to have:
- Clear verification loops
- Success metrics
- Observability and monitoring
- Analytics
- Rollout, adoption, and awareness (from users and the org)
So my basic loop is: understand, align, de-risk, execute, validate, iterate.