Added AI skills
This commit is contained in:
Jose Selesan
320
.agents/skills/clean-code-principles/rules/_sections.md
Normal file
320
.agents/skills/clean-code-principles/rules/_sections.md
Normal file
@@ -0,0 +1,320 @@
|
||||
# Clean Code Principles - Rule Categories
|
||||
|
||||
This document defines the organizational structure for clean code principles, ordered by priority and impact.
|
||||
|
||||
## Category Overview
|
||||
|
||||
| Priority | Category | Impact | Rule Count | Prefix |
|
||||
|----------|----------|--------|------------|--------|
|
||||
| 1 | SOLID Principles | CRITICAL | 10 | `solid-` |
|
||||
| 2 | Core Principles | CRITICAL | 12 | `core-` |
|
||||
| 3 | Design Patterns | HIGH | 1 | `pattern-` |
|
||||
| 4 | Code Organization | HIGH | 0 | `org-` |
|
||||
| 5 | Naming & Readability | MEDIUM | 0 | `name-` |
|
||||
| 6 | Functions & Methods | MEDIUM | 0 | `func-` |
|
||||
| 7 | Comments & Documentation | LOW | 0 | `doc-` |
|
||||
|
||||
## 1. SOLID Principles (CRITICAL)
|
||||
|
||||
**Priority:** CRITICAL
|
||||
**Impact:** Architectural foundation, affects entire codebase structure
|
||||
**Prefix:** `solid-`
|
||||
|
||||
The five fundamental principles of object-oriented design that guide maintainable, scalable software architecture.
|
||||
|
||||
### Rules
|
||||
|
||||
#### Single Responsibility Principle (SRP)
|
||||
- `solid-srp-class` - A class should have only one reason to change
|
||||
- `solid-srp-function` - A function should do one thing and do it well
|
||||
|
||||
#### Open/Closed Principle (OCP)
|
||||
- `solid-ocp-extension` - Open for extension, closed for modification
|
||||
- `solid-ocp-abstraction` - Use abstractions to enable extension
|
||||
|
||||
#### Liskov Substitution Principle (LSP)
|
||||
- `solid-lsp-contracts` - Subtypes must honor base type contracts
|
||||
- `solid-lsp-preconditions` - Cannot strengthen preconditions or weaken postconditions
|
||||
|
||||
#### Interface Segregation Principle (ISP)
|
||||
- `solid-isp-clients` - Client-specific interfaces, not general-purpose
|
||||
- `solid-isp-interfaces` - Small, cohesive interfaces
|
||||
|
||||
#### Dependency Inversion Principle (DIP)
|
||||
- `solid-dip-abstractions` - Depend on abstractions, not concretions
|
||||
- `solid-dip-injection` - Inject dependencies from outside
|
||||
|
||||
**Key Concepts:**
|
||||
- Architectural soundness
|
||||
- Maintainability at scale
|
||||
- Testability through design
|
||||
- Flexibility for change
|
||||
- Reduced coupling
|
||||
|
||||
**When to Apply:**
|
||||
- Designing new features or systems
|
||||
- Refactoring existing architecture
|
||||
- Addressing technical debt
|
||||
- Improving testability
|
||||
- Planning for future extensibility
|
||||
|
||||
---
|
||||
|
||||
## 2. Core Principles (CRITICAL)
|
||||
|
||||
**Priority:** CRITICAL
|
||||
**Impact:** Daily coding practices, code quality foundation
|
||||
**Prefix:** `core-`
|
||||
|
||||
Fundamental principles that apply to every line of code you write, regardless of paradigm or language.
|
||||
|
||||
### Rules
|
||||
|
||||
#### DRY (Don't Repeat Yourself)
|
||||
- `core-dry` - Every piece of knowledge should have a single representation
|
||||
- `core-dry-extraction` - Extract duplicated code into reusable functions
|
||||
- `core-dry-single-source` - Single source of truth for configuration and data
|
||||
|
||||
#### KISS (Keep It Simple, Stupid)
|
||||
- `core-kiss-simplicity` - Choose the simplest solution that works
|
||||
- `core-kiss-readability` - Optimize for readability over cleverness
|
||||
|
||||
#### YAGNI (You Aren't Gonna Need It)
|
||||
- `core-yagni-features` - Don't implement features before they're needed
|
||||
- `core-yagni-abstractions` - Don't create abstractions prematurely
|
||||
|
||||
#### Other Core Principles
|
||||
- `core-separation-concerns` - Different concerns in different modules
|
||||
- `core-composition` - Favor composition over inheritance
|
||||
- `core-law-demeter` - Only talk to immediate friends
|
||||
- `core-fail-fast` - Detect and report errors early
|
||||
- `core-encapsulation` - Hide implementation details
|
||||
|
||||
**Key Concepts:**
|
||||
- Code duplication elimination
|
||||
- Simplicity over complexity
|
||||
- Lean development
|
||||
- Modularity
|
||||
- Information hiding
|
||||
|
||||
**When to Apply:**
|
||||
- Writing any new code
|
||||
- Code reviews
|
||||
- Refactoring sessions
|
||||
- Bug fixes
|
||||
- Performance optimization
|
||||
|
||||
---
|
||||
|
||||
## 3. Design Patterns (HIGH)
|
||||
|
||||
**Priority:** HIGH
|
||||
**Impact:** Solves recurring problems with proven solutions
|
||||
**Prefix:** `pattern-`
|
||||
|
||||
Common design patterns that provide tested solutions to recurring software design problems.
|
||||
|
||||
### Rules
|
||||
|
||||
- `pattern-repository` - Abstraction for data access layer
|
||||
- `pattern-factory` - Object creation without specifying exact class (planned)
|
||||
- `pattern-strategy` - Encapsulate algorithms for runtime selection (planned)
|
||||
- `pattern-decorator` - Add behavior without modifying objects (planned)
|
||||
- `pattern-observer` - Define one-to-many dependencies (planned)
|
||||
- `pattern-adapter` - Make incompatible interfaces work together (planned)
|
||||
- `pattern-facade` - Simplified interface to complex subsystems (planned)
|
||||
|
||||
**Key Concepts:**
|
||||
- Proven solutions
|
||||
- Common vocabulary
|
||||
- Design reusability
|
||||
- Best practices codified
|
||||
- Language-agnostic approaches
|
||||
|
||||
**When to Apply:**
|
||||
- Solving common architectural problems
|
||||
- Improving code structure
|
||||
- Reducing coupling between components
|
||||
- Making systems more testable
|
||||
- Communicating design intent
|
||||
|
||||
---
|
||||
|
||||
## 4. Code Organization (HIGH)
|
||||
|
||||
**Priority:** HIGH
|
||||
**Impact:** Project structure, module boundaries, discoverability
|
||||
**Prefix:** `org-`
|
||||
|
||||
Principles for organizing code into modules, packages, and directories for maintainability and scalability.
|
||||
|
||||
### Rules (Planned)
|
||||
|
||||
- `org-feature-folders` - Organize by feature, not by layer
|
||||
- `org-module-boundaries` - Clear boundaries between modules
|
||||
- `org-layered-architecture` - Proper separation of layers
|
||||
- `org-package-cohesion` - Keep related code together
|
||||
- `org-circular-dependencies` - Avoid circular imports
|
||||
|
||||
**Key Concepts:**
|
||||
- Feature-based organization
|
||||
- Module boundaries
|
||||
- Layer separation
|
||||
- Dependency direction
|
||||
- Discoverability
|
||||
|
||||
**When to Apply:**
|
||||
- Starting new projects
|
||||
- Restructuring existing codebases
|
||||
- Scaling applications
|
||||
- Onboarding new team members
|
||||
- Managing microservices
|
||||
|
||||
---
|
||||
|
||||
## 5. Naming & Readability (MEDIUM)
|
||||
|
||||
**Priority:** MEDIUM
|
||||
**Impact:** Code comprehension, maintenance speed
|
||||
**Prefix:** `name-`
|
||||
|
||||
Conventions and principles for naming variables, functions, classes, and other identifiers.
|
||||
|
||||
### Rules (Planned)
|
||||
|
||||
- `name-meaningful` - Use intention-revealing names
|
||||
- `name-consistent` - Follow consistent naming conventions
|
||||
- `name-searchable` - Avoid magic numbers and strings
|
||||
- `name-avoid-encodings` - No Hungarian notation
|
||||
- `name-domain-language` - Use ubiquitous domain language
|
||||
|
||||
**Key Concepts:**
|
||||
- Intention revelation
|
||||
- Consistency
|
||||
- Searchability
|
||||
- Domain terminology
|
||||
- Avoid abbreviations
|
||||
|
||||
**When to Apply:**
|
||||
- Creating new identifiers
|
||||
- Refactoring unclear names
|
||||
- Code reviews
|
||||
- Domain modeling
|
||||
- API design
|
||||
|
||||
---
|
||||
|
||||
## 6. Functions & Methods (MEDIUM)
|
||||
|
||||
**Priority:** MEDIUM
|
||||
**Impact:** Code readability, testability at function level
|
||||
**Prefix:** `func-`
|
||||
|
||||
Principles for writing clean, focused functions and methods.
|
||||
|
||||
### Rules (Planned)
|
||||
|
||||
- `func-small` - Keep functions small and focused
|
||||
- `func-single-purpose` - Do one thing only
|
||||
- `func-few-arguments` - Limit function parameters
|
||||
- `func-no-side-effects` - Minimize or document side effects
|
||||
- `func-command-query` - Separate commands from queries
|
||||
|
||||
**Key Concepts:**
|
||||
- Small functions
|
||||
- Single purpose
|
||||
- Few parameters
|
||||
- Pure functions when possible
|
||||
- Predictable behavior
|
||||
|
||||
**When to Apply:**
|
||||
- Writing new functions
|
||||
- Refactoring long methods
|
||||
- Improving testability
|
||||
- Code reviews
|
||||
- Performance optimization
|
||||
|
||||
---
|
||||
|
||||
## 7. Comments & Documentation (LOW)
|
||||
|
||||
**Priority:** LOW
|
||||
**Impact:** Code maintainability, knowledge transfer
|
||||
**Prefix:** `doc-`
|
||||
|
||||
Guidelines for when and how to use comments and documentation effectively.
|
||||
|
||||
### Rules (Planned)
|
||||
|
||||
- `doc-self-documenting` - Write code that explains itself
|
||||
- `doc-why-not-what` - Comments should explain why, not what
|
||||
- `doc-avoid-noise` - No redundant or obvious comments
|
||||
- `doc-api-docs` - Document public APIs and interfaces
|
||||
|
||||
**Key Concepts:**
|
||||
- Self-documenting code
|
||||
- Intent over implementation
|
||||
- Avoid redundancy
|
||||
- Public API documentation
|
||||
- Living documentation
|
||||
|
||||
**When to Apply:**
|
||||
- Complex business logic
|
||||
- Non-obvious algorithms
|
||||
- Public APIs
|
||||
- Architectural decisions
|
||||
- Workarounds and hacks
|
||||
|
||||
---
|
||||
|
||||
## Rule Naming Convention
|
||||
|
||||
All rules follow a consistent naming pattern:
|
||||
|
||||
```
|
||||
{prefix}-{concept}-{specificity}
|
||||
```
|
||||
|
||||
Examples:
|
||||
- `solid-srp-class` - SOLID principle, SRP concept, class level
|
||||
- `core-dry-extraction` - Core principle, DRY concept, extraction technique
|
||||
- `pattern-repository` - Design pattern category, repository pattern
|
||||
|
||||
## Priority Levels Explained
|
||||
|
||||
- **CRITICAL**: Core architectural and coding principles. Violations significantly impact maintainability, testability, and scalability.
|
||||
- **HIGH**: Important patterns and organizational principles. Violations complicate future development.
|
||||
- **MEDIUM**: Best practices that improve code quality. Violations make code harder to read and maintain.
|
||||
- **LOW**: Nice-to-have practices. Violations have minimal impact but reduce clarity.
|
||||
|
||||
## Impact Assessment
|
||||
|
||||
- **CRITICAL Impact**: Affects entire system architecture, multiple teams, long-term maintainability
|
||||
- **HIGH Impact**: Affects module design, team productivity, medium-term maintainability
|
||||
- **MEDIUM Impact**: Affects code readability, individual developer productivity
|
||||
- **LOW Impact**: Affects code clarity, documentation quality
|
||||
|
||||
## Usage Guidelines
|
||||
|
||||
1. Start with SOLID and Core Principles - these are non-negotiable
|
||||
2. Apply Design Patterns when solving specific architectural problems
|
||||
3. Use Code Organization principles when structuring projects
|
||||
4. Follow Naming & Readability guidelines for all new code
|
||||
5. Apply Function principles during refactoring and new development
|
||||
6. Add Comments only when necessary to explain complex logic
|
||||
|
||||
## Cross-References
|
||||
|
||||
Rules often relate to each other. The `related` field in each rule's frontmatter indicates:
|
||||
- Rules that commonly apply together
|
||||
- Rules that solve similar problems
|
||||
- Rules that complement each other
|
||||
- Rules that provide context or prerequisites
|
||||
|
||||
## Evolution
|
||||
|
||||
This categorization will evolve as:
|
||||
- New rules are added
|
||||
- Patterns emerge from practice
|
||||
- Team feedback is incorporated
|
||||
- Language-specific adaptations are needed
|
||||
Reference in New Issue
Block a user