distributed-architect
A reasoning framework that helps Claude analyze distributed system code changes for correctness before writing code. It provides an always-o
Open source Repository Open in the app JSON README (API)
About
A reasoning framework that helps Claude analyze distributed system code changes for correctness before writing code. It provides an always-on boundary detector that recognizes when changes cross component boundaries (state mutations, data serialization, failure handling, new interactions), then loads targeted reasoning checklists on demand. Three slash commands cover the full development lifecycle: /dist-check for coding-time two-pass analysis, /dist-design for architecture trade-off eval...
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- langerrr
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 1
- Last push
- 2026-09-02T20:29:28Z
- Repository state
- ativo
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
langerrr/distributed-architect/distributed-architect
README
# distributed-architect
A reasoning framework plugin for [Claude Code](https://claude.ai/code) that helps LLMs catch distributed system bugs before they reach production.
## The Problem
LLMs reason about code **locally** — they read a function, understand its logic, and suggest changes that are locally correct. Distributed systems require **globally correct** changes: every state mutation must be valid from every observer's perspective, including under partial failure.
This gap produces specific, recurring mistakes:
- Setting a service to "idle" without checking if the system will immediately re-dispatch to the same broken instance (tight retry loops)
- Assuming a monitoring channel failure means the operation failed (channel conflation)
- Losing data at acknowledgment boundaries because the only copy was in the queue
- Missing feedback loops that span multiple components
These aren't knowledge gaps — they're reasoning gaps. The LLM knows about distributed systems. It just doesn't systematically apply that knowledge at the moment of writing code.
## How It Works
**Three layers, loaded incrementally to minimize context cost:**
| Layer | What | When Loaded | Context Cost |
|-------|------|-------------|-------------|
| Boundary Signal Reference | Recognizes when a change crosses a distributed boundary | `@`-imported into a project's `CLAUDE.md` (opt-in), or read directly by the skills | Near zero |
| Reasoning Modules | Checklists for specific concern types (5 modules) | On signal detection | ~50 lines each |
| Anti-Pattern Catalog | Named patterns with shape/detection/fix | Review or debug mode | ~10 lines each |
**Two-pass analysis at coding time:**
1. **Boundary correctness** — Does this single operation work correctly across components?
2. **Concurrency correctness** — Do simultaneous operations conflict? (Triggered by project topology)
**Three entry points for different phases:**
- `/dist-check` — Coding time: verify changes before committing
- `/dist-design` — Design time: evaluate architecture trade-offs
- `/dist-debug` — Debug time: trace symptoms backward to root cause
## Project Topology
Each project creates a lightweight topology file that captures component relationships and cardinality. This drives analysis decisions:
```yaml
topology:
- from: api-gateway
count: 1 (fixed)
to: task-runner
count: N (dynamic)
via: message queue
notes: "1:N — concurrency on the gateway side"
- from: task-runner
count: 1 (fixed)
to: execution-backend
count: 1 (fixed, per-runner)
via: HTTP + event stream
notes: "1:1 tight coupling"
```
Cardinality determines which analysis is triggered:
- **1:N** — Concurrency analysis mandatory on the "1" side
- **1:1** — Failure cascade analysis
- **N:1** — Bottleneck / SPOF analysis
## Anti-Pattern Catalog
Six patterns identified from real debugging sessions, with more added over time:
| Pattern | Shape |
|---------|-------|
| Tight Retry Loop | Error handler sets state to "ready" -> system immediately retries -> same error |
| Lost Data at ACK | Data only in queue -> consumer ACKs -> data gone -> needed later |
| Channel Conflation | Monitoring channel drops -> assume the monitored operation failed |
| Boundary State Leak | Component exposes internal state across its interface |
| Compounding Retry | Multiple retry layers multiply into retry storms |
| Premature State Transition | Advertise new state before preconditions are verified |
## Usage
Load as a Claude Code plugin:
```bash
claude --plugin-dir /path/to/distributed-architect
```
Skills are registered as `/distributed-architect:dist-check`, etc. Use them during your work:
- `/distributed-architect:dist-check` before committing distributed system changes
- `/distributed-architect:dist-design` when evaluating architecture options
- `/distributed-architect:dist-debug` when investigating cross-component failures
Claude Code doesn't load an installed plugin's `CLAUDE.md` into every session, so passive detection isn't automatic. For a project where you want the boundary-signal table always active, `@`-import it from this plugin's `CLAUDE.md` into that project's own `CLAUDE.md`.
## Design Philosophy
This is a **reasoning coach, not a knowledge base**. It doesn't try to document your system — it teaches the LLM what questions to ask at the right moment. Documents go stale; reasoning patterns don't.
See `docs/design-philosophy.md` for the full rationale.
## Structure
```
distributed-architect/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest
├── CLAUDE.md # Plugin instructions + boundary-signal reference (not auto-loaded — see Usage)
├── modules/ # Layer 2: reasoning checklists (loaded on demand)
│ ├── state-mutation.md
│ ├── data-lifecycle.md
│ ├── failure-mode.md
│ ├── interaction.md
│ └── concurrency.md
├── catalog/ # Layer 3: anti-pattern reference
│ ├── _drafts/ # Auto-captured, pending promotion
│ └── *.md # Promoted patterns
├── skills/ # Registered skills (SKILL.md per skill)
│ ├── dist-check/
│ │ └── SKILL.md
│ ├── dist-design/
│ │ └── SKILL.md
│ └── dist-debug/
│ └── SKILL.md
├── templates/
│ └── topology.yaml # Project topology template
└── docs/ # Design documents & case studies
```