Compétence de planification de projet Next.js (nextjs-plan)
Une compétence d'orchestration structurée pour planifier des applications Next.js App Router. Lorsqu'elle est invoquée, elle extrait les spécifications techniques des fichiers de l'espace de travail existant, mène un entretien ciblé sur les besoins utilisateur, et produit des spécifications de projet canoniques (docs/project.json), des registres de code type-safe dans lib/, des documents de design dans docs/design/, et une feuille de route d'implémentation modulaire en 7 phases dans docs/plan/.
Aperçu du flux de travail
flowchart TD
Invoke["Invoquer /nextjs-plan"] --> Step1["1. Inspection automatique de l'espace de travail<br/>(Extraire dépendances, arborescence des répertoires, styles, configurations, routes)"]
Step1 --> Step2["2. Entretien d'évaluation sur les pages et les besoins<br/>(Pages ➔ Sections ➔ Composants)"]
Step2 --> Step3["3. Génération des spécifications canoniques<br/>(docs/project.json et registres lib/)"]
Step3 --> Step4["4. Documentation de la stratégie et des systèmes de design<br/>(docs/design/ 01-stratégie, 02-plan-du-site, 03-tokens)"]
Step4 --> Step5["5. Génération du plan d'implémentation modulaire en 7 phases<br/>(docs/plan/ README.md et fichiers phases 01-07)"]
Step5 --> Step6["6. Achèvement et clôture<br/>(Présenter le tableau de bord récapitulatif ; NE PAS invoquer de compétences en aval)"]
Architecture de répertoire de projet standardisée
├── lib/ # Source de vérité du code Next.js type-safe
│ ├── routes.ts # Registre centralisé des routes et constructeurs de chemins
│ ├── site-config.ts # Métadonnées du site, biographie auteur, liens sociaux
│ └── utils.ts # Assistant cn Tailwind
├── docs/ # Architecture, planification et justifications de design
│ ├── project.json # Spécifications canoniques lisibles par machine
│ ├── plan/ # Feuille de route d'implémentation modulaire en 7 phases
│ │ ├── README.md # Tableau de bord principal : suivi de progression et index des phases
│ │ ├── 01-discovery-and-architecture.md
│ │ ├── 02-environment-and-cicd.md
│ │ ├── 03-system-health-probe.md
│ │ ├── 04-core-foundations.md
│ │ ├── 05-pages-and-components.md
│ │ ├── 06-server-functions-and-metadata.md
│ │ └── 07-integrations-and-release.md
│ ├── design/ # Spécifications UX/UI et écrans
│ │ ├── 01-strategy-brief.md # Objectif, personas, buts, KPI, références
│ │ ├── 02-sitemap-and-routes.md # Inventaire des pages, hiérarchie des sections, matrice de rendu
│ │ ├── 03-ui-design-tokens.md # Tokens CSS sémantiques, typographie, primitives de composants
│ │ └── components/ # Spécifications de design des composants et captures d'écran Stitch
│ └── adr/ # Architecture Decision Records
Runbook d'exécution étape par étape
1. Inspection automatique de l'espace de travail (sans interruption)
[!IMPORTANT] Inspecter d'abord, demander ensuite. Ne jamais demander à l'utilisateur des informations qui peuvent être déduites directement des fichiers de l'espace de travail.
- Analyser le contexte de l'espace de travail : Inspecter
package.json, les lockfiles (pnpm-lock.yaml,bun.lockb), la structure de routage (app/vssrc/app/), le répertoire des composants,app/globals.css, les bibliothèques UI (shadcn/ui,lucide-react, animations), la configurationnext-intl(dossier racinemessages/), les routes existantes (page.tsx,route.ts), et les configurations de test/Docker. - Pour la liste de contrôle complète d'inspection, consulter workspace-inspection.md.
2. Entretien d'évaluation utilisateur (Pages ➔ Sections ➔ Composants)
- Mener un entretien d'évaluation adaptatif : Engager l'utilisateur dans des rounds structurés en utilisant la méthodologie de la frontière d'évaluation. Numéroter chaque question et fournir des réponses recommandées.
- Séquence d'évaluation obligatoire :
- Évaluation des pages : Énumérer toutes les pages web requises et les routes URL cibles.
- Évaluation des sections : Pour chaque page, identifier toutes les sections de contenu de haut en bas.
- Évaluation des composants : Pour chaque section, définir tous les composants UI requis.
- Demandes principales : Énoncé du problème, personas cibles, authentification, couche de données/ORM, paramètres régionaux i18n et RTL, tonalité esthétique visuelle, et cible de déploiement.
- Pour les modèles d'entretien et les règles de décision, consulter grilling-interview.md.
3. Générer les spécifications canoniques et le code type-safe
- Créer
docs/project.json: Renseigner les métadonnées techniques (gestionnaire de paquets, répertoires de composants, styles, bibliothèques UI/animation/test, langues supportées, chemins de dictionnaires). Consulter project-schema.md et déployer project.json.template. - Créer
lib/routes.ts: Générer un registre de routes type-safe à partir de routes.ts.template. - Créer
lib/site-config.ts: Générer un profil et des métadonnées de site centralisés à partir de site-config.ts.template.
4. Documenter la stratégie de design dans docs/design/
- Créer
docs/design/01-strategy-brief.md: Déployer 01-strategy-brief.md.template. - Créer
docs/design/02-sitemap-and-routes.md: Déployer 02-sitemap-and-routes.md.template. - Créer
docs/design/03-ui-design-tokens.md: Déployer 03-ui-design-tokens.md.template.
5. Générer la feuille de route d'implémentation modulaire en 7 phases (docs/plan/)
- Échafauder le répertoire
docs/plan/: Déployer les fichiers de plan modulaires en utilisant les modèles dans resources/templates/plan/ :docs/plan/README.md(Tableau de bord de progression principal)docs/plan/01-discovery-and-architecture.md(Phase 1)docs/plan/02-environment-and-cicd.md(Phase 2)docs/plan/03-system-health-probe.md(Phase 3 : sonde de vivacité/api/health)docs/plan/04-core-foundations.md(Phase 4 : variables d'environnement, i18n, tokens de thème, layouts, OTel)docs/plan/05-pages-and-components.md(Phase 5 : listes de contrôle canoniques des pages et composants avec SEO et fichiers de support)docs/plan/06-server-functions-and-metadata.md(Phase 6 : Actions Serveur, routes API, SEO global)docs/plan/07-integrations-and-release.md(Phase 7 : Intégrations et mise en production)
- Source unique de vérité avec fichiers obligatoires au niveau page : La Phase 5 (
05-pages-and-components.md) est la liste de contrôle canonique exclusive pour les pages et les composants. Pour chaque page, imposer des sous-tâches de liste de contrôle pourpage.tsx,loading.tsx,error.tsx,generateMetadata,JSON-LD Schema, etgenerateStaticParams()(pour les routes dynamiques). - Règle d'achèvement des pages : Dans la Phase 5, marquer un élément de page comme
- [x]si et seulement si toutes ses sous-tâches de composants et les tâches SEO/de support au niveau page sont terminées. - Consulter plan-checklist-structure.md pour les directives complètes des phases.
6. Récapitulatif et porte d'achèvement
- Présenter à l'utilisateur un rapport récapitulatif concis détaillant les résultats de l'espace de travail, les spécifications dans
docs/project.json, et la feuille de route dansdocs/plan/README.md. - NE PAS invoquer automatiquement des compétences Next.js en aval. Conclure l'exécution et permettre à l'utilisateur de réviser le plan.
Cas limites et pièges IA connus
[!WARNING]
- Enchaînement de commandes : Ne jamais exécuter de commandes composées avec
&&,||ou;sur une seule ligne. Toujours exécuter les commandes terminal individuellement.- Demander avant d'inspecter : Ne pas demander à l'utilisateur des informations de base qui peuvent être lues directement dans
package.jsonou les listes de répertoires.- Séquencement inversé des jalons : La sonde de santé (
/api/health) appartient à la Phase 3, suivie des Fondations de base (i18n, Thème, Layouts, OTel) dans la Phase 4 avant l'implémentation des pages/composants.- Omission des fichiers au niveau page : Lors de la rédaction des listes de contrôle de la Phase 5, ne jamais omettre les tâches pour
loading.tsx,error.tsx,generateMetadata, ou le schéma JSON-LD pour une page.- Duplication de la liste des pages : Conserver tout le suivi des pages et des composants strictement dans
docs/plan/05-pages-and-components.md.- Validation prématurée des pages : Une page dans la Phase 5 doit rester
- [ ]jusqu'à ce que chaque composant enfant et fichier de support au niveau page soit terminé.- Emplacement incorrect des dictionnaires : Dans les configurations i18n de Next.js, les dictionnaires sont situés dans
messages/à la racine (par exemple,messages/en.json), jamais dansapp/dictionaries.- Déclenchement de compétences en aval : Ne pas déclencher automatiquement des compétences d'implémentation ou de style après avoir terminé le plan ; s'arrêter et attendre les directives de l'utilisateur.
Schéma du récapitulatif de sortie
À la fin de la phase de planification, présenter le récapitulatif dans ce format :
### Planification du projet Next.js terminée
- **Spécifications canoniques** : `[docs/project.json](file:///...)`
- **Registres type-safe** : `[lib/routes.ts](file:///...)` | `[lib/site-config.ts](file:///...)`
- **Spécifications de design et de stratégie** : `[docs/design/01-strategy-brief.md](file:///...)`, `[docs/design/02-sitemap-and-routes.md](file:///...)`, `[docs/design/03-ui-design-tokens.md](file:///...)`
- **Tableau de bord de la feuille de route modulaire** : `[docs/plan/README.md](file:///...)`
- **Pages identifiées** : X routes totales cartographiées
- **Composants identifiés** : Y composants totaux catalogués dans Z sections
- **Phases terminées** : N / 7 phases vérifiées
_Planification terminée. Consulter `docs/plan/README.md` pour procéder à la conception des composants ou à l'implémentation._
Guides de référence et modèles
- Guide d'inspection de l'espace de travail — Liste de contrôle de découverte du codebase avant entretien.
- Guide d'entretien d'évaluation — Protocole de questionnement en plusieurs rounds et domaines d'investigation.
- Référence du schéma de projet — Champs de spécification et critères de validation pour
docs/project.json. - Référence de la structure de plan — Structure de la feuille de route modulaire en 7 phases et règles pages-composants.
- Modèle JSON du projet — Schéma de démarrage pour
docs/project.json. - Modèles de plan modulaire — Modèles de démarrage pour
docs/plan/. - Modèle TypeScript des routes — Définitions de routes type-safe pour
lib/routes.ts. - Modèle de configuration du site — Profil de site centralisé pour
lib/site-config.ts. - Modèle de note de stratégie — Modèle pour
docs/design/01-strategy-brief.md. - Modèle de plan du site et des routes — Modèle pour
docs/design/02-sitemap-and-routes.md. - Modèle de jetons de design UI — Modèle pour
docs/design/03-ui-design-tokens.md. - Modèle d'exemple de variables d'environnement — Modèle source unique de vérité pour
.env.example(renommé en.envpour les déploiements en production). - Modèle d'environnement de développement — Variables de développement par défaut pour
.env.development(développement local, gitignoré).