Add ai-code-project-template repo files.

2025-08-23 06:09:26 -07:00
parent 9321e54bce
commit e725ecf942
76 changed files with 17830 additions and 8 deletions
--- a/.ai/docs/philosophy.md
+++ b/.ai/docs/philosophy.md
@@ -0,0 +1,422 @@
+# Philosophy Guide
+
+Understanding the philosophy behind this template is key to achieving 10x productivity with AI assistants.
+
+## 🧠 Core Philosophy: Human Creativity, AI Velocity
+
+### The Fundamental Principle
+
+> **You bring the vision and creativity. AI handles the implementation details.**
+
+This isn't about AI replacing developers—it's about developers achieving what was previously impossible. Your unique problem-solving approach, architectural vision, and creative solutions remain entirely yours. AI simply removes the friction between idea and implementation.
+
+## 🎯 The Three Pillars
+
+### 1. Amplification, Not Replacement
+
+**Traditional Approach**:
+
+- Developer thinks of solution
+- Developer implements every detail
+- Developer tests and debugs
+- Time: Days to weeks
+
+**AI-Amplified Approach**:
+
+- Developer envisions solution
+- AI implements under guidance
+- Developer reviews and refines
+- Time: Hours to days
+
+**Key Insight**: You still make every important decision. AI just executes faster.
+
+### 2. Philosophy-Driven Development
+
+**Why Philosophy Matters**:
+
+- Consistency across all code
+- Decisions aligned with principles
+- AI understands your preferences
+- Team shares mental model
+
+**In Practice**:
+
+```
+/prime  # Loads philosophy
+# Now every AI interaction follows your principles
+```
+
+### 3. Flow State Preservation
+
+**Flow Killers** (Eliminated):
+
+- Context switching for formatting
+- Looking up syntax details
+- Writing boilerplate code
+- Manual quality checks
+
+**Flow Enhancers** (Amplified):
+
+- Desktop notifications
+- Automated quality
+- Natural language interaction
+- Continuous momentum
+
+## 📋 Implementation Philosophy
+
+### Simplicity First
+
+**Principle**: Every line of code should have a clear purpose.
+
+**Application**:
+
+```python
+# ❌ Over-engineered
+class AbstractFactoryManagerSingleton:
+    def get_instance_factory_manager(self):
+        return self._factory_instance_manager_singleton
+
+# ✅ Simple and clear
+def get_user(user_id: str) -> User:
+    return database.find_user(user_id)
+```
+
+**Why It Works**: Simple code is:
+
+- Easier to understand
+- Faster to modify
+- Less likely to break
+- More maintainable
+
+### Pragmatic Architecture
+
+**Principle**: Build for today's needs, not tomorrow's possibilities.
+
+**Application**:
+
+- Start with monolith, split when needed
+- Use boring technology that works
+- Optimize when you measure, not when you guess
+- Choose patterns that fit, not patterns that impress
+
+**Example Evolution**:
+
+```
+Version 1: Simple function
+Version 2: Add error handling (when errors occur)
+Version 3: Add caching (when performance matters)
+Version 4: Extract to service (when scale demands)
+```
+
+### Trust in Emergence
+
+**Principle**: Good architecture emerges from good practices.
+
+**Application**:
+
+- Don't over-plan the system
+- Let patterns reveal themselves
+- Refactor when clarity emerges
+- Trust the iterative process
+
+**Real Example**:
+
+```
+Week 1: Build auth quickly
+Week 2: Notice pattern, extract utilities
+Week 3: See bigger pattern, create auth module
+Week 4: Clear architecture has emerged naturally
+```
+
+## 🔧 Modular Design Philosophy
+
+### Think "Bricks & Studs"
+
+**Concept**:
+
+- **Brick** = Self-contained module with one responsibility
+- **Stud** = Clean interface others connect to
+
+**Implementation**:
+
+```python
+# user_service.py (Brick)
+"""Handles all user-related operations"""
+
+# Public Interface (Studs)
+def create_user(data: UserData) -> User: ...
+def get_user(user_id: str) -> User: ...
+def update_user(user_id: str, data: UserData) -> User: ...
+
+# Internal Implementation (Hidden inside brick)
+def _validate_user_data(): ...
+def _hash_password(): ...
+```
+
+### Contract-First Development
+
+**Process**:
+
+1. Define what the module does
+2. Design the interface
+3. Implement the internals
+4. Test the contract
+
+**Example**:
+
+```python
+# 1. Purpose (README in module)
+"""Email Service: Sends transactional emails"""
+
+# 2. Contract (interface.py)
+@dataclass
+class EmailRequest:
+    to: str
+    subject: str
+    body: str
+
+async def send_email(request: EmailRequest) -> bool:
+    """Send email, return success status"""
+
+# 3. Implementation (internal)
+# ... whatever works, can change anytime
+
+# 4. Contract Test
+def test_email_contract():
+    result = await send_email(EmailRequest(...))
+    assert isinstance(result, bool)
+```
+
+### Regenerate, Don't Patch
+
+**Philosophy**: When modules need significant changes, rebuild them.
+
+**Why**:
+
+- Clean slate avoids technical debt
+- AI excels at regeneration
+- Tests ensure compatibility
+- Cleaner than patching patches
+
+**Process**:
+
+```
+/ultrathink-task Regenerate the auth module with these new requirements:
+- Add OAuth support
+- Maintain existing API contract
+- Include migration guide
+```
+
+## 🎨 Coding Principles
+
+### Explicit Over Implicit
+
+```python
+# ❌ Implicit
+def process(data):
+    return data * 2.5  # What is 2.5?
+
+# ✅ Explicit
+TAX_MULTIPLIER = 2.5
+
+def calculate_with_tax(amount: float) -> float:
+    """Calculate amount including tax"""
+    return amount * TAX_MULTIPLIER
+```
+
+### Composition Over Inheritance
+
+```python
+# ❌ Inheritance jungle
+class Animal: ...
+class Mammal(Animal): ...
+class Dog(Mammal): ...
+class FlyingDog(Dog, Bird): ...  # 😱
+
+# ✅ Composition
+@dataclass
+class Dog:
+    movement: MovementBehavior
+    sound: SoundBehavior
+
+flying_dog = Dog(
+    movement=FlyingMovement(),
+    sound=BarkSound()
+)
+```
+
+### Errors Are Values
+
+```python
+# ❌ Hidden exceptions
+def get_user(id):
+    return db.query(f"SELECT * FROM users WHERE id={id}")
+    # SQL injection! Throws on not found!
+
+# ✅ Explicit results
+def get_user(user_id: str) -> Result[User, str]:
+    if not is_valid_uuid(user_id):
+        return Err("Invalid user ID format")
+
+    user = db.get_user(user_id)
+    if not user:
+        return Err("User not found")
+
+    return Ok(user)
+```
+
+## 🚀 AI Collaboration Principles
+
+### Rich Context Provision
+
+**Principle**: Give AI enough context to make good decisions.
+
+**Application**:
+
+```
+# ❌ Minimal context
+Fix the bug in auth
+
+# ✅ Rich context
+Fix the authentication bug where users get logged out after 5 minutes.
+Error: "JWT token expired" even though expiry is set to 24h.
+See @auth/config.py line 23 and @auth/middleware.py line 45.
+Follow our error handling patterns in IMPLEMENTATION_PHILOSOPHY.md.
+```
+
+### Iterative Refinement
+
+**Principle**: First version gets you 80%, iteration gets you to 100%.
+
+**Process**:
+
+1. Get something working
+2. See it in action
+3. Refine based on reality
+4. Repeat until excellent
+
+**Example Session**:
+
+```
+Create a data table component
+[Reviews output]
+Actually, add sorting to the columns
+[Reviews again]
+Make the sorted column show an arrow
+[Perfect!]
+```
+
+### Trust but Verify
+
+**Principle**: AI is powerful but not infallible.
+
+**Practice**:
+
+- Review generated code
+- Run tests immediately
+- Check edge cases
+- Validate against requirements
+
+**Workflow**:
+
+```
+/ultrathink-task [complex request]
+# Review the plan before implementation
+# Check the code before running
+# Verify behavior matches intent
+```
+
+## 🌟 Philosophy in Action
+
+### Daily Development Flow
+
+```
+Morning:
+/prime  # Start with philosophy alignment
+
+Feature Development:
+/create-plan "New feature based on our principles"
+/execute-plan
+# Automated checks maintain quality
+# Notifications keep you informed
+
+Review:
+/review-changes
+# Ensure philosophy compliance
+```
+
+### Problem-Solving Approach
+
+```
+1. Understand the real problem (not the symptom)
+2. Consider the simplest solution
+3. Check if it aligns with principles
+4. Implement iteratively
+5. Let architecture emerge
+```
+
+### Team Collaboration
+
+```
+# Share philosophy through configuration
+git add ai_context/IMPLEMENTATION_PHILOSOPHY.md
+git commit -m "Update team coding principles"
+
+# Everyone gets same guidance
+Team member: /prime
+# Now coding with shared philosophy
+```
+
+## 📚 Living Philosophy
+
+### Evolution Through Experience
+
+This philosophy should evolve:
+
+- Add principles that work
+- Remove ones that don't
+- Adjust based on team needs
+- Learn from project outcomes
+
+### Contributing Principles
+
+When adding principles:
+
+1. Must solve real problems
+2. Should be broadly applicable
+3. Include concrete examples
+4. Explain the why
+
+### Anti-Patterns to Avoid
+
+1. **Dogmatic Adherence**: Principles guide, not dictate
+2. **Premature Abstraction**: Wait for patterns to emerge
+3. **Technology Over Problem**: Solve real needs
+4. **Complexity Worship**: Simple is usually better
+
+## 🎯 The Meta-Philosophy
+
+### Why This Works
+
+1. **Cognitive Load Reduction**: Principles make decisions easier
+2. **Consistency**: Same principles = coherent codebase
+3. **Speed**: No debate, follow principles
+4. **Quality**: Good principles = good code
+5. **Team Scaling**: Shared principles = aligned team
+
+### The Ultimate Goal
+
+**Create systems where:**
+
+- Humans focus on what matters
+- AI handles what's repetitive
+- Quality is automatic
+- Innovation is amplified
+- Work remains joyful
+
+## 🔗 Related Documentation
+
+- [Implementation Philosophy](../../ai_context/IMPLEMENTATION_PHILOSOPHY.md)
+- [Modular Design Philosophy](../../ai_context/MODULAR_DESIGN_PHILOSOPHY.md)
+- [Command Reference](commands.md)
+- [AI Context Guide](ai-context.md)