Spec-First Engineering (RFC-Driven AI Dev)

1. Concept Overview & Systemic Problem

The main pitfall for beginners in vibecoding is haste. A developer opens an agent IDE and immediately types in the chat: "Create a shopping cart page with promo codes." The agent generates 1000 lines of code in 15 seconds, but:

• An outdated hook is used instead of the project's modern state manager.
• Promo codes are calculated on the client side instead of the backend (a security hole).
• Type names are duplicated, and localization is completely ignored.

Spec-First Engineering is the golden rule of productive AI coding: never touch the code without an approved plan. The engineer acts as the chief architect, formulating a comprehensive contract (implementation_plan.md), agreeing on edge cases, and only then instructing the agent to generate code.

2. Architectural Taxonomy & Mental Model

┌─────────────────────────────────────────────────────────────┐
│                 SPEC-FIRST ENGINEERING CYCLE                │
├─────────────────────────────────────────────────────────────┤
│ 1. Intent Exploration (Intent Exploration)                   │
│    • Brainstorming, Edge-Case Interview ("Grill-Me")        │
│    • Defining Anti-Goals (what must NOT be included)        │
├─────────────────────────────────────────────────────────────┤
│ 2. Formal Spec Artifact Creation                             │
│    • Types & Data Contracts (TypeScript interfaces / Zod)   │
│    • File Mutation Map ([NEW], [MODIFY], [DELETE])          │
│    • Verification Criteria (Automated test commands)        │
├─────────────────────────────────────────────────────────────┤
│ 3. Human Gate & Peer Approval                                │
│    • Engineer reviews the plan, makes adjustments            │
├─────────────────────────────────────────────────────────────┤
│ 4. Deterministic Autonomous Execution                        │
│    • Agent executes the plan step-by-step without deviations │
└─────────────────────────────────────────────────────────────┘

3. Technical Pipeline & Internal Mechanics

01. Model Interviewing Before Feature (Grill-Me Pattern)

Before writing the development plan, the developer instructs: "I want to add a Stripe payment system. Ask me 5 probing questions about webhook handling, retries, and security before writing the plan." This uncovers hidden issues at the idea stage rather than in production.

02. Protection Against Architectural Erosion

If the project is led by a team of three engineers with agents, all changes first go through a PR in the docs/specs/ folder. The team sees the intent before the model creates 50 new components.

4. Production Engineering Scenarios

• Analysis Paralysis: Writing a 20-page plan for changing a button color is a waste of time. For trivial edits, the direct editing rule applies. Specifications are needed for tasks affecting more than 2 files or business logic.
• Spec Drift: If the agent discovers a new detail during coding and autonomously changes the architecture without updating the specification, the system loses control. Require the agent to update the plan for any unforeseen difficulties.

5. Pitfalls, Common Mistakes & Security

In a world where code generation costs zero cents, the most valuable engineering skill becomes not typing speed, but the depth and accuracy of formulating a technical specification. Whoever controls the specification controls the system.