Architecting a project — Coding with AI course

La spec AVANT le code

L'erreur la plus coûteuse avec l'IA : ouvrir un chat et écrire "crée-moi une application de..." sans avoir d'abord réfléchi à ce qu'on veut. L'IA va produire quelque chose, vous allez itérer 20 fois, et au final le résultat ne correspondra pas à votre besoin initial.

La solution : spec-driven development. Écrire la spécification AVANT de demander une seule ligne de code. La spec est le document qui dit à l'IA (et à vous-même) exactement ce que vous construisez.

Le workflow en 4 phases :

Phase 1 : Spécifier    Quoi, pour qui, contraintes, edge cases
Phase 2 : Planifier    Architecture, fichiers, dépendances
Phase 3 : Découper     5-10 tâches atomiques ordonnées
Phase 4 : Implémenter  Une tâche = un prompt = une review

Phase Action Livrable

Le contexte persistant : CLAUDE.md

Les outils IA modernes (Claude Code, Cursor, Copilot) permettent de configurer un contexte persistant : un fichier qui décrit votre projet et vos conventions, que l'IA lit automatiquement à chaque session.

CLAUDE.md : pour Claude Code
.cursorrules : pour Cursor
.github/copilot-instructions.md : pour GitHub Copilot

Ce fichier contient :

La stack technique du projet
Les conventions de code (nommage, structure)
Les commandes de build/test/deploy
Les erreurs courantes à éviter
Le contexte métier essentiel

Sans ce fichier, vous répétez les mêmes instructions à chaque session. Avec lui, l'IA connait votre projet dès le départ.

Décomposer en tâches atomiques

Une feature = 5 à 10 tâches atomiques. Chaque tâche doit être :

Indépendante : réalisable sans attendre les autres
Vérifiable : on sait immédiatement si c'est fait
Petite : un seul prompt, un seul fichier, une seule fonction

Exemple : "Ajouter des notifications utilisateur" se décompose en :

Créer la table notifications en base de données
Écrire la fonction createNotification(userId, message, type)
Écrire la fonction getUnreadNotifications(userId)
Créer le composant UI qui affiche le badge de notifications
Créer la page qui liste toutes les notifications
Ajouter la fonction markAsRead(notificationId)
Intégrer les appels de création de notification dans les événements existants
Écrire les tests

Chaque tâche = un prompt = un résultat vérifiable. Vous gardez le contrôle à chaque étape.

La matrice de délégation

Tout ne se délègue pas à l'IA de la même façon. Deux critères : les enjeux (impact si c'est faux) et la vérifiabilité (facilité à vérifier si c'est correct) :

	Facile à vérifier	Difficile à vérifier
Enjeux faibles	Déléguer	Déléguer + vérifier
Enjeux élevés	Déléguer + tests	Faire soi-même

Exemples concrets :

Enjeux faibles + facile à vérifier : génération de CSS, formatage, scripts utilitaires
Enjeux faibles + difficile à vérifier : migration de données de test
Enjeux élevés + facile à vérifier : fonctions avec tests unitaires, API avec des contrats clairs
Enjeux élevés + difficile à vérifier : logique financière, sécurité critique, algorithmes métier complexes

The spec BEFORE the code

The most costly mistake with AI: opening a chat and writing "create me an application for..." without first thinking about what you want. The AI will produce something, you will iterate 20 times, and in the end the result will not match your initial need.

The solution: spec-driven development. Write the specification BEFORE asking for a single line of code. The spec is the document that tells the AI (and yourself) exactly what you are building.

The 4-phase workflow:

Phase 1 — Specify     What, for whom, constraints, edge cases
Phase 2 — Plan        Architecture, files, dependencies
Phase 3 — Decompose   5-10 ordered atomic tasks
Phase 4 — Implement   One task = one prompt = one review

Phase Action Deliverable

Persistent context: CLAUDE.md

Modern AI tools (Claude Code, Cursor, Copilot) allow you to configure a persistent context — a file that describes your project and conventions, which the AI reads automatically at each session.

CLAUDE.md — for Claude Code
.cursorrules — for Cursor
.github/copilot-instructions.md — for GitHub Copilot

This file contains:

The project tech stack
Code conventions (naming, structure)
Build/test/deploy commands
Common mistakes to avoid
Essential business context

Without this file, you repeat the same instructions every session. With it, the AI knows your project from the start.

Decompose into atomic tasks

One feature = 5 to 10 atomic tasks. Each task should be:

Independent — achievable without waiting for others
Verifiable — you know immediately if it is done
Small — one prompt, one file, one function

Example: "Add user notifications" breaks down into:

Create the notifications database table
Write the createNotification(userId, message, type) function
Write the getUnreadNotifications(userId) function
Create the UI component that displays the notification badge
Create the page that lists all notifications
Add the markAsRead(notificationId) function
Integrate notification creation calls into existing events
Write the tests

Each task = one prompt = one verifiable result. You keep control at every step.

The delegation matrix

Not everything should be delegated to AI the same way. Two criteria: stakes (impact if wrong) and verifiability (ease of checking if correct):

	Easy to verify	Hard to verify
Low stakes	Delegate	Delegate + verify
High stakes	Delegate + tests	Do it yourself

Concrete examples:

Low stakes + easy to verify — CSS generation, formatting, utility scripts
Low stakes + hard to verify — test data migration
High stakes + easy to verify — functions with unit tests, APIs with clear contracts
High stakes + hard to verify — financial logic, critical security, complex business algorithms