Engineering

The Two Levers Every Tech Lead Needs: Solid Specs and a Dash of AI

Code Is Expensive. Specs Are Cheap.

10 PM on a Thursday. The feature is "done." 2,000 lines of beautiful, elegant code that solves a problem nobody actually had. All because of a misunderstanding in a Slack thread two weeks ago.

Code is the most expensive way to communicate an idea. It's rigid, slow to write, and even slower to change. Before we spend that cost, we owe it to ourselves to be clear about what we're building and why.

The best tool for this has always been the tech spec. And for years, developers have groaned at the mention of it. But there are two ways to fix that: make specs actually useful, and use AI to take the friction out of writing them.

Lever 1: The spec as a clarity engine

A tech spec isn't a novel. It's a map. It's a contract between product, engineering, and the future version of you who'll maintain this at 2 AM.

A spec that earns its keep covers:

  • Problem: What user pain are we solving? If you can't say it in two sentences, you aren't ready to code.
  • Goals: "Improve onboarding" is a wish. "Reduce first-24-hour drop-off by 15%" is a goal.
  • Non-Goals: What are we explicitly not doing? This section alone prevents half of all scope creep.
  • Proposed Solution: High-level technical approach. Which services, which endpoints, what data model.
  • Alternatives Considered: Why this approach and not another? This preempts 80% of review-cycle questions.

Every hour spent here saves ten hours of refactoring, debugging, and explaining later. It's the highest-leverage work an engineer can do.

The friction is real

Knowing this doesn't make the blank page any less intimidating. The pull to open the IDE and start coding is strong. Writing requires a different part of the brain. And that's where lever two comes in.

Lever 2: AI as spec-drafting assistant

AI won't write a perfect tech spec. Your domain knowledge and critical thinking are irreplaceable. But it can kill the blank-page problem and handle 80% of the boilerplate, so you focus on the 20% that needs your brain.

The workflow: dump raw, messy context (product brief, meeting notes, Slack thread) into the AI. Get a structured first draft back.

From messy notes to a coherent draft

Product manager sends this:

"Hey team, we need a 'refer a friend' feature. Users get a unique link to share. When someone signs up with that link, the original user gets 100 points. Need this for Q1. Use the existing PointsService. Make sure people can't refer themselves."

Normally, you'd schedule a meeting, ask for clarification, then painstakingly write a spec from scratch. Instead, feed it to a script:

import OpenAI from 'openai';
 
const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});
 
const rawProductRequest = `
Hey team, we need to add a 'refer a friend' feature. Users should get a unique link
they can share. When a new user signs up with that link, the original user gets 100
points. We need this for the Q1 launch. Should probably use the existing PointsService.
Oh, and make sure people can't just refer themselves.
`;
 
const systemPrompt = `
You are a principal software engineer creating a technical specification.
Convert a raw product request into a structured spec. Focus on edge cases,
system interactions, and clarifying questions.
 
Generate Markdown output:
 
# Tech Spec: [Feature Name]
## 1. Problem
## 2. Goals
## 3. Non-Goals
## 4. Proposed Solution
## 5. Key Questions & Edge Cases
`;
 
async function generateTechSpec() {
  console.log('Generating tech spec draft...');
  const response = await openai.chat.completions.create({
    model: 'gpt-4-turbo-preview',
    messages: [
      { role: 'system', content: systemPrompt },
      { role: 'user', content: rawProductRequest },
    ],
    temperature: 0.5,
  });
 
  console.log(response.choices[0].message.content);
}
 
generateTechSpec();

What you get back

# Tech Spec: User Referral Program
 
## 1. Problem
No built-in mechanism for word-of-mouth growth. Users who want to refer friends
have no way to do it and get rewarded.
 
## 2. Goals
- Existing users can generate a unique referral link.
- New user signs up via link → referrer gets 100 points.
- Ship by Q1 launch.
 
## 3. Non-Goals
- Referral tracking dashboard (simple point notification for V1).
- Tiered rewards or variable point values.
- Retroactive referral credits.
 
## 4. Proposed Solution
1. Extend UserService with `GET /users/me/referral-code`.
   Generate a unique, URL-friendly code; store in Users table.
2. Update `POST /users` to accept optional `referralCode`.
   Link new user to referrer if valid code provided.
3. On successful referral sign-up, emit `user.signedup.with.referral` event.
   PointsService listener credits 100 points to referrer.
 
## 5. Key Questions & Edge Cases
- Fraud: How to prevent fake-account self-referrals?
- Timing: Points on sign-up, or after first purchase?
- Expiration: Do referral codes expire?
- Attribution: Multiple links clicked → who gets credit?
- Schema: New `Referrals` table or just `referredById` on Users?

In seconds, you have a document that's 90% there. Structured, clear, and it already identified the critical edge cases that would have surfaced during a chaotic PR review.

The right workflow: augment, don't abdicate

The AI's output is a starting point. Your job is to correct its assumptions, answer its questions, and add the domain context that only you have. AI handles formatting and brainstorming. You handle strategy and validation.

Stop treating documentation as a tax on your time. With the right tools, it's an investment that pays for itself before you write a single line of code.