Add usage guide for AI architecture prompts, detailing workflows, scenarios, and best practices for applying black box principles in software development.

2025-08-23 22:04:21 +01:00
parent 4f8b8d6c3d
commit 068d6e21b4
1 changed files with 319 additions and 0 deletions
--- a/resources/usage-guide.md
+++ b/resources/usage-guide.md
@@ -0,0 +1,319 @@
+# Usage Guide - AI Architecture Prompts
+
+A practical guide to applying Eskil Steenberg's black box architecture principles using AI tools for maximum development velocity.
+
+## 🎯 Quick Start Workflow
+
+### 1. Choose Your Scenario
+
+- **New Project** → Start with Claude Prompt (planning)
+- **Refactoring Existing Code** → Start with Claude Code Prompt
+- **Debugging/Testing Issues** → Use Cursor Prompt
+- **Architecture Review** → Use Claude Prompt
+
+### 2. Prepare Your Context (Recommended)
+
+Extract relevant code context using AI context tools:
+
+```bash
+# For JavaScript/TypeScript projects
+npx repomix --include "src/**/*.{js,ts,jsx,tsx}" --output context.xml
+
+# For Python projects
+git clone https://github.com/jimmc414/onefilellm.git
+cd onefilellm
+python onefilellm.py ./your-project/src/ --output context.xml
+
+# For specific folders only
+npx repomix --include "src/components/**" --output component-context.xml
+```
+
+### 3. Apply the Appropriate Prompt
+
+Copy the relevant prompt from this repo and paste it into your AI tool, then include your context and specific question.
+
+## 📋 Detailed Usage Scenarios
+
+### Scenario 1: Planning a New Project
+
+**Tool**: Claude (Web/Desktop)  
+**Prompt**: `claude-prompt.md`
+
+**Example Session**:
+
+```
+[Paste Claude Prompt]
+
+I'm building a real-time chat application that needs to support:
+- Multiple message types (text, images, files)
+- User presence indicators
+- Message history persistence
+- Mobile and web clients
+
+Can you help me architect this using black box principles?
+```
+
+**What You'll Get**:
+
+- Module breakdown (MessageStore, PresenceManager, ClientAdapter, etc.)
+- Interface specifications between components
+- Risk assessment and mitigation strategies
+- Implementation roadmap with priorities
+- Team organization recommendations
+
+### Scenario 2: Refactoring Complex Code
+
+**Tool**: Claude Code  
+**Prompt**: `claude-code-prompt.md`
+
+**Example Session**:
+
+```
+[Paste Claude Code Prompt]
+
+[Attach context.xml from your project]
+
+This React component has grown to 500+ lines with complex state management,
+DOM manipulation, and API calls all mixed together. How can I break this
+into replaceable black box modules?
+```
+
+**What You'll Get**:
+
+- Identification of black box boundaries
+- Specific refactoring steps
+- New interface designs
+- Code examples for each module
+- Testing strategy for the refactored code
+
+### Scenario 3: Debugging and Testing Strategy
+
+**Tool**: Cursor  
+**Prompt**: `cursor-prompt.md`
+
+**Example Session**:
+
+```
+[Paste Cursor Prompt]
+
+[Include relevant code files]
+
+I have integration issues between my payment module and user authentication.
+The tests pass individually but fail when used together. How should I debug
+this using black box principles?
+```
+
+**What You'll Get**:
+
+- Debugging methodology for module boundaries
+- Test isolation strategies
+- Interface validation approaches
+- Mock/stub recommendations
+- Root cause analysis guidance
+
+## 🔧 Advanced Workflows
+
+### The Context + Prompt Combination
+
+**Most Powerful Approach**: Combine AI context extraction with architecture prompts
+
+1. **Extract Focused Context**
+
+   ```bash
+   # Focus on specific problem area
+   npx repomix --include "src/auth/**" --include "src/payments/**" --output modules-context.xml
+   ```
+
+2. **Apply Architecture Analysis**
+
+   ```
+   [Claude Code Prompt]
+
+   [Attach modules-context.xml]
+
+   These two modules are tightly coupled and causing issues.
+   How can I create clean black box interfaces between them?
+   ```
+
+3. **Implement Incrementally**
+   - Use the AI's suggestions to refactor one module at a time
+   - Maintain existing interfaces during transition
+   - Test each change in isolation
+
+### Multi-Stage Architecture Evolution
+
+**Stage 1: Strategic Planning** (Claude Prompt)
+
+- Define overall system architecture
+- Identify major module boundaries
+- Plan implementation phases
+
+**Stage 2: Implementation** (Claude Code Prompt)
+
+- Build individual modules
+- Create clean interfaces
+- Implement black box boundaries
+
+**Stage 3: Testing & Debugging** (Cursor Prompt)
+
+- Validate module interfaces
+- Debug integration issues
+- Optimize performance
+
+### The "Folder Focus" Method
+
+Perfect for large codebases:
+
+1. **Identify Problem Folder**
+
+   ```bash
+   # Extract context for specific folder
+   npx repomix --include "src/components/editor/**" --output editor-context.xml
+   ```
+
+2. **Analyze with Architecture Prompt**
+
+   ```
+   [Claude Code Prompt]
+   [Attach editor-context.xml]
+
+   This folder contains our text editor components. They're becoming
+   hard to maintain and test. How can I restructure this using
+   black box principles?
+   ```
+
+3. **Implement Suggested Changes**
+   - Refactor one component at a time
+   - Maintain backward compatibility
+   - Test interfaces thoroughly
+
+## 🎨 Prompt Customization Tips
+
+### Adapting for Your Domain
+
+Add domain-specific context to any prompt:
+
+```markdown
+## Additional Context
+
+You are working on a [HEALTHCARE/FINTECH/GAMING] application where:
+
+- [Specific regulatory requirements]
+- [Performance constraints]
+- [Security considerations]
+- [Integration requirements]
+
+Apply black box principles while considering these domain constraints.
+```
+
+### Technology-Specific Adaptations
+
+**For React Projects**:
+
+```markdown
+## React-Specific Considerations
+
+- Components should be black boxes with clear prop interfaces
+- State management should be isolated within modules
+- Side effects should be contained and testable
+- Context should not leak implementation details
+```
+
+**For Backend APIs**:
+
+```markdown
+## API-Specific Considerations
+
+- Each endpoint should represent a clear business capability
+- Database interactions should be hidden behind service interfaces
+- External API dependencies should be wrapped and mockable
+- Error handling should be consistent across all modules
+```
+
+## 🚨 Common Pitfalls & Solutions
+
+### Pitfall 1: Over-Engineering
+
+**Problem**: Creating too many tiny modules  
+**Solution**: Use the "one person rule" - each module should be maintainable by one developer
+
+### Pitfall 2: Leaky Abstractions
+
+**Problem**: Interfaces that expose implementation details  
+**Solution**: Test if you could completely rewrite the implementation using only the interface
+
+### Pitfall 3: Context Overload
+
+**Problem**: Including too much code context, confusing the AI  
+**Solution**: Focus on specific folders or files relevant to your question
+
+### Pitfall 4: Ignoring Dependencies
+
+**Problem**: Not considering how modules connect  
+**Solution**: Always ask about interface design and integration points
+
+## 📊 Measuring Success
+
+### Before/After Metrics
+
+Track these improvements:
+
+- **Lines of code per module** - should decrease
+- **Interface complexity** - fewer public methods/functions
+- **Test isolation** - can modules be tested independently?
+- **Replacement difficulty** - how hard is it to rewrite a module?
+- **Developer onboarding** - how quickly can new devs contribute?
+
+### Architecture Quality Checklist
+
+After applying the prompts, verify:
+
+- [ ] Each module has a single, clear responsibility
+- [ ] Interfaces are documented and obvious to use
+- [ ] Implementation details are completely hidden
+- [ ] Modules can be tested without knowing internals
+- [ ] External dependencies are wrapped, not used directly
+- [ ] Any module could be rewritten using only its interface
+
+## 🔄 Iteration Strategy
+
+### Continuous Architecture Improvement
+
+1. **Weekly Architecture Reviews**
+
+   - Pick one module that's causing friction
+   - Apply the appropriate prompt
+   - Implement one suggested improvement
+
+2. **New Feature Integration**
+
+   - Before building new features, use Claude Prompt for planning
+   - Ensure new code follows black box principles
+   - Update existing interfaces if needed
+
+3. **Bug-Driven Refactoring**
+   - When bugs occur, use Cursor Prompt to understand root cause
+   - Often bugs indicate poor module boundaries
+   - Fix the architecture, not just the symptom
+
+## 💡 Pro Tips
+
+### Combining with Other Tools
+
+- **Use with GitHub Copilot**: Let Copilot generate code, then use these prompts to structure it properly
+- **Integration with IDEs**: Keep prompt snippets in your IDE for quick access
+- **Documentation**: Use the architectural insights to improve your README and API docs
+
+### Team Collaboration
+
+- **Share Architecture Decisions**: Use Claude Prompt outputs as design documents
+- **Code Review Focus**: Review interfaces and module boundaries, not just implementation
+- **Onboarding**: New team members can use these prompts to understand the codebase architecture
+
+### Long-term Maintenance
+
+- **Architecture Debt**: Regularly review and refactor using these prompts
+- **Technology Migration**: Black box architecture makes it easier to migrate technologies
+- **Scaling Preparation**: Well-architected modules handle growth better
+
+Remember: The goal isn't perfect architecture immediately, but architecture that stays maintainable as your project grows. Use these prompts iteratively to continuously improve your codebase structure.