Clean Code Guard
Reviews AI-written code against Clean Code, SOLID and 15 documented LLM failure modes
Test report
- Verdict
- Tested · Works
- Score
- Tested
- Jul 21, 2026
- Environment
- Claude Code 2.x (agent harness)
- Upstream re-checked
- Aug 10, 2026 · 0c54f29
GitHub API was rate-limited so I shallow-cloned the repo; SKILL.md sits at skills/clean-code-guard/ with 7 reference files, and I raw-fetched three of them (ai-failure-modes.md, solid.md, sources.md) — all HTTP 200. Frontmatter parses with name plus a 938-char description (under the 1024 limit); the only non-Markdown file is a 4-line agents/openai.yaml of display metadata, and grep found no pipe-to-shell, base64 blobs, secret reads or injection text. For the output stage I wrote a 72-line Python OrderProcessor with planted defects, produced a baseline review WITHOUT reading the skill body, then re-reviewed following SKILL.md plus review-checklist.md and ai-failure-modes.md: the baseline gave 14 flat unranked bullets with the merge-blocking swallowed-payment-exception buried at position 4 between an unused import and a "+=" nit, while the skill run forced a refactor-vs-correctness pre-flight, severity tiers and a per-section Coverage line, and caught three things the baseline missed — the unchecked response status (a 200 with a declined body still persists the order), raw card data POSTed to a payment_url that defaults to None framed as a trust-boundary finding, and float-money correctly demoted to "behavior change, confirm with author" rather than listed as a fix. Costs are real: about 470 lines of reference reading, and the checklist's max-3-nits cap dropped two legitimate baseline items. Docs lost a point because SKILL.md line 42 claims "14 systematic ways" while ai-failure-modes.md line 3 says 15 and lists 15, and the frontmatter's "invoke it on your own initiative the moment you finish writing code" clause is an over-trigger risk on routine coding turns. Trigger phrasings judged: SHOULD fire — "I just finished implementing the checkout handler, review it before I commit" (yes), "Review this PR, is it safe to merge?" (yes), "Refactor this OrderProcessor class, keep behavior identical" (yes); SHOULD NOT fire — "The pytest suite fails on CI with a fixture teardown error, help me debug it" (no, excluded twice as test-running and CI), "Should we use event sourcing or CRUD for the orders service?" (no, excluded as pure architecture discussion). 5/5 correct. All four cited source URLs I spot-checked (arXiv 2409.19182, Fowler Yagni, Metz Wrong Abstraction, USENIX Spracklen) returned 200, so the research claims are backed rather than decorative.
Scored on four weighted criteria — install, triggering, output vs. baseline, docs. How scoring works
- Installs cleanly 5/5
- Triggers reliably 5/5
- Output vs. baseline 7/10
- Docs & honesty 4/5
What Clean Code Guard does
A review-pass skill that checks generated or changed production code against Clean Code, SOLID, DRY/KISS/YAGNI and a catalog of 15 LLM-specific failure modes such as swallowed exceptions, hardcoded success returns, hallucinated APIs and copy-from-similar bugs. It triggers after a coding agent writes, edits, refactors or fixes code and before the result is presented, committed or merged, and on requests like "review this PR", "is this safe to merge" or "refactor this". It stays out of CI config, git workflow, test debugging, architecture discussion and test-code review, which the sibling test-guard covers.
How to install Clean Code Guard
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
Skills live in ~/.claude/skills/ (global) or .claude/skills/
(per-project). Restart Claude Code after installing.
Commands — how to trigger Clean Code Guard
-
/clean-code-guardReviews AI-written code against Clean Code, SOLID and 15 documented LLM failure modes
It also activates on plain-language prompts like these:
-
Is this code safe to merge -
Review this PR against Clean Code principles -
Audit this refactor for SOLID violations
Frequently asked questions
- Is the Clean Code Guard skill free?
- Yes. The skill itself is free from amElnagdy/guard-skills. SkillProof publishes the install command and an independent test verdict at no cost.
- Does Clean Code Guard work with Claude Code?
- We tested it with Claude Code 2.x (agent harness) on Jul 21, 2026. Verdict: Tested · Works. GitHub API was rate-limited so I shallow-cloned the repo; SKILL.md sits at skills/clean-code-guard/ with 7 reference files, and I raw-fetched three of them (ai-failure-modes.md, solid.md, sources.md) — all HTTP 200. Frontmatter parses with name plus a 938-char description (under the 1024 limit); the only non-Markdown file is a 4-line agents/openai.yaml of display metadata, and grep found no pipe-to-shell, base64 blobs, secret reads or injection text. For the output stage I wrote a 72-line Python OrderProcessor with planted defects, produced a baseline review WITHOUT reading the skill body, then re-reviewed following SKILL.md plus review-checklist.md and ai-failure-modes.md: the baseline gave 14 flat unranked bullets with the merge-blocking swallowed-payment-exception buried at position 4 between an unused import and a "+=" nit, while the skill run forced a refactor-vs-correctness pre-flight, severity tiers and a per-section Coverage line, and caught three things the baseline missed — the unchecked response status (a 200 with a declined body still persists the order), raw card data POSTed to a payment_url that defaults to None framed as a trust-boundary finding, and float-money correctly demoted to "behavior change, confirm with author" rather than listed as a fix. Costs are real: about 470 lines of reference reading, and the checklist's max-3-nits cap dropped two legitimate baseline items. Docs lost a point because SKILL.md line 42 claims "14 systematic ways" while ai-failure-modes.md line 3 says 15 and lists 15, and the frontmatter's "invoke it on your own initiative the moment you finish writing code" clause is an over-trigger risk on routine coding turns. Trigger phrasings judged: SHOULD fire — "I just finished implementing the checkout handler, review it before I commit" (yes), "Review this PR, is it safe to merge?" (yes), "Refactor this OrderProcessor class, keep behavior identical" (yes); SHOULD NOT fire — "The pytest suite fails on CI with a fixture teardown error, help me debug it" (no, excluded twice as test-running and CI), "Should we use event sourcing or CRUD for the orders service?" (no, excluded as pure architecture discussion). 5/5 correct. All four cited source URLs I spot-checked (arXiv 2409.19182, Fowler Yagni, Metz Wrong Abstraction, USENIX Spracklen) returned 200, so the research claims are backed rather than decorative.
- What is the Clean Code Guard SkillProof Score?
- 8.4/10 — installs cleanly 5/5, triggers reliably 5/5, output vs. baseline 7/10, docs & honesty 4/5.
- How do I install Clean Code Guard?
- Copy the install command from this page, run it in your terminal, and restart Claude Code. Skills live in ~/.claude/skills/ (global) or .claude/skills/ inside a project.
- Can I use Clean Code Guard with Cursor, Copilot, Gemini CLI, Codex or other AI tools?
- The SKILL.md format is native to Claude (Claude Code, Desktop, claude.ai). The instructions inside adapt to other assistants: Cursor rules, GitHub Copilot instructions, Windsurf rules, Custom GPTs, AGENTS.md for OpenAI Codex, and GEMINI.md for Google Gemini CLI — our conversion guides cover each, and the free converter on the tools page does the wrapping for you.