lidge-jun/codexclaw / plugins/codexclaw/skills/dev-architecture
cxc-dev-architecture
VerifiedUse for module boundaries and dependencies. Triggers: circular import, coupling, barrel, re-export, validation placement, 모듈 경계, 순환 참조.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.7 KB |
| agents/openai.yaml | config | 174 B |
| references/01-module-boundaries.md | markdown | 5.2 KB |
| references/02-import-structure.md | markdown | 5.6 KB |
| references/03-boundary-validation.md | markdown | 3.5 KB |
| references/04-architecture-review.md | markdown | 5.3 KB |
| references/barrel-discipline.md | markdown | 3.9 KB |
| references/circular-dependencies.md | markdown | 4.2 KB |
| references/coupling-taxonomy.md | markdown | 5.3 KB |
references/coupling-taxonomy.md
View on GitHub# Implicit Coupling Taxonomy
Last reviewed: 2026-07-02
Deep reference for classifying, detecting, and resolving coupling in code reviews.
---
## The 8 Coupling Types
### 1. Content Coupling (CRITICAL)
**Definition:** Module directly accesses/modifies another module's internal data.
**Examples:**
- Reading `other._privateField` (bypassing encapsulation)
- Monkey-patching another module's internals
- Directly manipulating another component's DOM/state
**Refactoring:** Expose a public method or getter. If no natural API exists, the modules may need to merge.
### 2. Common Coupling (CRITICAL)
**Definition:** Multiple modules read/write the same global mutable state.
**Examples:**
- Global config object mutated by multiple services
- Shared singleton with mutable state
- Module-level `let` variable imported and modified by others
**Refactoring:** Dependency injection. Pass config explicitly. Use immutable config frozen at startup.
### 3. Control Coupling (HIGH)
**Definition:** Module passes a flag/enum that controls another module's internal logic flow.
**Examples:**
- `processOrder(order, isRetry=true, skipValidation=false)`
- Boolean parameter that switches between two unrelated behaviors
- Enum that selects internal algorithm
**Refactoring:** Polymorphism. Split into `processNewOrder()` / `retryOrder()`. Strategy pattern for algorithm selection.
### 4. Stamp Coupling (HIGH)
**Definition:** Module passes a large data structure when only a small part is needed.
**Examples:**
- `renderHeader(entireUserObject)` when only `user.name` is needed
- Passing full DB row to a function that uses one field
- React component receiving entire store slice as prop
**Refactoring:** Pass only needed fields. Define minimal interface. Destructure at call site.
### 5. External Coupling (HIGH)
**Definition:** Multiple modules independently depend on the same external data format or protocol.
**Examples:**
- Two services both parse the same CSV format with inline logic
- Multiple modules assume specific JSON structure from third-party API
- Hardcoded external URL in multiple places
**Refactoring:** Single adapter/parser module. All consumers import the parsed result, not raw external data.
### 6. Temporal Coupling (MEDIUM)
**Definition:** Modules must execute in a specific (undocumented) order.
**Examples:**
- `init()` must be called before `process()` but nothing enforces this
- Service A must start before Service B
- Config must be loaded before any module initializes
**Refactoring:** State machine (make illegal states unrepresentable). Builder pattern. Explicit initialization chain.
### 7. Sequential Coupling (LOW)
**Definition:** Output of module A feeds directly as input to module B (pipeline).
**Examples:**
- ETL: extract -> transform -> load
- Middleware chain: parse -> validate -> authorize -> handle
- Compiler: lex -> parse -> analyze -> generate
**Refactoring:** Usually acceptable. Document the contract between stages. Validate at stage boundaries.
### 8. Functional Coupling (LOW — TARGET STATE)
**Definition:** Modules interact through well-defined, typed interfaces.
**Examples:**
- Function call with typed parameters and return value
- Interface implementation
- Event with typed payload
**Refactoring:** No refactoring needed. This is the goal state for all inter-module communication.
---
## Severity Matrix (Review Decision)
| Severity | Types | Merge Decision | Required Action |
|----------|-------|----------------|-----------------|
| CRITICAL | Content, Common | BLOCK | Refactor before merge. No exceptions. |
| HIGH | Control, Stamp, External | BLOCK unless justified | Tech-debt ticket with deadline + reviewer approval |
| MEDIUM | Temporal | ALLOW with docs | Add ordering documentation or state assertions |
| LOW | Sequential, Functional | ALLOW | No action needed |
---
## Banned Review Responses
These responses are NEVER acceptable when coupling is identified:
| Banned Response | Why It's Banned | What To Say Instead |
|-----------------|-----------------|---------------------|
| "It works so it's fine" | Working code can be unmaintainable | "It works, but this is [type] coupling (severity: X). Must fix / ticket." |
| "We'll fix it later" (no ticket) | "Later" = never in practice | "Creating ticket [PROJ-XXX] with deadline [date] for decoupling." |
| "It's just one place" | One instance becomes ten within weeks | "Fix now while blast radius is small." |
| "The tests pass" | Tests don't measure architectural integrity | "Tests verify behavior, not structure. Static analysis says X." |
| "It's internal, nobody else uses it" | Internal coupling compounds fastest | "Internal coupling is MORE dangerous — harder to detect, easier to spread." |
---
## Detection Signals During Review
| Signal in Code | Likely Coupling Type | Investigate |
|----------------|---------------------|-------------|
| Accessing `._private` or internal field | Content | Encapsulation breach |
| Global `let` / mutable singleton | Common | Shared mutable state |
| Boolean/enum parameter controlling flow | Control | Hidden polymorphism |
| Passing full object, using 1-2 fields | Stamp | Over-broad interface |
| Duplicated parsing logic | External | Missing shared adapter |
| Comment: "must call X before Y" | Temporal | Missing state machine |
| Pipeline without input validation | Sequential | Undocumented contract |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |