AI Engineering System (AES)

AES vous aide à mener un projet logiciel avec une IA de façon organisée et fiable, que vous soyez développeur expérimenté, débutant, ou adepte du vibe coding (construire un projet en dialoguant avec une IA sans nécessairement écrire ou lire soi-même le code produit). Il installe dans votre projet un socle documentaire commun à tous vos agents IA (Claude Code, Codex, ou tout autre), avec des règles de comportement claires, un processus de travail étape par étape, et une trace vérifiable de ce qui a été décidé.

Le développeur décide. Les agents assistent. AES fournit le cadre, la traçabilité et les preuves de fraîcheur qui rendent cette collaboration vérifiable, sans garantir le comportement de l'agent.

Installation

Prérequis : Node.js 18 ou plus récent.

npm install -g aes-framework

Vérifier l'installation

aes-framework --version

Cette commande doit afficher, sans erreur, le numéro de la version installée (par exemple 1.6.0).

aes-framework --help

Cette commande affiche la liste complète des commandes disponibles, avec un exemple copiable pour chacune.

Premier usage

Depuis le dossier de votre projet (. désigne toujours le dossier courant) :

cd mon-projet
aes-framework analyze .

analyze n'écrit jamais rien : il montre seulement ce qui serait installé. Exemple de sortie sur un projet vierge (sortie abrégée) :

Analyse de /chemin/vers/mon-projet (aucune écriture, git ignoré) :

  CREATE    SYSTEM.md               absent du projet cible
  CREATE    RULES_OF_ENGAGEMENT.md  absent du projet cible
  CREATE    WORKFLOW.md             absent du projet cible
  ...

État global (analyse) : OK

Quand l'analyse vous convient, lancez l'installation réelle :

aes-framework apply .

apply crée un dossier ia/ contenant les 14 documents du socle AES. Il ne crée que ce qui manque et ne remplace jamais un fichier déjà présent. Par sécurité, il refuse par défaut un projet sans dépôt Git ou avec des modifications non enregistrées (options --allow-no-git et --allow-dirty, voir la référence de la CLI).

Ensuite, remplissez ia/CONTEXT.md (nom, objectif et périmètre du projet), même sommairement : c'est le point de départ réel du projet. Le guide complet pas à pas se trouve dans docs/INSTALLATION.md.

Plus tard, quand une nouvelle version d'AES fait évoluer un de ces documents, apply ne l'écrase jamais automatiquement. C'est aes-framework update . qui vous guide, fichier par fichier, entre adopter la nouvelle version officielle ou garder la vôtre (détail dans la fiche update de la référence CLI).

Mettre à jour un projet AES

Une nouvelle version d'AES ne remplace jamais automatiquement un document déjà installé dans votre projet. C'est toujours vous qui décidez, document par document.

aes-framework update .

Sans argument, cette commande vous guide dans tout le processus. Elle repère les documents qui ont évolué depuis votre dernière installation et vous propose, pour chacun, quatre choix. Adopter la nouvelle version officielle, conserver la vôtre, voir le détail des différences, ou décider plus tard.

Vous pouvez aussi agir document par document, sans passer par le mode guidé.

Voir les mises à jour disponibles, sans rien modifier.

aes-framework update . --status

Comparer un document avec la version officielle.

aes-framework update . --file SYSTEM.md --show

Adopter la nouvelle version officielle.

aes-framework update . --file SYSTEM.md --accept

Conserver votre version personnalisée.

aes-framework update . --file SYSTEM.md --keep

Quand vous choisissez de conserver un document, AES mémorise cette décision. Il ne vous la reproposera plus tant que ni le document officiel ni votre version locale n'auront changé entre temps.

Détail complet (mode scripté, garanties Git, résolution par lot) dans la fiche update de la référence CLI.

Sans installation : npx

Pour un usage ponctuel, sans installation globale, toutes les commandes fonctionnent avec npx :

npx --yes aes-framework@latest --version

cd mon-projet
npx aes-framework analyze .
npx aes-framework apply .

Intégrer Claude Code

Le socle que vous venez d'installer (ia/) est un ensemble de documents indépendant de tout outil : il fonctionne à l'identique avec n'importe quel agent, y compris sans jamais taper les commandes de cette section. Une intégration est différente : optionnelle, propre à un agent précis, elle automatise le rattachement de ce même socle à l'outil plutôt que de le faire à la main.

Si vous travaillez avec Claude Code, une commande dédiée branche le socle sur l'outil : chargement automatique des documents dans CLAUDE.md, compétences /aes-check (vérification de conformité) et /aes-close (clôture de tâche), et rappel non bloquant à chaque message.

L'intégration exige un dépôt Git propre : enregistrez d'abord le socle qui vient d'être installé.

git add ia
git commit -m "Ajout du socle AES Framework"

Puis, toujours depuis le dossier de votre projet :

aes-framework integration analyze claude-code .
aes-framework integration apply claude-code .

Comme pour le socle, integration analyze n'écrit rien et integration apply effectue l'installation réelle. Toute configuration déjà présente (.claude/settings.json, CLAUDE.md) est préservée : les ajouts sont strictement additifs. Détail des artefacts installés : voir la référence de la CLI.

