Clean Code

by davila78da17d671b6fNo license32K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated today

Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments

Instructions onlySoftware Development

AI-generated overview

Pragmatic coding standards for AI agents: concise code, clear naming, small functions, and pre-edit dependency checks.

What it does: This skill provides a set of coding standards and rules for AI agents writing or editing software. It covers core principles such as single responsibility, DRY, KISS and YAGNI, plus naming conventions, function size limits, code structure patterns, and anti-patterns to avoid. It also instructs the agent to check dependent files before editing and to run a self-check before declaring a task complete.
When to use it: Use it when an AI agent is writing, editing, or reviewing code and should follow consistent pragmatic standards. It is suited to implementation tasks where concise, direct code is preferred over explanations or over-engineering.
Requirements: No scripts or packages are required; it is an instructions-only skill. It references external verification scripts and tools such as Python-based audit and lint scripts, but those are not bundled with this skill.

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

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

AI Coding Style

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:

Quick Check:

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

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 ~/.claude/skills/frontend-design/scripts/ux_audit.py .`
frontend-specialist	A11y Check	`python ~/.claude/skills/frontend-design/scripts/accessibility_checker.py .`
backend-specialist	API Validator	`python ~/.claude/skills/api-patterns/scripts/api_validator.py .`
mobile-developer	Mobile Audit	`python ~/.claude/skills/mobile-design/scripts/mobile_audit.py .`
database-architect	Schema Validate	`python ~/.claude/skills/database-design/scripts/schema_validator.py .`
security-auditor	Security Scan	`python ~/.claude/skills/vulnerability-scanner/scripts/security_scan.py .`
seo-specialist	SEO Check	`python ~/.claude/skills/seo-fundamentals/scripts/seo_checker.py .`
seo-specialist	GEO Check	`python ~/.claude/skills/geo-fundamentals/scripts/geo_checker.py .`
performance-optimizer	Lighthouse	`python ~/.claude/skills/performance-profiling/scripts/lighthouse_audit.py <url>`
test-engineer	Test Runner	`python ~/.claude/skills/testing-patterns/scripts/test_runner.py .`
test-engineer	Playwright	`python ~/.claude/skills/webapp-testing/scripts/playwright_runner.py <url>`
Any agent	Lint Check	`python ~/.claude/skills/lint-and-validate/scripts/lint_runner.py .`
Any agent	Type Coverage	`python ~/.claude/skills/lint-and-validate/scripts/type_coverage.py .`
Any agent	i18n Check	`python ~/.claude/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:

Run the script and capture ALL output
Parse the output - identify errors, warnings, and passes
Summarize to user in this format:

markdown

## 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?**

## 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 and attribution

Source:davila7/claude-code-templatesincli-tool/components/skills/development/clean-codeat commit8da17d6

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

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`

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

Situation	Action
User asks for feature	Write it directly
User reports bug	Fix it, don't explain
No clear requirement	Ask, don't assume

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

Clean Code

Clean Code - Pragmatic AI Coding Standards

Core Principles

Naming Rules

Function Rules

Code Structure

AI Coding Style

Anti-Patterns (DON'T)

🔴 Before Editing ANY File (THINK FIRST!)

Summary

🔴 Self-Check Before Completing (MANDATORY)

Verification Scripts (MANDATORY)

Agent → Script Mapping

🔴 Script Output Handling (READ → SUMMARIZE → ASK)

Source and attribution

More from davila7/claude-code-templates

React Best Practices

Web Performance Optimization

Find Bugs

Browser Automation

Code Review

Commit

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices