Clean Code Skill
When to use
- Applying clean code principles to any codebase (Go, TypeScript, etc.)
- Refactoring code to improve readability and maintainability
- Reviewing code for clarity, simplicity, and adherence to standards
- Ensuring consistent naming, structure, and organization
- Removing unnecessary complexity, comments, or abstractions
Core Principles
| Principle |
Rule |
| SRP |
Single Responsibility - each function/class does ONE thing |
| DRY |
Don't Repeat Yourself - extract duplicates, reuse |
| KISS |
Keep It Simple - simplest solution that works |
| YAGNI |
You Aren't Gonna Need It - don't build unused features |
| Boy Scout |
Leave code cleaner than you found it |
Naming Rules
| Element |
Convention |
| Variables |
Reveal intent: userCount not n |
| Functions |
Verb + noun: getUserById() not user() |
| Booleans |
Question form: isActive, hasPermission, canEdit |
| Constants |
SCREAMING_SNAKE: MAX_RETRY_COUNT |
Rule: If you need a comment to explain a name, rename it.
Function Rules
| Rule |
Description |
| Small |
Max 20 lines, ideally 5-10 |
| One Thing |
Does one thing, does it well |
| One Level |
One level of abstraction per function |
| Few Args |
Max 3 arguments, prefer 0-2 |
| No Side Effects |
Don't mutate inputs unexpectedly |
Code Structure
| Pattern |
Apply |
| Guard Clauses |
Early returns for edge cases |
| Flat > Nested |
Avoid deep nesting (max 2 levels) |
| Composition |
Small functions composed together |
| Colocation |
Keep related code close |
AI Coding Style
| Situation |
Action |
| User asks for feature |
Write it directly |
| User reports bug |
Fix it, don't explain |
| No clear requirement |
Ask, don't assume |
Anti-Patterns (DON'T)
| ❌ Pattern |
✅ Fix |
| Comment every line |
Delete obvious comments |
| Helper for one-liner |
Inline the code |
| Factory for 2 objects |
Direct instantiation |
| utils.ts with 1 function |
Put code where used |
| "First we import..." |
Just write code |
| Deep nesting |
Guard clauses |
| Magic numbers |
Named constants |
| God functions |
Split by responsibility |
🔴 Before Editing ANY File (THINK FIRST!)
Before changing a file, ask yourself:
| Question |
Why |
| 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
| Do |
Don't |
| Write code directly |
Write tutorials |
| Let code self-document |
Add obvious comments |
| Fix bugs immediately |
Explain the fix first |
| Inline small things |
Create unnecessary files |
| Name things clearly |
Use abbreviations |
| Keep functions small |
Write 100+ line functions |
Remember: The user wants working code, not a programming lesson.
Self-Check Before Completing
Before saying "task complete", verify:
| Check |
Question |
| ✅ 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 type checks pass? |
| ✅ Nothing forgotten? |
Any edge cases missed? |
References
| File |
Purpose |
| .cursor/rules/go-style-guide.mdc |
Go coding standards, naming conventions, error handling, context usage, domain layer design, service patterns, testing conventions |
| .cursor/rules/frontend-patterns.mdc |
TypeScript standards, React patterns, state management, code organization, unused imports/variables rules, control flow statement braces |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: clean-code-63description: Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments Use when this capability is needed.4---56# Clean Code Skill78## When to use910- Applying clean code principles to any codebase (Go, TypeScript, etc.)11- Refactoring code to improve readability and maintainability12- Reviewing code for clarity, simplicity, and adherence to standards13- Ensuring consistent naming, structure, and organization14- Removing unnecessary complexity, comments, or abstractions1516## Core Principles1718| Principle | Rule |19|-----------|------|20| **SRP** | Single Responsibility - each function/class does ONE thing |21| **DRY** | Don't Repeat Yourself - extract duplicates, reuse |22| **KISS** | Keep It Simple - simplest solution that works |23| **YAGNI** | You Aren't Gonna Need It - don't build unused features |24| **Boy Scout** | Leave code cleaner than you found it |2526---2728## Naming Rules2930| Element | Convention |31|---------|------------|32| **Variables** | Reveal intent: `userCount` not `n` |33| **Functions** | Verb + noun: `getUserById()` not `user()` |34| **Booleans** | Question form: `isActive`, `hasPermission`, `canEdit` |35| **Constants** | SCREAMING_SNAKE: `MAX_RETRY_COUNT` |3637> **Rule:** If you need a comment to explain a name, rename it.3839---4041## Function Rules4243| Rule | Description |44|------|-------------|45| **Small** | Max 20 lines, ideally 5-10 |46| **One Thing** | Does one thing, does it well |47| **One Level** | One level of abstraction per function |48| **Few Args** | Max 3 arguments, prefer 0-2 |49| **No Side Effects** | Don't mutate inputs unexpectedly |5051---5253## Code Structure5455| Pattern | Apply |56|---------|-------|57| **Guard Clauses** | Early returns for edge cases |58| **Flat > Nested** | Avoid deep nesting (max 2 levels) |59| **Composition** | Small functions composed together |60| **Colocation** | Keep related code close |6162---6364## AI Coding Style6566| Situation | Action |67|-----------|--------|68| User asks for feature | Write it directly |69| User reports bug | Fix it, don't explain |70| No clear requirement | Ask, don't assume |7172---7374## Anti-Patterns (DON'T)7576| ❌ Pattern | ✅ Fix |77|-----------|-------|78| Comment every line | Delete obvious comments |79| Helper for one-liner | Inline the code |80| Factory for 2 objects | Direct instantiation |81| utils.ts with 1 function | Put code where used |82| "First we import..." | Just write code |83| Deep nesting | Guard clauses |84| Magic numbers | Named constants |85| God functions | Split by responsibility |8687---8889## 🔴 Before Editing ANY File (THINK FIRST!)9091**Before changing a file, ask yourself:**9293| Question | Why |94|----------|-----|95| **What imports this file?** | They might break |96| **What does this file import?** | Interface changes |97| **What tests cover this?** | Tests might fail |98| **Is this a shared component?** | Multiple places affected |99100**Quick Check:**101```102File to edit: UserService.ts103└── Who imports this? → UserController.ts, AuthController.ts104└── Do they need changes too? → Check function signatures105```106107> 🔴 **Rule:** Edit the file + all dependent files in the SAME task.108> 🔴 **Never leave broken imports or missing updates.**109110---111112## Summary113114| Do | Don't |115|----|-------|116| Write code directly | Write tutorials |117| Let code self-document | Add obvious comments |118| Fix bugs immediately | Explain the fix first |119| Inline small things | Create unnecessary files |120| Name things clearly | Use abbreviations |121| Keep functions small | Write 100+ line functions |122123> **Remember: The user wants working code, not a programming lesson.**124125---126127## Self-Check Before Completing128129Before saying "task complete", verify:130131| Check | Question |132|-------|----------|133| ✅ **Goal met?** | Did I do exactly what user asked? |134| ✅ **Files edited?** | Did I modify all necessary files? |135| ✅ **Code works?** | Did I test/verify the change? |136| ✅ **No errors?** | Lint and type checks pass? |137| ✅ **Nothing forgotten?** | Any edge cases missed? |138139---140141## References142143| File | Purpose |144|------|---------|145| [.cursor/rules/go-style-guide.mdc](.cursor/rules/go-style-guide.mdc) | Go coding standards, naming conventions, error handling, context usage, domain layer design, service patterns, testing conventions |146| [.cursor/rules/frontend-patterns.mdc](.cursor/rules/frontend-patterns.mdc) | TypeScript standards, React patterns, state management, code organization, unused imports/variables rules, control flow statement braces |147148---149> Converted and distributed by [TomeVault](https://tomevault.io/claim/pedromsmoreira) — claim your Tome and manage your conversions.150<!-- tomevault:4.0:skill_md:2026-04-13 -->
tomevault-io