Plus tard, quand une nouvelle version d'AES fait évoluer un de ces artefacts, integration apply ne l'écrase jamais automatiquement, exactement comme pour le socle. C'est aes-framework integration update claude-code . qui vous guide, artefact par artefact, entre adopter la nouvelle version officielle ou garder la vôtre, avec la même syntaxe que update (détail dans la fiche integration update de la référence CLI).

Toutes les commandes

| Objectif | Commande | |---|---| | Afficher la version | aes-framework --version | | Afficher l'aide | aes-framework --help | | Analyser un projet (aucune écriture) | aes-framework analyze . | | Installer le socle ia/ | aes-framework apply . | | Mettre à jour les documents du socle | aes-framework update . | | Analyser l'intégration Claude Code | aes-framework integration analyze claude-code . | | Installer l'intégration Claude Code | aes-framework integration apply claude-code . | | Mettre à jour l'intégration Claude Code | aes-framework integration update claude-code . | | Créer une clôture de tâche | aes-framework closure create . | | Vérifier une clôture | aes-framework closure verify . |

Chaque commande s'utilise à l'identique avec npx aes-framework .... Les options --allow-no-git et --allow-dirty s'appliquent à analyze, apply et aux trois commandes integration. Syntaxes détaillées, statuts et codes de sortie : voir la référence de la CLI.

Clôturer une tâche

À la fin d'une tâche, AES peut enregistrer une preuve de clôture locale (.aes/closure/closure.json), les déclarations sur le travail accompli plus une empreinte de l'état du dépôt au moment de la clôture.

Cette clôture ne se déclenche jamais d'elle-même à la simple fin d'un échange, quel que soit l'agent utilisé. WORKFLOW.md (Étape 9) impose toujours la même séquence bloquante avant toute clôture : rappel de l'état Git, présentation du travail que l'agent estime achevé, puis une question de validation explicite.

« Je considère avoir achevé le travail demandé pour cette tâche. Souhaitez-vous :

1. poursuivre cette tâche ;
2. demander des corrections ;
3. valider cette tâche et lancer la procédure de clôture AES ? »

Le silence, une réponse ambiguë ou un changement de sujet ne valent jamais validation : dans ce cas, l'agent ne doit jamais avancer vers la clôture. Une réponse de validation explicite (par exemple « Je valide cette tâche. ») suffit en revanche à faire enchaîner l'agent de lui-même vers la clôture, sans qu'il soit nécessaire de taper /aes-close ni de mentionner la clôture dans votre réponse.

Validation, clôture, commit et push sont quatre étapes distinctes, jamais fusionnées entre elles. Une fois la clôture réussie (closure verify répond OK), WORKFLOW.md pose encore deux questions bloquantes séparées, dans cet ordre : « Dois-je committer ces modifications ? », puis, seulement une fois le commit réalisé, « Dois-je pousser ce commit ? ». Ni la validation de la tâche, ni la clôture elle-même, ne valent accord pour l'une ou l'autre.

Deux parcours existent ensuite pour exécuter cette clôture. Repérez d'abord lequel correspond à votre situation, avant de lancer la moindre commande.

Vous utilisez Claude Code (ou un autre agent intégré) ⭐ Recommandé

C'est le parcours normal dès que l'intégration a été installée (voir Intégrer Claude Code plus haut). Vous ne lancez vous-même ni closure create ni closure verify.

Une fois votre validation obtenue selon la séquence ci-dessus, la compétence /aes-close prend le relais d'elle-même, sans jamais redemander cette validation (voir integrations/claude-code/skills/aes-close/SKILL.md, Contexte A). Vous pouvez aussi l'invoquer directement à tout moment, nouvelle session, reprise, clôture d'une tâche ancienne, en tapant /aes-close ; si aucune validation n'a déjà été donnée dans la conversation en cours, elle vous la demande elle-même avant de continuer (Contexte B).

Une fois lancée, la compétence évalue elle-même chaque item de la checklist et l'état des documents vivants, puisque c'est l'agent qui a réalisé le travail. Elle construit un fichier temporaire à votre place, en dehors de votre projet, appelle en interne aes-framework closure create --input <fichier-temporaire>, supprime ce fichier une fois la clôture écrite, puis lance aes-framework closure verify . et vous en présente le résultat.

Vous ne créez ni ne modifiez jamais de fichier JSON vous-même dans ce parcours.

Vous utilisez AES sans agent intégré

Si vous travaillez seul, sans agent orchestrateur, appliquez manuellement l'Étape 9 ci-dessus (rappel de l'état Git, validation explicite avant de poursuivre), puis lancez la commande vous-même.

aes-framework closure create .

Comme aucun agent ne connaît le détail du travail effectué à votre place, la commande vous guide au lieu de refuser sèchement. Au premier lancement, elle génère un modèle à compléter, .aes/closure/input.json, et vous le signale.

