The AI-Era Greenfield Playbook

The AI-Era Greenfield Playbook

Six months ago I started a new project from scratch knowing that AI agents would be doing most of the coding. Not assisting — doing most of it. The question wasn't whether to use them. It was how to structure everything so the output was actually good.

There's a lot of noise about this. "AI will replace developers." "AI is just autocomplete." Both miss the real story, which is more interesting and more operational: AI agents have made some problems much easier and introduced a completely different set of failure modes. The playbook for a new project has changed materially. Here's what's working.

---

The spec is the product

This is the single most important shift in how I think about greenfield projects now.

Before AI agents, a rough spec was fine. A Jira ticket with three bullet points was enough to orient a developer. They could ask clarifying questions, make reasonable judgments, fill in the gaps from context.

Agents don't do that. They fill in gaps with plausible-looking code that implements something adjacent to what you wanted. The output is syntactically clean, the tests pass, and three weeks later you're debugging behavior that is technically "correct" given the spec — which just wasn't the right spec.

A good spec for agent consumption is different from a traditional PRD:

Behavioral, not architectural. Describe what the system does (inputs, outputs, invariants), not how it does it. Let the agent make implementation choices within your constraints. If you dictate implementation, you're just writing code by proxy.

Constraint-explicit. Technology choices, performance requirements, security requirements — state them. An agent won't infer "this needs to handle 10k requests/second" from surrounding context.

Scope-bounded. "Implement the user system" is not a spec. "Implement JWT authentication with 1-hour access tokens, 7-day refresh tokens in httpOnly cookies, three specific endpoints, bcrypt password hashing" is a spec.

Test-anchored. The best specs include acceptance criteria written as testable statements. Write the tests before the agent writes the implementation. A failing test that the agent must make pass is the strongest spec enforcement mechanism available.

Size tasks to one PR. If a spec implies changes to more than three or four files, split it. An agent that loses the thread mid-task produces worse output than two agents each completing a smaller, scoped task cleanly.

A solid spec takes 30–45 minutes for a medium feature. That time isn't overhead — it is the engineering work. The implementation is what used to take days and now takes 20 minutes.

---

Your job title changed

You are an architect now. Not an implementer.

The job is design, specify, review. Everything else is agent work.

This sounds appealing until you're actually doing it. The cognitive weight of implementation is gone, but it's replaced by a different weight: you have to be right at the design level, because the agents will implement exactly what you describe, faithfully and fast. A wrong architecture decision that previously took a week to manifest in code now manifests in hours.

The framework I've settled into: delegate, review, own.

• Delegate mechanical work — boilerplate, scaffolding, test generation, refactoring to a pattern, documentation
• Review all agent output — does it match the spec? Is the logic correct? Does it introduce security issues?
• Own everything that can't be undone — architecture, product direction, security posture, external API contracts

The honest constraint: one hour of agent implementation typically requires 30–60 minutes of human review. If you're merging faster than you can actually review, technical debt is accumulating invisibly. The temptation is strong — the tests pass, the code looks right. That's exactly how it gets away from you.

---

Structure the repo for a reader with no memory

The primary reader of your codebase is now an AI agent that starts every session with zero context. It doesn't remember yesterday. It doesn't know what you were thinking when you named that module. It reads what's there.

Two structural decisions that matter more than anything else:

Go monorepo. AI agents are repo-scoped. A monorepo gives them cross-service visibility without extra context injection. They can see that two services share a contract without you explaining it. I've watched teams that were committed polyrepo shops reverse course in the last 18 months.

Write the orientation file. A root CLAUDE.md (or AGENTS.md — same concept) is the highest-leverage file in the codebase. An agent reading it should know: what the system does, the service topology, where to make any given type of change, the tech stack, and what it is not allowed to touch. Keep it under 500 lines. Agents start ignoring the bottom half of long instruction files.

Supporting structural choices that compound the benefit:

• Define types before implementing anything — agents stop hallucinating field names when there's a canonical source of truth
• Co-locate tests (next to the file, not in a separate __tests__/ tree)
• Flat beats deep — deeply nested structures eat context window on path traversal
• Delete dead code aggressively — agents trained on a codebase with dead code generate more dead code

---

The loop that actually works

Forget sprints. Sprints were designed for synchronous teams where human throughput was the bottleneck. It isn't anymore.

The replacement is a continuous spec-driven loop:

SPECIFY (~30 min per feature)
  Write spec. Define acceptance criteria as tests. Break into agent tasks.
    ↓
IMPLEMENT (~5–30 min, agent)
  Agent picks up task. Generates code + tests + docs. Opens draft PR.
    ↓
REVIEW (~30–60 min, human)
  Check against spec. Check security. Check test coverage quality.
    ↓
VALIDATE (automated CI)
  Type check. Unit tests. Integration tests. Acceptance tests.
  All must pass before merge.
    ↓
