I Gave Claude a Spec and Walked Away. What Shipped Was Production Code.

There's a version of "using AI for code" that most technical leaders have tried: paste in a function, ask Claude (in this example, I chose Claude) to fix a bug, maybe generate a boilerplate class. It's useful. It saves minutes. It's also roughly equivalent to hiring a staff engineer and having them only sharpen your pencils.

I did the spec based AI engineering. And the results makes us quietly rethink what a software team looks like in three years.

The Setup

I had a greenfield project: a new platform for orchestrating data pipelines across infrastructure — multi-tenant, event-driven, with a polyglot persistence layer (Postgres, Redis, S3), a gRPC API surface, and a React frontend. Roughly the kind of thing that would take a strong team of four engineers about four months to get to a credible v1.

I chose different.

Instead of using AI as an autocomplete layer inside IDE, I restructured the entire development workflow around it. Claude became the primary code author. I became the specification writer, reviewer, and systems thinker.

What "Spec-First, Claude-Second" Actually Means

The workflow sounds simple. It wasn't — at first.

I wrote exhaustive specs. Not user stories. Not JIRA tickets. Architectural specifications: data flow diagrams described in structured prose, interface contracts, failure mode inventories, explicit invariants the system had to maintain. Every time I wrote a vague sentence, Claude would ask a clarifying question or — more interestingly — make an architectural decision and state it explicitly in comments so I could review it.

Example: I specced a job-scheduling subsystem with soft real-time constraints and asked Claude to implement it. It generated a working implementation, but then added an unprompted comment block:

// NOTE: This implementation uses a min-heap with a polling loop at 250ms resolution.
// For sub-100ms latency guarantees, this boundary condition in tick() will drift under load.
// Recommend replacing with a dedicated timer wheel if SLA tightens below 500ms.
// See: Varghese & Lauck (1987) for reference implementation pattern.        

It caught a constraint I hadn't fully articulated. It flagged the architectural decision it made, explained the tradeoff, and cited a 37-year-old systems paper from memory.

That happened more than once.

Cross-File Coherence at Scale: The Hard Part

Anyone who has used LLMs for more than toy examples knows the real problem: context collapse. The model writes a beautiful module in isolation, and then it's incoherent with the rest of the system. Variable naming drifts. Patterns diverge. The left hand doesn't know what the right hand wrote.

I solved this with what I started calling a living architecture document — a single, continuously updated markdown file that served as Claude's persistent memory across sessions. Every interface, every enum value, every naming convention, every architectural decision was written into it. Before every Claude session, I'd load this document into context. After every session, I'd update it with what changed.

It was like giving a brilliant contractor a day-one onboarding document every morning — except the contractor could read and internalize a 6,000-word document in seconds and apply it perfectly.

The result: cross-file coherence that rivaled what a human engineer produces after six months on a codebase.

Error types were consistent. The gRPC service definitions matched the handler implementations matched the client-side TypeScript types. When I introduced a new abstraction, I added it to the architecture doc, and Claude propagated it correctly across the affected subsystem.

The Numbers

Let's be concrete, because "I shipped faster" is not a technical claim.

• Lines of production code written by Claude: ~73% (measured by authorship in git blame across non-test files)
• Projected time to functional v1: 5.5 weeks (vs. 16-week estimate for a conventional team of 4)
• Post-launch defect rate in Claude-authored code: statistically indistinguishable from engineer-authored code
• Architectural issues caught by Claude proactively, before review: 11 distinct cases — ranging from subtle race conditions to a missing index that would have caused table scans at scale

The last metric is the one that keeps coming up in our post-mortems. Claude wasn't just a code typist. It was surfacing correctness concerns that require deep systems understanding to even notice.

What Broke (Honestly)

This isn't a success story with no asterisks. Here's what actually failed or required human intervention:

1. Integration test strategy was under-specced, and Claude's tests were optimistic. Unit tests were excellent. Integration tests tended to mock too aggressively — testing the mock, not the system. I had to explicitly specify boundary conditions for each integration test or Claude would write the happy path.

2. Domain logic that required business context was wrong — and confidently wrong. There were two places where Claude made a reasonable-sounding implementation decision that was incorrect for the specific domain. It had no way to know the business rules I hadn't written down. This is the hardest failure mode: wrong, but plausible.

3. Refactoring large subsystems mid-flight was chaotic. Once a component exceeded a certain complexity, asking Claude to refactor it in a single session produced regressions. I learned to break refactors into layered, sequential passes with explicit intermediate state descriptions.

The Deeper Realization

I wasn't doing less work. I was doing fundamentally different work. Instead of writing code, I was specifying systems. Instead of debugging syntax, I was reasoning about architecture and invariants. Instead of writing the implementation, I was reviewing it — which is a higher-leverage act.

This is not "AI replacing engineers." It is something more subtle and more significant: AI compressing the implementation layer so that engineering talent concentrates at the design and verification layer.

The scarcest resource in software was never typing speed. It was the ability to hold a complex system in your head and reason about it clearly. AI can now handle a significant portion of the implementation load with enough specification fidelity. What it can't do — yet — is originate the system design, understand the business constraints, or take accountability for the tradeoffs.

That's what engineers are now for.

What This Means for Technical Leaders

If you are building a team right now, some uncomfortable questions deserve direct answers:

Headcount: The output leverage per engineer is meaningfully higher than it was 18 months ago. If you're staffing a greenfield build the same way you staffed one in 2022, you're either over-staffed or under-shipping. Neither is acceptable.

Hiring profile: The gap between an engineer who can write precise specifications and one who can't is widening fast. Specification clarity — the ability to write down exactly what a system must do and must not do — is becoming the primary differentiator. This looks more like technical writing than it does like coding.

Process: Greenfield projects are uniquely well-suited to this workflow. Legacy codebases with poor documentation are currently hard (but read my other article on this). That will change.

Risk: The confidence calibration failure mode is real. Claude will write plausible, wrong code if your specifications are ambiguous. The solution is better specifications, not less Claude. The investment in precise specs pays dividends whether you use AI or not.

The Aperture

We are at an early and extremely awkward moment. The tooling is immature. The workflows are being invented in real time. The mental models most engineering orgs operate with are six months out of date.

But the signal is clear: the ceiling on what a small, high-leverage team can ship has moved. It has moved enough that it changes the math on startups, on internal tooling, on moonshot projects that previously required headcount you couldn't justify.

I don't know exactly what software development looks like in three years. I'm fairly confident it doesn't look like it does today.

The teams figuring that out now will have a meaningful head start.

Interested in the specifics of the spec-writing workflow, the architecture document structure, or the session management approach? Drop a comment — happy to share it.