When you delegate implementation to an agent, you also give up some of the learning that happens as you build: discovering dependencies, edge cases and missing requirements. Writing a short technical design document helps you explore these upfront and record the decisions you’ll use to evaluate the agent’s work.
Implementation is also investigation
Peter Naur described programming as “the programmers building up knowledge of a certain kind” in Programming as Theory Building (1985). That knowledge includes why the code is written the way it is and how it should change when the problem changes. Naur treats documentation as a supporting record. Engineers build understanding by working through the problem.
Fig. 1: An engineer works through a problem as the solution materializes
Writing code helps engineers build that understanding. An engineer might discover an unexpected dependency while working on the data model or realise that nobody has decided what should happen in an edge case (Figure 1).
When an agent writes the code, the engineer gives instructions and reviews the result while the agent works through those details (Figure 2). Engineers need to make time to investigate the problem themselves for their understanding to keep up.
Fig. 2: An engineer guides an agent and reviews the code as the agent chips away at the problem
Why understanding matters
Addy Osmani describes a limitation of code review in Comprehension Debt:
The organizational assumption that reviewed code is understood code no longer holds.
As comprehension debt grows, the team may know what the business needs, but no longer understand how to make the software do it. It becomes harder to work out what needs to change and what else will be affected. The team may become increasingly dependent on agents while losing its ability to judge the tradeoffs in their proposals. Shared understanding helps people investigate incidents, adapt the system as the business changes and take over when colleagues leave.
For example, an agent implements retries for failed payment requests. The tests pass: failed requests are retried on schedule. But what happens when the provider charges the customer and the connection drops before the application receives confirmation? Does the order remain pending, get marked as failed, or trigger another payment attempt?
Resolving those questions requires understanding the payment flow and deciding what the business should do when the outcome is uncertain. If nobody investigates them, an agent might quietly settle a policy that nobody consciously chose.1
The business must also decide how long fulfilment should wait for confirmation, what the customer is told and when support should intervene.
Working through a technical design document can lead to clearer data models and simpler solutions. When the design makes invalid states impossible to represent and removes unnecessary interactions, fewer cases need testing.
Understanding also helps target those tests. Someone who understands the payment flow can simulate a lost confirmation and check that the order recovers once the provider’s payment status becomes available. Retries can run on schedule while the order remains stuck.
Technical design can also expose unanswered product questions. Engineers will bring these back to product and design, along with the options and their consequences.
Guide with technical design
Before delegating implementation, work through a short technical design document. Use it to investigate the problem, discuss open questions with product and design and record the chosen approach and its tradeoffs. Give that context to the agent (Figure 3), then use your understanding of the design to evaluate its implementation.
Fig. 3: The engineer develops understanding through technical design documents before handing implementation to an agent
Use the document when a change leaves important behaviour or tradeoffs unresolved. A small, well-understood change may need only a few sentences. Some questions need a prototype or a sandbox experiment before you can make a decision.
Collaborate across engineering and product
Many developers were writing technical design documents long before LLMs and already benefit from the practice. It is not universal, though.
Sharing the document with product and design gives everyone something concrete to discuss and a place to write down answers and decisions. Much of that discussion can happen in comments, leaving less to cover in refinement meetings.
When someone revisits the code, the document explains why the team chose this approach. An agent can use it for the same reason.
Keep the document simple
- Start small. Start with a problem statement, add context and list the questions that need answers.
- Write the core reasoning yourself. Use AI for search, investigation and exploring alternatives, but work through the findings and explain the decisions in your own words. Writing is part of building understanding. Put long supporting material, including AI output, in a linked appendix if needed.
- Include detail that helps resolve a question or explain a decision. Full endpoint specifications belong in the repository. A design document may only need a brief description of the interaction. Think about the reader.
- Keep it as a decision record. Once the approach is agreed, keep the document as a record of what was decided and why at that time.
For example, a team adding payment by bank to a web checkout might start with this draft:
Suppose the team decides that an order should remain awaiting confirmation when the payment outcome is unknown. We don’t know whether the payment failed, so we shouldn’t tell the customer it did. Keeping it pending requires a way to recover the payment status and a decision about how long to reserve stock. The engineer or agent would need to check the provider’s recovery options and record the findings in the document.
These decisions describe how the payment flow should behave: a lost confirmation leaves the order awaiting confirmation, a duplicate confirmation does not trigger fulfilment twice and a late payment follows the agreed stock and refund policy. The agent can use these cases to guide implementation and testing.
If implementation uncovers something the design did not account for, return to the discussion (Figure 4).
Fig. 4: The design guides implementation. The dotted arrow shows an optional return to the discussion
For your next feature, consider starting a technical design document with a problem statement, context and one question you cannot yet answer. Investigate it, then write down the decision and its consequences in your own words. Use that understanding to guide the agent and judge the result.
Example here is fairly common for easier understanding in the blog post. LLMs would probably ask operator for confirmation in plan mode. ↩︎