Markdown
Markdown est le format de texte qui relie l'élève, l'agent et le dépôt. Comprendre sa syntaxe, c'est apprendre à donner des consignes claires.
Qu'est-ce qu'un Markdown ?
Un Markdown est un fichier texte qui contient quelques repères simples : des # pour les titres, des - pour les listes, des ** pour le gras. Ces repères s'appellent une syntaxe : ils disent à la machine comment lire le document, sans l'alourdir de mise en forme cachée.
Un fichier Markdown porte l'extension .md (ou .markdown). Il s'ouvre dans n'importe quel éditeur de texte et se lit presque aussi bien brut qu'une fois mis en forme.
Markdown n'est pas un programme : c'est une convention d'écriture. Vos consignes restent du texte, ce qui les rend durables et comparables d'un projet à l'autre.
Pourquoi ce format, et pourquoi avec une IA ?
C'est du texte pur
Un fichier Markdown est un simple fichier texte, avec une extension .md. Il s'ouvre partout, il ne dépend d'aucun logiciel, et il ne casse pas au fil des ans.
C'est structuré pour la machine
Titres, listes, tableaux, blocs de code : les mêmes repères se retrouvent d'un fichier à l'autre. L'agent IA sait exactement où se trouve chaque information.
C'est lisible sans être rendu
Même brut, un Markdown reste compréhensible : les #, les - et les ** sautent aux yeux. On n'a pas besoin d'un aperçu pour suivre un document.
Git suit chaque modification
Une consigne en Markdown se compare, se corrige et se restaure comme du code. C'est la mémoire des règles du projet.
L'agent IA lit un Markdown comme une suite de consignes clairement délimitées : un titre annonce un sujet, une liste énumère des règles, un bloc de code montre un exemple. Moins d'ambiguïté, donc moins d'allers-retours.
La syntaxe de base, par l'exemple
| Ce que vous écrivez | Ce que le lecteur voit | À quoi ça sert |
|---|---|---|
# Titre | Titre | Le titre principal du document. |
## Sous-titre | Sous-titre | Une section, puis des sous-sections. |
- une puce | • une puce | Une liste d'éléments à parcourir. |
1. une étape | 1. une étape | Une suite ordonnée : un mode d'emploi. |
**important** | important | Un mot mis en avant, en gras. |
`une commande` | une commande | Du code court, au milieu d'une phrase. |
> une citation | Citation | Une règle ou un avertissement mis à part. |
Il n'y a rien d'autre à retenir pour commencer. Le reste s'apprend en lisant les fichiers du projet : README.md, AGENTS.md, et le workflow.mdfourni en classe.
Comment on crée un Markdown
- Ouvrir un éditeur de texte — celui d'OpenCode, VS Code, Nano, peu importe. Le fichier doit rester du texte pur.
- Écrire le contenu avec les repères de la table ci-dessus, en commençant par un titre de niveau 1.
- Enregistrer avec l'extension
.md:README.md,notes.md,workflow.md. - Relire le fichier brut : si on le comprend sans aperçu, il sera compris par l'agent aussi.
Comment l'IA crée un Markdown
Vous n'avez pas besoin de tout taper vous-même : c'est exactement le genre de tâche qu'un agent réussit très bien. Décrivez le document, laissez-le écrire, puis relisez.
Rédiger le document
« Écris un fichier AGENTS.md qui décrit ce projet, ses conventions et ce qu'il ne faut pas casser. Explique chaque section. »
Relire avant d'accepter
Un document de consignes engage tout le travail qui suit : il se lit, se corrige et se committe, comme du code.
Guider l'agent
Le workflow.md remis en début de projet sert de mode d'emploi : l'agent s'en sert pour vous guider, étape après étape.
Trois erreurs à éviter
À éviter Écrire un "document Word" et le renommer en .md.
À la place : Un Markdown est du texte pur. On l'écrit dans un éditeur de texte, pas dans un traitement de texte qui ajoute sa propre mise en forme invisible.
À éviter Mélanger consignes, code et brouillons dans un même gros fichier.
À la place : Un fichier, un rôle : l'agent s'y retrouve mieux, et vous aussi. On découpe plutôt que d'entasser.
À éviter Copier un tutoriel sans jamais le relire.
À la place : Un document de consignes se vérifie avant d'être donné à l'agent : il engage le travail qui suit.
Le fichier workflow.md
Ce fichier rassemble tout le workflow, écrit pour être remis à l'agent IA au début du projet. Il rappelle que l'élève débute, qu'il n'a jamais utilisé GitHub ni Cloudflare Pages, et que l'agent doit faire le maximum des manipulations techniques — en expliquant ce qu'il fait.
La version remise en classe ajoute le mécanisme de journalisation des prompts : l'agent dépose chaque demande pour garder la trace du travail, sans que l'élève ait à le faire à la main.
Pour aller plus loin
Piloter l'agent
Transformer une intention en consignes précises, structurées comme un Markdown.
Espace de travailOpenCode
Où vivent AGENTS.md et les fichiers du projet.
Déposer un prompt
Garder la trace des consignes envoyées à l'agent.
Le projetDu site au jeu
Le même workflow, adapté à la création d'un jeu vidéo.