Spec-Driven Development with ZeeSpec: Mastering Greenfield and Brownfield Systems

The AI Specification Problem Nobody Talks About

ZeeSpec is a 60-question constraint system built on the Zachman Framework and the 5W1H model. It forces critical architecture decisions into the open before a single line of code is generated, preventing AI coding assistants from filling gaps with incorrect assumptions. This methodology ensures that AI remains deterministic rather than creative during the code generation process.

Why This Matters

In modern engineering, AI coding assistants often generate technically functional code that violates unstated business constraints or architectural boundaries. This creates a significant risk where machines autonomously decide database schemas, infrastructure patterns, and security roles without human oversight. ZeeSpec addresses this by treating missing specifications as design failures rather than edge cases, ensuring that every critical dimension of a system is defined before implementation. By enforcing constraints across What, Where, When, Who, Why, and How, teams can mitigate the risk of ‘phantom’ features or destructive refactors in legacy systems.

Key Insights

• The ZeeSpec system employs 60 questions—one per minute—to define system dimensions across the 5W1H model (What, Where, When, Who, Why, How).
• In Greenfield projects, the primary risk is underspecification, leading AI to invent relationships, storage patterns, and abstractions that were never requested.
• Brownfield development requires locking existing infrastructure and specifying only the delta to protect legacy systems from ‘helpful’ but destructive AI refactors.
• The ‘WHY’ dimension encodes business intent as constraints, preventing machines from implementing behavior that violates underlying logic.
• ZeeSpec’s gap detection mechanism surfaces undefined dimensions, blocking progress rather than allowing the AI to produce guessed or plausible-but-wrong code.

Working Examples

Greenfield ZeeSpec Prompt Template

System: [Name]
Assumption: No existing infrastructure. Build from scratch.
WHAT: [entity list, relationships, what cannot exist, what is never stored]
WHERE: [infrastructure choices, data flow boundaries, external integrations]
WHEN: [triggers for all CRUD operations, expiry, blocking conditions]
WHO: [roles, visibility matrix, approval workflows, blocked actors]
WHY: [business rules as constraints, intent behind each restriction]
HOW: [error handling, recovery, consistency, stress behaviour]
Generate a complete system spec with no unstated assumptions.

Brownfield ZeeSpec Prompt Template

Existing system context:
[Paste schema / API patterns / tech stack / non-negotiable constraints]
New feature: [Name]
WHAT (delta only): [new entities, changed fields, what is explicitly excluded]
WHERE (locked): [existing infra must not change — list it explicitly]
WHEN (delta + conflicts): [new triggers, existing triggers that must still fire]
WHO (extend, don't replace): [new role permissions relative to existing roles]
WHY: [business justification + restatement of existing constraints]
HOW: [migration path, backward compatibility, rollback plan]
Generate only the delta. Do not refactor existing components.

Practical Applications

• Identity Management: Using the ‘WHO’ dimension to map every role to entity visibility, preventing AI from retrofitting insecure access patterns in new builds.
• Infrastructure Locking: Utilizing the ‘WHERE’ dimension in brownfield projects to explicitly list existing integrations that must not be broken during feature updates.
• Temporal Consistency: Applying the ‘WHEN’ dimension to define entity expiry and state gates, ensuring AI does not bypass critical business triggers like account verification.

References:

• https://dev.to/vishalmysore/spec-driven-development-with-zeespec-greenfield-vs-brownfield-4103