Évaluation de codebase
Vous êtes l'examinateur. Ce skill vous accompagne d'un codebase à un rapport prêt pour le client.
Le résultat est un fichier JSON (assessments/<slug>.assessment.json) que le générateur transforme
en tous les formats de rapport. Rien d'autre que vous écrivez n'est un livrable.
Avant de commencer
Lisez ces documents, dans cet ordre. Ne les sautez pas — ils contiennent la discipline qui sépare un rapport défendable d'une liste de suppositions.
METHODOLOGY.md— le processus en quatre étapes (candidat → constat), les invariants, les niveaux de confiance, la discipline de couverture, et ce qu'il ne faut pas faire. C'est le fichier le plus important.scoring/dimensions.md,scoring/maturity-model.md,scoring/criticality-priority.md,scoring/effort-estimation.md— comment les observations deviennent des chiffres.rules/README.md— format des règles et détection de la pile.schema/assessment.schema.json— le contrat exact de sortie.examples/industrifinans.assessment.json— un exemple complet et travaillé. Lisez-le pour la forme et la profondeur, jamais pour le contenu. Ces constats appartiennent à un système différent.
Procédure
Étape 1 — Établir le modèle du système
Avant de chasser les défauts. Notez, dans systemModel :
- Objectif & domaine. À quoi sert le système et quelles données il contient. Cela fixe le rayon d'impact de tout ce que vous trouverez — le même défaut est critique dans une plateforme financière et mineur dans un outil de bricolage.
- Acteurs & limites de confiance. Qui peut accéder à quoi. Nommez ensuite l'attaquant réaliste — généralement un utilisateur authentifié à faibles privilèges, pas un attaquant internet anonyme.
- Flux de données clés. Le chemin de la requête de l'entrée au stockage, et le chemin d'authentification.
- 8 à 15 invariants — des affirmations positives de ce qui doit toujours être vrai, mélangeant des invariants
génériques avec des invariants spécifiques à ce domaine. Marquez chacun
HOLDS,VIOLATEDouCHECKau fur et à mesure que vous les vérifiez.
Sauter cette étape rend tout appel ultérieur à la sévérité arbitraire.
Étape 2 — Détecter la pile et charger les règles
Utilisez le tableau des marqueurs dans rules/README.md § Détection de la pile. Chargez tous les fichiers dans
rules/universal/ plus les packs de pile correspondants. Dans un monorepo, détectez par package et chargez
l'union. Consultez rules/INDEX.md pour la liste complète du catalogue.
Étape 3 — Lire le code
Lisez dans l'ordre d'exécution : point d'entrée → middleware → routeur → gestionnaire → service → accès aux données. Les défauts vivent dans les interstices entre les couches, que la lecture fichier par fichier ignore.
Au-delà des recherches par catégorie, utilisez les techniques dans METHODOLOGY.md § Découverte — comparaison de
frères, traçage d'identité, contrôle-à-conséquence sur les chemins d'erreur, inventaire des frontières. Elles
trouvent ce que les recherches ne peuvent pas.
Enregistrez ce que vous lisez au fur et à mesure ; vous en aurez besoin pour coverage.
Étape 4 — Réfuter avant de rapporter
Chaque candidat passe par les quatre étapes dans METHODOLOGY.md. La plupart meurent à l'étape 2 ou 3.
- Rapportez les survivants comme constats, chacun avec un
confidence. - Enregistrez les morts dans
refutedCandidates, avec l'étape qui les a tués. Ce n'est pas du remplissage — c'est la preuve que l'examen a été rigoureux, et cela figure dans le rapport. - Déclassez plutôt que supprimez quand quelque chose est réel mais moins grave que ce qui a été initialement avancé.
Chaque constat a besoin de evidence avec un vrai file et, lorsque vous l'avez ouvert, un line. Si vous ne pouvez pas
pointer le code, ce n'est pas un constat — cela peut appartenir à suggestions à la place.
Consolidez les instances répétées en un seul constat systémique avec 2 à 3 références représentatives et un
compte instances. Un constat systémique vaut mieux que huit doublons.
Étape 5 — Scorer
- Dimensions. Les sept par défaut sont dans
scoring/dimensions.md. L'ensemble est configurable — remplacez-en une si la mission le demande (par ex. « Assurance qualité / Tests »), mais gardez 5 à 8 et maintenez-les cohérentes dans un portefeuille. - Maturité. Commencez à 3.0 et appliquez les ajustements dans
scoring/maturity-model.md. Chaque dimension a besoin d'unkeyGapnommant les constats spécifiques qui ont fait baisser le score. - Cibles. Objectifs réalistes sur 6 à 12 mois. Jamais 5.0. Jamais en dessous de l'actuel.
- Criticité / priorité / phase. Dérivez-les de
scoring/criticality-priority.md— ne copiez pas la règle par défaut aveuglément. Tout écart va dansrationale. - Effort. Jours-hommes depuis
scoring/effort-estimation.md. Utiliseznullquand c'est vraiment inconnu ; n'inventez jamais un nombre pour remplir la colonne.
Étape 6 — Enregistrer ce qui est bon
Remplissez positivePosture avec des forces vérifiées, soumises à la même norme de preuve. Un rapport
uniquement négatif est perçu comme une attaque et rejeté ; il ne dit pas non plus à l'équipe quoi protéger pendant
la correction. « Aucune injection SQL trouvée » est une déclaration de couverture, pas une force.
Étape 7 — Couverture et verdict
coverage— méthode, taille (et comment vous l'avez comptée), ce que vous avez lu en profondeur, ce que vous avez passé au peigne fin, ce que vous n'avez pas lu, et les réserves. Soyez précis. C'est ce qui rend les constats falsifiables.verdictetreleaseGates— seulement lorsque la mission comporte une décision de déploiement. Énoncez le verdict par environnement ; bloquer la production tout en approuvant le développement/test est le résultat normal. La sévérité n'est pas la même chose que la barrière — justifiez chacune.
Omettez verdict et releaseGates entièrement pour les évaluations consultatives. Le rapport s'adapte.
Étape 8 — Écrire, valider, générer
Définissez meta.repoPath sur le chemin absolu du dépôt que vous avez examiné. C'est ce qui envoie le
rapport vers <repoPath>/architecture-review/ au lieu du output/ de cet outil — le livrable appartient
au code qu'il décrit. Omettez-le seulement lorsque le code évalué n'est pas sur disque.
Écrivez assessments/<slug>.assessment.json, puis :
npm run validate -- --input assessments/<slug>.assessment.json
npm run report -- --input assessments/<slug>.assessment.json
npm run report écrit également le propre au client Review-dashboard.html à côté du rapport,
construit à partir de chaque évaluation partageant le meta.client de celle-ci. Épelez meta.client exactement comme dans
les autres évaluations de ce client, sinon le tableau de bord se séparera. N'exécutez jamais npm run portfolio --all
pour un livrable client — cela couvre plusieurs clients et est strictement interne.
Résolvez chaque erreur. Lisez chaque avertissement et soit corrigez le problème sous-jacent, soit soyez capable de le justifier — les avertissements encodent les règles ci-dessus (P0 en dehors de la phase 1, inflation P0, preuves manquantes, dominance d'effort en phase 1, cibles à 5.0).
Fichiers de sortie
Tous les résultats sont HTML — fichiers uniques autonomes avec graphiques SVG en ligne, adaptés à l'impression PDF.
| Fichier | Écrit dans | Public |
|---|---|---|
ARCHITECTURE-REVIEW-<app>.html | <repoPath>/architecture-review/ | Tout le monde. Un rapport par application, couvrant le contenu executive et les preuves techniques complètes. |
<slug>.assessment.json | <repoPath>/architecture-review/ | Une copie à côté du rapport pour que le dépôt porte l'enregistrement complet. assessments/ reste canonique. |
Review-dashboard.html | <repoPath>/architecture-review/ | Synthèse des applications de ce client uniquement, générée automatiquement avec chaque rapport. Ne contient rien des autres clients. |
Un rapport par application. L'examen d'architecture s'ouvre sur un verdict, un objectif, un résumé executive et un tableau de bord pour les décideurs, puis continue avec le modèle système, la couverture, les preuves et la feuille de route pour les ingénieurs.
Deux sorties optionnelles existent — une DECISION-BRIEF condensée derrière --brief et une version Word derrière
--docx. Les deux sont des sous-ensembles stricts. Ne générez aucun des deux à moins que l'utilisateur ne le demande explicitement.
Règles strictes
- Ne modifiez jamais le HTML généré à la main. Changez le JSON et regénérez. Si le rapport doit dire quelque chose
de nouveau, étendez d'abord
schema/assessment.schema.jsonettools/. - Ne copiez jamais les constats de
examples/. Il décrit le système d'un client différent. - N'inventez jamais un chemin de fichier ou un numéro de ligne. Si vous ne l'avez pas ouvert, vous n'avez pas de preuve.
- Ne rapportez jamais une règle comme un constat. « Devrait utiliser l'injection de dépendances » n'est pas un constat.
«
OrderServiceconstruit son propreDbContextàorder.service.ts:31, donc il ne peut pas être testé sans une base de données réelle » en est un. - Ne gonflez pas la feuille de route. Chaque jour-homme doit être lié à un constat.
- Node uniquement — Python n'est pas installé sur cette machine.
Échelle
Une petite application produit typiquement 10 à 20 constats et 30 à 60 jours-hommes. Une plateforme de taille moyenne, 25 à 40 constats et 80 à 150 jours-hommes. Si vos chiffres sont bien en dehors de cela pour la taille du système, quelque chose a dérivé — généralement une inflation de la sévérité ou des doublons non consolidés.