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.