# Compagnon IA

> Un seul fichier qui breffe un modèle d’IA sur l’écriture de programmes invités Apogee. Téléchargez-le, placez-le devant votre modèle, et celui-ci part des mêmes règles que celles qu’enseigne ce manuel.

Une bonne part du code écrit pour Apogee sera rédigée par un modèle. Un modèle qui n’a jamais vu Apogee écrira un programme invité plausible qui utilise `std`, alloue dans chaque boucle, recourt à un compteur atomique, se fie à ses données auxiliaires (*advice*) et consigne un `usize`. Le **Compagnon IA** est un seul fichier Markdown qui place d’emblée en tête tout ce qui prévient ces erreurs : ce qu’est un programme invité, les règles impératives, la surface publique complète du SDK avec ses signatures exactes, des motifs à copier, les erreurs et leurs corrections, et une liste de vérification pour la revue.

[Télécharger le compagnon](https://apogee.gweb3networks.com/docs/apogee-ai-companion.md)
Copier dans le presse-papiers
[Ouvrir en texte brut](https://apogee.gweb3networks.com/docs/apogee-ai-companion.md)

## Comment l’utiliser

- **Dans une conversation :** joignez le fichier, ou collez-le comme premier message, avant de décrire ce que vous voulez construire.
- **Dans un agent de programmation :** enregistrez-le à la racine de votre projet sous le nom que votre outil lit par convention, comme `AGENTS.md` ou `CLAUDE.md`, ou ajoutez-le aux règles de projet de l’outil. L’agent le lit alors au début de chaque session.
- **Pour la revue :** demandez au modèle de vérifier un programme invité ligne par ligne par rapport à la section 8 du fichier, la liste de vérification pour la revue.

Le fichier énonce ses règles sous forme de **MUST** et de **MUST NOT**, chacune accompagnée de sa raison, parce que les modèles suivent plus fidèlement des contraintes explicites et expliquées que des conventions qu’ils sont censés deviner.

## Ce qu’il contient

| Section | Contenu |
| --- | --- |
| 0. Instructions au modèle | Traiter les règles comme des contraintes impératives; ne jamais appeler une API qui n’est pas répertoriée; les preuves ne sont pas à divulgation nulle de connaissance |
| 1. Ce qu’est un programme invité | La cible, le hart unique, ce qu’énonce une preuve, l’identité du programme, les trois régions mémoire |
| 2. Règles impératives | 23 règles : la forme du programme, `usize` et les pointeurs sur 32 bits, l’allocateur linéaire, la pile, l’alignement, les opérations atomiques, l’absence de monde extérieur, les données auxiliaires, les limites des valeurs publiques, le jeu d’instructions, les flottants, les vérifications de dépassement, le coût |
| 3. Organisation et compilation | Les gabarits de crate, l’espace de travail des programmes invités, la commande de compilation, la séparation en une bibliothèque testée d’abord sur l’hôte |
| 4. Le SDK des programmes invités | Chaque fonction publique avec sa signature exacte, les faits sur l’environnement d’exécution et la carte mémoire, les opérations déléguées et les crates embarquées |
| 5. Motifs | Des données auxiliaires vérifiées par rapport à un hachage; une requête de Merkle et une transition d’état; la réutilisation des tampons; des données auxiliaires structurées; des condensés pour les sorties qui grandissent |
| 6. Côté hôte | L’exécution dans l’émulateur, le profilage, l’exportation de l’image, la preuve et la vérification, les hauteurs et les shards en cours de traitement |
| 7. Erreurs et corrections | Chaque statut de sortie, erreur fatale et refus que rencontre un programme invité, avec sa cause et sa correction |
| 8. Liste de vérification pour la revue | Onze vérifications à effectuer avant de proposer du code de programme invité |
| 9. Faits | L’ISA, le système de preuve, le niveau de sécurité, les limites et les résultats mesurés |

## Les règles sur lesquelles il insiste

Le compagnon reprend les règles de ce manuel, et trois d’entre elles méritent d’être soulignées, parce que ce sont celles que les modèles enfreignent le plus souvent :

- **Les pointeurs et `usize` font 32 bits.** Un modèle entraîné surtout sur du code 64 bits sérialise `usize` sans y penser à deux fois. Le programme invité et l’hôte divergent alors sur les octets.
- **Le tas ne libère jamais rien.** Le Rust idiomatique alloue sans retenue parce qu’un véritable allocateur rend la mémoire. Ici, chaque allocation est permanente pour le reste de l’exécution : le compagnon demande donc partout la réutilisation et `with_capacity`.
- **Les opérations atomiques se compilent, et n’ont pas leur place dans le code d’un nouveau programme invité.** Elles sont prises en charge pour la compatibilité avec les bibliothèques existantes. Sur un seul hart, elles ne synchronisent rien, et elles ajoutent une famille de circuits à la preuve.

## Pour les agents qui lisent directement cette documentation

- [`/llms.txt`](/llms.txt) répertorie chaque page de ce site en Markdown, pour les modèles qui lisent le Web.
- [`/docs/llms-full.txt`](https://apogee.gweb3networks.com/docs/llms-full.txt) contient toute la documentation anglaise, spécification comprise, en un seul fichier.
- Chaque page comporte un lien **Voir en Markdown** et un bouton **Copier en Markdown**, sous son titre et dans la colonne de droite.

L’anglais est la langue canonique de la documentation, et le compagnon est publié en anglais pour toutes les langues : c’est la langue que les modèles suivent le plus fidèlement, et celle dans laquelle la spécification est écrite.