The spec is the code 📐

TL;DR: Greenfield does not start with code but with the specification. The specification is the source of truth that outlives the code, changing requirements, and team turnover. An agent that starts from a clear specification produces coherent code; an agent that starts from a vague idea produces vague code.

The greenfield paradox 🌱

Everyone wants to build the new project. It is every developer’s greatest temptation: zero technical debt, zero compromises, zero “why is it built this way?”. That is why greenfield is the use case where coding agents are used worst.

The classic scenario: open the terminal, ask the agent to “create a REST API for order management”, and wait. The agent produces 500 lines of working code. Working in the sense that it compiles, tests pass, the server starts. But inside there is latent architectural disorder: circular dependencies, incoherent patterns, a structure nobody wants to maintain.

The problem is not the code the agent writes. It is the code the agent does not know it should write because nobody told it what you really want.

The specification as a contract 📜

The specification is not a preliminary document to write and forget. It is the living contract of the project. It defines what the system must do (not how), who uses it, what scenarios it must support, and what criteria determine success.

When the specification is clear, the agent has a precise target. When it is vague, the agent guesses. And agents are very good at guessing — the problem is that they guess plausibly, not correctly.

The difference between “create an API for orders” and “create a REST API with GET/POST/PUT endpoints for order management, JWT authentication, rate limiting at 100 req/min, PostgreSQL persistence, and integration tests for all endpoints” is not the prompt length. It is the number of architectural decisions you made before delegating.

Specify → Clarify → Plan → Implement 🔁

The flow that works with agents is not “ask and receive.” It is a cycle:

1. Specify: write what you want the system to do. Objectives, users, scenarios, acceptance criteria.
2. Clarify: the agent asks questions about ambiguities. Do not brush off the questions: answer. Every unanswered question is an architectural assumption the agent will make for you.
3. Plan: the agent proposes architecture, modules, interfaces. Review before approving.
4. Implement: only after approval does the agent write code. In increments, with tests, with validation.

This is exactly what I explained in Planning before generating: planning is not an optional step. It is the moment where you prevent 90% of errors.

The specification outlives the code 💡

There is an aspect many underestimate: the specification has a longer life than the code. The code is rewritten, refactored, replaced. The specification remains as documentation of what the system was supposed to do. And when a new team member asks “why was it built this way?”, the specification answers.

In Greenfield from specification we explore the complete workflow: from writing the specification to the initial AGENTS.md, from the architectural plan to TDD as a pillar of implementation.

The specification is not a constraint: it is a liberation. It frees you from having to remember every architectural decision. It frees you from having to rewrite the code when requirements change. It frees you from having to explain to every new team member why things are built this way.

In practice 🔧

Some concrete rules for specifications that work with agents:

• Write the specification formally — not a Slack message, a document a colleague could read and understand.
• Define acceptance criteria — what does “working” mean? Green tests? Performance? Usability?
• Indicate constraints — what must NOT change? Existing APIs, data formats, dependencies.
• Update the specification when requirements change — an obsolete specification is worse than no specification.

The next time you start a new project, before opening the terminal, open a document. Write what you want. Then ask the agent to read it and tell you what it did not understand. Those questions are your first specification work.

And perhaps the most important lesson: specification is not the opposite of speed. It is its prerequisite. The better you specify, the less you rewrite. And the less you rewrite, the faster you are — despite all that time “spent” specifying.