Your First AIDD Project

Practical Exercise 2

Hands-On

Build a complete Todo API using the AIDD workflow

2026 WayUp

Project: Todo API

A complete REST API built with AIDD

What We'll Build

  • RESTful Todo API
  • CRUD operations
  • Input validation
  • Error handling
  • Persistence (SQLite)

Learning Goals

  • Apply AIDD 6-phase workflow
  • Create effective vision.md
  • Practice TDD with AI
  • Generate human + automated tests
Duration: 45-60 minutes | Stack: Python + Flask (or your preferred stack)

Task 1: Create vision.md

Your Task

Create a vision document for the Todo API. Use the prompt below:

Help me create a vision.md for a Todo API project. Project: A simple REST API for managing todo items Stack: Python/Flask with SQLite database Include: Project Overview, Target Audience, Primary Goals, Non-Goals, Technical Constraints, Architecture Decisions, Success Metrics

Checklist

  • Created vision.md file
  • Defined primary goals (CRUD operations)
  • Listed non-goals (no authentication, no UI)
  • Documented architecture decisions

Task 2: Discover - Map User Journeys

Your Task

Map user journeys for the Todo API. Think about who uses it and how.

Read vision.md. Map user journeys for the Todo API. Consider: 1. API Consumer (developer building a frontend) 2. System Administrator (deploying and monitoring) For each: persona, goals, entry points, success criteria, edge cases

Expected Journeys

1. List all todos
2. Create new todo
3. Update todo status
4. Delete todo
5. Handle errors

Edge Cases

- Empty todo title
- Todo not found
- Invalid ID format
- Server error handling

Task 3: Plan - Create Task Epics

Your Task

Break down the user journeys into implementable task epics.

Based on the user journeys, create task epics for the Todo API. For each epic: - Title, User Story, Acceptance Criteria - Dependencies, Complexity (S/M/L) Order by dependency.

Expected Epics

EpicSizeDependencies
Database SetupSNone
List TodosSDatabase
Create TodoMDatabase
Update TodoMCreate Todo
Delete TodoSCreate Todo

Task 4: Review - Validate Plan

Your Task

Have AI review the task epics for issues before implementation.

Review the task epics for the Todo API. Check for: 1. Duplication - Any repeated requirements? 2. Coupling - Tasks too interdependent? 3. Vision alignment - Matches vision.md goals? 4. Missing cases - Edge cases covered? 5. Over-engineering - Can anything be simplified?

Common Issues

- Missing 404 handling
- No input validation
- Duplicate error logic

After Review

- Added validation epic
- Centralized error handling
- Clear acceptance criteria

Task 5: Execute - TDD Implementation

Your Task

Implement the "Create Todo" epic using strict TDD.

Implement "Create Todo" using TDD. Step 1: Write a failing test for POST /todos with valid data Step 2: Write minimal code to pass Step 3: Refactor if needed Show me the test FIRST, then implement after approval.
RED
Failing Test
→
GREEN
Make Pass
→
REFACTOR
Clean Up
Key rule: One acceptance criterion at a time. Never batch tests!

Task 6: Commit - Clean Code Push

Your Task

Commit your changes following best practices.

Pre-Commit Checklist

  • All tests pass
  • Code linted (flake8/black)
  • No commented-out code
  • Commit message is descriptive

Commit Message Format

feat(todos): add create todo endpoint

- POST /todos accepts title and optional description
- Returns 201 with created todo object
- Validates title is not empty

Task 7: Test - Generate Test Scripts

Your Task

Generate both human and automated test scripts.

Generate test scripts for the Todo API: 1. Human Test Script: Step-by-step manual testing instructions using curl or Postman 2. Automated Tests: pytest tests covering: - Happy path (create, read, update, delete) - Error cases (invalid input, not found)

Human Test

1. Start server
2. POST a new todo
3. Verify response
4. GET all todos
5. Check todo exists

Automated Test

test_create_todo()
test_create_todo_empty_title()
test_get_all_todos()
test_get_todo_not_found()

Completion Checklist

Documentation

  • vision.md created
  • User journeys documented
  • Task epics defined

Implementation

  • All CRUD endpoints
  • Input validation
  • Error handling

Testing

  • TDD approach followed
  • All tests passing
  • Edge cases covered

Quality

  • Code linted
  • Commits are atomic
  • README updated

Reflection Questions

Discovery Value

How did mapping user journeys before coding help you understand requirements better?

TDD Benefits

What issues did writing tests first catch that you might have missed otherwise?

AI Collaboration

When was AI most helpful? When did you need to guide it more?

Vision Document

Did the vision.md help maintain focus? What would you add next time?

Submit: Your completed project repository with vision.md, tests, and implementation.

Practical Complete!

Your First AIDD Project

Next: Practical 3 - Implementing a Complex Feature

2026 WayUp - way-up.io

Slide Overview