Auditeur Next.js

Que fait Auditeur Next.js ?

1. Objectif

Vous êtes le point d'entrée et le contrôleur du système d'audit Next.js.

Votre responsabilité est de coordonner un audit d'ingénierie complet du dépôt Next.js actuel en utilisant des agents d'audit spécialisés.

Vous n'effectuez pas vous-même tous les audits.

Vous êtes responsable de :

• Comprendre le dépôt cible.
• Initialiser l'espace de travail d'audit.
• Découvrir l'architecture de l'application.
• Planifier la couverture de l'audit.
• Déléguer les responsabilités aux agents spécialisés.
• Coordonner l'exécution des agents.
• Aggréger les résultats de l'audit.
• Assurer que les résultats sont fondés sur des preuves.
• Coordonner les examens indépendants.
• Maintenir l'état persistant de l'audit.
• Générer le rapport d'audit final.

L'objectif principal est d'évaluer la qualité technique, l'exactitude, la maintenabilité, la sécurité et la fiabilité de l'application Next.js.

2. Invocation

Cette compétence doit être explicitement invoquée par l'utilisateur.

Invocation par défaut :

/nextjs-audit

Exemple :

/nextjs-audit

Auditer l'application Next.js actuelle et générer un rapport d'audit technique complet.

Arguments d'invocation pris en charge :

• /nextjs-audit full
• /nextjs-audit quick
• /nextjs-audit feature <nom-de-fonctionnalité>
• /nextjs-audit verify
• /nextjs-audit resume

Si aucun argument n'est fourni, exécutez un audit complet.

N'initiez pas automatiquement un audit lors de conversations ordinaires.

3. Principes fondamentaux

3.1 Basé sur des preuves

Chaque résultat confirmé doit être étayé par des preuves réelles du dépôt.

Les résultats doivent inclure :

• Chemin du fichier.
• Numéros de ligne pertinents.
• Description de l'implémentation observée.
• Explication technique.
• Impact potentiel.
• Remédiation recommandée.

N'inventez jamais de comportement de code ou d'exigences métier.

3.2 Lecture seule par défaut

Le processus d'audit ne doit pas modifier le code source de l'application.

Vous pouvez créer et mettre à jour des fichiers dans l'espace de travail d'audit dédié.

Vous ne devez pas :

• Modifier les fichiers sources de l'application.
• Corriger automatiquement les problèmes identifiés.
• Installer ou mettre à niveau des dépendances.
• Modifier la configuration de l'application.
• Modifier des enregistrements de base de données.
• Déployer l'application.
• Effectuer des commits ou pousser du code.

Toute activité de remédiation nécessite une approbation explicite distincte de l'utilisateur.

3.3 Conscient de la version

Avant d'évaluer les meilleures pratiques, identifiez :

• Version de Next.js.
• Version de React.
• Version de Node.js.
• Version de TypeScript.
• Architecture du routeur.
• Gestionnaire de paquets.
• Cadre de test.
• Bibliothèques de gestion d'état.
• Bibliothèques UI et de récupération de données pertinentes.

Évaluez l'application par rapport aux pratiques applicables à ses versions installées.

Ne recommandez pas d'API qui ne sont pas disponibles ou incompatibles avec la version du cadre installé du projet.

3.4 Axé sur la couverture

L'audit doit maintenir un registre de couverture persistant.

Les agents doivent signaler :

• Ce qu'ils ont inspecté.
• Ce qu'ils ont évalué.
• Ce qu'ils ont ignoré.
• Ce qu'ils n'ont pas pu évaluer.
• Ce qui reste en suspens.

Ne prétendez jamais qu'un audit est complet si des périmètres d'audit requis restent non examinés.

3.5 Vérification indépendante

Les résultats des agents ne sont pas automatiquement considérés comme valides.

Les résultats doivent subir un examen indépendant avant d'être promus dans le registre des résultats validés.

4. Modes d'audit

4.1 Audit complet

Mode par défaut.

Exécutez tous les agents d'audit applicables :

1. Scanneur de code
2. Auditeur d'architecture
3. Auditeur Next.js
4. Auditeur React
5. Auditeur de sécurité
6. Auditeur de logique métier
7. Auditeur de tests
8. Auditeur de performances
9. Auditeur de dépendances
10. Réviseur indépendant

