Assistants IA
Les assistants de code connaissent bien mieux TanStack Query que Qora. Livrés à eux-mêmes, ils écrivent du code TanStack avec une syntaxe Dart : queryFn au lieu de fetcher, cacheTime au lieu de gcTime, state.when(...), qui n'existe pas. Deux fichiers corrigent l'essentiel : un court fichier de règles que l'assistant charge à chaque session, et la documentation dans un format qu'il sait lire.
1. Ajouter les règles Qora au projet
qora-rules.md est un résumé d'une page écrit pour les assistants. Il contient la configuration, le rendu des états, le comportement hors-ligne, les mutations et l'invalidation, ainsi qu'un tableau des erreurs les plus fréquentes des assistants, chacune avec la forme Qora correcte. Le fichier est en anglais, la langue que les assistants suivent le mieux.
Téléchargez-le à la racine du projet :
curl -o qora-rules.md https://qora.meragix.dev/qora-rules.md
Puis référencez-le depuis le fichier d'instructions que lit votre assistant :
| Assistant | Où |
|---|---|
| Claude Code | Ajouter la ligne @qora-rules.md dans CLAUDE.md |
| Cursor | L'enregistrer sous .cursor/rules/qora.mdc avec l'en-tête ci-dessous |
| GitHub Copilot | Ajouter son contenu à .github/copilot-instructions.md |
Codex et les autres outils qui lisent AGENTS.md | Ajouter son contenu à AGENTS.md, ou demander dans AGENTS.md de lire qora-rules.md |
Pour Cursor, le fichier commence par :
---
description: Qora server-state library rules
globs: "**/*.dart"
alwaysApply: false
---
Téléchargez-le à nouveau quand vous mettez Qora à jour : il indique la version qu'il décrit.
2. Donner la documentation à l'assistant
La documentation est publiée dans des formats destinés aux modèles de langage :
| URL | Contenu |
|---|---|
/llms.txt | Index de toutes les pages, avec une description d'une ligne |
/llms-full.txt | Toute la documentation anglaise dans un seul fichier |
/raw/en/<section>/<page>.md | N'importe quelle page en Markdown, par exemple /raw/en/getting-started/quick-start.md |
Pour une tâche précise, donnez la ou les deux pages utiles plutôt que le fichier complet : un assistant suit mieux un contexte court et précis qu'un contexte long.
3. Vérifier ce qu'il a écrit
- Lancez
dart analyze. Une méthode ou un paramètre inventé est une erreur de compilation : c'est le moyen le plus rapide de repérer une habitude TanStack. - Cherchez un
switchsurQoraState. Un code qui testestate.isLoadingavant de lire la donnée perd souvent lepreviousDataconservé pendant les refetchs et les erreurs. - Testez hors-ligne. Le code généré à partir d'autres bibliothèques s'attend souvent à un
Failureou unInitialsans réseau. Qora se met en pause :LoadingavecFetchStatus.paused.
En cas de doute, comparez avec le Démarrage rapide, qui fonctionne tel quel, ou demandez à l'assistant de lire Venant de TanStack Query, qui fait correspondre chaque option.