---You give an AI agent a task, grab a coffee, and come back five minutes later.
Boom.
Three new files. Eight hundred lines of code. Four new abstractions. And somehow, a function called handleEverything().
Perfect. Totally under control.
AI agents are amazing. But with a growing list of tasks every day, we don’t always have time to review every generated line. Which left me with a question:
If AI helps us write code faster, how do we make sure we’re not writing bad code faster too?
I used to nod at clean code advice
In my first months as a junior developer, my tech lead kept saying things like:
- “Don’t repeat yourself.”
- “Keep it simple.”
- “Why are we keeping this? We’re not going to use it.”
- “Separate your concerns.”
I would nod like: Yes. Absolutely. Makes perfect sense.
While internally thinking: what does that actually mean?
After a year, hundreds of bugs and countless tickets, I finally connected those sentences to a few well-known clean code principles. And no, clean code isn’t about making code look pretty. Your app can work perfectly today and still become everyone’s nightmare in six months.
TL;DR
Five principles, no university lecture:
- DRY: one source of truth for each piece of logic.
- KISS: the simplest thing that solves the problem.
- YAGNI: build for today’s needs, not imagined ones.
- Separation of Concerns: data, business logic and presentation live apart.
- SRP: each class or module has one clear job.
1. DRY: Don’t Repeat Yourself
Copy the same validation into five files and everything works, until the rules change. Now you must find all five copies, and naturally you forget one. Congratulations, you’ve created a bug with a family tree. 🌳
// Before: the same rule pasted in three places if (!/^\S+@\S+\.\S+$/.test(email)) throw new Error("Invalid email"); // After: one source of truth export const assertValidEmail = (email: string) => { if (!/^\S+@\S+\.\S+$/.test(email)) throw new Error("Invalid email"); }; The goal isn’t zero repetition at all costs. It’s avoiding duplicated logic that should have one clear owner.
2. KISS: Keep It Simple, Seriously
Developers, and yes, AI too, love to over-engineer. You need to know if a user is active:
// Please do this const isActive = (user: User) => user.status === "active"; // Not this class UserActivityStatusManagerFactory { /* three layers, two interfaces... */ } Simple code is easier to read, test, debug and change. Simple doesn’t mean lazy; it means not adding complexity nobody asked for.
3. YAGNI: You Aren’t Gonna Need It
“Let’s keep this, we might need it later.” Will we? Probably not.
Maybe one day your app needs a multi-region, AI-powered, blockchain-compatible notification system. Today you just need to send an email. Build what you need now, and adapt when real requirements arrive instead of solving imaginary ones.
4. Separation of Concerns and SRP: One Job at a Time
Picture one function that fetches data, validates it, applies business rules, formats the response and sends an email. (Okay, maybe not the coffee.)
When everything is mixed together, understanding and changing the code gets hard. Two ideas help:
- Separation of Concerns: data access, business logic and presentation each get their own place.
- Single Responsibility Principle: a class or module has one clear responsibility. A PaymentService handles payments. It doesn't also generate PDF reports or send marketing emails.
When one class does everything, changing one thing can accidentally break ten others. Your classes are not superheroes.
So I built skills for it
I can’t inspect every line an agent writes, so I attacked the problem from both ends: before the code is written, and after. Two pairs of skills, each with one that guides the agent and one that checks its work.
The clean principles
- /clean_principles-first: write it right. This skill teaches the AI agent the five principles (DRY, KISS, YAGNI, Separation of Concerns and SRP) as guidelines to follow while it generates code. Fewer surprise abstractions, fewer handleEverything() moments.
- /clean_principles-audit: check it afterwards. This one reads the code and generates a report that tells you whether it’s actually good: how it holds up against each principle, where the problems are, and what to fix first. It turns “I don’t have an hour to review this” into a two-minute read.
*SOLID *(five design principles about how classes and modules depend on each other) has its own pair of skills, /solid-first and /solid-audit. I’ll explain SOLID properly in the next article. For now, you’ll find them in the repo.
- /solid-first: design it right. It kicks in when the agent creates or restructures code: a new module, an interface, a new payment provider. It keeps new variants additive and business logic free of hard-coded infrastructure. It also tells the agent not to over-apply SOLID, so no interface for a single implementation.
- /solid-audit: check the design. It gives a verdict on each of S, O, L, I and D, with file:line evidence, and flags abstractions that add complexity without a real need.
The idea isn’t to replace our judgment. It’s to give it a head start.
Try them. The -first skills load on their own when the agent writes code, and the audits run when you ask. Install all four with one line:
git clone https://github.com/nrimen/clean-code-skills && mkdir -p .claude/skills && cp -r clean-code-skills/{clean-principles-first,clean-principles-audit,solid-first,solid-audit} .claude/skills/Source code: nrimen/clean-code-skills. On Windows? The line above works as is in Git Bash or WSL. In PowerShell, use:
powershell
git clone https://github.com/nrimen/clean-code-skills; mkdir .claude\skills -Force; "clean_principles-first","clean_principles-audit" | ForEach-Object { Copy-Item -Recurse "clean-code-skills\$_" .claude\skills\ } Source code: https://github.com/nrimen/clean-code-skills
They won’t replace code review, but together they lower the baseline mess and make review faster.
Final thought
Clean code isn’t about the shortest code or code that looks smart. The real test isn’t “does it work?” but:
“Will we still understand it when we come back to it in six months?”
And if the answer is “absolutely not, good luck to whoever touches this next”… maybe it’s time to clean the code. 🧹