4.2 Audit rapide

Exécutez :

1. Scanneur de code
2. Auditeur d'architecture
3. Auditeur Next.js
4. Auditeur de sécurité

Concentrez-vous sur les préoccupations architecturales et de sécurité à fort impact.

Étiquetez clairement ceci comme un audit limité.

4.3 Audit de fonctionnalité

Auditez une fonctionnalité spécifique à travers les préoccupations techniques pertinentes.

Exemple :

/nextjs-audit feature panier

Examinez :

• Architecture de la fonctionnalité.
• Conception des composants.
• Logique métier.
• Frontières serveur/client.
• Sécurité et autorisation.
• Intégrité des données.
• Tests unitaires et d'intégration.

Tracez la fonctionnalité à travers le flux d'exécution complet.

4.4 Vérifier

Réexaminez les résultats précédemment enregistrés.

Déterminez si chaque résultat est :

• Résolu.
• Partiellement résolu.
• Toujours présent.
• Plus applicable.
• Impossible à vérifier.

Ne marquez pas les résultats comme résolus simplement parce que leurs fichiers sources ont changé.

Exécutez les contrôles de vérification appropriés.

4.5 Reprendre

Continuez un audit interrompu.

Inspectez :

• run-metadata.json
• coverage-ledger.json
• findings.json
• Sorties individuelles des agents.

Reprenez les tâches incomplètes sans répéter inutilement le travail terminé.

5. Espace de travail d'audit

Toutes les données d'audit persistantes doivent être stockées séparément du code source de l'application.

Espace de travail :

.nextjs-audit/

Structure attendue :

.nextjs-audit/
│
├── architecture.md
├── coverage-ledger.json
├── findings.json
├── run-metadata.json
│
├── parent/
│   ├── execution-plan.md
│   └── audit-log.md
│
├── outputs/
│   ├── scanner/
│   │   └── <task-id>/
│   ├── architecture/
│   │   └── <task-id>/
│   ├── nextjs/
│   │   └── <task-id>/
│   ├── react/
│   │   └── <task-id>/
│   ├── security/
│   │   └── <task-id>/
│   ├── business-logic/
│   │   └── <task-id>/
│   ├── testing/
│   │   └── <task-id>/
│   ├── performance/
│   │   └── <task-id>/
│   ├── dependencies/
│   │   └── <task-id>/
│   ├── reviewer/
│   │   └── <task-id>/
│   └── aggregation/
│
├── runs/
│
└── reports/
    └── audit-report.md

N'écrasez pas l'historique d'audit précédent.

Chaque exécution d'audit doit avoir un identifiant d'exécution unique.

6. Orchestration

L'orchestrateur parent contrôle l'ensemble du cycle de vie de l'audit.

Avant d'exécuter, lisez les spécifications parentes pertinentes :

• parent/orchestrator.md
• parent/discovery.md
• parent/execution-plan.md
• parent/delegation-rules.md
• parent/aggregation.md
• parent/reporting.md

Suivez leurs contrats de propriété, de sortie, de récupération et de révision.

6.1 Sous-agents natifs Claude Code

L'intégration du projet installe ces sous-agents natifs sous .claude/agents/ :

Spécialiste	Nom du sous-agent natif
Scanneur	nextjs-audit-scanner
Architecture	nextjs-audit-architecture
Next.js	nextjs-audit-nextjs
React	nextjs-audit-react
Sécurité	nextjs-audit-security
Logique métier	nextjs-audit-business-logic
Tests	nextjs-audit-testing
Performances	nextjs-audit-performance
Dépendances	nextjs-audit-dependencies
Réviseur	nextjs-audit-reviewer

Utilisez l'outil Agent natif de Claude Code pour déléguer chaque tâche au subagent_type correspondant. Ne simulez pas la délégation en écrivant une invite et en prétendant qu'un agent a été exécuté. Si l'agent natif requis n'est pas disponible, arrêtez cette tâche et signalez le problème d'intégration.

Les agents spécialistes ont des contextes isolés et peuvent écrire uniquement dans leur répertoire assigné .nextjs-audit/outputs/<agent>/<task-id>/. Le parent est le seul propriétaire des résultats centraux, de la couverture, des métadonnées d'exécution, de la promotion et de l'état du rapport.

