gaurang-vedlogic/codebase-assessment

Codebase-Bewertung

Du bist der Prüfer. Dieses Skill führt dich von einer Codebasis zu einem kundenfertigen Bericht.

Das Ergebnis ist eine JSON-Datei (assessments/<slug>.assessment.json), die der Generator in jedes Berichtsformat rendert. Nichts anderes, was du schreibst, ist ein Arbeitsergebnis.

---

Bevor du beginnst

Lies diese in dieser Reihenfolge. Überspringe sie nicht – sie enthalten die Disziplin, die einen verteidigungsfähigen Bericht von einer Liste von Vermutungen unterscheidet.

1. METHODOLOGY.md – der vierstufige Kandidaten→Findungsprozess, Invarianten, Konfidenzniveaus, Abdeckungsdisziplin und was du nicht tun sollst. Dies ist die wichtigste Datei.
2. scoring/dimensions.md, scoring/maturity-model.md, scoring/criticality-priority.md, scoring/effort-estimation.md – wie Beobachtungen zu Zahlen werden.
3. rules/README.md – Regelformat und Stack-Erkennung.
4. schema/assessment.schema.json – der genaue Ausgabevertrag.
5. examples/industrifinans.assessment.json – ein vollständiges durchgearbeitetes Beispiel. Lies es für Form und Tiefe, niemals für den Inhalt. Diese Erkenntnisse gehören zu einem anderen System.

---

Vorgehen

Schritt 1 – Das Systemmodell erstellen

Bevor du nach Mängeln suchst. Schreibe in systemModel:

• Zweck & Domäne. Wofür das System gedacht ist und welche Daten es enthält. Dies legt den Schadensradius von allem fest, was du findest – derselbe Mangel ist in einer Finanzplattform kritisch und in einem Spielzeug-Tool nebensächlich.
• Akteure & Vertrauensgrenzen. Wer kann auf was zugreifen. Benenne dann den realistischen Angreifer – normalerweise einen authentifizierten Benutzer mit niedrigen Berechtigungen, nicht einen anonymen Internet-Angreifer.
• Wichtige Datenflüsse. Der Anfragepfad vom Eintritt bis zur Speicherung und der Authentifizierungspfad.
• 8–15 Invarianten – positive Aussagen darüber, was immer wahr sein muss, gemischt mit generischen und für diese Domäne spezifischen. Markiere jede als HOLDS, VIOLATED oder CHECK, während du sie überprüfst.

Dies zu überspringen macht jede spätere Schweregradbewertung willkürlich.

Schritt 2 – Den Stack erkennen und Regeln laden

Verwende die Markertabelle in rules/README.md § Stack-Erkennung. Lade jede Datei in rules/universal/ plus die passenden Stack-Pakete. In einem Monorepo erkenne pro Paket und lade die Vereinigung. Konsultiere rules/INDEX.md für die vollständige Katalogauflistung.

Schritt 3 – Den Code lesen

Lese in Ausführungsreihenfolge: Einstiegspunkt → Middleware → Router → Handler → Dienst → Datenzugriff. Mängel leben in den Lücken zwischen den Schichten, die dateiweises Lesen überspringt.

Über Kategorie-Greps hinaus verwende die Techniken in METHODOLOGY.md § Entdeckung – Geschwistervergleich, Identitätsverfolgung, Steuerung-zu-Konsequenz bei Fehlerpfaden, Grenzinventar. Sie finden, was Greps nicht finden.

Halte fest, was du liest, während du es liest; du brauchst es für coverage.

Schritt 4 – Widerlegen, bevor du berichtest

Jeder Kandidat durchläuft die vier Schritte in METHODOLOGY.md. Die meisten sterben bei Schritt 2 oder 3.

• Berichte die Überlebenden als Erkenntnisse, jede mit confidence.
• Halte die Todesfälle in refutedCandidates fest, mit dem Schritt, der sie getötet hat. Das ist kein Füllmaterial – es ist der Beweis, dass die Überprüfung gründlich war, und es kommt in den Bericht.
• Stufe herab, anstatt zu löschen, wenn etwas real, aber weniger schwerwiegend ist als zunächst behauptet.

Jede Erkenntnis benötigt evidence mit einer echten file und, wo du sie geöffnet hast, einer line. Wenn du nicht auf den Code zeigen kannst, ist es keine Erkenntnis – es gehört möglicherweise stattdessen in suggestions.

Konsolidiere wiederholte Instanzen in eine systemische Erkenntnis mit 2–3 repräsentativen Referenzen und einer instances-Anzahl. Eine systemische Erkenntnis schlägt acht Dubletten.

Schritt 5 – Bewerten

• Dimensionen. Die standardmäßigen sieben sind in scoring/dimensions.md. Das Set ist konfigurierbar – tausche eine aus, wenn es der Auftrag erfordert (z. B. „Qualitätssicherung / Testen“), behalte aber 5–8 bei und halte sie über ein Portfolio hinweg konsistent.
• Reifegrad. Beginne bei 3.0 und wende die Anpassungen in scoring/maturity-model.md an. Jede Dimension benötigt ein keyGap, das die spezifischen Erkenntnisse benennt, die die Punktzahl nach unten getrieben haben.
• Ziele. Realistische 6–12-Monatsziele. Niemals 5.0. Niemals unter dem aktuellen Wert.
• Kritikalität / Priorität / Phase. Leite sie aus scoring/criticality-priority.md ab – kopiere nicht die Regelstandard blind. Jede Abweichung kommt in rationale.
• Aufwand. Personentage aus scoring/effort-estimation.md. Verwende null, wenn wirklich unbekannt; erfinde niemals eine Zahl, um die Spalte zu füllen.

Schritt 6 – Festhalten, was gut ist

Fülle positivePosture mit verifizierten Stärken, die demselben Beweisstandard unterliegen. Ein Bericht aus reinen Negativaussagen wirkt wie ein Angriff und wird ignoriert; er versäumt es auch, dem Team zu sagen, was es während der Behebung schützen soll. „Keine SQL-Injection gefunden“ ist eine Abdeckungsaussage, keine Stärke.

Schritt 7 – Abdeckung und Fazit

• coverage – Methode, Größe (und wie du gezählt hast), was du intensiv gelesen hast, was du mit Grep abgesucht hast, was du nicht gelesen hast, und die Einschränkungen. Sei spezifisch. Das macht die Erkenntnisse falsifizierbar.
• verdict und releaseGates – nur wenn der Auftrag eine Entscheidung zur Bereitstellung beinhaltet. Gib das Fazit pro Umgebung an; die Produktion zu blockieren, während dev/test genehmigt wird, ist das normale Ergebnis. Schweregrad ist nicht dasselbe wie Tor – rechtfertige jedes.

Lassee verdict und releaseGates bei beratenden Bewertungen vollständig weg. Der Bericht passt sich an.

Schritt 8 – Schreiben, validieren, generieren

Setze meta.repoPath auf den absoluten Pfad des Repositorys, das du überprüft hast. Dadurch wird der Bericht an <repoPath>/architecture-review/ gesendet, anstatt in das output/ dieses Tools – das Arbeitsergebnis gehört zu dem Code, den es beschreibt. Lasse es nur weg, wenn der bewertete Code nicht auf der Festplatte ist.

Schreibe assessments/<slug>.assessment.json, dann:

npm run validate -- --input assessments/<slug>.assessment.json
npm run report   -- --input assessments/<slug>.assessment.json

npm run report schreibt auch den client-bezogenen Review-dashboard.html neben den Bericht, erstellt aus allen Bewertungen, die sich meta.client teilen. Schreibebe meta.client genau so wie in den anderen Bewertungen dieses Clients, sonst spaltet sich das Dashboard. Führe niemals npm run portfolio --all für ein Client-Arbeitsergebnis aus – es erstreckt sich über mehrere Clients und ist nur für den internen Gebrauch.

Behebe jeden Fehler. Lese jede Warnung und behebe entweder das zugrunde liegende Problem oder sei in der Lage, es zu rechtfertigen – die Warnungen kodieren die obigen Regeln (P0 außerhalb von Phase 1, P0-Inflation, fehlende Beweise, Phasen-1-Aufwandsdominanz, Ziele bei 5.0).

---

Ausgabedateien

Die gesamte Ausgabe ist HTML – in sich geschlossene Einzeldateien mit eingebetteten SVG-Diagrammen, druck-zu-PDF-freundlich.

Datei	Geschrieben nach	Zielgruppe
ARCHITECTURE-REVIEW-<app>.html	<repoPath>/architecture-review/	Alle. Ein Bericht pro Anwendung, der Führungsmaterial und vollständige technische Beweise abdeckt.
<slug>.assessment.json	<repoPath>/architecture-review/	Eine Kopie neben dem Bericht, damit das Repository die gesamte Aufzeichnung trägt. assessments/ bleibt kanonisch.
Review-dashboard.html	<repoPath>/architecture-review/	Zusammenfassung nur der Anwendungen dieses Clients, automatisch mit jedem Bericht generiert. Enthält nichts von anderen Clients.

Ein Bericht pro Anwendung. Der Architekturbericht beginnt mit Fazit, Ziel, Zusammenfassung für Entscheidungsträger und Bewertungstabelle, gefolgt von Systemmodell, Abdeckung, Beweisen und Fahrplan für Ingenieure.

Es gibt zwei optionale Ausgaben – eine komprimierte DECISION-BRIEF hinter --brief und eine Word-Version hinter --docx. Beide sind strikte Teilmengen. Generiere keine von beiden, es sei denn, der Benutzer fordert dies explizit an.

---

Harte Regeln

• Bearbeite niemals generiertes HTML von Hand. Ändere das JSON und generiere neu. Wenn der Bericht etwas Neues sagen muss, erweitere zuerst schema/assessment.schema.json und tools/.
• Kopiere niemals Erkenntnisse aus examples/. Es beschreibt das System eines anderen Kunden.
• Erfinde niemals einen Dateipfad oder eine Zeilennummer. Wenn du es nicht geöffnet hast, hast du keine Beweise.
• Melde niemals eine Regel als Erkenntnis. „Sollte Dependency Injection verwenden“ ist keine Erkenntnis. „OrderService konstruiert seinen eigenen DbContext in order.service.ts:31, daher kann es nicht ohne eine Live-Datenbank getestet werden“ ist es.
• Fülle den Fahrplan nicht auf. Jeder Personentag muss auf eine Erkenntnis zurückgehen.
• Nur Node – Python ist auf diesem Rechner nicht installiert.

Maßstab

Eine kleine Anwendung ergibt typischerweise 10–20 Erkenntnisse und 30–60 Personentage. Eine mittelgroße Plattform, 25–40 Erkenntnisse und 80–150 Personentage. Wenn deine Zahlen für die Systemgröße weit davon abweichen, ist wahrscheinlich etwas abgedriftet – normalerweise Schweregradinflation oder nicht konsolidierte Duplikate.