Transform any codebase into modular, maintainable "black boxes" using Eskil Steenberg's architecture principles.
AI prompts optimized for Claude Code, Claude that teach your AI assistant to think in terms of replaceable, modular components.
Three specialized AI prompts that apply Eskil Steenberg's battle-tested principles:
- Black box interfaces - Clean APIs between modules
- Replaceable components - If you can't understand it, rewrite it
- Constant velocity - Write 5 lines today vs. edit 1 line later
- Single responsibility - One module, one person
# Install the skill (if Claude skill system is available)
claude skill install black-box-architecture
# Use in any project
# The AI will automatically apply black box principles# Copy commands to your project
cp -r commands/ .claude/commands/
# Use with:
# /arch - Refactor code with black box principles
# /arch-plan - Design system architecture
# /arch-debug - Debug with modular isolation"It's faster to write 5 lines of code today than to write 1 line today and then have to edit it in the future." — Eskil Steenberg
These prompts optimize for:
- Human cognitive load over algorithmic efficiency
- Long-term maintainability over short-term cleverness
- Team scalability (one person per module)
- Constant developer velocity regardless of project size
| Prompt | Use Case | Token Cost |
|---|---|---|
| refactor | Break apart monoliths, create module boundaries | ~750 tokens |
| plan | Design new systems, strategic architecture | ~1,140 tokens |
| debug | Systematic debugging, testing strategies | ~1,450 tokens |
- ✅ Structured 4-phase workflow (Discovery → Analysis → Design → Implementation)
- ✅ Mandatory output templates (consistent, parseable responses)
- ✅ Quality validation checklists (explicit success criteria)
- ✅ Multi-language support (Python, TypeScript, Go, Rust, C, PHP)
- ✅ Token-optimized (compact but comprehensive)
- ✅ Tool integration (Glob, Grep, Read, Edit for Claude Code)
# Using as a command
/arch Analyze the UserService class and break it into black box modulesWhat you get:
- Current architecture analysis with
file:linereferences - Identified primitives and coupling issues
- Proposed black box module design
- Step-by-step refactoring plan
- Risk assessment and mitigation
- Quality validation checklist
# Using the skill or command
/arch-plan I'm building a real-time chat app with React and Node.jsWhat you get:
- System primitives identification
- Module architecture with clear boundaries
- Interface specifications
- Implementation roadmap (phased)
- Risk assessment
- Team organization recommendations
- Installation Guide - Detailed setup for skills and commands
- Usage Guide - Workflows and examples
- Principles Guide - Eskil's methodology explained
- Code Examples - Before/after transformations
- Contributing - How to contribute
See the examples/ directory for complete before/after refactoring examples in:
- Python - Repository pattern, service abstractions
- TypeScript - Interface-driven design, dependency injection
- Go - Interface composition, struct patterns
- Rust - Trait-based black boxes, generic implementations
- C - Opaque types, function pointers (Eskil's approach!)
- PHP - Service layer, strategy pattern, Laravel integration
Watch Eskil Steenberg's complete lecture: Architecting LARGE Software Projects
This legend has built 3D engines, networked games, and complex systems all in C using these exact principles.
- Primitive-First Design - Identify core data types that flow through your system
- Black Box Boundaries - Modules communicate only through documented interfaces
- Replaceable Components - Any module can be rewritten using only its interface
- Single Responsibility - One module = one person can own it
- Wrap Dependencies - Never depend directly on code you don't control
Each prompt follows a structured workflow:
Phase 1: Discovery (15-20%)
- Map codebase structure
- Find core primitives
- Read critical files
- STOP and confirm understanding
Phase 2: Analysis (25-30%)
- Identify black box boundaries
- Map dependencies
- Find coupling violations
- Document with file:line references
Phase 3: Design (30-35%)
- Design clean interfaces
- Show before/after examples
- Plan migration path
- Get user approval
Phase 4: Implementation (30-35%)
- Refactor one module at a time
- Surgical edits with tests
- Validate continuously
- Commit incrementally
All responses follow a consistent template:
## 🔍 Current Architecture
[Primitives, modules, coupling issues, violations]
## 🎯 Proposed Black Box Design
[Module designs with interfaces]
## 📝 Implementation Steps
[Specific, actionable steps]
## ⚠️ Risks & Mitigation
[What could go wrong + how to prevent]
## ✅ Quality Gates
[Validation checklist]Contributions welcome! See CONTRIBUTING.md for:
- How to report issues
- Suggesting improvements
- Sharing successful patterns
- Adding language examples
These prompts are token-optimized for frequent use:
- Compact versions: ~3,300 tokens total
- Enhanced versions available (12,000 tokens) for reference
- 71% smaller while maintaining full structured workflow
- Original ai-architecture-prompts - Inspiration and foundation
- Eskil's Video: Architecting LARGE Software Projects
- Enhanced Versions - Comprehensive reference documentation
MIT License - see LICENSE for details.
Traditional software grows complex over time. Developer velocity slows. Features take longer. Bugs multiply.
Black box architecture maintains constant velocity:
- Modules are small enough for one person
- Changes are isolated to single modules
- Components can be completely rewritten
- New developers can contribute immediately
These AI prompts teach your assistant to think this way automatically.
Not affiliated with Anthropic, Eskil Steenberg, or any tools mentioned. Battle-tested principles from real development work.