Skip to Content
DocsConceptsSpecs

Spec-Driven Development

AIDEN follows a spec-driven approach to software development. Instead of jumping straight into code, you define what needs to be built through structured specifications, and AI agents handle the how.

How Specs Work

Project-Level Specs

When AIDEN analyzes your project, it generates a .aiden/SPEC.md file containing:

  • Project goals and scope
  • Architecture decisions
  • Technical constraints
  • Feature requirements

Story-Level Specs

Each story on the Kanban board can have its own spec. During the Plan phase, you collaborate with the AI in chat to refine the spec:

  • The AI suggests spec fields via :::spec-update blocks
  • You can accept, modify, or reject suggestions
  • Specs include acceptance criteria, technical approach, and file changes

Spec Updates in Chat

When chatting with the AI about a story, it can propose spec changes inline:

:::spec-update
field: acceptance_criteria
value: |
  - User can log in with email/password
  - Session persists across app restarts
  - Error messages shown for invalid credentials
:::

These structured updates keep specs in sync with the conversation.

Why Specs Matter

  1. AI Context — Agents use specs as their primary instructions. Better specs = better code.
  2. Reproducibility — Specs document intent, making it easy to re-run or adjust agent work.
  3. Review — Specs provide clear criteria for reviewing AI-generated code.
  4. Collaboration — Multiple agents working in parallel reference specs to avoid conflicts.
ProjectsAI Agents