Development Principles

Last Updated: {{DATE}}

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:

Security: Is it secure by design? (OWASP, NIST standards)
Standards Compliance: Does it follow industry standards? (ISO, RFC, W3C)
Correctness: Does it solve the problem correctly?
Simplicity (KISS): Is it the simplest solution that works?
Necessity (YAGNI): Do we actually need this now?
Maintainability: Can future developers understand and modify it?
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