AI coding agents generate production code, write test suites, and review pull requests with enough accuracy that most engineering teams trust the output for a meaningful share of their implementation work.
The downstream side of the development lifecycle, everything after the decision of what to build and how, got dramatically faster this year. The upstream side barely moved.
Software design documents, the artifacts where feasibility analysis, service boundaries, dependency mapping, and implementation approach get captured, still depend entirely on one or two senior engineers who carry the system's mental model. That work consumes 60 to 70% of their time, and the entire team queues behind them before a single line of code gets written.
The pre-coding bottleneck that AI skipped over
Every new feature follows the same sequence. Someone creates a Jira ticket. A senior engineer or architect reads it and starts answering the hard questions.
- Can this be built on top of our current service topology?
- Which downstream consumers will break if we change this data flow?
- What implementation approach fits the patterns we already have in production?
- Where did we try something similar before and what went wrong?
Those answers require system level context that spans repositories, past incidents, architectural decisions made years ago, and tribal knowledge that lives in very few heads.
Writing a software design document that captures all of this takes a full day or more, and the person qualified to write it is the same person every other team is waiting on for their feature too.
The coding agent sitting downstream is ready to generate code the moment it receives a clear, grounded input. The bottleneck is producing that input. The bottleneck is the software design document.
What makes this bottleneck so persistent
Coding agents operate well within a bounded scope. Give an agent a file, a function signature, a clear specification, and it produces strong output.
Pre-coding work requires the opposite of bounded scope. It requires understanding how dozens of services interact, what operational patterns have failed before, which APIs are deprecated, and what constraints the business layer imposes on the technical design.
That understanding lives in the heads of senior engineers who built or maintained the system over years. When those engineers are available, they produce the software design document and the team moves forward. When they are pulled into another project, on vacation, or have left the company, the team either waits or builds on assumptions that surface as rework three weeks into implementation.
The persistence of this bottleneck comes from the nature of the knowledge itself. System level context resists documentation because it changes constantly. Services get added, dependencies shift, incident patterns evolve.
A software design document written six months ago may reference an architecture that no longer exists. The person writing the document needs live, current understanding of the system, and that understanding refreshes through daily exposure to the codebase and its operational behavior.
Why this matters more now than it did two years ago
Two years ago, the pre-coding phase and the coding phase moved at roughly the same speed. Both were manual, both depended on senior engineering time, and both took days. The ratio between planning and execution was close to balanced.
AI compressed the coding phase from days to hours. The planning phase stayed the same. That compression exposed a ratio that was always there but never felt urgent. When coding took a week and planning took three days, the planning overhead felt proportional. When coding takes an afternoon and planning still takes three days, the planning phase becomes the dominant cost of every feature.
Senior engineers now spend the vast majority of their time on work that happens before the coding agent receives its first prompt. Feasibility analysis, technical design, cross-repo impact assessment, and scope breakdown. The software design document that captures this work is the single highest leverage artifact in the entire workflow, because it determines the quality of everything the coding agent produces downstream.
For teams looking to structure this artifact well, Bito published a comprehensive guide to software design documents that walks through the sections, templates, and practices that make a design doc usable for both engineers and AI agents.
The upstream layer is starting to move
One approach I have seen work is AI Architect in Jira from Bito, which generates software design documents directly from epics and stories before anyone writes a line of code. It builds a knowledge graph of the entire codebase and operational history from past Jira tickets, then runs feasibility analysis, technical design, impact assessment, and scope breakdown against it. The output posts as a structured planning artifact directly in the Jira ticket.
The senior engineer who used to spend a full day producing that artifact now reviews a grounded first draft instead of starting from scratch. Their time shifts from context gathering to the architectural decisions that actually require their judgment.
AI made the coding layer fast. The quality of that speed depends entirely on the quality of the thinking that precedes it. Software design documents capture that thinking, and they are finally getting the same AI treatment that code generation and code review received over the last two years.
Top comments (0)