451 lines
14 KiB
Markdown
451 lines
14 KiB
Markdown
# Clean Code Principles - Agent Documentation
|
|
|
|
**Version:** 1.0.2
|
|
**Focus:** SOLID Principles, Core Principles (DRY, KISS, YAGNI), Design Patterns
|
|
**Rules:** 23 (10 SOLID + 12 Core + 1 Pattern); 4 categories planned
|
|
**License:** MIT
|
|
|
|
---
|
|
|
|
This skill provides comprehensive clean code principles, SOLID guidelines, and design patterns for building maintainable, scalable software.
|
|
|
|
## Overview
|
|
|
|
The clean-code-principles skill offers language-agnostic software design principles organized into 7 categories, from CRITICAL (SOLID, Core Principles) to LOW priority (Comments). Each rule provides bad/good examples, explanations, and practical guidance.
|
|
|
|
## When to Use This Skill
|
|
|
|
Activate this skill when:
|
|
- Reviewing code architecture or design
|
|
- Refactoring existing code
|
|
- Making design decisions
|
|
- Establishing coding standards
|
|
- Teaching software design principles
|
|
- Addressing technical debt
|
|
- Improving code quality and maintainability
|
|
|
|
## Trigger Phrases
|
|
|
|
The skill activates on:
|
|
- "review architecture"
|
|
- "check code quality"
|
|
- "SOLID principles"
|
|
- "design patterns"
|
|
- "clean code"
|
|
- "refactoring advice"
|
|
- "code smells"
|
|
- "best practices"
|
|
- "DRY principle"
|
|
- "separation of concerns"
|
|
|
|
## Skill Structure
|
|
|
|
```
|
|
clean-code-principles/
|
|
├── SKILL.md # Main skill definition
|
|
├── AGENTS.md # This file - agent documentation
|
|
├── README.md # User-facing documentation
|
|
├── metadata.json # Structured metadata and references
|
|
└── rules/
|
|
├── _sections.md # Category definitions and organization
|
|
├── _template.md # Template for new rules
|
|
├── solid-*.md # SOLID principles (10 rules)
|
|
├── core-*.md # Core principles (12 rules)
|
|
└── pattern-*.md # Design patterns (1 rule)
|
|
```
|
|
|
|
## Rule Categories
|
|
|
|
### 1. SOLID Principles (CRITICAL - 10 rules)
|
|
**Prefix:** `solid-`
|
|
|
|
Five fundamental object-oriented design principles:
|
|
- **S**ingle Responsibility: `solid-srp-class`, `solid-srp-function`
|
|
- **O**pen/Closed: `solid-ocp-extension`, `solid-ocp-abstraction`
|
|
- **L**iskov Substitution: `solid-lsp-contracts`, `solid-lsp-preconditions`
|
|
- **I**nterface Segregation: `solid-isp-clients`, `solid-isp-interfaces`
|
|
- **D**ependency Inversion: `solid-dip-abstractions`, `solid-dip-injection`
|
|
|
|
**Use when:** Designing architecture, planning refactoring, discussing system design
|
|
|
|
### 2. Core Principles (CRITICAL - 12 rules)
|
|
**Prefix:** `core-`
|
|
|
|
Fundamental coding practices:
|
|
- **DRY** (Don't Repeat Yourself): 3 rules
|
|
- **KISS** (Keep It Simple): 2 rules
|
|
- **YAGNI** (You Aren't Gonna Need It): 2 rules
|
|
- **Other**: Separation of Concerns, Composition Over Inheritance, Law of Demeter, Fail Fast, Encapsulation
|
|
|
|
**Use when:** Daily coding, code reviews, addressing duplication or complexity
|
|
|
|
### 3. Design Patterns (HIGH - 1 rule)
|
|
**Prefix:** `pattern-`
|
|
|
|
Common solutions to recurring problems:
|
|
- Repository Pattern (data access abstraction)
|
|
|
|
**Use when:** Solving architectural problems, abstracting infrastructure concerns
|
|
|
|
### 4-7. Future Categories
|
|
- **Code Organization** (`org-`): Module structure, boundaries
|
|
- **Naming & Readability** (`name-`): Identifier naming conventions
|
|
- **Functions & Methods** (`func-`): Function-level best practices
|
|
- **Comments & Documentation** (`doc-`): Documentation guidelines
|
|
|
|
## How to Use Rules
|
|
|
|
### Accessing Rules
|
|
|
|
1. **By ID:** Reference specific rules using their ID
|
|
```
|
|
Check against solid-srp-class and core-dry
|
|
```
|
|
|
|
2. **By Category:** Apply all rules in a category
|
|
```
|
|
Review this class against SOLID principles
|
|
```
|
|
|
|
3. **By Scenario:** Choose relevant rules for the context
|
|
```
|
|
This has duplicated validation logic - check DRY rules
|
|
```
|
|
|
|
### Rule Format
|
|
|
|
Each rule follows a consistent structure:
|
|
|
|
```markdown
|
|
---
|
|
id: {rule-id}
|
|
title: {Full Title}
|
|
category: {category}
|
|
priority: {critical|high|medium|low}
|
|
tags: [{tags}]
|
|
related: [{related-rule-ids}]
|
|
---
|
|
|
|
# {Rule Title}
|
|
|
|
{One-sentence summary}
|
|
|
|
## Bad Example
|
|
{Anti-pattern code with problems listed}
|
|
|
|
## Good Example
|
|
{Correct implementation with benefits}
|
|
|
|
## Why
|
|
{5-7 benefits explaining the value}
|
|
|
|
## When to Apply
|
|
{Practical scenarios}
|
|
```
|
|
|
|
### Output Format
|
|
|
|
When identifying violations, use:
|
|
|
|
```
|
|
file:line - [rule-id] Description of issue
|
|
```
|
|
|
|
Example:
|
|
```
|
|
src/services/UserService.ts:15 - [solid-srp-class] Class handles validation, persistence, and notifications
|
|
src/utils/helpers.ts:42 - [core-dry] Email validation duplicated from validators/email.ts
|
|
src/models/Order.ts:28 - [core-kiss-simplicity] Overly complex abstraction for simple use case
|
|
```
|
|
|
|
## Agent Strategies
|
|
|
|
### Strategy 1: Architecture Review
|
|
|
|
**Goal:** Assess overall system design
|
|
|
|
**Approach:**
|
|
1. Start with SOLID principles (highest impact)
|
|
2. Identify violations of SRP, DIP, OCP
|
|
3. Check for proper separation of concerns
|
|
4. Evaluate composition vs inheritance
|
|
5. Assess interface design (ISP)
|
|
|
|
**Output:** Prioritized list of architectural issues with rule references
|
|
|
|
### Strategy 2: Code Quality Audit
|
|
|
|
**Goal:** Find code quality issues in specific files
|
|
|
|
**Approach:**
|
|
1. Scan for duplication (DRY rules)
|
|
2. Check complexity (KISS rules)
|
|
3. Look for overengineering (YAGNI rules)
|
|
4. Verify single responsibility
|
|
5. Assess encapsulation
|
|
|
|
**Output:** File-by-file findings with specific line references
|
|
|
|
### Strategy 3: Refactoring Guidance
|
|
|
|
**Goal:** Provide actionable refactoring steps
|
|
|
|
**Approach:**
|
|
1. Identify the primary issue (which rule violated)
|
|
2. Reference the good example from that rule
|
|
3. Suggest specific refactoring steps
|
|
4. Mention related rules that may also help
|
|
5. Prioritize changes by impact
|
|
|
|
**Output:** Step-by-step refactoring plan with rule references
|
|
|
|
### Strategy 4: Design Decision Support
|
|
|
|
**Goal:** Help choose between design alternatives
|
|
|
|
**Approach:**
|
|
1. Analyze each option against relevant principles
|
|
2. Consider YAGNI (simplest solution first)
|
|
3. Evaluate against SOLID principles
|
|
4. Check alignment with KISS
|
|
5. Recommend based on principle adherence
|
|
|
|
**Output:** Comparative analysis with principle-based recommendation
|
|
|
|
### Strategy 5: Pattern Application
|
|
|
|
**Goal:** Suggest appropriate design patterns
|
|
|
|
**Approach:**
|
|
1. Identify the problem being solved
|
|
2. Check if any patterns apply
|
|
3. Verify pattern aligns with SOLID principles
|
|
4. Ensure pattern isn't overengineering (YAGNI)
|
|
5. Provide implementation guidance
|
|
|
|
**Output:** Pattern recommendation with integration guidance
|
|
|
|
## Best Practices for Agents
|
|
|
|
### Do:
|
|
- Start with CRITICAL rules (SOLID, Core)
|
|
- Provide specific line numbers when possible
|
|
- Reference rule IDs in all findings
|
|
- Explain WHY a rule matters, not just that it's violated
|
|
- Give actionable refactoring suggestions
|
|
- Consider the codebase context
|
|
- Prioritize by impact (CRITICAL > HIGH > MEDIUM > LOW)
|
|
- Show code examples from the rules
|
|
- Mention related rules that apply together
|
|
|
|
### Don't:
|
|
- Don't cite every minor violation
|
|
- Don't recommend patterns without clear need (YAGNI)
|
|
- Don't ignore context (some violations may be acceptable)
|
|
- Don't focus on LOW priority rules when CRITICAL issues exist
|
|
- Don't provide fixes without explaining the principle
|
|
- Don't recommend complex solutions for simple problems (KISS)
|
|
- Don't suggest abstractions without concrete use cases (YAGNI)
|
|
|
|
### Prioritization
|
|
|
|
When multiple issues exist:
|
|
1. **CRITICAL - SOLID violations:** Architecture-level problems
|
|
2. **CRITICAL - Core violations:** Duplication, complexity, overengineering
|
|
3. **HIGH - Pattern opportunities:** Where patterns genuinely help
|
|
4. **MEDIUM - Naming/Functions:** Readability improvements
|
|
5. **LOW - Documentation:** Comment and doc issues
|
|
|
|
## Example Interactions
|
|
|
|
### Example 1: Architecture Review
|
|
|
|
**User:** "Review the architecture of this OrderService class"
|
|
|
|
**Agent Approach:**
|
|
1. Check class responsibilities against `solid-srp-class`
|
|
2. Evaluate dependencies against `solid-dip-injection`
|
|
3. Look for data access against `pattern-repository`
|
|
4. Check for proper separation against `core-separation-concerns`
|
|
|
|
**Agent Output:**
|
|
```
|
|
Architecture Review - OrderService
|
|
|
|
CRITICAL Issues:
|
|
1. [solid-srp-class] Class has multiple responsibilities:
|
|
- Order validation (should be separate validator)
|
|
- Direct database access (should use repository)
|
|
- Email sending (should be separate service)
|
|
- Payment processing (should be separate service)
|
|
|
|
2. [solid-dip-abstractions] Direct dependency on concrete implementations:
|
|
- Instantiates MySQLDatabase directly (line 15)
|
|
- Creates StripePaymentGateway in constructor (line 18)
|
|
|
|
3. [pattern-repository] Direct SQL queries in service layer:
|
|
- Lines 45-50: Raw SQL should be in repository
|
|
|
|
Recommendations:
|
|
1. Split into focused classes following SRP
|
|
2. Inject dependencies through constructor (DIP)
|
|
3. Create repository abstraction for data access
|
|
4. Extract email and payment to separate services
|
|
|
|
See: solid-srp-class.md, solid-dip-injection.md, pattern-repository.md
|
|
```
|
|
|
|
### Example 2: Code Quality Check
|
|
|
|
**User:** "Check this validation function for code quality issues"
|
|
|
|
**Agent Approach:**
|
|
1. Check for duplication (`core-dry`)
|
|
2. Check complexity (`core-kiss-simplicity`)
|
|
3. Check function responsibility (`solid-srp-function`)
|
|
|
|
**Agent Output:**
|
|
```
|
|
Code Quality Issues:
|
|
|
|
utils/validation.ts:
|
|
Line 23 - [core-dry] Email regex duplicated from line 45 and validators/email.ts
|
|
Line 30 - [core-dry-extraction] Password validation logic should be extracted to reusable function
|
|
Line 50 - [solid-srp-function] Function validates both email AND password - split into two functions
|
|
|
|
Suggested refactoring:
|
|
1. Extract common regex patterns to constants file (core-dry-single-source)
|
|
2. Create separate validateEmail() and validatePassword() functions (solid-srp-function)
|
|
3. Import from shared validators module (core-dry-extraction)
|
|
|
|
See: core-dry.md, core-dry-extraction.md, solid-srp-function.md
|
|
```
|
|
|
|
### Example 3: Design Decision
|
|
|
|
**User:** "Should I use inheritance or composition for this User/Admin relationship?"
|
|
|
|
**Agent Approach:**
|
|
1. Apply `core-composition` principle
|
|
2. Check LSP implications (`solid-lsp-contracts`)
|
|
3. Consider YAGNI (`core-yagni-abstractions`)
|
|
|
|
**Agent Output:**
|
|
```
|
|
Recommendation: Use Composition
|
|
|
|
Analysis:
|
|
1. [core-composition] Composition is preferred over inheritance for flexibility
|
|
- Admins can have additional capabilities without inheritance constraints
|
|
- Easier to test each capability independently
|
|
- Can mix different permission sets dynamically
|
|
|
|
2. [solid-lsp-contracts] Inheritance risks LSP violations
|
|
- If Admin overrides User methods differently
|
|
- If Admin has different behavior expectations
|
|
|
|
3. [core-yagni-abstractions] Start simple
|
|
- Don't create inheritance hierarchy unless you need polymorphism
|
|
- Compose from Permission and Role objects instead
|
|
|
|
Suggested approach:
|
|
```typescript
|
|
class User {
|
|
constructor(
|
|
private permissions: PermissionSet,
|
|
private roleManager: RoleManager
|
|
) {}
|
|
}
|
|
```
|
|
|
|
See: core-composition.md, solid-lsp-contracts.md
|
|
```
|
|
|
|
## Integration with Other Skills
|
|
|
|
This skill complements:
|
|
- **refactoring**: Provides principles for refactoring decisions
|
|
- **architecture-review**: Supplies SOLID and design principles
|
|
- **code-review**: Offers quality criteria for reviews
|
|
- **testing**: Promotes testable design (DIP, SRP)
|
|
|
|
## Rule Reference Quick Guide
|
|
|
|
### Most Common Rules
|
|
|
|
**For duplication:**
|
|
- `core-dry` - Main DRY principle
|
|
- `core-dry-extraction` - How to extract duplicated code
|
|
- `core-dry-single-source` - Configuration and constants
|
|
|
|
**For complex code:**
|
|
- `core-kiss-simplicity` - Avoid overengineering
|
|
- `core-kiss-readability` - Optimize for readability
|
|
- `core-yagni-features` - Don't build unused features
|
|
- `core-yagni-abstractions` - Don't abstract prematurely
|
|
|
|
**For class design:**
|
|
- `solid-srp-class` - Single responsibility for classes
|
|
- `solid-dip-injection` - Dependency injection
|
|
- `core-separation-concerns` - Separate different concerns
|
|
- `core-composition` - Favor composition over inheritance
|
|
|
|
**For function design:**
|
|
- `solid-srp-function` - Single responsibility for functions
|
|
- `core-kiss-readability` - Clear, readable functions
|
|
|
|
**For interfaces:**
|
|
- `solid-isp-interfaces` - Small, focused interfaces
|
|
- `solid-isp-clients` - Client-specific interfaces
|
|
|
|
**For extensibility:**
|
|
- `solid-ocp-extension` - Open for extension, closed for modification
|
|
- `solid-ocp-abstraction` - Use abstractions for extension points
|
|
|
|
**For inheritance:**
|
|
- `solid-lsp-contracts` - Subtypes must honor contracts
|
|
- `solid-lsp-preconditions` - Pre/postcondition rules
|
|
- `core-composition` - Prefer composition
|
|
|
|
**For data access:**
|
|
- `pattern-repository` - Abstract data persistence
|
|
|
|
## Metadata
|
|
|
|
**Version:** 1.0.2
|
|
**Rules:** 23 (10 SOLID, 12 Core, 1 Pattern)
|
|
**Categories:** 7 (3 implemented, 4 planned)
|
|
**Languages:** Language-agnostic (examples in TypeScript)
|
|
**Last Updated:** 2026-03-07
|
|
|
|
## Resources
|
|
|
|
### Books
|
|
- Clean Code (Robert C. Martin)
|
|
- Design Patterns (Gang of Four)
|
|
- Refactoring (Martin Fowler)
|
|
- The Pragmatic Programmer (Hunt & Thomas)
|
|
|
|
### Online
|
|
- [Refactoring Guru](https://refactoring.guru/) - Design patterns and code smells
|
|
- [Martin Fowler's Catalog](https://refactoring.com/catalog/) - Refactoring techniques
|
|
- [Uncle Bob's Blog](https://blog.cleancoder.com/) - Software craftsmanship
|
|
|
|
## Contributing New Rules
|
|
|
|
When adding new rules:
|
|
1. Use `rules/_template.md` as starting point
|
|
2. Follow naming convention: `{prefix}-{concept}-{specificity}.md`
|
|
3. Include YAML frontmatter with all required fields
|
|
4. Provide clear bad/good examples
|
|
5. Explain 5-7 benefits in "Why" section
|
|
6. Add to `metadata.json` rules array
|
|
7. Update category counts in `_sections.md`
|
|
8. Reference related rules in frontmatter
|
|
9. Keep examples language-agnostic (TypeScript preferred)
|
|
10. Aim for 300-400 lines of content
|
|
|
|
## License
|
|
|
|
MIT License. This skill is provided as-is for educational and development purposes.
|