AGENT SKILL

clean-code

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

License 许可
MIT
最近更新
2026-09-12
Stars
★ 2
Forks
0

01 前言 Front Matter

name
clean-code
version
2
priority
CRITICAL
description
Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments
allowed-tools
Read, Write, Edit

03 SKILL.md 正文

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 ~/.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:

  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.

04 同仓库更多 Skills

Carchaloneo22
Carchaloneo22/Claude-Code-template

zapier-make-patterns

No-code automation democratizes workflow building. Zapier and Make (formerly Integromat) let non-developers automate business processes without writing code. But no-code doesn't mean no-complexity - these platforms have their own patterns, pitfalls, and breaking points. This skill covers when to use which platform, how to build reliable automations, and when to graduate to code-based solutions. Key insight: Zapier optimizes for simplicity and integrations (7000+ apps), Make optimizes for power

★ 2
Carchaloneo22
Carchaloneo22/Claude-Code-template

yeet

Use only when the user explicitly asks to stage, commit, push, and open a GitHub pull request in one flow using the GitHub CLI (`gh`).

★ 2
Carchaloneo22
Carchaloneo22/Claude-Code-template

workflow-automation

Workflow automation is the infrastructure that makes AI agents reliable. Without durable execution, a network hiccup during a 10-step payment flow means lost money and angry customers. With it, workflows resume exactly where they left off. This skill covers the platforms (n8n, Temporal, Inngest) and patterns (sequential, parallel, orchestrator-worker) that turn brittle scripts into production-grade automation. Key insight: The platforms make different tradeoffs. n8n optimizes for accessibility

★ 2
Carchaloneo22
Carchaloneo22/Claude-Code-template

trigger-dev

Trigger.dev expert for background jobs, AI workflows, and reliable async execution with excellent developer experience and TypeScript-first design. Use when: trigger.dev, trigger dev, background task, ai background job, long running task.

★ 2
Carchaloneo22
Carchaloneo22/Claude-Code-template

planning-with-files

Transforms workflow to use Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Use when starting complex tasks, multi-step projects, research tasks, or when the user mentions planning, organizing work, tracking progress, or wants structured output.

★ 2
Carchaloneo22
Carchaloneo22/Claude-Code-template

n8n-workflow-patterns

Proven workflow architectural patterns from real n8n workflows. Use when building new workflows, designing workflow structure, choosing workflow patterns, planning workflow architecture, or asking about webhook processing, HTTP API integration, database operations, AI agent workflows, or scheduled tasks.

★ 2