improve-codebase-architecture
코드베이스 아키텍처 개선
코드베이스에는 테스트 어렵고 탐색하기 어려운 얕은 모듈들이 축적됩니다. 이 스킬은 모듈 깊이와 Seam을 분석하여 심화 기회를 찾고, 리팩토링 의사결정을 안내하여 아키텍처를 더 유지보수하기 쉽게 만듭니다.
스킬 ZIP 다운로드
Claude에서 업로드
설정 → 기능 → 스킬 → 스킬 업로드로 이동
토글을 켜고 사용 시작
테스트해 보기
"improve-codebase-architecture" 사용 중입니다. 우리 결제 처리 코드에서 심화 기회 찾기
예상 결과:
다음은 3개의 심화 후보입니다:
1. **주문 수신 모듈**
- 파일: OrderHandler.ts, OrderValidator.ts, OrderPersistence.ts
- 문제: 주문 수신의 일부를 수행하는 3개의 모듈로, 주문 제약 조건이 그들 사이에 퍼져 있음
- 해결책: 주문 수신을 위한 명확한 인터페이스로 하나의 모듈로 결합
- 이점: 주문 검증 규칙의 지역성; 테스트를 위한 단일 인터페이스 활용
2. **결제 게이트웨이 어댑터**
- 파일: StripeClient.ts, PaymentController.ts
- 문제: 결제 로직이 전송 concerns과 혼합됨
- 해결책: 포트를 정의하고, 로직은 심층 모듈에 유지하고 Stripe를 어댑터로 주입
- 이점: 테스트를 위한_mock 어댑터 활용; 결제 규칙의 지역성
첫 번째로 어떤 것을 탐색하시겠습니까?
"improve-codebase-architecture" 사용 중입니다. 우리 캐시 모듈의 대체 인터페이스 설계
예상 결과:
**문제 공간:** 캐시 모듈은 현재 캐시 무효화를 검색에 결합합니다. 클라이언트는 무효화 시기를 알아야 합니다.
**설계 1 (최소화):** 1개의 진입점 `get(key, loader)` - 로더가 캐시 미스 시 지연 로드, 무효화 자동.
**설계 2 (유연함):** 구성 가능한 무효화 정책과 함께 분리된 `get`, `set`, `invalidate`.
**설계 3 (일반 케이스 우선):** 비동기 `get`이 캐시에서 즉시 반환, 로더가 백그라운드에서 실행.
**권장사항:** 설계 1은 진입점당 가장 높은 활용도를 제공합니다. 로더 패턴은 호출자에서 무효화 책임을 제거합니다.
보안 감사
안전All 41 static findings are false positives. The scanner incorrectly flagged 'interface' as weak cryptography and backticks as shell execution. This is a documentation skill that guides AI code analysis using software architecture vocabulary (module, interface, seam, adapter). No malicious patterns, no command injection vectors, no credential access.
높은 위험 문제 (3)
낮은 위험 문제 (1)
품질 점수
만들 수 있는 것
대규모 리팩토링 전
대규모 기능을 다루기 전에 어떤 모듈을 심화해야 하는지 파악하세요. 트레이드오프 분석과 함께 건축적 기회의 순위 목록을 얻으세요.
테스트 커버리지 개선
현재 인터페이스를 통해 테스트하기 어려운 모듈을 찾으세요. Seam을 통한 테스트를 가능하게 하는 심화 권장사항을 받으세요.
새 팀 온보딩
새 팀원을 위해 코드베이스의 아키텍처 형태를 드러내세요. 심화 대화를 사용하여 아키텍처가 왜 현재 형태로 설계되었는지 설명하세요.
이 프롬프트를 사용해 보세요
우리 코드베이스에서 심화 기회를 찾으세요. 먼저 CONTEXT.md와 docs/adr/에 있는 ADR들을 읽어보세요.
[기능 영역]과 관련된 모듈에 집중하세요. 얕은 모듈, Seam 간의 긴밀한 결합, 하나의 개념을 이해하기 위해 여러 모듈을 오가야 하는 영역을 찾으세요.
테스트하기 어려운 모듈을 찾으세요. 각 모듈에 대해 현재 인터페이스가 테스트를 어렵게 만드는 이유와 심화하면 어떻게 도움이 되는지 설명하세요.
[모듈 이름]의 대체 인터페이스를 탐색하고 싶습니다. 먼저 문제 공간을 이해시킨 후 3개의 다른 인터페이스 옵션을 설계해주세요.
모범 사례
- 코드베이스를 탐색하기 전에 CONTEXT.md와 ADR을 읽으세요 - 도메인 언어가 좋은 Seam에 이름을 부여합니다
- 삭제 테스트를 적용하세요: 모듈을 삭제하면 복잡성이 집중되거나 다른 곳으로 이동하나요?
- 일관된 용어를 사용하세요: 'boundary' 대신 'seam', 'service' 대신 'adapter'라고 하세요
피하기
- 어떤 후보를 먼저 탐색할지 묻지 않고 인터페이스를 제안하지 마세요
- 최소 두 개의 어댑터가 없는 한 모듈 심화를 제안하지 마세요 (단순 인디렉션이 아닌 실제 Seam)
- ADR과 모순되는 후보를 노출하지 마세요 - 마찰이 실제로 reopened할 만큼 현실적이지 않는 한