binary-agents 1.1.5 → 1.3.1

package/agents/refactor-analyzer.md

@@ -21,11 +21,12 @@ model: opus
 
 ---
 
-## 분석 영역
+## 평가 원칙
 
-### 1. 코드 중복 (Weight: 25%)
+### 1. 코드 중복
 
 **🔍 검색 대상:**
+
 - 여러 파일의 동일한 로직 블록
 - 유사한 조건 패턴
 - 반복되는 계산
@@ -33,7 +34,8 @@ model: opus
 - 중복된 타입 정의
 - 모듈 간 유사한 유틸 함수
 
-**감지 전략:**
+**🔍 검색:**
+
 - Grep으로 유사한 함수명 검색 (예: `calculateNext`, `getActive`)
 - 유사한 책임을 가진 파일 비교
 - JSX의 반복되는 문자열 패턴 찾기
@@ -60,6 +62,7 @@ function useMaintenanceSheet() {
 ```
 
 **✅ 중복을 허용할 때:**
+
 - 유사하지만 분기될 요구사항을 가진 다른 도메인
 - 조기 추상화가 결합도를 증가시킬 때
 - 공유 코드로 테스트 부담이 증가할 때
@@ -67,23 +70,27 @@ function useMaintenanceSheet() {
 - 인스턴스가 2개뿐일 때 (아직 추상화할 가치 없음)
 
 **❌ 중복을 제거할 때:**
+
 - 로직이 진정으로 동일하고 계속 그럴 때 (3개 이상 인스턴스)
 - 동기화되어야 하는 핵심 비즈니스 규칙
 - 명확한 SRP 위반 (같은 책임이 중복)
 - 높은 유지보수 부담 (한 곳의 버그 수정이 다른 곳 누락)
 
 **결정 프레임워크:**
+
 1. **분기 가능성 평가**: 미래에 요구사항이 달라질 것인가?
 2. **결합 비용 계산**: 공유 코드가 독립 기능을 강하게 결합시키는가?
 3. **테스트 영향 평가**: 추상화가 테스트를 어렵게 만드는가?
 4. **팀 커뮤니케이션 고려**: 명확한 공유 이해가 있는가?
 
 **🌐 웹 검색:**
+
 - "DRY principle best practices [current year]"
 - "React component composition patterns"
 - "when to allow code duplication"
 
 **영향 지표:**
+
 - 제거 가능 라인 수
 - 영향받는 파일 수
 - 유지보수 부담 감소
@@ -92,9 +99,10 @@ function useMaintenanceSheet() {
 
 ---
 
-### 2. 순환 복잡도 (Weight: 20%)
+### 2. 순환 복잡도
 
 **🔍 검색 대상:**
+
 - 4개 이상 조건 분기가 있는 함수
 - 중첩된 if/else (2레벨 이상)
 - 5개 이상 case가 있는 switch문
@@ -102,6 +110,7 @@ function useMaintenanceSheet() {
 - Boolean 로직 조합
 
 **복잡도 지표:**
+
 ```typescript
 // 높은 복잡도 (7개 분기)
 function process(a, b, c) {
@@ -125,15 +134,17 @@ function process(a, b, c) {
 ```
 
 **🌐 웹 검색:**
+
 - "cyclomatic complexity reduction techniques"
 - "strategy pattern vs conditional statements"
 - "simplifying conditional expressions"
 
 ---
 
-### 3. 추상화 기회 (Weight: 25%)
+### 3. 추상화 기회
 
 **🔍 식별 대상:**
+
 - 훅으로 만들 수 있는 반복 패턴
 - 로직을 공유할 수 있는 유사 컴포넌트
 - 컴포넌트에 묻힌 유틸 함수
@@ -142,6 +153,7 @@ function process(a, b, c) {
 - 횡단 관심사 (로깅, 에러 처리 등)
 
 **추출 후보:**
+
 - 순수 계산 → utils 파일
 - 상태 로직 → 커스텀 훅
 - UI 패턴 → 공유 컴포넌트
@@ -149,15 +161,17 @@ function process(a, b, c) {
 - 횡단 관심사 → HOC/미들웨어/데코레이터
 
 **🌐 웹 검색:**
+
 - "React custom hooks patterns [current year]"
 - "higher-order components vs custom hooks"
 - "composition over inheritance React"
 
 ---
 
-### 4. 코드 스멜 (Weight: 15%)
+### 4. 코드 스멜
 
 **일반적인 스멜:**
+
 - 긴 파라미터 목록 (4개 이상) → 객체 파라미터 패턴
 - 긴 함수 (50줄 이상) → 메서드 추출
 - 큰 파일 (300줄 이상) → 책임 분리
@@ -167,6 +181,7 @@ function process(a, b, c) {
 - Data Clumps → 객체 생성
 
 **감지 예시:**
+
 ```typescript
 // 스멜: 긴 파라미터 목록
 function create(name, email, age, address, phone, role) { ... }
@@ -190,15 +205,17 @@ class Customer {
 ```
 
 **🌐 웹 검색:**
+
 - "code smells catalog [current year]"
 - "[특정 스멜] modern solutions"
 - "refactoring techniques"
 
 ---
 
-### 5. 성능 기회 (Weight: 10%)
+### 5. 성능 기회
 
 **🔍 검색 대상:**
+
 - 비싼 컴포넌트에 React.memo 누락
 - 적절한 의존성 없는 useEffect
 - useMemo로 감싸지 않은 비싼 계산
@@ -209,15 +226,17 @@ class Customer {
 - 불필요한 리렌더링
 
 **🌐 웹 검색:**
+
 - "React performance optimization [current year]"
 - "React profiler best practices"
 - "useMemo vs useCallback when to use"
 
 ---
 
-### 6. 아키텍처 부채 (Weight: 5%)
+### 6. 아키텍처 부채
 
 **🔍 식별 대상:**
+
 - 누락된 아키텍처 레이어
 - 모듈 간 강한 결합
 - 순환 의존성
@@ -227,6 +246,7 @@ class Customer {
 - 복잡한 도메인의 Transaction Script 패턴
 
 **🌐 웹 검색:**
+
 - "clean architecture React TypeScript"
 - "domain-driven design frontend"
 - "frontend architecture patterns"
@@ -280,6 +300,7 @@ class Customer {
    - 예시와 함께 마이그레이션 경로 제공
 
 **도구 사용:**
+
 - Glob: `**/*.ts`, `**/*.tsx`, `**/hooks/*.ts`, `**/utils/*.ts`, `**/components/**/*.tsx`
 - Grep: 함수 패턴, 중복 로직, 복잡도 지표 검색
 - Read: 검색으로 플래그된 파일 상세 분석
@@ -287,6 +308,7 @@ class Customer {
 - WebFetch: 특정 예시, 카탈로그, 문서 가져오기
 
 **웹 리서치 전략:**
+
 - WebSearch로 모던 리팩토링 패턴 조사
 - WebFetch로 리팩토링 카탈로그 (refactoring.guru, sourcemaking.com)
 - 프레임워크별 리팩토링 기법 연구
@@ -298,276 +320,83 @@ class Customer {
 
 ## Output Format
 
-```markdown
+````markdown
 # 리팩토링 기회 분석 리포트
 
-## 기술 스택 & 아키텍처
-**프레임워크:** [Next.js / React / 등]
-**현재 패턴:** [식별된 아키텍처 패턴]
-**아키텍처 성숙도:** [기초 / 중급 / 고급]
+## 발견 사항 요약
 
-## 업계 벤치마크
-**비교 대상:**
-- [Refactoring Guru 카탈로그]
-- [프레임워크 베스트 프랙티스 현재년도]
-- [업계 리더 패턴]
+- **Critical:** N개 (즉시 수정 필요)
+- **Recommended Improvements:** M개 (권장 개선)
+- **Best Practices Found:** P개 (잘하고 있음)
 
 ---
 
-## 요약
-- **발견된 총 이슈:** X개
-- **중복 코드 총 라인:** Y줄
-- **예상 정리 영향:** Z줄 제거
-- **복잡도 감소:** W% 평균
-- **업계 갭:** [뒤처짐 / 동등 / 앞서감]
+## Critical Issues (즉시 수정)
 
----
-
-## High Priority (먼저 수행)
-
-### 1. [이슈 제목]
-**유형:** 코드 중복 | 복잡도 | 추상화 | 코드 스멜 | 성능 | 아키텍처
-**영향:** High/Medium/Low | **노력:** Low/Medium/High | **ROI:** ⭐⭐⭐⭐⭐
-**영향 파일:** X개
+### 1. [Issue Name]
 
-**현재 상태:**
-- [file1.ts:42-58] - [간략 설명]
-- [file2.ts:120-136] - [간략 설명]
+**위반 원칙:** [해당 원칙]
+**파일:** [file:line]
 
 **문제:**
-[이슈 상세 설명]
+[설명]
 
-**업계 표준:**
-[모던 코드베이스가 다르게 하는 것]
-**출처:** [URL과 함께 WebSearch/WebFetch 결과]
+**현재 코드:**
 
-**권장 솔루션:**
 ```typescript
-// [출처]의 [패턴명] 기반:
-// 1단계: 공통 인터페이스 추출
-export interface Strategy {
-  execute(): Result
-}
-
-// 2단계: 전략 구현
-export class StrategyA implements Strategy {
-  execute() { /* 통합 구현 */ }
-}
-
-// 3단계: 전략 패턴 사용
-function process(strategy: Strategy) {
-  return strategy.execute()
-}
+// 문제 코드
 ```
+````
 
-**마이그레이션 경로:**
-1. [1단계 - 특정 파일 및 변경]
-2. [2단계 - 특정 파일 및 변경]
-3. [3단계 - 검증 단계]
-
-**영향 지표:**
-- 제거 라인: ~XX줄
-- 감소 복잡도: Y 포인트
-- 유지보수 부담: Z% 감소
-- 테스트 커버리지: 더 쉬워짐 (N곳 대신 1곳)
-
-**학습 리소스:**
-- [패턴 문서 링크]
-- [구현 예시 링크]
-- [마이그레이션 가이드 링크]
-
----
-
-## Medium Priority
-
-### 2. [이슈 제목]
-[웹 소스와 함께 같은 구조]
-
----
-
-## Low Priority (있으면 좋음)
-
-### 3. [이슈 제목]
-[같은 구조]
-
----
+**수정 방법:**
 
-## 코드 품질 지표
-
-### 복잡도 핫스팟
-| 파일 | 함수 | 복잡도 | 현재 | 목표 | 리팩토링 |
-|------|------|--------|------|------|----------|
-| [file:line] | funcName | 8 | 중첩 if | 3 | 전략 패턴 |
-| [file:line] | funcName | 6 | 긴 함수 | 2 | 메서드 추출 |
-
-### 중복 매트릭스
-| 패턴 | 발생 | 라인 | 우선순위 | 모던 솔루션 |
-|------|------|------|----------|-------------|
-| 네비게이션 로직 | 3파일 | 53줄 | High | 커스텀 훅 |
-| 검증 체크 | 5파일 | 42줄 | Medium | 공유 검증기 |
-
-### 아키텍처 갭
-| 누락 레이어 | 영향 | 업계 표준 | 학습 리소스 |
-|-------------|------|-----------|-------------|
-| 도메인 모델 | High | DDD 패턴 | [링크] |
-| API 추상화 | Medium | Repository 패턴 | [링크] |
-
----
-
-## 권장 리팩토링 패턴
-
-코드베이스 분석 및 업계 연구 기반:
-
-### 패턴 1: [패턴명]
-**사용 사례:** [코드에서 적용할 때]
-**업계 채택:** [일반적 / 부상 중 / 최신]
-**적용 파일:** [특정 파일 참조]
-**예시:** [WebFetch 결과 또는 코드 예시]
-**더 알아보기:** [URL]
-
-### 패턴 2-N: [계속...]
-
----
-
-## 구현 순서
-
-### Phase 1: Quick Wins (1-2일)
-1. **[리팩토링명]** - 이유: [높은 ROI, 낮은 리스크]
-   - 파일: [file1, file2]
-   - 패턴: [패턴 링크]
-   - 영향: [특정 지표]
-
-### Phase 2: 중간 노력 (1주)
-2. **[리팩토링명]** - 이유: [Phase 1 의존성]
-   - 파일: [file3, file4]
-   - 전제조건: [Phase 1 완료]
-   - 영향: [특정 지표]
-
-### Phase 3: 아키텍처 (2-4주)
-3. **[리팩토링명]** - 이유: [미래 기능의 기반]
-   - 파일: [많은 파일, 아키텍처 변경]
-   - 마이그레이션 전략: [가이드 링크]
-   - 영향: [장기적 이점]
-
----
-
-## 업계 비교
-
-### 잘하고 있는 것 ✅
-- [업계 리더와 일치하는 패턴/관행]
-- [또 다른 좋은 패턴]
-
-### 놓치고 있는 업계 트렌드 ⚠️
-1. **[모던 패턴]**
-   - **무엇인가:** [간략 설명]
-   - **왜 중요한가:** [이점]
-   - **채택률:** [업계 사용 %]
-   - **더 알아보기:** [웹 리서치 링크]
-
-2. **[또 다른 트렌드]**
-   - [같은 구조]
-
-### 최신 기술 (미래 고려) 🔮
-- [매우 새로운 패턴 - 주의와 함께 설명]
-- [연구/블로그 포스트 링크]
-
----
-
-## 감지된 안티패턴
-
-### 1. [안티패턴명]
-**발견 위치:** [file:line 참조]
-**왜 문제인가:** [설명]
-**업계 관점:** [WebSearch 결과]
-**리팩토링:** [리팩토링 기법 링크]
-**수정된 예시:**
 ```typescript
-// Before (안티패턴)
-[현재 코드]
-
-// After (모던 패턴)
-[리팩토링된 코드]
+// 개선 코드
 ```
 
 ---
 
-## 학습 경로
-
-이 분석 기반으로 큐레이션된 학습 경로:
-
-### 즉시 (이번 스프린트)
-- [ ] [주제 1] - [리소스 링크]
-- [ ] [주제 2] - [리소스 링크]
-
-### 단기 (이번 달)
-- [ ] [심층 주제] - [코스/책 링크]
-- [ ] [패턴 마스터] - [예시 링크]
+## Recommended Improvements (권장 개선)
 
-### 장기 (이번 분기)
-- [ ] [아키텍처 주제] - [종합 가이드 링크]
-- [ ] [고급 패턴] - [문서 링크]
+[같은 형식]
 
 ---
 
-## 리팩토링 리소스
+## Best Practices Found (잘하고 있음)
 
-### 패턴 카탈로그
-- [Refactoring Guru - 특정 섹션]
-- [SourceMaking - 특정 패턴]
-- [프레임워크별 가이드]
+### [Good Pattern]
 
-### 업계 리더 예시
-- [오픈 소스 프로젝트 예시]
-- [회사 테크 블로그 포스트]
-- [컨퍼런스 발표/프레젠테이션]
+**원칙:** [해당 원칙]
+**파일:** [file:line]
 
-### 도움이 되는 도구
-- [스택에 맞는 리팩토링 도구]
-- [린터/정적 분석]
-- [테스팅 프레임워크]
+**잘한 점:**
+[설명]
 
 ---
 
-## 리스크 평가
+## Metrics
 
-### Low Risk 리팩토링 ✅
-즉시 수행 가능:
-1. [파일 참조와 함께 리팩토링]
-2. [또 다른 안전한 리팩토링]
-
-### Medium Risk 리팩토링 ⚠️
-철저히 테스트 필요:
-1. [동작을 변경하는 리팩토링]
-2. [여러 파일에 영향을 주는 리팩토링]
+### 복잡도 핫스팟
 
-### High Risk 리팩토링 🚨
-계획과 점진적 마이그레이션 필요:
-1. [아키텍처 변경]
-   - **리스크:** [무엇이 깨질 수 있는지]
-   - **완화:** [웹 리서치의 전략]
-   - **롤백 계획:** [되돌리는 방법]
+| 파일        | 함수     | 복잡도 | 현재    | 목표 | 리팩토링    |
+| ----------- | -------- | ------ | ------- | ---- | ----------- |
+| [file:line] | funcName | 8      | 중첩 if | 3    | 전략 패턴   |
+| [file:line] | funcName | 6      | 긴 함수 | 2    | 메서드 추출 |
 
----
-
-## 성공 지표
+### 중복 매트릭스
 
-리팩토링 성공을 측정하기 위한 지표:
+| 패턴            | 발생  | 라인 | 우선순위 | 모던 솔루션 |
+| --------------- | ----- | ---- | -------- | ----------- |
+| 네비게이션 로직 | 3파일 | 53줄 | High     | 커스텀 훅   |
+| 검증 체크       | 5파일 | 42줄 | Medium   | 공유 검증기 |
 
-**Before:**
-- 평균 함수 복잡도: X
-- 중복 코드 비율: Y%
-- 테스트 커버리지: Z%
-- 빌드 시간: A초
+### 아키텍처 갭
 
-**Target (리팩토링 후):**
-- 평균 함수 복잡도: <X (업계 표준: <5)
-- 중복 코드 비율: <Y% (업계 표준: <3%)
-- 테스트 커버리지: >Z% (업계 표준: >80%)
-- 빌드 시간: <A초
+| 누락 레이어 | 영향   | 업계 표준       | 학습 리소스 |
+| ----------- | ------ | --------------- | ----------- |
+| 도메인 모델 | High   | DDD 패턴        | [링크]      |
+| API 추상화  | Medium | Repository 패턴 | [링크]      |
 
-**측정 방법:**
-- [지표 측정 도구/명령]
-- [측정 빈도]
 ```
 
 ---
@@ -590,19 +419,10 @@ function process(strategy: Strategy) {
 - 패턴이 프로덕션 준비 상태인지 확인 (실험적이 아닌)
 - 케이스 스터디와 실제 예시 찾기
 
-**우선순위화:**
-- High Priority: 높은 영향 + 낮은 노력 + 업계 검증 (quick wins)
-- Medium Priority: 높은 영향 + 높은 노력 OR 낮은 영향 + 낮은 노력
-- Low Priority: 낮은 영향 + 높은 노력 OR 실험적 패턴
-
-**점수 가이드라인 (ROI):**
-- ⭐⭐⭐⭐⭐: Critical 리팩토링, 업계 표준, 높은 ROI
-- ⭐⭐⭐⭐: 중요한 개선, 검증된 패턴, 좋은 ROI
-- ⭐⭐⭐: 가치 있지만 긴급하지 않음, 중간 ROI
-- ⭐⭐: 있으면 좋음, 낮은 ROI
-- ⭐: 선택사항, 불확실한 ROI
-
----
+**심각도 분류 기준:**
+- **Critical** (즉시 수정): 높은 영향 + 높은 빈도 - 보안 취약점, 메모리 누수, 심각한 코드 스멜
+- **Recommended Improvements** (권장 개선): 중간~높은 영향 - 중복 코드, 복잡도, 추상화 기회
+- **Best Practices Found** (잘하고 있음): 이미 잘 적용된 패턴
 
 ## 항상 리포트할 Red Flags
 
@@ -632,3 +452,4 @@ function process(strategy: Strategy) {
 - [SourceMaking](https://sourcemaking.com/refactoring)
 - [React Docs - Hooks](https://react.dev/reference/react)
 - [Martin Fowler's Refactoring](https://martinfowler.com/books/refactoring.html)
+```