How Good Programmers Use AI as a Real Pair Partner: Spec-Driven Development Meets Socratic Inquiry
Or: Why "write me a function" is the worst prompt you will ever write
There is a running joke in the developer community: "AI wrote the code, but nobody knows what it does."
The punchline lands because it is true. Programmers everywhere are pasting vague prompts into chat windows, copying the output verbatim, and shipping it straight to production. The code appears. The tests pass. The bug report arrives three hours later.
This is not an AI problem. It is a workflow problem.
The developers who actually get better results with AI are not the ones who type faster. They are the ones who treat AI like a junior engineer — one who is brilliant, tireless, and has zero context — and structure their collaboration accordingly.
This article lays out a concrete workflow for that: Spec-Driven Development (SDD) combined with Socratic inquiry, anchored in real GitHub tooling and open-source patterns. If you have been using AI to code but feeling like something is off, this is probably what you have been missing.
The Core Problem: AI Amplifies Your Thinking, Not Your Silence
When you ask AI to "build a user auth system," you are doing the same thing as handing a blank sheet of paper to a contractor and saying "build me a house." You will get something. It might even look right. But you will not like the result.
AI is a pattern engine with no skin in the game. It does not know your codebase, your users, your constraints, or your trade-offs. It will confidently produce something wrong if you do not give it something to work with.
Good programmers know this. They use AI as a thinking partner, not a code vending machine. And the mechanism they use to do that is specification-first development — writing down what they want before they ask for it.
What Is Spec-Driven Development?
Spec-Driven Development is exactly what it sounds like: you write a specification first, then you write code. The spec is the source of truth, not the code.
GitHub is official spec tool (part of the instructor family) is built for exactly this. It lets you define structured specifications — JSON schemas, pydantic models, domain objects — and have AI generate code that conforms to those specs. More importantly, it gives you a contract to validate against.
Here is the basic idea:
from pydantic import BaseModel
from typing import Optional
import instructor
# Define the spec — this is your contract with the AI
class APIResponse(BaseModel):
success: bool
data: Optional[dict] = None
error: Optional[str] = None
retry_after: Optional[int] = None
# Now the AI must conform to this shape — no surprises
response = client.chat.completions.create(
model="gpt-4",
messages=[...],
response_model=APIResponse
)
The spec is not documentation. It is a machine-readable contract that forces you to think through the structure of your output before you ask for it. And that thinking — that specification discipline — is what separates developers who get great AI results from those who do not.
The Socratic Layer: Asking Better Questions
Writing specs is thinking. But sometimes you do not even know what the spec should be. That is where Socratic inquiry comes in.
Socratic questioning is not about getting answers — it is about examining assumptions. In the context of AI pair programming, it means using AI to stress-test your thinking before you commit to a direction.
Instead of:
"Write me a caching layer"
Try:
"What are the failure modes of a TTL-based cache in a distributed system? What happens when the cache node goes down during a write? Are there scenarios where cache invalidation is harder than just eating the latency?"
The difference is enormous. The first prompt gives you code. The second gives you model clarity — you understand the problem space better, which means your spec will be better, which means the code will be right.
Three Socratic Moves Every Developer Should Use with AI
1. The Assumption Challenge
Before specifying anything, ask: "What am I assuming that might not be true?"
"I am assuming Redis is a good fit for this use case. When would it not be? What alternatives should I consider?"
2. The Edge Case Probe
Before writing code, ask: "What is the most surprising thing that could happen here?"
"What is the strangest valid input this function could receive? What would break?"
3. The Reverse Engineer
Before implementing, ask: "If this were wrong, how would I know?"
"What test would fail if my pagination logic had an off-by-one error? Write that test first."
These questions cost you nothing. They take 30 seconds. And they routinely prevent hours of debugging.
The SDD + Socratic Workflow: A Practical Map
Here is the workflow I recommend for any non-trivial AI-assisted development task:
Phase 1: Clarify (Socratic)
- What problem am I actually solving?
- What are the constraints? (latency, scale, team size, existing stack)
- What could go wrong? What is the worst-case scenario?
- What does "done" actually look like?
Phase 2: Specify (SDD)
- Write a spec document or structured schema
- Define the input/output contract
- List acceptance criteria (not "it works," but what specifically works)
- Identify what you are not doing (scope boundary)
Phase 3: Generate (AI)
- Ask AI to produce code matching the spec
- Request multiple approaches if uncertain
- Ask AI to challenge its own solution
Phase 4: Validate
- Run the spec against the output (where tools like
instructorshine) - Write tests that match the acceptance criteria
- Code review as if a human wrote it (because the liability is still yours)
Phase 5: Reflect
- Did the spec accurately represent the problem?
- What did the AI miss? What did you miss in the spec?
- What would you do differently next time?
Key Checkpoints: When to Stop and Think
This is where developers lose the most time. Here are the critical junctions where you need to engage your brain, not just the AI:
| Checkpoint | Question to Ask | Red Flag |
|---|---|---|
| Before writing a single line | "Do I understand the problem domain?" | You cannot explain it to a non-engineer |
| After the first spec draft | "Does this spec have ambiguity?" | The AI gives two different interpretations |
| After code generation | "Would I pass a code review on this?" | You would reject it from a junior |
| Before integration | "What breaks if this service goes down?" | No answer or "it will just be slow" |
| Before shipping | "What would I do if this failed in production at 2am?" | No rollback plan |
AI is great at Phases 2 and 3. Phases 1, 4, and 5 are still on you.
Real Reference: GitHub Projects Worth Studying
If you want to see these patterns in action, a few open-source projects demonstrate spec-driven and AI-augmented development at a high level:
instructor — The GitHub-maintained tool that makes structured outputs (specs) first-class in Python LLM development. If you are doing AI-assisted coding in Python, start here.
Ponytail — A lightweight CLI framework for building AI-augmented command-line tools with structured spec handling. Demonstrates clean separation between specification and execution, which is exactly the pattern you want in your own AI workflows.
microsoft/playwright — Not AI-specific, but a masterclass in what happens when you have a very clear spec (cross-browser automation contract) and build everything around it. The discipline here is transferable.
sweepai/sweep — An AI coding assistant that practices what it preaches: it reads repo specs, breaks down tickets, and generates code. Worth studying as a reference implementation of SDD principles.
anthropics/anthropic-cookbook — Not spec-driven per se, but excellent patterns for structuring AI prompts and outputs in production codebases.
The Anti-Patterns (Do Not Do These)
Just as important as the workflow is knowing what not to do:
- Prompt dumping: Pasting 800 lines of code with "fix this bug"
- Unvalidated output: Running AI-generated SQL in production without review
- Missing scope boundary: Letting the AI expand the feature beyond what was asked
- No rollback plan: Shipping AI code with no way to undo it
- Treating the spec as optional: "I will just tell it in the prompt" — you will not, consistently
The Deeper Principle
Here is the uncomfortable truth: AI is not making you a better programmer. Your workflow is.
If you use AI to skip thinking, you will ship worse code than if you had never used it. If you use AI to accelerate thinking — to stress-test assumptions, explore edge cases, and validate your understanding — you will become dramatically more effective.
The programmers who will thrive in the AI era are not the ones who can write the most prompts per hour. They are the ones who know what they want, can specify it precisely, and know when to stop the AI and pick up the keyboard themselves.
Spec-Driven Development gives you the structure. Socratic inquiry gives you the depth. GitHub is tooling ecosystem gives you the leverage.
Use all three.
If you found this useful, the best next step is to pick one feature in your current project and rebuild it using the spec-first workflow. Not because the old way was wrong — but because you want to build the muscle before you need it in production.
Top comments (0)