---

name: black-box-architecture description: Apply Eskil Steenberg's black box architecture principles to build modular, maintainable software. Automatically refactors code into replaceable components, designs system architectures with clean boundaries, and debugs with modular isolation.

Black Box Architecture Skill

This skill teaches Claude to apply Eskil Steenberg's battle-tested black box architecture principles for building modular, maintainable software systems.

Philosophy

"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

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

Core Principles

1. Primitive-First Design - Identify core data types that flow through your system
2. Black Box Boundaries - Modules communicate only through documented interfaces
3. Replaceable Components - Any module can be rewritten using only its interface
4. Single Responsibility - One module = one person can own it
5. Wrap Dependencies - Never depend directly on code you don't control

Variants

This skill has three specialized variants that are automatically selected based on your request:

Refactor Variant

When to use: Code refactoring, breaking apart monoliths, creating module boundaries

Triggers:

• "Refactor [code/class/module]"
• "Break apart this monolith"
• "Create black box modules"
• "Analyze [component] and suggest modular refactoring"

File: refactor.md

Plan Variant

When to use: Strategic architecture planning, designing new systems

Triggers:

• "Design architecture for [system]"
• "Plan the module structure"
• "How should I architect [feature]"
• "Design a [type] system"

File: plan.md

Debug Variant

When to use: Systematic debugging, testing strategies, integration issues

Triggers:

• "Debug [issue]"
• "Fix this bug"
• "Why is [component] failing"
• "Test strategy for [feature]"

File: debug.md

Output Format

All variants follow a structured 4-phase protocol and produce consistent output:

Copy## 🔍 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]

Supported Languages

• Python
• TypeScript/JavaScript
• Go
• Rust
• C
• PHP
• Java

Learn More

Based on Eskil Steenberg's lecture: Architecting LARGE Software Projects