MERGE + SHIP

Cycle time for a small-to-medium feature: 2–4 hours end-to-end including review. A solo developer running this loop cleanly can turn out 3–5 production-ready features per week.

CI is not optional and not just hygiene. It's the mechanical safety net for spec drift. The bugs agents characteristically introduce aren't syntax errors — they're locally-correct logic that fails on boundary conditions, and confident refactors that silently break a contract two services away. That's the class CI has to catch, because reading the code in review won't.

---

Anti-patterns that will sink you

Starting without a spec. The most common failure, by a large margin. Everything in the first section is the fix; skipping it is the single most reliable way to sink a project.

Vibe-reviewing PRs. "Tests pass, code looks right, ship it." Review against the spec explicitly: "Does this implement what the spec says?" — not "Does this code look right?"

Tool sprawl. Running three or four AI coding tools simultaneously fragments your context conventions. Each tool has different instruction files, different mental models, different configuration overhead. Pick two, get good at them.

Skipping the simplification pass. AI generates working code on the first pass. It rarely generates clean code. Set a recurring weekly block — 2 hours per active project — to simplify without changing behavior. Without this, AI-authored codebases become as hard to navigate as any legacy system, except they have no institutional memory.

Security blind spots. Agents are systematically weak at reasoning about security in the context of the whole system. They see the function they're writing, not the trust boundary they're crossing. Any code that handles user input, authentication tokens, or external API responses needs explicit human security review. No exceptions.

Letting sessions run too long. The inverse of cold-start. A long agent session accumulates stale context — far enough in, the agent starts contradicting decisions it made at the start, reverting its own changes, reintroducing bugs you already fixed. One PR per session. Start every session with a fresh orientation file. Write a short session-summary capturing key decisions so the next session inherits them instead of rediscovering them.

---

The solo numbers

If you're running this alone — one person, multiple products — here's what's realistic:

3–5 production-ready features per week on a well-maintained codebase with good specs. The ceiling is your spec quality and review capacity, not agent speed. If you're not hitting that rate, the bottleneck is almost always unclear specs or review discipline.

The economics are stark. The full AI tool stack — autonomous agents, interactive IDE, hosting, task tracking — runs $360–860/month at heavy usage. One junior engineer at market rate costs more than that annually. The stack gives you comparable throughput on well-specified work at roughly 5–10% of the cost.

Where hiring still makes sense: you're spending 4+ hours per day on review (agents are outrunning you), or you need continuous judgment in a specialist domain that agents handle unreliably. Security, payments, regulatory compliance — agents are systematically bad at these because they require deep contextual judgment, not pattern matching.

---

What doesn't change

All of this is new tooling. The fundamentals didn't change:

Architecture is still the one thing that can't be delegated. If you don't design the system, agents will implement a tangled mess that is locally coherent and globally incoherent. Nobody designed it, so nobody understands it.

Human review is still mandatory. The best AI-assisted PR review tools hit 84% detection recall — useful signal, not a replacement for judgment. Every PR needs human eyes before it ships.

Deterministic CI is still the safety net. The spec says X. The agent ships Y. CI is how you detect that mechanically.

What changed is where your time goes. You're not writing the code. You're writing the spec, reviewing the output, and owning the architecture. That's the whole job now.

One caveat worth stating plainly: this playbook assumes you already have working engineering process — specs, CI, review discipline. Agents accelerate what's already working. They don't fix what isn't. Drop agents onto a team with no CI and no review culture and you amplify the dysfunction, faster.

If you've been in software long enough to remember when the move from manual testing to CI felt like a shift in what engineering actually was — this is another one of those moments.

---

Quick Reference

The full post is the reasoning. This is the checklist.

Repo setup (once)

• Monorepo
• Orientation file at the root (CLAUDE.md / AGENTS.md) — under 500 lines
• All shared types defined in one place before any implementation starts
• Tests co-located next to source files, not in a separate tree
• No dead code — delete aggressively and keep it deleted

Every feature

• Spec before any agent touches the codebase — behavioral, constraint-explicit, scope-bounded
• Acceptance criteria written as failing tests before implementation begins
• Tasks sized to one PR (if the spec implies more than 3–4 files, split it)

Every PR

• Human review against the spec: "Does this implement what the spec says?" — not just "does it look right?"
• All CI gates must pass: type check, unit tests, integration tests, acceptance tests
• Any code touching user input, auth tokens, or external API responses: explicit security review, no exceptions

Every week

• 2-hour simplification pass per active project — agents run it, humans review the result
• One PR per session — never let a single agent session run long enough to accumulate context rot

Hiring threshold

• Spending 4+ hours/day on review → agents are outrunning you, hire a reviewer
• Specialist domain (security, payments, compliance) that agents handle unreliably → hire a contractor
• Below that threshold: the tool stack is cheaper than a junior hire at comparable throughput on well-specified work