ForgeLM/.agents/rules/core-design-principles.md

trigger

trigger
always_on

Core Design Principles

SOLID Principles

Single Responsibility Principle (SRP):

• Each class, module, or function should have ONE and ONLY ONE reason to change
• Generate focused, cohesive units of functionality
• If explaining what something does requires "and", it likely violates SRP

Open/Closed Principle (OCP):

• Software entities should be open for extension but closed for modification
• Design abstractions (interfaces, ports) that allow behavior changes without modifying existing code
• Use composition and dependency injection to enable extensibility

Liskov Substitution Principle (LSP):

• Subtypes must be substitutable for their base types without altering program correctness
• Inheritance hierarchies must maintain behavioral consistency
• If substituting a subclass breaks functionality, LSP is violated

Interface Segregation Principle (ISP):

• Clients should not be forced to depend on interfaces they don't use
• Create focused, role-specific interfaces rather than monolithic ones
• Many small, cohesive interfaces > one large, general-purpose interface

Dependency Inversion Principle (DIP):

• Depend on abstractions (interfaces/ports), not concretions (implementations/adapters)
• High-level modules should not depend on low-level modules; both should depend on abstractions
• Core principle enabling Testability-First architecture

Essential Design Practices

DRY (Don't Repeat Yourself):

• Eliminate code duplication through proper abstraction, shared utilities, composable functions
• Each piece of knowledge should have single, authoritative representation
• Don't duplicate logic, algorithms, or business rules

YAGNI (You Aren't Gonna Need It):

CRITICAL: Code maintainability always prevail

• Avoid implementing functionality before it's actually required
• Don't add features based on speculation about future needs
• Build for today's requirements, refactor when needs change

KISS (Keep It Simple, Stupid):

CRITICAL: Code maintainability always prevail

• Prefer simple(simple to maintain), straightforward solutions over complex, clever ones
• Complexity should be justified by actual requirements, not theoretical flexibility
• Simple code is easier to test, maintain, and debug

Separation of Concerns:

• Divide program functionality into distinct sections with minimal overlap
• Each concern should be isolated in its own module or layer

Composition Over Inheritance:

• Favor object composition and delegation over class inheritance for code reuse
• Composition is more flexible and easier to test
• Use interfaces/traits for polymorphism instead of deep inheritance hierarchies

Principle of Least Astonishment:

• Code should behave in ways that users and maintainers naturally expect
• Avoid surprising or counterintuitive behavior
• Follow established conventions and patterns

User Experience vs Maintainability:

• Both user experience AND code maintainability matter
• When they conflict, prefer maintainable code that can evolve
• Poor UX from clean code can be fixed; poor code from UX pressure becomes tech debt
• Maintainability enables future UX improvements
• Never sacrifice code quality for short-term UX gains

Related Principles

• Architectural Patterns — Testability-First Design @architectural-pattern.md
• Code Organization Principles @code-organization-principles.md
• Documentation Principles @documentation-principles.md
• Accessibility Principles @accessibility-principles.md