ai-architecture-prompts/resources/usage-guide.md

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:

# 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

   # 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

   # 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:

## 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:

## 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:

## 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.