clean-code-guard

A reactive review layer for production code, applying Clean Code, SOLID, DRY, KISS, and YAGNI principles alongside checks for failure modes specific to LLM-generated code, across any programming language. It is designed to run as a guard pass after an agent writes, edits, refactors, or fixes code, before the result is presented, committed, or merged, catching problems that generic "follow clean code" instructions tend to miss.

Three modes cover different situations. Guard-pass mode checks a diff or target files against a set of always-applied imperatives once an implementation exists. Live mode applies the same rules while writing when the skill is explicitly invoked before a risky edit, followed by a self-check before delivery. Review mode walks a structured checklist against the target files and produces prioritized findings without editing code unless asked. The imperatives cover intention-revealing names, small single-purpose functions, an argument ceiling, command/query separation, comment discipline, matching existing file style, and the five SOLID rules.

The distinguishing focus is a catalogue of systematic ways LLMs produce bad code, for example duplicated knowledge, hallucinated packages, catch-all error handling that swallows failures, and agents declaring success against failing tests, each grounded in published research cited within the skill. Rule bodies and the full review checklist live in linked reference files read on demand: naming and functions, comments and formatting, SOLID, DRY/KISS/YAGNI, AI failure modes, the review checklist, and a sources bibliography. It is a portable instruction skill requiring no MCP server, network access, API key, or bundled script, and it deliberately does not replace project linters, formatters, type checkers, or test runners, which handle mechanical verification while the skill supplies the judgement layer. It stays silent for conceptual questions, CI and tooling config, git workflow, test running, pure architecture discussion, prose, data analysis, and test-code review.