Clean Code Principles

A comprehensive collection of software engineering best practices, principles, patterns, and techniques from the most influential books in the field.

When to Apply

Use this skill when:

• Writing new code or refactoring existing code
• Reviewing code for quality and maintainability
• Designing software architecture
• Learning or teaching software engineering principles
• Making technical decisions about patterns and practices
• Working with legacy code
• Setting up naming conventions and coding standards
• Debugging and troubleshooting

What This Skill Covers

1. Principles

• SOLID (Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion)
• GRASP (General Responsibility Assignment Software Patterns)
• DRY, KISS, YAGNI

2. Design Patterns

• GoF Patterns (23 classic patterns)
• Enterprise Patterns (POEAA)
• Stability Patterns (Release It!)
• Distributed Systems Patterns (DDIA)

3. Code Quality

• Code Smells (25+ smells to identify)
• Refactoring Techniques (60+ techniques)
• Clean Code practices (Uncle Bob)

4. Architecture

• Clean Architecture
• Hexagonal/Onion Architecture
• Microservices
• Event-Driven Architecture

5. Domain-Driven Design

• Strategic Design (Bounded Contexts, Ubiquitous Language)
• Tactical Design (Entities, Value Objects, Aggregates, Repositories)

6. Best Practices

• Pragmatic Programmer tips
• Legacy Code techniques
• Testing strategies (TDD)
• Continuous Delivery
• Naming Conventions for multiple languages
• Terry Davis Engineering Principles - Radical simplicity and zero dependencies

Quick Reference

Category	Key Concepts
SOLID	SRP, OCP, LSP, ISP, DIP
Patterns	23 GoF + Enterprise + Stability
Smells	25+ code smells to detect
Refactoring	60+ techniques
Architecture	Clean, Hexagonal, Microservices
DDD	Entities, Value Objects, Aggregates
Terry Davis	Zero dependencies, Radical simplicity

Rule Categories

Principles

• solid-srp - Single Responsibility Principle
• solid-ocp - Open/Closed Principle
• solid-lsp - Liskov Substitution Principle
• solid-isp - Interface Segregation Principle
• solid-dip - Dependency Inversion Principle
• grasp-* - GRASP patterns
• dry, kiss, yagni - Core principles

Design Patterns

• pattern-factory-method
• pattern-singleton
• pattern-builder
• pattern-observer
• pattern-strategy
• pattern-circuit-breaker
• And 40+ more...

Code Smells

• smell-long-method
• smell-large-class
• smell-duplicate-code
• smell-feature-envy
• And 20+ more...

Refactorings

• refactor-extract-method
• refactor-rename-method
• refactor-move-method
• And 55+ more...

Architecture

• arch-clean
• arch-hexagonal
• arch-microservices

Terry Davis Principles

• Complete system comprehension
• Radical simplicity
• Zero dependencies
• Vertical integration
• Immediate feedback
• Source as truth
• One person, one vision

How to Use

Read individual rule files for detailed explanations and code examples:

rules/solid/srp.md
rules/patterns-creational/factory-method.md
rules/smells-bloaters/long-method.md
rules/best-practices/terry-davis-engineering-principles.md

Each rule file contains:

• Brief explanation of why it matters
• When to apply
• Incorrect code example with explanation
• Correct code example with explanation
• Trade-offs and considerations

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

References

This skill draws from:

• Clean Code - Robert C. Martin (2008)
• Clean Architecture - Robert C. Martin (2017)
• Design Patterns - GoF (1994)
• Domain-Driven Design - Eric Evans (2003)
• The Pragmatic Programmer - Hunt & Thomas (1999/2019)
• Refactoring - Martin Fowler (1999/2018)
• Working Effectively with Legacy Code - Michael Feathers (2004)
• Code Complete - Steve McConnell (2004)
• Patterns of Enterprise Application Architecture - Martin Fowler (2002)
• Effective Java - Joshua Bloch (2001/2017)
• Designing Data-Intensive Applications - Martin Kleppmann (2017/2024)
• Release It! - Michael Nygard (2007/2018)
• Building Microservices - Sam Newman (2015/2021)
• Test Driven Development - Kent Beck (2002)
• Continuous Delivery - Humble & Farley (2010)
• The Mythical Man-Month - Fred Brooks (1975/1995)
• TempleOS - Terry Davis