diff --git a/resources/usage-guide.md b/resources/usage-guide.md new file mode 100644 index 0000000..1b2a1ea --- /dev/null +++ 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.