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.
- What This Is
- Quick Start
- Core Philosophy
- What's Included
- Skills vs Commands vs Agents
- Autonomous Agents
- Example Usage
- Documentation
- Real-World Examples
- Learn More
- How It Works
- Contributing
- Next Steps
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
# Clone the repository
git clone https://github.com/gl0bal01/black-box-architecture.git
# For personal use (available in all projects)
mkdir -p ~/.claude/skills
cp -r black-box-architecture/skills ~/.claude/skills/black-box-architecture
# OR for project-specific use (shared with team via git)
mkdir -p .claude/skills
cp -r black-box-architecture/skills .claude/skills/black-box-architecture
# Claude will automatically discover and use the skill when relevant# 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# Copy agents for complex architectural workflows
cp -r agents/ .claude/agents/
# Agents autonomously handle:
# - Multi-step analysis and refactoring
# - Strategic architecture design
# - Complex debugging with module isolation
# - Coordinated workflows across multiple specialists"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)
Understanding the three ways to use black box architecture principles:
| Aspect | Skills | Commands | Agents |
|---|---|---|---|
| Activation | Auto-discovered by Claude | Manual /command |
Delegated by orchestrator |
| Use Case | Passive expertise | Quick templates | Complex autonomous tasks |
| Context | Shared | Shared | Separate (isolated) |
| Best For | Background knowledge | Direct control | Multi-step workflows |
Skills (Learn more):
- Claude automatically discovers when relevant
- Three variants: refactor, plan, debug
- Provides expertise without explicit invocation
Commands (Learn more):
- User explicitly triggers with
/arch,/arch-plan,/arch-debug - Full control over execution
- Template-based responses
Agents (Learn more):
- Autonomous specialists that coordinate together
- Handle complex, multi-step tasks
- Separate context windows prevent pollution
For complex, multi-step architectural work, use the specialized agent system:
# Copy agents to your project
cp -r agents/ .claude/agents/
# The orchestrator coordinates all agents automaticallyThe agent system follows black box principles itself - specialized agents with clear responsibilities:
| Agent | Role | Autonomous Actions |
|---|---|---|
| arch-orchestrator | Coordination | Analyzes requests, delegates to specialists, assembles results |
| arch-analyzer | Analysis | Explores codebases, identifies violations, maps dependencies |
| arch-planner | Design | Designs architectures, creates roadmaps, assesses risks |
| arch-implementer | Implementation | Refactors code, maintains boundaries, verifies changes |
| arch-debugger | Debugging | Isolates bugs to modules, proposes fixes, maintains integrity |
Analysis Only: arch-analyzer explores codebase and reports findings
Planning Only: arch-planner designs architecture from requirements
Full Refactoring: arch-analyzer → arch-planner → [USER APPROVAL] → arch-implementer
Debug & Fix: arch-debugger → arch-implementer (if fix needed)
Complete Transformation: All agents work together for major architectural overhaul
- Commands: Manual triggers for templates (user control)
- Skills: Passive knowledge Claude auto-discovers (expertise)
- Agents: Active specialists that autonomously execute complex tasks (delegation)
Agents provide:
- Autonomous execution - Multi-step workflows without constant guidance
- Context isolation - Separate context windows prevent pollution
- Specialized reasoning - Each agent is expert in its domain
- Composability - Agents coordinate through well-defined interfaces
Learn More:
- 📖 Complete Agent Documentation - Detailed guide for each agent
- 🔄 Agent Workflows - Step-by-step examples
- 🔗 Integration Examples - How agents coordinate
- ⚙️ Agent Specifications - Technical specifications
# 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, commands, and agents
- Principles Guide - Eskil Steenberg's methodology explained
- Skill System Guide - How skills work and auto-discovery
- Usage Guide - Commands and skills workflow
- Agent System Guide - Complete agent documentation
- Workflows Guide - Step-by-step examples for each agent
- Integration Examples - How agents coordinate together
- Code Examples - Before/after transformations in multiple languages
- Real-World Examples - Complete refactoring examples
- Contributing Guide - How to contribute, report issues, add examples
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
Original Source:
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.
Complete Documentation:
- 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.
Choose your path based on experience level:
🌱 Beginners - Start Here:
- Read Principles Guide to understand black box architecture
- Follow Installation Guide to set up skills
- Try Example Usage with a simple refactoring
🌿 Intermediate - Ready to Build:
- Review Usage Guide for commands and skills
- Explore Code Examples for patterns
- Study Workflows Guide for step-by-step processes
🌲 Advanced - Master the System:
- Set up Autonomous Agents for complex work
- Study Integration Examples
- Create custom agents for your team's needs
📺 Watch the Source:
Watch Eskil Steenberg's complete lecture - the foundation of everything here.
Not affiliated with Anthropic, Eskil Steenberg, or any tools mentioned. Battle-tested principles from real development work.