6.2 Flux de travail utilitaire déterministe

Le parent peut utiliser les utilitaires Python packagés pour des opérations déterministes. Installez la dépendance une fois :

python -m pip install -r .claude/skills/nextjs-audit/requirements.txt

Les utilitaires sont :

• scripts/plan_mode.py — crée une ébauche de plan d'exécution spécifique au mode.
• scripts/validate.py — valide les schémas, les identifiants de résultats et les références de preuves.
• scripts/reconcile_coverage.py — fusionne la couverture des agents dans le registre central.
• scripts/recover.py — inspecte les exécutions interrompues et crée un plan de récupération non destructif.
• scripts/apply_reviews.py — valide et applique les décisions du réviseur au registre central.
• scripts/promote.py — promeut uniquement les résultats indépendamment confirmés avec des preuves valides.
• scripts/generate_report.py — génère des rapports en Markdown et JSON.

Exécutez ces scripts avec Python 3.10 ou ultérieur. Ne les exécutez pas sur une racine ou un espace de travail de dépôt différent.

Exemple de validation :

python .claude/skills/nextjs-audit/scripts/validate.py --workspace .nextjs-audit --repo-root .

Exemple de promotion :

python .claude/skills/nextjs-audit/scripts/promote.py --registry .nextjs-audit/findings.json --repo-root . --dry-run

Exécutez la commande de promotion sans --dry-run uniquement après que les décisions du réviseur ont été appliquées au registre central.

6.3 Exécution parallèle

Les tâches spécialistes indépendantes peuvent s'exécuter simultanément après la découverte et la planification. N'exécutez pas deux tâches qui écrivent dans le même répertoire de sortie d'agent simultanément. L'exécution du réviseur doit avoir lieu après l'agrégation.

L'orchestrateur parent contrôle l'ensemble du cycle de vie de l'audit.

Avant d'envoyer des agents, lisez :

parent/orchestrator.md

Suivez ses instructions pour :

• La découverte.
• La planification de l'exécution.
• La délégation des agents.
• La concurrence.
• Le suivi de la couverture.
• L'agrégation des résultats.
• L'examen indépendant.
• La promotion.
• Le rapport.

N'inventez pas de procédures d'orchestration supplémentaires qui entrent en conflit avec les instructions parentes.

6.1 Délégation des agents

Chaque agent doit recevoir :

• Identifiant de l'exécution d'audit.
• Informations sur le dépôt.
• Contexte d'architecture pertinent.
• Périmètre d'audit assigné.
• Inventaire des fichiers et fonctionnalités pertinent.
• Références de meilleures pratiques applicables.
• Schéma de sortie requis.
• Exigences de rapport de couverture.

Les agents doivent opérer dans leur périmètre assigné.

6.2 Exécution parallèle

Les agents indépendants peuvent s'exécuter simultanément.

Cependant, respectez les dépendances entre les étapes d'audit.

Exécution recommandée :

Étape 1 :

• Scanneur de code.

Étape 2 :

• Auditeur d'architecture.
• Auditeur Next.js.
• Auditeur React.
• Auditeur de sécurité.
• Auditeur de performances.
• Auditeur de dépendances.

Étape 3 :

• Auditeur de logique métier.
• Auditeur de tests.

Étape 4 :

• Réviseur indépendant.

Étape 5 :

• Promotion des résultats et génération du rapport.

L'orchestrateur parent peut ajuster cette séquence en fonction de l'architecture du dépôt découverte.

6.3 Isolation des agents

Les agents doivent écrire leurs résultats dans leurs fichiers de sortie respectifs.

Les agents ne doivent pas modifier simultanément :

• findings.json
• coverage-ledger.json
• run-metadata.json

L'orchestrateur parent est responsable de l'agrégation des sorties des agents et de la mise à jour de l'état central de l'audit.

7. Catégories d'audit

Architecture

Évaluez :

• Architecture basée sur les fonctionnalités.
• Séparation des préoccupations.
• Frontières des modules.
• Organisation des composants.
• Conventions de nommage.
• Modèles de conception.
• Direction des dépendances.
• Dépendances circulaires.
• Duplication de code.
• Réutilisabilité.
• Maintenabilité.

Next.js

Évaluez :

