clean-code
Scannednpx machina-cli add skill vudovn/antigravity-kit/clean-code --openclawFiles (1)
SKILL.md
6.5 KB
Clean Code - Pragmatic AI Coding Standards
CRITICAL SKILL - Be concise, direct, and solution-focused.
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 (MANDATORY)
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 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
| Agent | Script | Command |
|---|---|---|
| frontend-specialist | UX Audit | python .agent/skills/frontend-design/scripts/ux_audit.py . |
| frontend-specialist | A11y Check | python .agent/skills/frontend-design/scripts/accessibility_checker.py . |
| backend-specialist | API Validator | python .agent/skills/api-patterns/scripts/api_validator.py . |
| mobile-developer | Mobile Audit | python .agent/skills/mobile-design/scripts/mobile_audit.py . |
| database-architect | Schema Validate | python .agent/skills/database-design/scripts/schema_validator.py . |
| security-auditor | Security Scan | python .agent/skills/vulnerability-scanner/scripts/security_scan.py . |
| seo-specialist | SEO Check | python .agent/skills/seo-fundamentals/scripts/seo_checker.py . |
| seo-specialist | GEO Check | python .agent/skills/geo-fundamentals/scripts/geo_checker.py . |
| performance-optimizer | Lighthouse | python .agent/skills/performance-profiling/scripts/lighthouse_audit.py <url> |
| test-engineer | Test Runner | python .agent/skills/testing-patterns/scripts/test_runner.py . |
| test-engineer | Playwright | python .agent/skills/webapp-testing/scripts/playwright_runner.py <url> |
| Any agent | Lint Check | python .agent/skills/lint-and-validate/scripts/lint_runner.py . |
| Any agent | Type Coverage | python .agent/skills/lint-and-validate/scripts/type_coverage.py . |
| Any agent | i18n Check | python .agent/skills/i18n-localization/scripts/i18n_checker.py . |
❌ WRONG:
test-engineerrunningux_audit.py✅ CORRECT:frontend-specialistrunningux_audit.py
🔴 Script Output Handling (READ → SUMMARIZE → ASK)
When running a validation script, you MUST:
- Run the script and capture ALL output
- Parse the output - identify errors, warnings, and passes
- 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?**
- Wait for user confirmation before fixing
- 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.
Source
git clone https://github.com/vudovn/antigravity-kit/blob/main/.agent/skills/clean-code/SKILL.mdView on GitHub Overview
Clean Code provides pragmatic standards for concise, direct software. It emphasizes SRP, DRY, KISS, and YAGNI, with clear naming and minimal comments. Following these rules keeps code maintainable, readable, and faster to evolve.
How This Skill Works
It enforces naming and structural rules: small, single-purpose functions, few arguments, and one level of abstraction. It promotes guard clauses, flat nesting, composition, and colocated code, while driving out unnecessary comments and magic numbers.
When to Use It
- Starting a new module or feature with clearly defined responsibilities.
- Refactoring legacy code to remove duplication and complexity.
- Building APIs or services where predictable behavior and readability matter.
- Collaborating in teams to improve maintainability and onboarding speed.
- Working on codebases where directness and minimal noise are prioritized over cleverness.
Quick Start
- Step 1: Audit current code for SRP, KISS, and DRY violations; mark areas with long functions, magic numbers, or unclear names.
- Step 2: Refactor into small, single-purpose functions with clear names; replace magic numbers with named constants.
- Step 3: Remove unnecessary comments; ensure code self-documents through naming and structure, and add guard clauses where appropriate.
Best Practices
- Name things clearly; avoid abbreviations and ambiguous terms.
- Keep functions small; strive for 5-10 lines, max 20 lines, with one responsibility.
- Use guard clauses and early returns to reduce nesting and complexity.
- Remove obvious comments; if a name isn’t descriptive, rename it instead.
- Replace magic numbers with named constants and document their meaning via the constant name.
Example Use Cases
- Rename a cryptic variable like n to userCount to reveal intent.
- Split a 120-line function into several small helpers that each do one thing.
- Replace nested if-else chains with guard clauses for edge cases.
- Replace magic numbers with named constants such as MAX_RETRY_COUNT or TIMEOUT_MS.
- Inline simple one-liner helpers when they’re used in only a couple places, rather than creating extra utility files.
Frequently Asked Questions
Add this skill to your agents
