Skip to content

MustafaKucukcoskun/Refine-agent-kit / .agents/skills/clean-code

clean-code

Unverified

Clean Code — Pragmatic AI Coding Standards

CRITICAL SKILL — Be concise, direct, solution-focused. This is the quality floor for every code change across every domain.

When to Use vs. Related Skills

You want to…Use
Apply quality gate to any code changeclean-code (this — always)
Refactor existing messy coderefactoring-patterns + clean-code
Choose between tech/architecture optionsarchitecture
Review a PRcode-review-checklist + clean-code
Lint/format automaticallylint-and-validate

Core Principles

PrincipleRule
SRPSingle Responsibility - each function/class does ONE thing
DRYDon't Repeat Yourself - extract duplicates, reuse
KISSKeep It Simple - simplest solution that works
YAGNIYou Aren't Gonna Need It - don't build unused features
Boy ScoutLeave code cleaner than you found it

Naming Rules

ElementConvention
VariablesReveal intent: userCount not n
FunctionsVerb + noun: getUserById() not user()
BooleansQuestion form: isActive, hasPermission, canEdit
ConstantsSCREAMING_SNAKE: MAX_RETRY_COUNT

Rule: If you need a comment to explain a name, rename it.


Function Rules

RuleDescription
SmallMax 20 lines, ideally 5-10
One ThingDoes one thing, does it well
One LevelOne level of abstraction per function
Few ArgsMax 3 arguments, prefer 0-2
No Side EffectsDon't mutate inputs unexpectedly

Code Structure

PatternApply
Guard ClausesEarly returns for edge cases
Flat > NestedAvoid deep nesting (max 2 levels)
CompositionSmall functions composed together
ColocationKeep related code close

AI Coding Style

SituationAction
User asks for featureWrite it directly
User reports bugFix it, don't explain
No clear requirementAsk, don't assume

