111 lines
6.1 KiB
Markdown
111 lines
6.1 KiB
Markdown
# Development Principles
|
|
|
|
**Last Updated:** {{DATE}}
|
|
|
|
<!-- SCOPE: Universal development principles for THIS project ONLY. Contains 8 core principles with rationale, Decision Framework, and Verification Checklist. NO implementation details (→ Architecture.md), NO project-specific requirements (→ Requirements.md), NO testing philosophy (→ docs/reference/guides/testing-strategy.md). -->
|
|
|
|
---
|
|
|
|
## Core Principles
|
|
|
|
| # | Name | Type | Principle | Approach/Rules |
|
|
|---|------|------|-----------|----------------|
|
|
| **1** | **Standards First** | code+docs | Industry standards (ISO/RFC/OWASP/WCAG) override development principles | **Hierarchy:** Industry Standards → Security Standards → Accessibility Standards → Dev Principles (YAGNI/KISS/DRY within standard boundaries) |
|
|
| **2** | **YAGNI (You Aren't Gonna Need It)** | code+docs | Don't build features "just in case". Build what's needed NOW | **Avoid:** Generic frameworks for one use case, caching without bottleneck, extensibility points without requirements |
|
|
| **3** | **KISS (Keep It Simple)** | code+docs | Simplest solution that solves the problem. No unnecessary complexity | **Approach:** Start with naive solution → Add complexity ONLY when proven necessary → Each abstraction layer must justify existence |
|
|
| **4** | **DRY (Don't Repeat Yourself)** | code+docs | Each piece of knowledge exists in ONE place. Link, don't duplicate | **Code:** Extract repeated logic, constants defined once. **Docs:** Single Source of Truth, reference via links, update immediately |
|
|
| **5** | **Consumer-First Design** | code | Design APIs/functions/workflows from consumer's perspective | **Design:** 1. Define interface/API FIRST (what consumers need) → 2. Implement internals SECOND (how it works) → 3. Never expose internal complexity to consumers. **Note:** This is for API/interface DESIGN, not task execution order (see Foundation-First Execution in workflow) |
|
|
| **6** | **No Legacy Code** | code | Remove backward compatibility shims immediately after migration | **Rules:** Deprecated features deleted in NEXT release (not "someday"), NO commented-out code (use git history), NO `if legacy_mode:` branches |
|
|
| **7** | **Documentation-as-Code** | docs | Documentation lives WITH code, updated WITH code changes | **Rules:** Documentation in same commit as code, NO separate "docs update" tasks, Outdated docs = bug (same severity as code bug) |
|
|
| **8** | **Security by Design** | code | Security integrated from design phase, not bolted on later | **Practices:** Never commit secrets → env vars/secret managers, Validate at boundaries → Pydantic models, Least Privilege → minimum permissions, Fail Securely → don't leak info in errors, Defense in Depth → multiple security layers |
|
|
|
|
---
|
|
|
|
## Decision-Making Framework
|
|
|
|
When making technical decisions, evaluate against these principles **in order**:
|
|
|
|
1. **Security:** Is it secure by design? (OWASP, NIST standards)
|
|
2. **Standards Compliance:** Does it follow industry standards? (ISO, RFC, W3C)
|
|
3. **Correctness:** Does it solve the problem correctly?
|
|
4. **Simplicity (KISS):** Is it the simplest solution that works?
|
|
5. **Necessity (YAGNI):** Do we actually need this now?
|
|
6. **Maintainability:** Can future developers understand and modify it?
|
|
7. **Performance:** Is it fast enough? (Optimize only if proven bottleneck)
|
|
|
|
### Trade-offs
|
|
|
|
When principles conflict, use the Decision-Making Framework hierarchy:
|
|
|
|
| Conflict | Lower Priority | Higher Priority | Resolution |
|
|
|----------|---------------|-----------------|------------|
|
|
| **Simplicity vs Security** | KISS | Security by Design | Choose secure solution, even if more complex |
|
|
| **YAGNI vs Standards** | YAGNI | Standards First | Implement standard now (e.g., OAuth 2.0), not "simple custom auth" |
|
|
| **Flexibility vs Constraints** | Flexibility | YAGNI | Choose constraints (clear boundaries), not open-ended "for future" |
|
|
|
|
---
|
|
|
|
## Anti-Patterns to Avoid
|
|
|
|
### God Objects
|
|
- ❌ One class/module that does everything
|
|
- ✅ Small, focused classes with single responsibility
|
|
|
|
### Premature Optimization
|
|
- ❌ Caching before measuring actual bottlenecks
|
|
- ✅ Measure first (profiling, metrics), optimize proven bottlenecks
|
|
|
|
### Over-Engineering
|
|
- ❌ Complex abstractions "for future flexibility"
|
|
- ✅ Simple solution now, refactor if complexity justified later
|
|
|
|
### Magic Numbers/Strings
|
|
- ❌ `if status == 200:` hardcoded everywhere
|
|
- ✅ `if status == HTTPStatus.OK:` or `STATUS_OK = 200` as constant
|
|
|
|
### Leaky Abstractions
|
|
- ❌ Service layer exposes database models to API layer
|
|
- ✅ Service layer returns DTOs/Pydantic schemas, hides ORM details
|
|
|
|
---
|
|
|
|
## Verification Checklist
|
|
|
|
Before submitting code, verify compliance with principles:
|
|
|
|
- [ ] **Standards First:** Follows industry standards (ISO, RFC, OWASP, WCAG 2.1 AA)
|
|
- [ ] **YAGNI:** Only building what's needed now (no speculative features)
|
|
- [ ] **KISS:** Solution is as simple as possible, not simpler
|
|
- [ ] **DRY:** No duplicated logic or documentation
|
|
- [ ] **Consumer-First Design:** API/interface designed from consumer perspective
|
|
- [ ] **No Legacy Code:** No deprecated code, no commented-out code
|
|
- [ ] **Documentation-as-Code:** Docs updated in same commit as code
|
|
- [ ] **Security by Design:** No secrets committed, input validated, least privilege
|
|
|
|
---
|
|
|
|
## Maintenance
|
|
|
|
**Update Triggers:**
|
|
- When adding new principles
|
|
- When changing decision framework hierarchy
|
|
- When industry standards evolve (ISO, RFC, OWASP updates)
|
|
- When trade-off examples change
|
|
- Annual review (Q1 each year)
|
|
|
|
**Verification:**
|
|
- [ ] All 8 principles documented
|
|
- [ ] Decision Framework clear (7 steps)
|
|
- [ ] Trade-offs explained (3 conflicts)
|
|
- [ ] Anti-patterns listed (5 patterns)
|
|
- [ ] Verification Checklist complete (8 items)
|
|
- [ ] Links to external resources valid
|
|
- [ ] Table format demonstrates principles clearly
|
|
|
|
**Last Updated:** {{DATE}}
|
|
|
|
---
|
|
|
|
**Template Version:** 3.0.0 (MAJOR: Removed domain-specific principles (Task Granularity→ln-113, Value-Based Testing→ln-116, Token Efficiency→documentation_standards.md), converted to table format (8 universal principles only), removed all detailed sections with examples for Progressive Disclosure)
|
|
**Template Last Updated:** {{DATE}}
|