Ouvrez ce fichier, remplacez chaque valeur à compléter par un statut réel (le message d'erreur d'un lancement prématuré vous rappelle les valeurs acceptées), puis relancez exactement la même commande.

aes-framework closure create .
aes-framework closure verify .

closure verify répond CLOSURE-VERIFY: OK tant que l'état suivi du projet n'a pas changé depuis la clôture, et CLOSURE-VERIFY: STALE (avec le détail) dès qu'un changement est détecté. Ni l'une ni l'autre de ces deux commandes ne certifie que vos déclarations sont vraies ni que le travail est correct, cette vérification reste entièrement votre responsabilité.

Le rôle de --input

Cette option ne s'adresse jamais à un humain qui découvre la commande. Sans elle, closure create s'adresse à vous et vous guide pas à pas. Avec elle, elle s'adresse à un programme (votre agent, un script, une étape de CI/CD) qui connaît déjà toutes les réponses et les fournit d'un coup, dans un fichier déjà prêt.

--input n'est donc pas un raccourci à utiliser vous-même. C'est l'interface interne par laquelle un agent dialogue avec AES sans jamais vous exposer de JSON, exactement ce que fait la compétence /aes-close décrite ci-dessus.

Détail du schéma attendu par le fichier de préparation (un résumé de tâche, 16 items de checklist, l'état des 7 documents vivants) : voir la fiche closure create de la référence CLI.

Fonctionnement complet (statuts ABSENT, SCHEMA_INVALID, ERROR, gestion automatique de .gitignore) : voir la référence de la CLI et docs/UTILISATION.md.

Utiliser AES au quotidien

• docs/UTILISATION.md : le cycle de travail quotidien avec un agent, avec des prompts prêts à copier-coller.
• docs/PHILOSOPHY.md : pourquoi AES existe et les principes qui le fondent, la lecture la plus accessible pour commencer.
• docs/INSTALLATION.md : le guide d'installation détaillé, y compris ce qui se passe après apply.
• SYSTEM.md : les règles du framework et un glossaire des termes techniques rencontrés en chemin.

Vous pouvez aussi confier toutes les commandes de cette page à votre agent IA plutôt que de les taper vous-même : ouvrez le dossier de votre projet avec lui et dites-lui « installe AES Framework dans ce projet ». Il lira docs/INSTALLATION.md et exécutera les étapes à votre place ; vous n'aurez qu'à décrire votre projet en quelques phrases quand il vous le demandera.

Depuis un clone Git (contributeurs)

Le clonage du dépôt est la méthode secondaire, utile pour contribuer au framework, inspecter le code source ou tester une évolution non encore publiée sur npm :

git clone https://github.com/sbg224/AES-framework.git
cd AES-framework
node install/installer.js analyze ../mon-projet
node install/installer.js apply ../mon-projet

node install/installer.js <commande> est strictement équivalent à aes-framework <commande>. Seuls changent le préfixe et la gestion des chemins, le comportement reste identique, y compris pour la mise à jour d'un projet déjà installé.

node install/installer.js update ../mon-projet --status
node install/installer.js update ../mon-projet --file SYSTEM.md --show
node install/installer.js update ../mon-projet --file SYSTEM.md --accept
node install/installer.js update ../mon-projet --file SYSTEM.md --keep

Mêmes options, même workflow que aes-framework update . (voir Mettre à jour un projet AES plus haut). Cette équivalence node install/installer.js <commande> / aes-framework <commande> vaut pour toute commande de cette page, y compris integration update :

node install/installer.js integration update claude-code ../mon-projet --status

Procédure complète (structure recommandée, chemins relatifs, toutes les commandes y compris integration analyze|apply|update et closure create|verify), voir install/README.md.

Ce qu'AES fait et ne fait pas

Ce qu'AES fait :

• garder une trace fiable de ce que fait l'IA et pourquoi ;
• vous permettre de comprendre et de valider chaque changement important, plutôt que de simplement le subir ;
• éviter qu'un agent oublie ou contredise une décision déjà prise ;
• fonctionner de la même façon avec Claude Code, Codex, ou tout autre assistant IA.

Ce qu'AES ne fait pas :

• il n'écrit pas de code à votre place, ce rôle reste celui de votre agent IA ;
• il ne garantit pas que les déclarations d'un agent sont vraies ni que son travail est correct : il rend les dérives visibles, il ne les empêche pas ;
• il ne remplace pas l'apprentissage de la programmation, il rend le travail avec une IA plus organisé et plus transparent ;
• il n'impose aucune technologie particulière.

Trois questions d'auto-évaluation permettent de vérifier régulièrement, projet après projet, qu'AES tient ses promesses : voir la section Auto-évaluation de docs/PHILOSOPHY.md.

Validation réelle

AES a été testé sur un projet réel (site vitrine Next.js), avec Claude Code et Codex. Le socle ia/ réel qui en résulte est disponible dans examples/nextjs-project, le récit complet du test dans docs/Rapport-test-AES.

Version et licence

Version courante : voir SYSTEM.md. Historique complet : voir CHANGELOG.md.

Licence MIT, voir LICENSE.