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
- Best Daily Workflow
- Core Philosophy
- What's Included
- Agents
- Legacy Prompts
- 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
# Install agents for this project
mkdir -p .claude/agents
cp -r black-box-architecture/agents/* .claude/agents/Legacy prompts are still available but no longer the recommended path.
# Skills (legacy)
mkdir -p .claude/skills
cp -r black-box-architecture/docs/legacy/skills .claude/skills/black-box-architecture
# Commands (legacy)
mkdir -p .claude/commands
cp -r black-box-architecture/docs/legacy/commands/ .claude/commands/- Use
arch-orchestratorfor most tasks. - Ask for concise output by default.
- Request a full report only for big changes.
- Approve any dependency, public API, or schema changes explicitly.
"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
- Agents pack in
agents/with orchestrator + specialists - Shared contract in
agents/AGENTS_CONTRACT.md - Legacy prompts in
docs/legacy/skills/anddocs/legacy/commands/(deprecated) - Examples and docs in
examples/anddocs/
Agents are the primary, recommended path. They enforce:
- scope discipline
- approval gates for risky changes
- evidence-backed findings
- concise, reviewable outputs
docs/legacy/skills/ and docs/legacy/commands/ are legacy prompts kept for compatibility.
They may drift from the contract and are not the best daily path.
For daily 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
- They follow a shared contract for consistent, reviewable outputs.
- They enforce approval gates for dependencies, APIs, and schemas.
- They scale from quick analysis to full refactors without changing tools.
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 the orchestrator
Ask arch-orchestrator: Analyze UserService and propose black-box boundariesWhat 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 orchestrator
Ask arch-orchestrator: Design a module map for a real-time chat appWhat you get:
- System primitives identification
- Module architecture with clear boundaries
- Interface specifications
- Implementation roadmap (phased)
- Risk assessment
- Team organization recommendations
- Installation Guide - Setup for agents and legacy prompts
- Principles Guide - Eskil Steenberg's methodology explained
- Usage Guide - Agent workflow and legacy prompts
- 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
- A shared contract governs agent behavior and output structure.
- Agents default to concise outputs and switch to full reports when needed.
- Approval gates prevent risky changes without explicit sign-off.
- Evidence and verification are required for non-trivial claims.
Contributions welcome! See CONTRIBUTING.md for:
- How to report issues
- Suggesting improvements
- Sharing successful patterns
- Adding language examples
- Original ai-architecture-prompts - Inspiration and foundation
- Eskil's Video: Architecting LARGE Software Projects
- Enhanced Versions - Legacy 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.
- Install agents and run a small analysis with
arch-orchestrator. - Use concise output for daily work, request full reports only when needed.
- Approve dependencies, public API changes, and schemas explicitly.
- If you must use legacy prompts, keep them aligned with the contract.
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.