improve-code-architecture
Apply design patterns to decouple modules and introduce testable abstractions.
Open source Open in the app JSON README (API)
About
Apply design patterns to decouple modules and introduce testable abstractions.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- zachcr-ws
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.2.1
- Last push
- 2026-04-23T07:51:38Z
- Repository state
- ativo
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
zachcr-ws/improve-code-architecture
README
# improve-code-architecture [](./LICENSE) [](./CHANGELOG.md) [](./skills/improve-code-architecture/SKILL.md) A Claude Code / Cursor / Codex / Gemini plugin shipping two complementary skills for design discipline: a restructuring workflow for codebases that need surgery, and a lightweight lens you wear during routine implementation. > **Core principle:** Every extraction must answer _what concern does this boundary hide?_ If you cannot name it, do not extract. ## When to Use Symptoms that mean this skill applies: - One file / function does HTTP + DB + external API + business rules - Changing one feature forces edits in many files (shotgun surgery) - Tests require the real DB, real HTTP, or mocked SDKs - The same shape repeats in slightly different forms (3+ times) - You cannot describe a module's responsibility in one sentence - Module-level singletons wired from `process.env` at import time - `any` types at internal boundaries ## When NOT to Use - One-off scripts or throwaway tooling - Cosmetic cleanup (renaming, formatting) — that's not architecture - There are no tests AND no budget to add them — refactoring without tests is rewriting - You cannot name a concrete pain point beyond "this feels messy" ## Install ### Claude Code ```bash /plugin marketplace add https://github.com/zachcr-ws/improve-code-architecture /plugin install improve-code-architecture ``` ### Cursor Point Cursor at the cloned repo in Plugin settings. Manifest lives at `.cursor-plugin/plugin.json`. ```bash git clone https://github.com/zachcr-ws/improve-code-architecture.git ``` ### Codex See [`.codex/INSTALL.md`](./.codex/INSTALL.md) — clone + symlink. ### Gemini CLI Install as a Gemini extension from this repo. Manifest: `gemini-extension.json`. Context is loaded from `GEMINI.md`. ### OpenCode (manual) No runtime plugin is provided. Copy `skills/improve-code-architecture/` into your OpenCode skills directory: ```bash git clone https://github.com/zachcr-ws/improve-code-architecture.git cp -R improve-code-architecture/skills/improve-code-architecture ~/.config/opencode/skills/ ``` (Adjust the destination path to match your OpenCode skills location.) ## How It Works The skill enforces a five-step workflow. Each step is mandatory; each scales with the size of the change. 1. **ASK** — 3–5 concrete questions about pain, scope, tests, constraints, and non-goals. No pattern talk until these are answered. 2. **DIAGNOSE** — rate each of the five qualities (Testable, Readable, Modular, Maintainable, Reusable) as OK / Weak / Broken with evidence. Name the 1–2 broken ones. Those drive the plan. 3. **PLAN** — current structure → target structure → patterns applied (each justified by _"Pattern X hides concern Y so Z can change independently"_) → migration sequence → trade-offs → verification. 4. **CONFIRM** — present the plan, wait for explicit approval. No coding mid-discussion. 5. **IMPLEMENT** — tests first, one concern per commit, strangler not big-bang, behavior preservation over purity. ## Skills in this repo This plugin ships two complementary skills: ### [`architecture-lens`](./skills/architecture-lens/SKILL.md) — start here A lightweight pre-flight + post-diff lens you wear during routine implementation. Guards five qualities — Architectural alignment, Readability, Modularity, Reusability, Maintainability — and escalates to `improve-code-architecture` when a problem is too deep for the current diff. Use during the IMPLEMENT step of a plan, alongside TDD. ### [`improve-code-architecture`](./skills/improve-code-architecture/SKILL.md) — escalation path A restructuring workflow for codebases that already need surgery. Five-step workflow (ASK → DIAGNOSE → PLAN → CONFIRM → IMPLEMENT) with an 11-pattern reference. Use when you are deliberately refactoring. ## Pattern Catalog Eleven patterns, each with Problem → Solution → Code shape → Use when → Do NOT use when → Trade-offs. See [`skills/improve-code-architecture/patterns-reference.md`](./skills/improve-code-architecture/patterns-reference.md). - **Dependency Injection** — hides a concrete collaborator (DB, clock, HTTP) - **Strategy** — hides a runtime choice of algorithm - **Repository + Unit of Work** — hides persistence / query details - **Ports & Adapters (Hexagonal)** — isolates domain from all I/O - **Facade** — hides a complex subsystem behind one verb - **Decorator** — hides cross-cutting behavior (logging, retry, auth) - **Factory** — hides construction complexity and wiring - **Command** — reifies an operation (undo, queue, audit) - **Observer / Domain Events** — reacts to a thing that happened - **Adapter** — integrates an incompatible interface - **Template Method** — a fixed workflow with swappable steps ## Contributing See [CONTRIBUTING.md](./CONTRIBUTING.md). New patterns must pass the _"hides concern Y"_ template test and include Problem / Solution / Code shape / Use when / Do NOT use when / Trade-offs. ## License MIT — see [LICENSE](./LICENSE).