aiase-sdd

name	aiase-sdd
description	Spec-Driven Development (SDD) — how to write specs before coding with AI, the dimensional ascension/descent workflow, and dialogue-to-spec-to-code pipeline. Load when the user asks about writing specs, requirements, AIASE course SDD, or before starting any AI-assisted coding task.

Spec-Driven Development (SDD)

From AIASE 2026 (NCKU), Weeks 2–5. The core thesis: write the spec first; let the AI write the code from the spec.

Core Model: Dimensional Ascension & Descent

• Ascent (1D → 3D): Lift fragmented requirements into a comprehensive architectural blueprint — structured Markdown + Mermaid diagrams.
• Descent (3D → 1D): Translate that blueprint into executable code precisely, with minimal ambiguity.

A good diagram beats ten paragraphs. AI translates visual logic into precise code; it can't reliably infer intent from prose.

The Three-Layer Contract

Every SDD project has three layers:

1. System Prompt / AGENTS.md = Architectural Specification

   • Role (capability boundary)
   • Goal (success metric)
   • Constraints (what's forbidden)
   • Output Format (testable spec)

2. Tool Schema = API Contract

   • Precise descriptions: when to use, when NOT to use
   • Parameter validation: type, range, defaults
   • Return format + explicit error cases

3. Eval Cases = Test Suite

   • Golden dataset (hand-verified examples)
   • Scoring: exact match, semantic match, or LLM-as-Judge
   • Regression tests (new changes must not break passing cases)

Dialogue-to-Spec Pipeline (W5 Phase 1–5)

Phase 1: Dialogue → Requirements
  Start with incomplete request. Claude asks clarifying questions.
  Define: feature boundary, permission model, response format, error handling.
  The dialogue IS the requirements process — no upfront spec needed.

Phase 2: Spec Document
  Crystallize discussion into structured Markdown.
  Version from v0.1 (endpoints) → v0.4 (MCP plans, Mermaid diagrams).
  Each iteration adds one concern; never rewrite the previous version.

Phase 3: Security Review
  Switch Claude to "information security expert" role.
  Threat-model against the spec.
  Produce security_check.md with 30+ actionable items.

Phase 4: Multi-Agent Team Design
  Match agent roles to project phases and security concerns.
  Write multiagent-plan.md describing each agent's mandate.

Phase 5: Execution
  Upload spec + security checklist + agent plan as shared knowledge.
  Team Lead coordinates; teammates resolve dependencies peer-to-peer.

Effective Prompt Structure

Every prompt to an AI needs four elements:

• Context — current program state
• Task — what to build/fix
• Constraints — forbidden libraries, required conditions
• Format — expected output structure

The Rolling Snowball Method

Build incrementally:

1. MVP only
2. Add one feature per iteration
3. Verify each step before proceeding

This prevents cascading errors and keeps it obvious which change caused a problem.

Interaction Maturity Levels

Level	Method	Typical User
Tier 1	Unstructured natural language	Casual users
Tier 2	Structured Markdown + constraints	Intermediate developers
Tier 3	Full SDD + diagrams + multi-agent	Senior engineers directing AI teams

Anti-Patterns

"Vibe Coding ≠ non-programmers writing programs. Vibe Coding = programmers who understand logic, accelerated by AI."

You must be able to:

• Verify AI outputs for logic errors
• Debug the generated code
• Catch hallucinated tool calls

---

See also: [[aiase-rpi]] for the Research-Plan-Implement workflow, [[aiase-harness]] for CLAUDE.md/AGENTS.md structure.