Skip to content

lidge-jun/codexclaw / plugins/codexclaw/skills/dev-architecture

cxc-dev-architecture

Verified

Use for module boundaries and dependencies. Triggers: circular import, coupling, barrel, re-export, validation placement, 모듈 경계, 순환 참조.

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 |
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall