codebase-design (mattpocock/skills)
Liefert eine gemeinsame Sprache für tiefe Module mit kleinen Schnittstellen und klaren Nahtstellen.
codebase-design: Gibt Architektur-Reviews das Vokabular für Tiefe und eine klarere Struktur (Kontrolle 3.2, Skill 3.9, One-Liner 4.5) bei 1.1x den Tokens, fand aber nicht mehr der eingebauten Probleme als der One-Liner-Prompt
Codex CLI · gpt-6-astra
23.6 / 30
Lift gegenüber ohne Skill: +0.71 · Situativ · 18 Läufe
Situativ: der Lift +0.71 liegt unter +1.0. Für „Empfohlen“ sind insgesamt 22/30, eine Ausgabequalität von 3.5 und ein Lift von +1.0 nötig.
SOTA
BestandenGetestet mit Codex.
Gilt für Codex, Claude Code
Codex CLI 0.166 (SOTA-Stufe): 18 bewertete Läufe. Ein Bestehen hier deckt gemäß unserer Stufenregel auch Claude Code ab; über die zweite Stufe sagt es nichts aus.
Punktzahlen
Jede Dimension reicht von 0 bis 5, und die sechs ergeben zusammen die Gesamtpunktzahl von 30. 5 ist in jeder Dimension besser. Kosten 5 bedeutet günstig und schnell. Installation 5 bedeutet einfach.
- Trigger-Zuverlässigkeit
- 5.0
- Lift gegenüber ohne Skill
- 2.7
- Ausgabequalität
- 3.9
- Token- und Zeitkosten
- 4.0
- Installation und Portabilität
- 4.0
- Sicherheit
- 4.0
Sicherheitsprüfung
SicherStatischer Scan: 0 CRITICAL / 0 HIGH / 0 MEDIUM. Manuelle Prüfung: Sicher in einer Sandbox ohne Netzwerk auszuführen (keine Befunde). Ein sauberer Scan beweist nicht, dass ein Skill sicher ist.
Installieren
npx skills@latest add mattpocock/skills --skill codebase-design
Fixierter Commit: 4ae2317ddb22b046e26455e4f9c9b3aaaf62212d
Getestet: 2026-11-02
Was wir getestet haben
- Architektur-Scan des gesamten Repos — Dieses kleine Shop-Backend auf Architekturverbesserungen prüfen: Wo würde eine Umstrukturierung den Code leichter änderbar und leichter testbar machen? Die Befunde als eigenständigen HTML-Bericht namens report.html in diesem Ordner schreiben (keinen Browser öffnen und keinen Se…
- Nur Payments und Inventory — Nur die Payment- und Inventory-Teile dieses Backends betrachten und sagen, welche Umstrukturierungen sich lohnen. Die Befunde als eigenständigen HTML-Bericht namens report.html in diesem Ordner schreiben (keinen Browser öffnen und keinen Server starten) und keine Co…
- Warum ist place_order schwer zu testen? — Es fühlt sich mühsam an, einen ordentlichen Test für place_order in diesem Backend zu schreiben. Warum, und welche Umstrukturierung würde das beheben? Keine Dateien ändern; in der letzten Nachricht antworten.
Vorteile
- Hebt den Mittelwert von 3.21 auf 3.92 gegenüber ohne Skill (+0.71).
- Der Skill wurde erkannt, ohne genannt zu werden: Skill-Datei in 6/6 Treatment-Läufen gelesen.
Nachteile
- Ein Ein-Satz-Prompt erzielte 4.54 gegenüber 3.92 mit dem Skill (-0.63).
- n=2 pro Aufgabe und Variante; Unterschiede unter etwa 1 Punkt sind Rauschen.
Bewertung
Codex CLI 0.166 (gpt-6-astra, niedriges Reasoning) auf einem dedizierten Windows-Test-PC, einem frischen temporären Projekt und temporären HOME/TMPDIR/Caches pro Lauf; Skill installiert (Treatment) oder nicht vorhanden (Kontrolle) oder nicht vorhanden mit der Kernanforderung des Skills in einem an den Prompt angehängten Satz (One-Liner-Gruppe); 2 Läufe pro Gruppe und Aufgabe; Netzwerk aus; Schreiben nach /tmp blockiert. Die Prompts nennen den Skill nie (außer der unten genannten Formulierung). Ein kleines Shop-Backend mit sechs eingebauten Reibungspunkten (flache Validatoren und Geld-Wrapper, ein durchreichender Inventory-Service, ein einzelner Payment-Adapter, duplizierte Logik und weitere). Aufgaben: einen HTML-Bericht über Architekturverbesserungen schreiben, einen Bericht nur zu Payment und Inventory, und „warum ist place_order schwer zu testen und wie es zu beheben wäre“ (Antwort im Chat). Die Prompts nennen keine Designbegriffe. Der One-Liner nennt die Tiefenidee und die Dinge, die markiert werden sollen.
Drei-Arm-Vergleich
| Variante | Durchschnittsnote (0-5) | Tokens pro Lauf |
|---|---|---|
| Ohne Skill | 3.21 | 119k |
| Ein-Satz-Prompt | 4.54 | 114k |
| Mit Skill | 3.92 | 133k |
Gemessen mit Codex CLI über 18 Läufe, bewertet durch regelbasierte Prüfungen ohne LLM-Richter. Gesamt 23.6 / 30, Urteil Situativ.
Urteil: Situativ (23.6 / 30). Quelle: mattpocock/skills, skills/engineering/codebase-design, gepinnt auf Commit 4ae2317. Installation: npx skills@latest add mattpocock/skills --skill codebase-design. Lizenz: MIT (Repo-LICENSE).
Worum es geht
Der Skill codebase-design (mattpocock/skills): ein Ansatz, Architektur nach Modultiefe zu bewerten: tiefe Module mit kleiner Schnittstelle, die viel Verhalten verbergen; flache Durchreich-Module melden, Single-Adapter-Seams, die nur hypothetisch sind, doppelte Logik und Verhalten, das nur über Hilfsfunktionen getestet wird; sagen, wohin ein Seam gehört, damit Verhalten über die Schnittstelle getestet wird.
So haben wir getestet
Codex CLI 0.166 (gpt-6-astra, niedriges Reasoning) auf einem dedizierten Windows-Test-PC, pro Lauf ein frisches temporäres Projekt und temporäre HOME/TMPDIR/Caches, Skill installiert (Skill-Gruppe), nicht vorhanden (Kontrollgruppe) oder nicht vorhanden, aber mit der Kernanforderung des Skills als einem an den Prompt angehängten Satz (Ein-Satz-Gruppe), 2 Läufe pro Gruppe und Aufgabe, Netzwerk aus, Schreibzugriffe auf /tmp blockiert. Die Prompts nennen den Skill nie (außer der unten genannten Formulierung).
Ein kleines Shop-Backend mit sechs eingebauten Reibungspunkten (flache Validatoren und Geld-Wrapper, ein durchreichender Inventory-Service, ein einzelner Payment-Adapter, doppelte Logik und weitere). Aufgaben: einen HTML-Bericht mit Architekturverbesserungen schreiben, einen Bericht nur zu Payment und Inventory und „warum ist place_order schwer zu testen und wie würdest du es beheben“ (Antwort im Chat). Die Prompts nennen keine Designbegriffe. Die Ein-Satz-Version nennt die Tiefenidee und die Dinge, die gemeldet werden sollen.
- Architektur-Scan des gesamten Repos — Prüfe dieses kleine Shop-Backend auf Architekturverbesserungen: Wo würde eine Umstrukturierung den Code leichter änderbar und leichter testbar machen? Schreibe deine Erkenntnisse als eigenständigen HTML-Bericht namens report.html in diesem Ordner (öffne keinen Browser und starte keinen Server …).
- Nur Payment und Inventory — Betrachte nur die Payment- und Inventory-Teile dieses Backends und sag mir, welche Umstrukturierungen sich lohnen würden. Schreibe deine Erkenntnisse als eigenständigen HTML-Bericht namens report.html in diesem Ordner (öffne keinen Browser und starte keinen Server) und ändere keinen Code …
- Warum ist place_order schwer zu testen? — Es fühlt sich mühsam an, einen ordentlichen Test für place_order in diesem Backend zu schreiben. Warum, und welche Umstrukturierung würde das beheben? Ändere keine Dateien; antworte in deiner letzten Nachricht.
Die Bewertung ist programmatisch (versteckte Tests / Erkennung eingebauter Probleme / Constraint-Checks / Rendern+OCR, wo relevant), 0–5 pro Lauf. Kein LLM-Richter hat einen Score vergeben.
Ergebnisse
Der Ein-Satz-Prompt für die dritte Gruppe: „Bewerte Module nach ihrer Tiefe: Ein tiefes Modul hat eine kleine Schnittstelle, die viel Verhalten verbirgt; melde flache Durchreich-Module, hypothetische Single-Adapter-Seams, doppelte Logik und Verhalten, das nur über Hilfsfunktionen getestet wird, und sage, wohin ein Seam gehört, damit Verhalten über die Schnittstelle getestet wird.“
| Aufgabe | Score Kontrolle | Ein-Satz | Mit Skill | Tokens Kontrolle | Tokens Ein-Satz | Tokens mit Skill | Skill gelesen |
|---|---|---|---|---|---|---|---|
| t1-scan | 2.54 | 3.63 | 3.83 | 135k | 135k | 177k | 2/2 |
| t2-focus | 2.5 | 5.0 | 3.75 | 153k | 139k | 148k | 2/2 |
| t3-testing | 4.58 | 5.0 | 4.17 | 65k | 65k | 72k | 2/2 |
Durchschnittsscore: 3.21 ohne vs. 3.92 mit dem Skill (Delta +0.71). Tokens pro Lauf: 119k vs. 133k (1.12x); Zeit 154s vs. 158s. Ein-Satz-Gruppe: 4.54 (Gewinn des Skills gegenüber der Ein-Satz-Version: -0.63; Gewinn der Ein-Satz-Version gegenüber ohne Skill: +1.34); Ein-Satz-Version 114k Tokens pro Lauf, der Skill kostet also 1.17x so viel wie die Ein-Satz-Version.
Was passiert ist
- Kontrolle 3.21, Skill 3.92, Ein-Satz-Version 4.54 (n=6 je Gruppe). Ohne Anleitung verwendeten die HTML-Berichte fast keine Architektur-Vokabeln (0-2 Verwendungen von deep/shallow/seam/interface, wo die Prüfung 6 verlangt) in 4 von 4 Berichtsläufen. Die Skill-Berichte verwendeten sie in allen 4 Läufen, die Ein-Satz-Berichte ebenso.
- Scan des gesamten Backends: Skill 4.24 und 3.41, Ein-Satz 3.41 und 3.86, Kontrolle 2.88 und 2.2. Beide angeleiteten Gruppen fanden 3-4 der 6 eingebauten Punkte; die flachen Validator-Wrapper und der einzelne Payment-Adapter wurden in mehreren Läufen von jeder Gruppe übersehen.
- Fokussierte Payment-/Inventory-Aufgabe: Skill in beiden Läufen 3.75, Kontrolle in beiden 2.5, Ein-Satz in beiden 5.0. Alle Skill- und Kontroll-Läufe fanden nur einen der beiden Punkte (der hypothetische einzelne Payment-Adapter wurde übersehen); die Ein-Satz-Version fand beide.
- Warum place_order schwer zu testen ist: Alle Gruppen liegen nah beieinander (Kontrolle 4.17 und 5.0, Skill 4.17 und 4.17, Ein-Satz 5.0 und 5.0); den Skill-Läufen entging in einem Lauf eine Ursache (Tests nur über Hilfsfunktionen) und in einem anderen durchreichende Schichten.
- Tokens: Skill 133k, Ein-Satz 114k, Kontrolle 119k pro Lauf (1.12x Kontrolle). Der Skill wurde in 6/6 Skill-Läufen gelesen.
Dimensionsbewertungen
| Dimension | Score | Begründung |
|---|---|---|
| 1_output_quality | 3.92 | Durchschnittsscore 3.92/5 mit dem Skill (programmatische Prüfungen, siehe Tabelle pro Aufgabe). |
| 2_lift_vs_no_skill | 2.71 | +0.71 Punkte gegenüber 3.21 ohne den Skill (n=2 pro Aufgabe; unter etwa 1 Punkt ist Rauschen). |
| 3_trigger | 5.0 | Skill-Datei in 6/6 Skill-Läufen gelesen. |
| 4_instructions_portability | 4 | SKILL.md plus einige Referenzdateien. |
| 5_efficiency | 4 | 1.12x Tokens (133k vs. 119k pro Lauf) und 1.03x Zeit (158s vs. 154s). |
| 6_safety_hygiene | 4 | Nur Prosa; siehe security.md. |
Grenzen dieses Tests
- Regelbasierte Recall-Prüfungen auf dem Berichtstext (Schlüsselwörter nahe Dateinamen) und eine Vokabelzählung; ob die vorgeschlagenen Umstrukturierungen tragfähig sind, wurde nicht beurteilt, und die Berichte wurden nicht im Browser geöffnet.
- Die Vokabelprüfung belohnt die Begriffe des Skills selbst, die auch die Ein-Satz-Version nennt, und bevorzugt angeleitete Gruppen.
- Die „Vorher/Nachher“-Prüfung schlägt nur bei 2 Läufen in der Scan-Aufgabe fehl; kein Unterscheidungsmerkmal.
- n=2 pro Zelle; eine kleine Codebasis.
- n = 2 pro Gruppe und Aufgabe: Unterschiede unter etwa 1 Punkt sind Rauschen.
- Regelbasierte Bewertung misst, was die Prüfungen sehen können; sie kann keinen Geschmack beurteilen oder ob ein Ergebnis das bestmögliche ist.
Sicherheit
Siehe security.md. Scan: 0 CRITICAL / 0 HIGH / 0 MEDIUM. Urteil: sicher ausführbar (Sandbox ohne Netzwerk). Ein sauberer Scan beweist nicht, dass ein Skill sicher ist.
Fazit
Der Skill gibt dem Review klar den Rahmen der Modultiefe, der einem nackten Prompt fehlt, mit einem kleinen Score-Gewinn gegenüber der Kontrolle; dieselbe Idee in einem Satz findet jedoch mehr der eingebauten Probleme bei weniger Tokens, sodass der Gewinn überwiegend stilistisch ist.
Transkript
Laufprotokoll: codebase-design (Codex CLI, network off, per-run temp HOME/TMPDIR, one row per graded run.) Spalten: Aufgabe, Gruppe-Lauf, Punktzahl (0-5), Tokens, Sekunden, bestandene Prüfungen, vom Agenten geöffnete Skill-Dateien. t1-scan control-1: Punkte 2.88, Tokens 135577, Sek. 182.2, Prüfungen 4/6, nichts geöffnet t1-scan control-2: Punkte 2.2, Tokens 136096, Sek. 168.8, Prüfungen 4/6, nichts geöffnet t1-scan oneliner-1: Punkte 3.86, Tokens 135437, Sek. 152.3, Prüfungen 5/6, nichts geöffnet t1-scan oneliner-2: Punkte 3.41, Tokens 135611, Sek. 172.2, Prüfungen 4/6, nichts geöffnet t1-scan treatment-1: Punkte 3.41, Tokens 176681, Sek. 216.0, Prüfungen 4/6, geöffnet codebase-design t1-scan treatment-2: Punkte 4.24, Tokens 178425, Sek. 181.7, Prüfungen 6/6, geöffnet codebase-design t2-focus control-1: Punkte 2.5, Tokens 164638, Sek. 128.2, Prüfungen 2/4, nichts geöffnet t2-focus control-2: Punkte 2.5, Tokens 143158, Sek. 298.9, Prüfungen 2/4, nichts geöffnet t2-focus oneliner-1: Punkte 5.0, Tokens 112021, Sek. 375.7, Prüfungen 4/4, nichts geöffnet
18 Läufe, 3 Artefakte
Beispielausgabe
SOTA · With the skill: report.html (t1-scan, run 1, Codex)
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Small shop backend — architecture review</title> <style> :root{color-scheme:light;--ink:#183047;--muted:#506276;--accent:#116b66;--line:#d8e2e8}*{box-sizing:border-box}body{margin:0;background:#f3f6f8;color:var(--ink);font:16px/1.65 system-ui,sans-serif}main{max-width:1060px;margin:auto;padding:48px 28px 70px}header{border-top:6px solid var(--accent);padding:24px 0}h1{font-size:2.5rem;line-height:1.15;letter-spacing:-.04em}h2{font-size:1.55rem;margin-top:0}h3{font-size:1.1rem;margin-bottom:6px}p{margin:10px 0 18px}.eyebrow,.meta{color:var(--muted)}.eyebrow{text-transform:uppercase;letter-spacing:.13em;font-size:.8rem;font-weight:700}section{background:white;border:1px solid var(--line);border-radius:12px;padding:26px;margin:22px 0}code,pre{font-family:Consolas,monospace;font-size:.9em}code{overflow-wrap:anywhere}pre{background:#edf4f5;padding:18px;white-space:pre-wrap;border-left:4px solid var(--accent)}table{width:100%;border-collapse:collapse;font-size:.93rem}th,td{text-align:left;vertical-align:top;padding:12px;border-bottom:1px solid var(--line)}th{background:#edf4f5}a{color:var(--accent)}.tag{display:inline-block;background:#e3f2ef;color:#155b53;border-radius:20px;padding:3px 10px;font-size:.8rem;font-weight:700}.note{border-left:4px solid #d1a03b;padding-left:16px}.flow{display:flex;gap:12px;flex-wrap:wrap;margin:18px 0}.flow div{flex:1;min-width:180px;background:#edf4f5;padding:16px;border-radius:8px}li{margin:8px 0}@media(max-width:650px){main{padding:24px 14px}section{padding:18px}h1{font-size:2rem}table{font-size:.83rem}th,td{padding:7px}}@media print{body{background:white}main{padding:0}section{break-inside:avoid}a{color:inherit}} </style> </head> <body><main> <header><div class="eyebrow">Architecture review · 2 November 2026</div> <h1>Make pricing and ordering the test surface.</h1> <p>The highest-value restructuring is to concentrate pricing policy in one pure module and let an order module own validation, stock decisions, and payment sequencing behind a small interface. Remove pass-through layers as this happens. This backend is small enough that a framework, generic repository hierarchy, or distributed decomposition would add more work than leverage.</p> <p class="meta">Scope: all ten Python files in <code>shop/</code>, <code>tests/test_helpers.py</code>, and the README. This report proposes changes; no application or test files were edited. Source references use the line numbers of the reviewed snapshot.</p> <nav aria-label="Report contents"><a href="#pricing">Pricing</a> · <a href="#orders">Order module</a> · <a href="#stock">Stock consistency</a> · <a href="#validation">Validation</a> · <a href="#plan">Migration & tests</a></nav> </header> <section><h2>Current structure and where knowledge leaks</h2> <pre aria-label="Current dependency diagram">cart ──→ money pricing (discount implementation) └── own discount rules ↑ imported by orders, never called orders ──→ validators + money + own discount rules ├─→ inventory_service ──→ inventory_repo ──→ g [... excerpt: first 3200 of 17083 characters]