App builder
Une façon reproductible de transformer une idée en une application web déployée, testée et sécurisée, sur n'importe quelle pile. Ce guide a été distillé
à partir de la construction d'un projet réel de bout en bout (une arène de débat IA : Next.js, Drizzle, Better Auth, Vercel,
Turso, QStash, Vitest, Playwright), incluant toutes les erreurs commises en chemin. Le cœur (ce fichier,
profiles/, reference/) est indépendant de la pile ; ce qui est spécifique à un produit ou un framework se trouve
dans stacks/ et n'est lu que par les projets qui l'utilisent. Suivez-le ; n'improvisez pas le processus.
Commencez ici (à chaque session)
- Trouvez l'état du projet. Si
docs/plan.mdexiste, lisez-le d'abord : il enregistre le profil, les décisions prises et le jalon en cours. Continuez à partir de là ; ne reposez pas les questions déjà réglées. - Choisissez le profil (nouveaux projets uniquement). Demandez une fois, en termes simples :
« Voulez-vous être impliqué dans les choix techniques (code, hébergement, bases de données), ou dois-je m'en occuper
et ne vous demander que ce que l'application fait et à quoi elle ressemble ? »
- Impliqué → lisez
profiles/technical.md - Non impliqué → lisez
profiles/guided.mdEnregistrez la réponse dansdocs/plan.mdsous « Comment nous travaillons ». Le profil décide comment vous demandez et expliquez ; le processus et le niveau de qualité ci-dessous sont les mêmes pour les deux.
- Impliqué → lisez
- Lisez les notes de pile utilisées par le projet (voir « Notes de pile » ci-dessous).
- Lisez
reference/process.mdet suivez ses phases dans l'ordre. Chargez les autres références lorsqu'une phase y fait référence, pas toutes en même temps.
Notes de pile
stacks/ contient un fichier par technologie : étapes de configuration, pièges et correctifs appris sur des projets réels.
- Lesquelles lire : la section « Comment nous travaillons » du plan les liste (« Notes de pile : nextjs, vercel, … »).
Lisez exactement celles-ci au début de chaque session. Jetez également un œil aux manifestes du projet
(
package.json,vercel.json,docker-compose.yml…) et au système d'exploitation de l'utilisateur : s'ils utilisent quelque chose avec une note que le plan ne liste pas, lisez-la et ajoutez-la à la liste. Les nouveaux projets choisissent leurs notes une fois la pile décidée (phase 2 du processus). - Rendez-le immanquable : le fichier d'instructions du projet (
CLAUDE.mdouAGENTS.md, chargé à chaque session) demande de liredocs/plan.mdet ses notes de pile au début de chaque session, quelle que soit la demande. Sinon, une session qui ne déclenche jamais ce skill ne voit jamais la liste. Le skill vit à l'extérieur du dépôt, donc formulez-le pour qu'il se dégrade élégamment : le plan est autonome ; les notes de pile ne sont lues que « si le skill app-builder est installé ». - Avant d'adopter un nouveau service ou une nouvelle bibliothèque, vérifiez si une note existe.
- Où va une nouvelle leçon : si elle ne s'applique qu'en utilisant un produit, elle va dans la note de ce produit
(créez-en une s'il n'y en a pas :
stacks/<produit>.md, commençant par « Charger quand… »). Si elle s'applique partout, elle va dansreference/en termes génériques, avec le produit comme exemple et un pointeur vers sa note. Exemple : « réessayer une fois lorsqu'un service distant abandonne une connexion inactive » est dansreference/lessons.md; l'encapsulation de récupération libSQL qui le fait est dansstacks/turso-libsql.md. - Les notes enregistrent des faits datés (limites, listes de modèles, prix) tels qu'ils ont été appris : revérifiez-les.
Audit d'un projet existant
Lorsqu'on vous demande d'appliquer ce skill à un projet qui existe déjà (ou après un changement important), ne redémarrez pas le processus ; auditez et faites un rapport :
- Comparez
docs/plan.mdavectemplates/plan.mdet listez les sections manquantes. - Parcourez
reference/quality-gates.mdsection par section (sécurité, résilience, performances avec des mesures réelles et Lighthouse, checklist UI, accessibilité dans les deux thèmes, opérations et quotas). - Recherchez dans le code les anti-patrons de
reference/lessons.mdet des notes de pile du projet. - Posez les questions de démarrage auxquelles le projet n'a jamais répondu (ex. cycle de vie des comptes, abus de quota).
- Rapportez les lacunes classées (lacunes réelles, lacunes du plan, faible priorité, ce qui est déjà bon), avec des correctifs. Les lacunes que le propriétaire refuse vont dans le tableau « Risques acceptés » du plan. Ne changez rien tant que le propriétaire n'est pas d'accord.
Non-négociables (les deux profils)
- Phases et jalons : travaillez à travers les phases de
reference/process.md, en construisant de petits jalons qui se terminent chacun par un résultat exécutable, testé, démontré et validé avant que le suivant commence. Convenez de la liste des jalons avec l'utilisateur au démarrage et tenez-la à jour dansdocs/plan.md. - L'application fonctionne comme prévu : chaque jalon se termine par un résultat exécutable, démontré dans un vrai navigateur, avec le résultat montré à l'utilisateur.
- Résilience : chaque dépendance externe et processus de longue durée a une réponse planifiée à la question « et si ça échoue ? » (indisponible, lent, limité, planté en cours de route, délivré deux fois), enregistrée dans le tableau des modes de défaillance du plan, gérée dans le code, visible par les utilisateurs en termes simples, et testée.
- Performances : objectifs convenus (ex. les pages répondent en moins d'une seconde près du public), mesurés après le déploiement ; pas de travail inutile évident (requêtes non indexées, interrogation inutile, charges utiles surdimensionnées).
- Qualité : chaque jalon passe les contrôles de
reference/quality-gates.md(linting, types, tests unitaires, tests de bout en bout, build, CI, la checklist de revue UI). Aucun défaut majeur connu n'est laissé ouvert. - Sécurité : la checklist de sécurité dans
reference/quality-gates.mds'applique à chaque jalon, pas comme une dernière vérification. - Conception maintenable : les règles métier vivent dans des modules simples et sans framework, avec des tests unitaires ; les services externes sont derrière de petites coutures (un fichier à échanger) ; le plan et le README restent à jour.
- Tests au bon niveau : tests unitaires pour les règles, tests navigateur de bout en bout pour les parcours utilisateur, un faux scripté pour tout service externe payant ou lent (modèles IA, paiements).
- Coûts maîtrisés : le budget de l'utilisateur est explicite dans le plan ; tout ce qui peut coûter de l'argent a un plafond, un niveau gratuit sans carte de crédit, ou la propre clé de l'utilisateur.
- Les secrets ne passent jamais par le chat : l'utilisateur place les secrets dans
.env.localet le tableau de bord d'hébergement lui-même, ou une intégration de marketplace les injecte (voirreference/third-party-setup.md). - Vérifiez d'abord par vous-même : après un changement ou un déploiement, vérifiez le résultat vous-même (le navigateur, les logs et le statut de déploiement de la plateforme d'hébergement via sa CLI, un script sonde) avant de faire un rapport ou de demander à l'utilisateur de regarder. Ne demandez à l'utilisateur que ce qui nécessite son intervention : connexion, secrets, argent, approbations. Vérifier la production vous-même est la façon dont les bogues cachés remontent.
- Rapports honnêtes : dites ce qui a été vérifié et comment, ce qui ne l'a pas été, et ce qui a échoué. Ne prétendez jamais avoir effectué une vérification que vous n'avez pas faite.
- Vérifiez les faits qui changent : les prix, les limites des niveaux gratuits, les API et versions des bibliothèques sont vérifiés
par rapport aux sources actuelles (documents dans
node_modules, pages officielles) avant de s'y fier, et les sources sont citées.
Fichiers de ce skill
| Fichier | À utiliser pour |
|---|---|
profiles/technical.md | Comment travailler avec un propriétaire technique : quoi demander, quoi décider et annoncer |
profiles/guided.md | Comment travailler avec un propriétaire non technique : langage, choix, instructions pas à pas |
reference/process.md | Les phases, du démarrage à la passation, avec ce que chacune doit produire |
reference/quality-gates.md | Définition du fini, stratégie de test, résilience, performance, sécurité et checklists de revue UI |
reference/stack-defaults.md | Pile et architecture par défaut, niveaux de budget, quand s'écarter |
reference/environment.md | Vérification préalable et paramètres de permission qui suppriment la plupart des interruptions |
reference/third-party-setup.md | Comptes, secrets et configuration de l'hébergement/base de données/file d'attente avec un travail manuel minimal |
reference/lessons.md | Pièges concrets déjà rencontrés et leurs correctifs, en termes indépendants de la pile. Parcourez avant chaque jalon |
templates/plan.md | Squelette pour le docs/plan.md du projet |
Notes de pile (à lire uniquement lorsque le projet les utilise) :
| Fichier | Couvre |
|---|---|
stacks/nextjs.md | App Router Next.js, Cache Components, proxy, route handlers, server actions, formulaires React 19, serveur de développement |
stacks/vercel.md | Hébergement Vercel : régions, variables d'environnement et redéploiements, CLI, logs, configuration de build |
stacks/turso-libsql.md | SQLite/libSQL avec Drizzle, Turso : configuration, migrations, récupération distante, connexions inactives mortes |
stacks/better-auth.md | Better Auth : confirmation par email, réinitialisation de mot de passe, liaison de comptes, pièges de session |
stacks/upstash-qstash.md | Upstash QStash : serveur de développement local, signatures, délais, planifications, quota |
stacks/ai-providers.md | SDK AI Vercel, Groq, Google AI Studio, OpenRouter (flux de connexion, modèles gratuits), Ollama |
stacks/gmail-smtp.md | Envoi d'emails de compte via Gmail sans domaine |
stacks/playwright.md | Tests de bout en bout Playwright : sélecteurs, pages cachées, simulations locales |
stacks/github.md | Dépôt GitHub, CI Actions, connexion GitHub |
stacks/google-oauth.md | Connexion Google : projet Cloud, écran de consentement, branding, un client pour le local et la production |
stacks/windows.md | Développement sur Windows : Smart App Control, PowerShell, Docker, CLI |