AI Code Design should come before AI Code-Gen
Last year’s Stack Overflow survey was the first to ask about AI. Of the respondents, 70% were “using or are planning to use AI tools in their development process.” The 2024 survey just closed–who knows what that number will be now.
AI code generation allows engineers to code faster, debug quicker, and learn more.
But does it make them better engineers? Probably, no. Alongside higher usage rates in the 2024 survey, we’ll probably see higher disillusionment. AI code generation does work within a limited scope of the engineering role, but engineering != code generation. And code generation isn’t where engineers need AI help, nor where the strengths of AI are best applied.
The optimal role for AI is in technical design, and not as a replacement for human engineers, but as a thought partner, helping guide the process and augment the engineer's skills.
The Wins of AI Code Gen
Let’s not pretend AI code generation isn’t extremely valuable. It is, for precisely those reasons above.
It enables engineers to rapidly prototype, iterate, and explore alternate implementations with unprecedented speed and ease. By offloading repetitive, boilerplate coding tasks to AI, developers can focus on higher-level problem-solving and creative work, leading to faster project completion and more innovative solutions.
AI code generation is also a powerful learning tool for junior developers and those venturing into new languages or frameworks. Know Ruby and want to learn JS? Just let it walk you through your own Ruby code implemented in JS.
We can wrap all these ideas up in the nebulous concept of “productivity.” But the productivity here is first-order. Yes, you can create code faster, but that code sucks more often and needs to be refactored. Yes, you can iterate through ideas, but with no thought involved, the code generated leads you down dead-ends.
Relying too heavily on AI code generation can lead to a mountain of technical debt from shallow, one-off solutions that have been slapped together without considering the bigger picture. You end up with an increasingly unstable tower of code that becomes more precarious with every poorly considered addition. You lose control over the codebase, as no one fully understands what the code does because no one wrote it. Fixing issues becomes even more challenging, as engineers first need to decipher what's going on in the code.
It’s great to suggest that with AI code generation, “developers can focus on higher-level problem-solving and creative work,” but there are two problems with this thesis:
- It doesn’t if engineers are sucked back into the code by AI mistakes, and
- The core of engineering work is already focused on problems and creativity.
Thus, AI isn’t helping engineers where we need it. We need help further up the stack.
Writing Code Isn’t What Engineers Do, Reasoning Is
Here is Gergely Orosz summarizing the issue:
Do engineers write code? Yeah, sometimes. But it’s not like an engineer sits at their desk and types thousands of IF statements all day long (only ML engineers do that).
Engineering is about thinking. Reasoning. Literal ingenium. This, from the Charity Majors essay Orosz is referencing, is the truth:
“People act like writing code is the hard part of software. It is not. It never has been, it never will be. Writing code is the easiest part of software engineering, and it’s getting easier by the day. The hard parts are what you do with that code—operating it, understanding it, extending it, and governing it over its entire lifecycle.”
Yes, you have to build stuff–ship features, fix bugs, etc. But the value is in the understanding. That is what allows you to ship faster and learn more.
Understanding the problem domain, the users, and the requirements is where the real engineering work happens. It's about asking the right questions, breaking down complex problems into manageable pieces, and grokking them. This is where engineers spend the majority of their time and mental energy.
Code is just the manifestation of that understanding. It's the final step in a long process. And while writing code is an essential skill, it's not the defining characteristic of a great engineer. A great engineer can take a vague, ill-defined problem into a clear, well-structured solution.
Design is Reason Manifest
You reason in your head; you design on paper.
The “well-structured solution” is design, where an engineer has to elucidate their understanding of the problem and define it, first in words and then in code. This process is where all those engineering dollars go: designing elegant, maintainable solutions.
That’s the idea. The reality is that the pressures of delivering the product faster often lead to problems even at this phase, with poor design and fragile solutions.
Thus, this is where AI has the greatest utility. Technical design is critical but also a slow, manual process. Engineers need to ensure new features integrate correctly with existing code, consider edge cases and potential failure points, and create clear, comprehensive specifications for implementation.
So technical design becomes where engineers a) spend most of their time, and b) need the most help. It’s the hard part of software. What would an AI solution for technical design look like? At Agentic Labs, we see this workflow as the most compelling.
Connect
First, connect your codebase. This starts with the knowledge you already have. This is crucial because it allows the AI to learn from your current solutions and design patterns. By analyzing your repos, the AI gains a deep understanding of your existing features, architecture, and coding style.
Connecting your codebase is crucial. Without codebase context, the code generated by AI provides almost no value. It's only when you get a solution customized to your codebase that AI can then provide more valuable and context-specific assistance.
With this knowledge, AI can identify potential integration points, flag compatibility issues, and suggest ways to maintain consistency with your established practices. Additionally, by understanding what features you already have, AI can help you avoid redundancy and identify opportunities for reuse or refactoring.
Create
Second, use AI to draft an initial design doc. Once the AI has a solid grasp of your codebase, you can start the design process by providing a high-level, natural language goal or task description. The AI generates a comprehensive design document draft from this input, incorporating design best practices tailored to your specific context.
The generated design document includes all the essential components of a well-structured design:
- Context and scope: The AI clearly defines the problem space and the boundaries of the proposed solution.
- Goals and non-goals: It outlines what the design aims to achieve and what is explicitly out of scope.
- Diagrams: Visual representations of the design, such as flowcharts or architecture diagrams, are generated to aid understanding and communication.
- Integration details: It specifies how the new feature or component will integrate with existing code, including APIs, databases, and other dependencies.
- Code or pseudocode: The AI provides code snippets or pseudocode to illustrate key aspects of the proposed implementation.
- Constraints: The AI identifies any technical, performance, or resource constraints that must be considered in the design.
Unlike ChatGPT or Copilot, which would provide a generic example implementation, AI-assisted design tailors the solution to your specific codebase, needs, constraints, and goals. This is a significant advantage of connecting your codebase and leveraging AI for design.
This doc serves as a starting point for further refinement. An engineer can review the draft, add missing details, and make adjustments based on their deeper understanding of the problem domain. This iterative process ensures that the final design document is comprehensive, accurate, and aligned with your specific needs.
Converse
With your design doc draft in place, you can chat with an AI thought partner. The AI helps do the above–helping you flesh out details, consider alternative approaches, and explore potential trade-offs.
You can challenge assumptions, ask probing questions, and gain additional insights through this conversation. The AI can provide real-time feedback, suggest optimizations, and help you build confidence in the proposed solution. This iterative process of discussion and refinement leads to a more robust, well-considered design.
Collaborate
Then, you can collaborate with your team. In-built commenting functionality, providing a collaborative experience similar to what you're used to with Google Docs, the tool most teams currently use for creating design documents.
At that point, you can generate your code using that design doc as the prompt or manually for quicker, better code.
This workflow allows engineers to focus on high-level problem-solving and creativity. It is a workflow designed around precisely that but aided by AI. AI handles repetitive tasks, provides intelligent suggestions, and builds out the document; the engineer reasons and designs.
Building Better Engineers Through Better Design
One of the purported reasons for AI code generation in the SO survey is learning. But what are they learning?
With AI integrated into technical design, they are learning the core element of engineering. They are learning not just "code" but how code works, how development processes evolve, and how engineering decisions are made.
By engaging with AI-assisted design, engineers gain a deeper understanding of the reasoning behind design choices. They learn to consider the broader context, weigh trade-offs, and anticipate potential issues. This exposure to best practices and design principles helps them develop a more strategic, design-oriented mindset.
AI-assisted design isn't just about creating better code; it's about nurturing better engineers. By emphasizing the critical thinking and collaboration aspects of design, this approach helps engineers grow technically and professionally. They become not just skilled coders but adept problem-solvers and actual engineers.
They also become more joyful coders. Coding is a fun part of this. You can use design docs to plug into a coding agent to write the code for you. But you can also use it as a helpful guide and do it yourself. The structure and reduced risk lead to a much more enjoyable programming experience.
We're building this at Agentic Labs. If you’re interested in using AI-assisted technical design in your engineering team or in helping us build these tools for engineers, then reach out to us to book a call.