gruperly/.agents/skills/clean-code-principles/AGENTS.md

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:

• Single Responsibility: solid-srp-class, solid-srp-function
• Open/Closed: solid-ocp-extension, solid-ocp-abstraction
• Liskov Substitution: solid-lsp-contracts, solid-lsp-preconditions
• Interface Segregation: solid-isp-clients, solid-isp-interfaces
• Dependency 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:

---
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.