Capstone Project Kickoff

Welcome to the start of your SDD Capstone Project. Throughout this course, you have learned the principles of Spec-Driven Development (SDD) and how to use AI to speed up your coding. Now, it is time to put everything together to build a professional, production-ready application.

In this unit, we are building RecipeBox. This is more than just a simple list of recipes. It is a tool for home cooks to:

• Manage Recipes: Store ingredients, steps, and tags.
• Plan Meals: Assign recipes to specific days of the week.
• Generate Shopping Lists: Automatically combine ingredients from a meal plan into a single list, grouped by category.
• Track Nutrition: Fetch and calculate calories and macros.

To build this, we will use a modern technical stack: FastAPI for the web framework, PostgreSQL to store data, and Redis to handle background tasks like fetching nutrition data. On CodeSignal, these libraries are usually pre-installed, but knowing the stack helps you understand how the "engine" of your app works.

Before we dive into the code, let’s quickly remember the workflow we have been practicing. In SDD, we never start by writing code. Instead, we follow a strict sequence:

1. Requirements: Define what we want.
2. Specification: Detail exactly how it should work.
3. Implementation: Use AI agents to write the code based on the spec.

In our previous lessons, you learned about Orchestration. This is the process where you act as the manager. You don't just ask an AI to "build the whole app." You break the project into small, atomic tasks and use a task-executor agent to finish them one by one. This ensures the AI stays focused and doesn't get "confused" by too much information at once.

Every great project starts with an idea. We begin by creating a file called informal-requirements.txt. It contains a few paragraphs describing the app in plain English. For RecipeBox, it might look like this:

Users need to manage recipes and plan meals for the week. 
Recipes have ingredients with amounts and units. 
Meal plans assign recipes to days. 
Shopping lists should be generated automatically from meal plans.

Next, we use an AI to turn this into a Product Requirements Document (PRD). This document is a formal version of your idea. It includes "Success Metrics" (how we know the app works) and "Constraints" (rules we must follow, like using PostgreSQL).

The most important part of this phase is the Domain Model. This is a map of how your data fits together. Let's look at how we build the relationship between Recipes and Ingredients.

The snippets below are conceptual pseudo-code to illustrate entities and relationships. They are not runnable Python (e.g., uuid and decimal are placeholders for "unique identifier" and "precise number"); your actual implementation will use proper types (e.g., SQLAlchemy columns or spec field types).

First, we define a Recipe.

# A Recipe has a name and basic info (pseudo-code; id might be UUID or int in implementation)
class Recipe:
    id: uuid
    name: str
    description: str

Next, we need Ingredients. But a recipe doesn't just "have" an ingredient; it needs a specific amount of that ingredient.

# An Ingredient is a general item like "Flour"
class Ingredient:
    id: uuid
    name: str
    category: str # e.g., "Baking"

Finally, we connect them using a "join table" called RecipeIngredient. This stores the connection and the amount.

# This connects a specific Recipe to a specific Ingredient
class RecipeIngredient:
    recipe_id: uuid
    ingredient_id: uuid
    amount: decimal
    unit: str # e.g., "cups"

By defining these relationships early, we ensure our database is organized and efficient.

Now that we have a PRD and a data map, we need a Functional Specification. Think of this as the "Instruction Manual" for the AI. It lists every API endpoint (like POST /recipes) and the exact rules for calculation.

For RecipeBox, we have complex rules like Serving Scaling. If a recipe is for 4 people, but you want to cook for 2, the app must divide every ingredient amount by 2.

To make sure our spec is high quality, we grade it on five dimensions:

1. Clarity: Is every field type exact (e.g., decimal(10,2))?
2. Completeness: Are all 7 data models and 15+ endpoints listed?
3. Testability: Are there "Given/When/Then" examples?
4. Consistency: Do all endpoints use the same naming style?
5. Appropriate Abstraction: Does it describe what the system does, not how to write the code?

In the capstone, we aim for a score of 85/100. If your spec is vague, you must refine it. For example, instead of saying "calculate nutrition," you should specify: "Sum the calories of all ingredients, multiplied by the serving factor."

With the "what" decided, we move to the "how." We create a Technical Plan. This defines our architecture. For RecipeBox, we use the Repository Pattern. This means our API doesn't talk to the database directly. Instead, it talks to a "Repository" file that handles the data. This keeps our code clean and easy to test.

The most critical file you will create is CLAUDE.md. This is your project’s Constitution. It contains the "laws" that every AI agent must follow.

# CLAUDE.md Guidelines

- **Tech Stack:** FastAPI, SQLAlchemy, PostgreSQL.
- **Code Style:** Use type hints and Google-style docstrings.
- **Architecture:** All database access must go through the /repositories directory.
- **Testing:** Every task must have 90%+ test coverage.

When an agent starts a task, it reads this file first. This ensures that even if different agents work on different parts of the app, the code looks like it was written by the same person.

In a large project, one AI isn't enough. We create a "workforce" of specialized agents in the .claude/agents/ directory. Each agent has a specific job:

• task-executor: The builder who writes the code.
• test-enhancer: The auditor who adds extra tests to find bugs.
• recipe-validator: The expert who checks if the math for servings and units is correct.
• doc-updater: The writer who keeps the documentation current.

Finally, we break the project into 23 atomic tasks. An "atomic" task is a small piece of work that takes 30–90 minutes and affects 3 or fewer files.

We also identify Parallel Workflows. For example, once the "Foundation" (database setup) is done, one agent can work on the Recipe API while another agent works on the Meal Planning system at the same time. This is how professional teams build software quickly.

In this lesson, you have seen how to set a professional foundation for a production app. You learned to:

• Turn informal ideas into a formal PRD and Domain Model.
• Write a high-quality Functional Specification and score it.
• Create a CLAUDE.md constitution to enforce coding standards.
• Set up a system of specialized agents and decompose a project into atomic tasks.

By finishing this setup, you have done the hardest part of engineering: the planning. In the upcoming practice exercises, you will go through these steps yourself in the CodeSignal IDE. You will generate these documents and prepare your RecipeBox project for implementation. Let’s get started!