Clean Code Guard

Revisiona il codice scritto dall'IA rispetto a Clean Code, SOLID e 15 modalità di fallimento LLM documentate

di amElnagdy · amElnagdy/guard-skills

Promosso ★ 8.4/10

Clean Code Guard — Revisiona il codice scritto dall'IA rispetto a Clean Code, SOLID e 15 modalità di fallimento LLM documentate

Cosa fa

Una skill di revisione che controlla il codice di produzione generato o modificato rispetto a Clean Code, SOLID, DRY/KISS/YAGNI e un catalogo di 15 modalità di fallimento specifiche degli LLM come eccezioni inghiottite, ritorni di successo hardcoded, API allucinate e bug di copia da simili. Si attiva dopo che un agente di codifica scrive, modifica, refactoring o corregge il codice e prima che il risultato venga presentato, commesso o unito, e su richieste come "review this PR", "is this safe to merge" o "refactor this". Rimane al di fuori della configurazione CI, del workflow git, del debug dei test, della discussione sull'architettura e della revisione del codice di test, che la skill sorella test-guard copre.

Rapporto di test

L'API di GitHub era limitata dalla frequenza, quindi ho clonato in modo superficiale il repo; SKILL.md si trova in skills/clean-code-guard/ con 7 file di riferimento, e ne ho recuperati raw tre (ai-failure-modes.md, solid.md, sources.md) — tutti HTTP 200. Il frontmatter è parsabile con name più una descrizione di 938 caratteri (sotto il limite di 1024); l'unico file non Markdown è un agents/openai.yaml di 4 righe di metadati di visualizzazione, e grep non ha trovato pipe-to-shell, blob base64, letture di segreti o testo di iniezione. Per la fase di output ho scritto un OrderProcessor Python di 72 righe con difetti impiantati, ho prodotto una revisione di base SENZA leggere il corpo della skill, quindi ho riesaminato seguendo SKILL.md più review-checklist.md e ai-failure-modes.md: la baseline ha dato 14 punti non classificati senza verdetto con l'eccezione di pagamento inghiottita che bloccava la fusione sepolta alla posizione 4 tra un'importazione inutilizzata e un pignoleria "+=", mentre l'esecuzione della skill ha forzato un pre-volo di refactoring vs correttezza, livelli di gravità e una riga di Copertura per sezione, e ha catturato tre cose che la baseline aveva completamente perso — lo stato della risposta non controllato (un 200 con un corpo rifiutato persiste comunque l'ordine), dati della carta raw POSTati a un payment_url che di default è None incorniciato come un risultato di confine di fiducia, e float-money correttamente declassato a "behavior change, confirm with author" anziché elencato come una correzione. I costi sono reali: circa 470 righe di lettura di riferimento, e il limite massimo di 3 pignolerie della checklist ha eliminato due elementi legittimi della baseline. La documentazione ha perso un punto perché SKILL.md riga 42 afferma "14 systematic ways" mentre ai-failure-modes.md riga 3 dice 15 ed elenca 15, e la clausola del frontmatter "invoke it on your own initiative the moment you finish writing code" è un rischio di sovra-attivazione sui turni di codifica di routine. Frasi trigger giudicate: DOVREBBE attivarsi — "I just finished implementing the checkout handler, review it before I commit" (sì), "Review this PR, is it safe to merge?" (sì), "Refactor this OrderProcessor class, keep behavior identical" (sì); NON DOVREBBE attivarsi — "The pytest suite fails on CI with a fixture teardown error, help me debug it" (no, escluso due volte come esecuzione di test e CI), "Should we use event sourcing or CRUD for the orders service?" (no, escluso come pura discussione sull'architettura). 5/5 corretto. Tutti e quattro gli URL di origine citati che ho controllato a campione (arXiv 2409.19182, Fowler Yagni, Metz Wrong Abstraction, USENIX Spracklen) hanno restituito 200, quindi le affermazioni di ricerca sono supportate anziché decorative.

Testato il: 2026-07-21 · Claude Code 2.x (agent harness)

Installazione

git clone --depth 1 https://github.com/amElnagdy/guard-skills.git /tmp/clean-code-guard-src
mkdir -p ~/.claude/skills
cp -R /tmp/clean-code-guard-src/skills/clean-code-guard ~/.claude/skills/clean-code-guard
# CLI instead: npx skills add amElnagdy/guard-skills --skill clean-code-guard --global
# (without --global it installs project-local, into ./.claude/skills)
# Whole 5-skill package: npx skills add amElnagdy/guard-skills
# Update later: npx skills update clean-code-guard

Comandi e prompt di esempio

  • /clean-code-guardRevisiona il codice scritto dall'IA rispetto a Clean Code, SOLID e 15 modalità di fallimento LLM documentate

Gli skill si attivano con richieste in linguaggio naturale, senza comandi da ricordare. Dopo l'installazione, prompt come questi lo attivano (in inglese):

  • Is this code safe to merge
  • Review this PR against Clean Code principles
  • Audit this refactor for SOLID violations