Greenfield project from a specification 🌱

A greenfield project is the greatest temptation and the highest risk. The agent can generate hundreds of lines of code in seconds — but if you do not have a clear specification, you will get hundreds of lines of wrong code in seconds. The difference between a successful greenfield and an architectural disaster is not the tool: it is the quality of the specification you put in front of it.

The specification is not a preliminary step: it is the contract that outlives the code.

When to use the agent for this case 🎯

• Completely new project — no existing code, stack to define.
• Rapid prototype from spec — you have a requirements document and want a working MVP.
• Initial scaffolding — project structure, README, CI, base tests.
• Complete rewrite — rewriting a legacy system as a new project from scratch.

When NOT to use the agent ⛔

• You do not have a specification — if the idea is vague, do not delegate the definition to the agent. Write what you want first, then ask how to do it.
• The stack is critical and undefined — the agent will choose the most common solution, not the best one for your case.
• The project requires hardware or physical integration — the agent cannot test what does not exist in its environment.

Opening prompt 📝

“Starting from this specification [link/block], build [project]. Stack: [x]. Constraints: [y]. Process: plan first, then tasks, then TDD. Do not generate everything in one step.”

Concrete example:

“Starting from this specification: ‘REST API for order management with JWT authentication, rate limiting, and PostgreSQL integration’, build the project in the current folder. Stack: Go + Chi + sqlx. Constraints: test coverage >= 80%, no unapproved dependencies. Process: architectural plan first, then incremental tasks with TDD.”

Context setup 🔧

1. Create AGENTS.md immediately — define stack, versions, approved libraries, and test commands. This is the contract that will guide the agent for the entire project duration.
2. Write the specification formally — objectives, users, scenarios, acceptance criteria. Not a vague idea: a document a colleague could read and understand.
3. Define the “constitution” — stack, coding standards, non-negotiable constraints (e.g., “no GPL dependencies”, “tests for every public function”).

Workflow 💡

The spec-driven flow is as follows:

1. Specify: write what you want the system to do (not how).
2. Clarify: the agent asks questions about ambiguities. Answer before proceeding.
3. Plan: the agent proposes module architecture, interfaces, data schema.
4. Approve: review the plan. This is where you stop architectural drift.
5. Implement incrementally: MVP first, expansion later. Each increment with green tests.

Do not generate the entire architecture in one step. Every unvalidated line is potential architectural debt.

Use lightweight models for initial phases (architecture, interfaces, data schema) and reserve the most powerful model for complex logic.

Greenfield architecture choice 🏗️

Architecture choice is the most impactful decision you make before delegating. Agents work better with certain structures than others.

The modular monolith is making a comeback in the agent era. Microservices require coordination overhead that agents do not handle well.

Practical rule: start with a modular monolith. Select modules along clear domain boundaries. Allow modules the possibility of being extracted into separate services in the future — but do not do it now.

The clarify phase: 5 question archetypes 💬

The clarification phase is where the agent analyzes the specification and asks questions about ambiguities. There are 5 recurring archetypes:

If the agent does not ask questions during the clarify phase, it is an alarming signal: it means the specification is too vague or the agent is skipping a critical step.

Template: ADR Agent-Optimized 📋

Architecture Decision Records (ADRs) document architectural decisions. This template is optimized for use with agents, with executable “Agent Execution Rules”:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

## ADR-NNN: [Title]

**Status:** [Proposed | Accepted | Deprecated]

### Context
[Description of the problem and constraints]

### Decision
[The decision expressed as an executable rule, not prose]
> "We use [choice] because [reason]. We do NOT use [alternative] because [reason]."

### Alternatives rejected
[List of alternatives considered and why they were discarded — MANDATORY SECTION]

### Agent Execution Rules
- [ ] Verify that code uses [choice]
- [ ] Report as an error the use of [alternative]

### Consequences
[What changes, what becomes harder]

The “Alternatives rejected” section is the most skipped and the most valuable: it documents not only what you chose, but why you discarded the alternatives. Without it, a future developer (or agent) might resurface a solution already evaluated and discarded.

Anti-pattern table 🚫

Acceptance criteria ✅

• Architectural plan approved before writing code.
• AGENTS.md present with stack, versions, and commands defined.
• Green tests for every increment.
• No architectural drift from the approved plan.
• README, .gitignore, and CI scaffolding present from the first release.

Further reading 📚

• Writing prompts that work — how to structure the specification in the prompt.
• Configuring the repository — AGENTS.md as a project contract.
• Blog: Question-driven specification — the method for turning questions into executable specifications.
• Blog: Unknowns-driven development — how to manage uncertainty in development.