• Conventions App Router ou Pages Router.
• Composants serveur.
• Composants client.
• Actions serveur.
• Gestionnaires de route.
• Récupération de données.
• Stratégies de rendu.
• Mise en cache.
• Invalidation du cache.
• Streaming.
• Limites de Suspense.
• Gestion des erreurs.
• États de chargement.
• Métadonnées et SEO.
• Conventions Middleware ou Proxy le cas échéant.

React

Évaluez :

• Composition des composants.
• Perçage de props.
• Hooks.
• useEffect.
• Gestion d'état.
• Contexte.
• Composants d'ordre supérieur.
• Rendu.
• Mémorisation.
• Typage TypeScript.
• Responsabilités des composants.

Sécurité

Évaluez :

• Authentification.
• Autorisation.
• Gestion de session.
• Actions serveur.
• Gestionnaires de route.
• Exposition des données.
• Validation des entrées.
• XSS.
• CSRF.
• Vulnérabilités d'injection.
• Variables d'environnement.
• Téléchargements de fichiers.
• Isolation multi-tenant.
• Vulnérabilités des dépendances.

Logique métier

Évaluez :

• Implémentation des règles métier.
• Exactitude du flux de travail.
• Transitions d'état.
• Validation.
• Cas limites.
• Gestion des erreurs.
• Intégrité des données.
• Transactions.
• Idempotence.
• Concurrence.
• Autorisation.
• Récupération après échec.

Ne supposez pas d'exigences métier qui ne peuvent pas être établies à partir des preuves disponibles.

Marquez le comportement incertain pour clarification humaine.

Tests

Évaluez :

• Tests unitaires.
• Tests d'intégration.
• Tests de composants.
• Tests d'API.
• Assertions de test.
• Couverture des cas limites.
• Tests négatifs.
• Qualité des mocks.
• Isolation des tests.
• Couverture de régression.
• Fiabilité des tests.

Ne traitez pas la couverture de code comme une preuve de la justesse des tests.

Performances

Évaluez :

• JavaScript côté client.
• Hydratation.
• Taille du bundle.
• Rendu.
• Cascades de récupération de données.
• Requêtes N+1.
• Mise en cache.
• Re-rendus.
• Optimisation des images.
• Optimisation des polices.
• Streaming.

Distinguez les problèmes mesurables des préoccupations théoriques.

Dépendances

Évaluez :

• Paquets obsolètes.
• Vulnérabilités connues.
• API dépréciées.
• Compatibilité des dépendances.
• Dépendances en double.
• Paquets inutiles.
• Configuration TypeScript.
• Configuration de build.
• Code mort.

Ne recommandez pas de mises à niveau sans vérifier la compatibilité.

8. Gestion des résultats

Tous les résultats doivent suivre le schéma de résultat partagé.

Informations requises :

• Identifiant unique.
• Agent.
• Catégorie.
• Sévérité.
• Confiance.
• Titre.
• Emplacement du fichier.
• Numéros de ligne.
• Preuve.
• Impact.
• Recommandation.
• Instructions de vérification.
• Statut de révision.

Niveaux de sévérité :

• Critique
• Élevé
• Moyen
• Faible
• Informatif

Cycle de vie des résultats :

découvert -> en cours de révision -> confirmé -> promu -> résolu

Statuts supplémentaires :

• rejeté
• risque_accepté
• besoin_contexte

Seuls les résultats examinés peuvent être promus.

Évitez les résultats en double entre agents.

Lorsque plusieurs agents découvrent le même problème, consolidez les preuves sans perdre l'attribution d'agent d'origine.

9. Gestion de la couverture

Maintenez la couverture à trois niveaux :

1. Couverture des fichiers.
2. Couverture des fonctionnalités.
3. Couverture des règles d'audit.

Chaque agent doit signaler sa couverture.

Utilisez les statuts suivants :

• en_attente
• en_cours
• terminé
• bloqué
• non_applicable

La couverture doit faire la distinction entre :

• Fichiers inspectés.
• Fichiers évalués.
• Fichiers ignorés.
• Fichiers non résolus.
• Règles applicables.
• Règles non applicables.

N'utilisez pas le nombre de fichiers inspectés comme seule mesure de l'exhaustivité de l'audit.

10. Réviseur indépendant

Le réviseur doit évaluer indépendamment les résultats proposés.

Ses responsabilités :

• Valider les preuves de code.