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/circular-dependencies.md
View on GitHub# Circular Dependency Detection & Resolution
Last reviewed: 2026-07-02
Deep reference for detecting, classifying, and resolving circular dependencies across ecosystems.
---
## Detection Commands
### Node.js / TypeScript
```bash
# madge — the standard tool for JS/TS circular detection
npx madge --circular --extensions ts,tsx src/
npx madge --circular --extensions ts,tsx --image graph.svg src/ # visual graph
# dpdm — faster for single-entry analysis
npx dpdm --circular --tree false src/index.ts
# ESLint rule (catches at lint time, not just CI)
# .eslintrc: { "rules": { "import/no-cycle": ["error", { "maxDepth": 3 }] } }
# dependency-cruiser — most configurable
npx depcruise --validate .dependency-cruiser.cjs src/
```
### Python
```bash
# pydeps — package-level cycle detection
pydeps --no-output --show-cycles src/
# importlab — Google's import analysis tool
importlab --trim src/
# Manual: grep for cross-imports
grep -rn "from.*import" src/ | sort | uniq -d
```
### Go
```bash
# Go compiler catches import cycles at build (always enforced)
go build ./... # cycle = compile error
# For analysis without build:
go vet ./...
```
### Rust
Distinguish Cargo package dependency cycles from references between Rust modules.
Do not claim that compiling proves an acyclic architectural module graph. Use the
repository's dependency rules or inspect module edges when that property matters.
---
## Fix Strategies
### Strategy 1: Interface Extraction
**When:** Two modules need each other's types.
```
BEFORE (circular):
user.ts imports order.ts (for OrderSummary type)
order.ts imports user.ts (for UserInfo type)
AFTER (fixed):
types/contracts.ts defines OrderSummary + UserInfo
user.ts imports from types/contracts.ts
order.ts imports from types/contracts.ts
```
### Strategy 2: Dependency Inversion
**When:** Module A calls Module B, but B also needs to notify A.
```
BEFORE (circular):
payment.ts imports notification.ts (to send receipt)
notification.ts imports payment.ts (to check payment status)
AFTER (fixed):
payment.ts defines PaymentObserver interface
notification.ts implements PaymentObserver
payment.ts calls observer.onPaymentComplete() — no import of notification
```
### Strategy 3: Event Bus / Mediator
**When:** Multiple modules have cross-cutting communication needs.
```
BEFORE (circular web):
auth -> user -> billing -> auth (cycle)
AFTER (fixed):
eventBus.ts (no domain imports)
auth emits 'user.authenticated'
user listens 'user.authenticated', emits 'user.profile.loaded'
billing listens 'user.profile.loaded'
No module imports another — all communicate via events
```
### Strategy 4: Merge Modules
**When:** Two small modules are truly co-dependent and represent one concept.
```
BEFORE (circular, both small):
validator.ts (50 lines) <-> parser.ts (40 lines)
AFTER (merged):
parse-and-validate.ts (90 lines) — single responsibility, no cycle
```
---
## Common Patterns & Resolutions
| Pattern | Root Cause | Resolution |
|---------|-----------|------------|
| Model A references Model B and vice versa | Bidirectional relationship modeled as imports | Extract shared types to `models/types.ts` |
| Service imports Repository that imports Service | Layering violation | Repository never imports Service; use events for reverse flow |
| Test helper imports source, source imports test util | Test infrastructure leaks into production | Move test utils to `__test_utils__/` outside source tree |
| Barrel (index.ts) creates hidden cycle | Re-export graph hides actual dependencies | Remove barrel, use direct imports |
| Monorepo package A depends on B depends on A | Shared types scattered across packages | Create `@org/contracts` package |
| Plugin imports host, host imports plugin | Plugin boundary confused | Define plugin interface in host; plugin implements without importing host internals |
---
## Verification After Fix
After resolving a cycle, always:
1. Re-run detection command — must report zero cycles
2. Run the affected tests/checks at the depth required by `dev` §3; respect explicit execution constraints
3. Check bundle size — extraction should not increase bundle
4. Review the dependency direction — dependencies point inward toward Domain; outer layers depend on inner layers, never the reverse
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 |