code-principles

name

code-principles

description

Software engineering principles for code review, planning validation, and learning. Covers SOLID, DRY, YAGNI, design heuristics, testing, API design, architecture patterns, and React best practices. Use when reviewing code, validating plans/specs, injecting review criteria into council sessions, or when user asks about a specific principle. Triggers on "principles", "code review checklist", "SOLID", "DRY", "design heuristics", "review criteria", "best practices", or any named principle like "Law of Demeter", "Liskov", "YAGNI", etc.

Code Principles

Principle Index

Principle	Group	One-liner
SRP	solid	One reason to change
OCP	solid	Open for extension, closed for modification
LSP	solid	Subtypes must be substitutable
ISP	solid	Small interfaces > fat interfaces
DIP	solid	Depend on abstractions
DRY	simplicity	Don't repeat yourself
YAGNI	simplicity	You aren't gonna need it
AHA	simplicity	Avoid hasty abstractions
Rule of Three	simplicity	Abstract after 3 occurrences
CQS	design	Commands mutate, queries return
Law of Demeter	design	Don't talk to strangers
Tell Don't Ask	design	Push logic to the object
POLA	design	Code should behave as expected
Composition > Inheritance	design	Compose behavior from small pieces
IoC	design	Framework calls you
Fail Fast	resilience	Validate early, throw early
Robustness Principle	resilience	Liberal in, strict out
Least Privilege	resilience	Minimum access needed
Hyrum's Law	meta	All observable behavior becomes API
Connascence	meta	Measure and minimize coupling
Locality of Behavior	meta	Understand code in one place
Pit of Success	meta	Easiest path = correct path
TDD	testing	Red-green-refactor
AAA	testing	Arrange-Act-Assert
Test Isolation	testing	Tests don't affect each other
Test Behavior	testing	Test what, not how
Testing Pyramid	testing	Many unit, fewer integration, few e2e
Idempotency	api-design	Same request = same result
Backwards Compat	api-design	Don't break existing consumers
Semver	api-design	Communicate change impact
Defensive Coding	api-design	Validate at boundaries
SoC	architecture	Each layer handles one concern
CQRS	architecture	Separate read and write models
Hexagonal Architecture	architecture	Ports and adapters
Bounded Contexts	architecture	Explicit domain boundaries
Feature Directories	react	Organize by feature, not type
Component SRP	react	One job per component
Colocation	react	Keep related files together
Unidirectional Flow	react	Data down, events up
State Placement	react	State at lowest common ancestor
Barrel Exports	react	Public API via index.ts

Usage Modes

1. Checklist mode (default)

Scan code or a plan against relevant principles. Read the reference files for the groups most relevant to the task, then output a checklist:

- [ ] SRP: Does each module have one reason to change?
- [ ] DRY: Is logic duplicated unnecessarily?
- [x] YAGNI: No speculative features found
...

Select groups based on context:

• Code review → solid, simplicity, design, testing
• Architecture/design review → architecture, design, resilience, meta
• API review → api-design, design, resilience
• React review → react, solid, simplicity

2. Council mode

Generate a review criteria block for injection into review-council prompts. Read the reference files for the persona's relevant groups (see review-council personas), extract the "Review question" from each principle, and format as:

## Code Principles Review Criteria
- SRP: Does each class/module have exactly one reason to change?
- OCP: Can behavior be extended without modifying existing code?
...

3. Deep-dive mode

When user asks about a specific principle ("what is the Law of Demeter?", "explain CQS"), read the relevant reference file and present the full entry: rule, violation example, correct example, when to break it.