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