3.4 — Piloter son projet : les fichiers .md

Durée : 5 min | Type : Théorie | Slides : ~2-3

Le problème#

Un agent IA n'a pas de mémoire entre les conversations. Chaque fois que vous ouvrez un nouveau chat, il repart de zéro. Il ne sait pas ce que vous construisez, quelles décisions vous avez prises, où vous en êtes, ni ce qu'il a déjà fait.

La solution : des fichiers texte (.md = markdown) que l'agent lit au début de chaque session. Ces fichiers sont le cerveau de votre projet — l'agent s'y réfère en permanence, et c'est lui qui les maintient à jour.

La structure#

Créez ces fichiers à la racine de votre projet :

mon-projet/
├── AGENTS.md          # Instructions permanentes pour l'agent
├── CDC.md             # Cahier des charges (ce qu'on construit)
├── DESIGN.md          # Direction visuelle
├── PLANNING.md        # Plan par phases
├── notes/
│   └── JOURNAL.md     # Problèmes, solutions, décisions
└── src/               # Le code (géré par l'agent)

💡 Vous n'avez pas à écrire tout ça seul. Commencez par décrire votre projet à l'agent, et demandez-lui de générer ces fichiers. Ensuite vous ajustez.

AGENTS.md — Les instructions permanentes#

C'est le fichier le plus important. L'agent le lit en premier. Il contient qui vous êtes, ce qu'est le projet, et les règles à suivre.

# Instructions pour l'agent

## Contexte
Je suis prof de comptabilité dans une école secondaire en Belgique.
Ce projet est un outil de gestion des grilles d'évaluation.

## Stack technique
- Python + Streamlit
- Base de données : SQLite
- Langue du code : français pour l'interface, anglais pour le code

## Règles
- Toujours lire CDC.md et PLANNING.md avant de commencer
- Suivre le plan phase par phase — ne pas sauter d'étapes
- Tester le code avant de dire que c'est terminé
- Mettre à jour PLANNING.md après chaque phase complétée
- Noter les problèmes et solutions dans notes/JOURNAL.md
- Ne jamais supprimer de fichier sans demander
- Pas de données personnelles d'élèves dans le code

## Structure du projet
[L'agent remplira ça au fur et à mesure]

💡 Si vous utilisez Claude Code au lieu de Codex, le fichier s'appelle CLAUDE.md — c'est la même chose, c'est juste le nom que Claude Code cherche automatiquement.

CDC.md — Le cahier des charges#

C'est la bible du projet. Ce que l'application fait, pour qui, et comment.

# Cahier des charges — Gestionnaire de grilles d'évaluation

## Description
Application Streamlit pour créer des grilles d'évaluation par compétences,
encoder les points des élèves, et générer des fiches de résultats en PDF.

## Fonctionnalités MVP (prioritaire)
- Créer une grille : compétences, critères, pondérations
- Encoder les résultats par élève
- Calcul automatique des totaux
- Export PDF de la fiche individuelle

## Fonctionnalités secondaires (si le temps le permet)
- Réutiliser une grille d'une année à l'autre
- Statistiques par classe (moyenne, distribution)
- Export Excel

## Exigences
- Interface simple et claire (les collègues doivent pouvoir l'utiliser)
- Données stockées localement (SQLite)
- Pas de connexion internet requise

Pas besoin de 10 pages. Un CDC clair et concis vaut mieux qu'un roman que personne ne lit.

PLANNING.md — Le plan par phases#

L'agent le propose, vous le validez. Chaque phase est petite et testable.

# Plan d'implémentation

## Phase 1 — Structure de base ⬜
- Initialiser le projet Streamlit
- Configurer SQLite
- Page d'accueil minimale

## Phase 2 — Créer une grille ⬜
- Formulaire de création de grille
- Ajout de compétences et critères
- Sauvegarde en base

## Phase 3 — Encoder les résultats ⬜
- Sélectionner une grille et une classe
- Tableau d'encodage par élève
- Calcul automatique

## Phase 4 — Export PDF ⬜
- Génération de la fiche individuelle
- Mise en page propre avec logo

Légende : ⬜ À faire | 🔄 En cours | ✅ Validé

⚠️ Règle d'or : une bonne phase se résume en une phrase et se teste en 2 minutes. Si c'est trop gros, découpez.

DESIGN.md — La direction visuelle#

Pas besoin de maquettes Figma. Quelques lignes suffisent pour donner une direction :

# Design — Grilles d'évaluation

## Ambiance
Interface épurée et professionnelle. Sobre, pas de fioritures.
Inspiration : outils Google (Sheets, Forms).

## Couleurs
- Primaire : #2563EB (bleu)
- Fond : #F8FAFC (gris très clair)
- Texte : #1E293B (quasi-noir)
- Succès : #16A34A (vert)
- Erreur : #DC2626 (rouge)

## Principes
- Beaucoup d'espace blanc
- Tableaux lisibles avec lignes alternées
- Boutons clairs avec icônes

notes/JOURNAL.md — La mémoire du projet#

C'est l'agent qui le maintient. Demandez-lui après chaque session :

"Mets à jour notes/JOURNAL.md avec ce qu'on vient de faire, les problèmes rencontrés et les solutions."

# Journal du projet

## 2026-02-13 — Phase 1 : Structure de base

### Ce qui a été fait
- Projet Streamlit initialisé
- SQLite configuré avec les tables grilles, compétences, résultats
- Page d'accueil avec navigation sidebar

### Problèmes rencontrés
- Streamlit ne trouvait pas le fichier de base de données
  → Solution : utiliser un chemin absolu via Path(__file__).parent

### Décisions
- On utilise st.session_state pour garder l'état entre les pages

### Statut : Phase 1 ✅

Le journal a deux utilités : il aide l'agent à retrouver le contexte quand vous reprenez le travail, et il vous aide à documenter votre progression.

En pratique : le workflow#

1. Début de projet : décrivez votre idée à l'agent → demandez-lui de générer AGENTS.md, CDC.md, DESIGN.md et PLANNING.md
2. Vous relisez et ajustez (c'est VOTRE projet, pas celui de l'agent)
3. Chaque session : l'agent lit les fichiers → travaille sur la phase en cours → met à jour PLANNING.md et JOURNAL.md
4. Quand vous reprenez : l'agent relit tout et sait exactement où il en est

💡 Le but c'est que l'agent travaille pour vous, pas l'inverse. Vous décidez, il exécute et documente.