https://github.com/gl0bal01/black-box-architecture
Transform any codebase into modular, maintainable "black boxes" using Eskil Steenberg's architecture principles
https://github.com/gl0bal01/black-box-architecture
ai-prompts claude-agents claude-code claude-prompts claude-skills modular-design software-architecture
Last synced: about 17 hours ago
JSON representation
Transform any codebase into modular, maintainable "black boxes" using Eskil Steenberg's architecture principles
- Host: GitHub
- URL: https://github.com/gl0bal01/black-box-architecture
- Owner: gl0bal01
- License: mit
- Created: 2025-10-25T17:30:36.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-04-12T20:25:44.000Z (3 months ago)
- Last Synced: 2026-06-28T16:31:28.409Z (5 days ago)
- Topics: ai-prompts, claude-agents, claude-code, claude-prompts, claude-skills, modular-design, software-architecture
- Homepage:
- Size: 223 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
- Agents: docs/AGENTS.md
Awesome Lists containing this project
README
# Black Box Architecture Agents
AI agents for maintaining and improving software architecture using black-box design principles — inspired by [Eskil Steenberg's lecture](https://www.youtube.com/watch?v=sSpULGNHyoI) and rooted in information hiding (Parnas, 1972).
Five coordinated specialists — analyze, plan, implement, debug — governed by a shared contract that enforces scope discipline, evidence minimums, approval gates, and a self-improvement loop.
## Quick Install
```bash
git clone https://github.com/gl0bal01/black-box-architecture.git
# Project-specific
mkdir -p .claude/agents
cp -r black-box-architecture/agents/* .claude/agents/
# Or personal (all projects)
cp -r black-box-architecture/agents/* ~/.claude/agents/
```
## Agents
| Agent | Role | Model | Writes Code |
|-------|------|-------|-------------|
| **arch-orchestrator** | Entry point. Classifies, delegates, synthesizes. | Opus | No |
| **arch-analyzer** | Maps module boundaries, coupling, violations. | Sonnet | No |
| **arch-planner** | Designs modules, interfaces, migration roadmaps. | Opus | No |
| **arch-implementer** | Executes approved plans with commit discipline. | Sonnet | Yes (requires approval) |
| **arch-debugger** | Isolates bugs to contract boundaries, fixes autonomously. | Sonnet | Yes (approval gates apply) |
All agents follow `agents/BLACKBOX_CONTRACT.md` — 13 rules covering scope discipline, evidence requirements, approval gates, commit checkpoints, and self-improvement.
## Usage
```
"Ask arch-orchestrator to analyze UserService and propose black-box boundaries"
"Ask arch-analyzer to find coupling issues in src/services/"
"Ask arch-planner to design a payment processing module"
"Ask arch-implementer to execute the approved refactoring plan"
"Ask arch-debugger to isolate and fix the checkout bug"
```
## Workflows
| Workflow | Agents | Approval Gate |
|----------|--------|---------------|
| Analysis only | Analyzer | — |
| Planning only | Planner | — |
| Full refactoring | Analyzer → Planner → Implementer | After plan, before implementation |
| Debug & fix | Debugger → (Implementer) | Before non-trivial fixes |
| Complete transformation | All agents in sequence | After plan + between phases |
## Documentation
- [Agent System Guide](docs/AGENTS.md) — Architecture, agents, workflows, troubleshooting
- [Black Box Principles](docs/PRINCIPLES.md) — Design philosophy (Steenberg, Parnas)
- [Code Examples](docs/EXAMPLES.md) — Before/after refactorings in 6 languages
- [Contributing](docs/CONTRIBUTING.md) — How to contribute
## License
MIT