Anti-Patterns (DON'T)

❌ Pattern✅ Fix
Comment every lineDelete obvious comments
Helper for one-linerInline the code
Factory for 2 objectsDirect instantiation
utils.ts with 1 functionPut code where used
"First we import..."Just write code
Deep nestingGuard clauses
Magic numbersNamed constants
God functionsSplit by responsibility

🔴 Before Editing ANY File (THINK FIRST!)

Before changing a file, ask yourself:

QuestionWhy
What imports this file?They might break
What does this file import?Interface changes
What tests cover this?Tests might fail
Is this a shared component?Multiple places affected

Quick Check:

File to edit: UserService.ts
└── Who imports this? → UserController.ts, AuthController.ts
└── Do they need changes too? → Check function signatures

🔴 Rule: Edit the file + all dependent files in the SAME task. 🔴 Never leave broken imports or missing updates.


Summary

DoDon't
Write code directlyWrite tutorials
Let code self-documentAdd obvious comments
Fix bugs immediatelyExplain the fix first
Inline small thingsCreate unnecessary files
Name things clearlyUse abbreviations
Keep functions smallWrite 100+ line functions

Remember: The user wants working code, not a programming lesson.


🔴 Self-Check Before Completing (MANDATORY)

Before saying "task complete", verify:

CheckQuestion
✅ Goal met?Did I do exactly what user asked?
✅ Files edited?Did I modify all necessary files?
✅ Code works?Did I test/verify the change?
✅ No errors?Lint and TypeScript pass?
✅ Nothing forgotten?Any edge cases missed?

🔴 Rule: If ANY check fails, fix it before completing.


Verification Scripts (MANDATORY)

🔴 CRITICAL: Each agent runs ONLY their own skill's scripts after completing work.

Agent → Script Mapping

AgentScriptCommand
frontend-specialistUX Auditpython .agent/skills/frontend-design/scripts/ux_audit.py .
frontend-specialistA11y Checkpython .agent/skills/frontend-design/scripts/accessibility_checker.py .
backend-specialistAPI Validatorpython .agent/skills/api-patterns/scripts/api_validator.py .
mobile-developerMobile Auditpython .agent/skills/mobile-design/scripts/mobile_audit.py .
database-architectSchema Validatepython .agent/skills/database-design/scripts/schema_validator.py .
security-auditorSecurity Scanpython .agent/skills/vulnerability-scanner/scripts/security_scan.py .
seo-specialistSEO Checkpython .agent/skills/seo-fundamentals/scripts/seo_checker.py .
seo-specialistGEO Checkpython .agent/skills/geo-fundamentals/scripts/geo_checker.py .
performance-optimizerLighthousepython .agent/skills/performance-profiling/scripts/lighthouse_audit.py <url>
test-engineerTest Runnerpython .agent/skills/testing-patterns/scripts/test_runner.py .
test-engineerPlaywrightpython .agent/skills/webapp-testing/scripts/playwright_runner.py <url>
Any agentLint Checkpython .agent/skills/lint-and-validate/scripts/lint_runner.py .
Any agentType Coveragepython .agent/skills/lint-and-validate/scripts/type_coverage.py .
Any agenti18n Checkpython .agent/skills/i18n-localization/scripts/i18n_checker.py .

❌ WRONG: test-engineer running ux_audit.py ✅ CORRECT: frontend-specialist running ux_audit.py


🔴 Script Output Handling (READ → SUMMARIZE → ASK)

When running a validation script, you MUST:

  1. Run the script and capture ALL output
  2. Parse the output - identify errors, warnings, and passes
  3. Summarize to user in this format:
## Script Results: [script_name.py]

### ❌ Errors Found (X items)
- [File:Line] Error description 1
- [File:Line] Error description 2

### ⚠️ Warnings (Y items)
- [File:Line] Warning description

### ✅ Passed (Z items)
- Check 1 passed
- Check 2 passed

**Should I fix the X errors?**
  1. Wait for user confirmation before fixing
  2. After fixing → Re-run script to confirm

🔴 VIOLATION: Running script and ignoring output = FAILED task. 🔴 VIOLATION: Auto-fixing without asking = Not allowed. 🔴 Rule: Always READ output → SUMMARIZE → ASK → then fix.


AI-Slop Anti-Patterns (Reject these on sight)

These patterns signal AI-generated filler — remove or reject them when reviewing code:

Anti-patternExampleFix
Narrator comments// Loop through the users above for (const user of users)Delete the comment
Restating types in JSDoc@param {string} name - the nameDelete — TypeScript already says it
Defensive nothing-checksif (!obj) return; const x = obj.x; when obj is guaranteedDelete the check
Premature error wrappingtry { simpleAssign(); } catch(e) { throw e; }Delete the try/catch
Fake extensibilityIUserServiceFactoryBuilderProvider for a single useUse a plain function
Emojis in code// 🎉 Yay! Successfully savedDelete
"In this section..." prose// This section handles X above sectionDelete — structure already shows it
Leftover print/debugconsole.log('got here');Delete before commit
Empty try-catchtry { ... } catch {} without intentEither handle or propagate
Renaming _ vars on importimport { foo as _foo } just to silence lintRemove import OR actually use it

Edge Cases & Gotchas

SituationRight move
Deleted code you think might be neededActually delete it — git has history
Commented-out code "just in case"Delete — it rots instantly
Copy-pasted block that's "almost identical"Extract — but only if ≥3 uses and shape stable
Public API changeDeprecate with clear migration note, don't yank
Test that's flakyFix root cause or delete — never skip silently
Long function that's clearLeave it — length alone isn't smell
Abstraction "for future needs"Don't — wait until 3rd real use

Pre-Commit Checklist

  • No narrator comments
  • No emojis in code/logs
  • No console.log / print leftovers
  • No // TODO without issue link
  • No commented-out code
  • No abstractions for single use
  • Tests added for new behavior
  • Lint passes

Related Skills

SkillWhen
refactoring-patternsSystematic refactoring of existing code
code-review-checklistPR / merge-time review
lint-and-validateAutomated enforcement
systematic-debuggingWhen "clean" code breaks
testing-patternsTest design alongside code
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 318kUpdated Claude CodeCodexUnverifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexUnverifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 318kUpdated Claude CodeCodexUnverifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 318kUpdated Claude CodeCodexUnverifiedInstall