reverse-engineer-strategies

name	reverse-engineer-strategies
description	기존 Kotlin + Spring Boot 백엔드 코드베이스를 분석하여 claude-code-playbook의 strategies/ 문서를 자동 생성하는 스킬. 레거시 프로젝트나 기존 코드베이스에 플레이북을 적용할 때, strategies/ 디렉토리 하위에 프로젝트 실제 구현 패턴을 반영한 컨벤션 문서를 만들어야 할 때 사용한다. "기존 코드 분석해서 strategies 문서 만들어줘", "레거시 코드베이스에서 전략 문서 추출", "코드 보고 strategies/ 채워줘", "기존 프로젝트 플레이북 적용해줘" 같은 요청에 반드시 이 스킬을 사용한다.
model	opus

기존 코드베이스 → Strategies 문서 역공학

기존 Kotlin + Spring Boot 백엔드 코드베이스를 읽어 각 아키텍처 레이어의 실제 구현 전략을 파악하고, docs/backend/architecture/*/strategies/ 하위 문서들을 자동으로 생성한다.

---

참고 문서

작업 전 아래 두 파일을 읽어 분석 방법과 출력 형식을 숙지한다.

• references/layer-analysis-guide.md — 레이어별 분석 방법 (어떤 파일을 읽고, 어떤 패턴을 찾아야 하는지)
• references/strategies-doc-templates.md — 출력 문서 형식 (README.md와 컨벤션 문서 템플릿)

---

Step 1. 입력 파악

사용자에게 다음 두 가지를 확인한다.

1-A. 분석 대상 코드베이스 경로

"분석할 코드베이스 경로를 알려주세요. (예: /Users/me/projects/my-backend)"

사용자가 현재 디렉토리라고 하거나 생략하면 CWD를 사용한다.

1-B. 문서 출력 경로

"생성된 strategies/ 문서를 어디에 저장할까요?

• [1] 현재 플레이북의 docs/backend/architecture/
• [2] 대상 코드베이스 내 docs/backend/architecture/
• [3] 직접 입력"

기본값: 현재 플레이북의 docs/backend/architecture/.

1-C. 분석 대상 레이어 (선택 사항)

"특정 레이어만 분석할까요? (app / application / domain / storage / external) 지정하지 않으면 존재하는 레이어를 모두 분석합니다."

---

Step 1-D. 기존 문서 상태 파악 (레이어별)

출력 경로를 확인하여 레이어별로 기존 strategies/ 파일 유무를 확인한다. 레이어마다 독립적으로 아래 두 가지 모드 중 하나를 결정한다.

레이어별 모드 결정

각 레이어에 대해:

• {출력경로}/{레이어}/strategies/ 하위에 파일이 하나라도 존재하면 → 병합 대상 레이어
• 파일이 전혀 없으면 → 신규 생성 레이어 (사용자에게 묻지 않음)

레이어별 모드 맵을 기록한다:

레이어별 처리 모드
- app        → 신규 생성 (기존 파일 없음)
- application → 병합 대상 (기존 파일 N개 발견)
- domain     → 신규 생성 (기존 파일 없음)
- storage    → 병합 대상 (기존 파일 N개 발견)
- external   → 신규 생성 (기존 파일 없음)

병합 대상 레이어가 하나라도 있을 때만 사용자에게 전체 병합 방식을 묻는다.

"일부 레이어에 기존 strategies/ 문서가 있습니다.

• [{레이어명}: N개 파일] 기존 파일이 있는 레이어를 어떻게 처리할까요?
• [1] 병합 — 기존 내용과 코드 분석 결과를 대조하여, 일치하면 보존·부족한 항목만 추가하고, 코드와 불일치하는 내용은 수정합니다.
• [2] 덮어쓰기 — 기존 파일을 삭제하고 코드 분석 결과로 새로 작성합니다."

기본값: [1] 병합

신규 생성 레이어는 선택과 무관하게 항상 새로 생성한다.

---

Step 2. 프로젝트 구조 탐색

입력 받은 코드베이스 경로에서 아래 순서로 탐색한다.

2-1. 멀티 모듈 vs 단일 모듈 식별

먼저 대상 코드베이스가 멀티 모듈인지 단일 모듈인지 식별한다.

• settings.gradle.kts가 존재하고 include(...) 선언이 2개 이상이면 → 멀티 모듈
• 그렇지 않으면 → 단일 모듈

2-2. 구조 파악

멀티 모듈인 경우

settings.gradle.kts, 각 모듈의 build.gradle.kts, src/main 구조를 읽어 레이어별 모듈 후보를 식별한다.

cat {codebase_path}/settings.gradle.kts
find {codebase_path} -name "build.gradle.kts" | grep -v "build/" | head -20
find {codebase_path} -name "*.kt" -path "*/src/main/*" | head -50

단일 모듈인 경우

src/main/kotlin 이하 패키지와 디렉토리 구조를 읽어 레이어별 디렉토리 후보를 식별한다.

find {codebase_path}/src/main/kotlin -type d | head -40
find {codebase_path}/src/main/kotlin -name "*.kt" | head -50

2-3. 로컬 레이어 매핑

식별한 모듈·디렉토리를 플레이북의 개념 레이어에 매핑한다.

• domain, application, storage, external, app 같은 플레이북 개념 레이어를 먼저 떠올리되, 실제 프로젝트가 쓰는 로컬 레이어 이름과 경계를 우선 기록한다.
• 플레이북에 적힌 예시 레이어명과 정확히 일치하지 않더라도, 실제 코드에서 드러나는 역할과 책임을 기준으로 매핑한다.
• 예를 들어 app 대신 api, presentation, bootstrap을 쓸 수 있고, storage와 external을 infra 또는 infrastructure 하위에 둘 수도 있다.
• 추측하지 말고 실제 클래스 역할, 어노테이션, 네이밍 패턴, 의존 방향을 근거로 판단한다.

매핑 결과는 아래 형식으로 기록한다.

로컬 레이어 맵
- {로컬 이름} -> {개념 레이어}
- {로컬 이름} -> {개념 레이어}
- ...

---

Step 3. 레이어별 코드 분석

각 레이어에 대해 references/layer-analysis-guide.md를 참고하여 분석한다. 레이어별 분석 대상, 확인할 패턴, 결과 기록 형식이 모두 해당 문서에 정의되어 있다.

각 레이어 분석 시 반드시 실제 파일을 읽어서 사실 기반으로 답한다. 추측 금지.

레거시/불명확 패턴 감지

분석 중 아래 신호를 발견하면 레거시 코드베이스로 간주하고 별도 메모를 남긴다:

• 서비스 클래스 명명이 혼재 (Service, Manager, Handler, Helper 동시 사용)
• @Transactional이 레이어 경계를 벗어난 클래스에 붙어 있음
• Controller에서 URL 동사 사용 (/do-confirm, /create-order 등)
• 도메인 로직이 Service 클래스에 직접 구현됨 (도메인 모델 없음)
• JPA Entity와 도메인 모델 미분리
• 순환 의존 또는 레이어 역방향 의존

레거시 코드베이스로 판단되면 현재 패턴을 있는 그대로 문서화하면서, Step 5 문서 생성 시 각 컨벤션 문서 하단에 ## 개선 제안 섹션을 추가한다 (Step 5 참조).

---

Step 4. 불확실한 부분 확인

분석 후 확실하지 않은 부분이 있다면 사용자에게 질문한다. 단, 코드에서 명확히 드러나는 사항은 질문하지 않는다.

예시 질문:

• "Auth 모듈이 두 가지 방식(JWT + Session)을 혼용하는 것 같은데, 주된 방식이 무엇인가요?"
• "QueryDsl 모듈은 있는데 실제로 사용하는 Repository가 보이지 않습니다. 다른 패턴을 쓰시나요?"

---

Step 5. 문서 생성

분석 결과를 바탕으로 references/strategies-doc-templates.md를 참고하여 문서를 생성한다.

레이어별 처리 모드 맵(Step 1-D에서 작성)에 따라 레이어마다 아래 분기로 처리한다.

---

[신규 생성 레이어]

기존 파일이 없는 레이어는 코드 분석 결과만을 바탕으로 처음부터 새로 작성한다.

---

[병합 대상 레이어 + 병합 선택 시]

1. 기존 파일 목록을 확인한다
2. 각 파일을 읽고 내용을 파악한다
3. 코드 분석 결과와 항목별로 대조한다:
   • 코드와 일치하는 내용 → 그대로 보존
   • 코드와 불일치하는 내용 (예: docs는 QueryDSL이라 했는데 코드는 JOOQ) → 코드 기반으로 수정
   • 플레이스홀더 {...} 형태 → 코드 분석으로 발견한 실제 값으로 채움
   • 코드에서 새로 발견된 패턴 → 해당 문서 또는 새 문서에 추가
4. 불일치 수정이 발생한 경우, 완료 보고(Step 6)의 "수정됨" 항목에 기록한다

왜 불일치를 수정하는가: strategies 문서의 목적은 "이 코드베이스가 실제로 선택한 전략"을 기술하는 것이다. 문서가 코드와 다른 내용을 담으면 팀원들이 잘못된 방향으로 개발하게 된다. 기존 문서가 사람이 직접 작성한 것이더라도, 코드가 그 내용을 따르지 않고 있다면 코드가 정답이다.

---

[병합 대상 레이어 + 덮어쓰기 선택 시]

해당 레이어의 strategies/ 디렉토리 내 파일을 모두 삭제하고, 코드 분석 결과만을 바탕으로 처음부터 새로 작성한다.

---

레거시 코드베이스 문서화

Step 3에서 레거시로 판단된 코드베이스의 경우, 각 컨벤션 문서 맨 하단에 ## 개선 제안 섹션을 추가한다.

이 섹션의 목적은 "앞으로 이 코드를 어떻게 개선해나갈 수 있는지" 방향을 제시하는 것이다. 현재 패턴을 비판하는 것이 아니라, 팀이 점진적으로 나아갈 수 있는 실용적 개선 방향을 제안한다.

## 개선 제안

> 현재 코드베이스에서 관찰된 패턴과 점진적 개선 방향.

### 관찰된 안티패턴

| 패턴 | 현재 코드 | 권장 방향 |
|-----|---------|---------|
| {안티패턴명} | {현재 코드 예시} | {개선 방향} |

### 점진적 개선 로드맵

1. **즉시 개선 가능**: {작은 변경으로 큰 효과를 낼 수 있는 항목}
2. **중기 개선**: {설계 변경이 필요하지만 단계적으로 가능한 항목}
3. **장기 개선**: {아키텍처 재설계가 필요한 항목}

---

Step 5-B. 미사용 문서 제거 (병합 모드 전용)

병합 모드에서, strategies/ 디렉토리에 있는 기존 파일 중 코드 분석 결과 해당 컴포넌트 패턴이 코드베이스에 존재하지 않는 파일을 제거한다.

제거 판단 기준

모든 strategies/ 파일을 대상으로 아래 절차로 확인한다. (특정 파일명 목록에 의존하지 않는다.)

1. 파일명에서 컴포넌트 키워드를 추출한다 (예: flow-convention.md → Flow, querydsl-convention.md → QueryDSL)
2. 코드베이스에서 해당 컴포넌트 타입의 클래스 또는 라이브러리 사용이 존재하는지 확인한다
3. 존재하지 않으면 → 제거 대상

확인 방법 예시:

문서 파일명 키워드	코드베이스 존재 여부 확인 방법
flow	class \w+Flow 패턴의 @Service / @Component 클래스
validator	@Component class \w+Validator 패턴
mapper	@Component class \w+Mapper 또는 @Service class \w+Mapper 패턴
querydsl	JPAQueryFactory 또는 QueryDsl import 사용 여부
jooq	DSLContext 또는 jooq import 사용 여부
resttemplate	RestTemplate 사용 여부
okhttp	OkHttpClient 사용 여부
기타 커스텀 파일	파일명에서 추론한 핵심 타입/라이브러리를 코드에서 grep으로 확인

처리 절차

제거 대상으로 판단된 파일마다 다음 순서로 처리한다.

1. 내용 검토: 파일을 읽어 다른 문서에 아직 반영되지 않은 유용한 내용(금지 패턴, 체크리스트 항목 등)이 있는지 확인한다.
2. 내용 이전: 반영 안 된 내용은 가장 관련성 높은 컨벤션 문서에 섹션으로 추가한다.
3. 파일 삭제: 내용 이전이 완료된 파일을 삭제한다.
4. 링크 정리: 삭제된 파일을 참조하는 strategies/README.md의 역할별 컴포넌트 표·Post-Work Verification 체크리스트에서 해당 링크를 제거하거나, 내용이 이전된 문서 링크로 교체한다.

제거하지 않는 경우

아래 중 하나에 해당하면 파일을 유지한다.

• 코드베이스에 해당 컴포넌트가 실제로 존재한다.
• 파일 내용이 "이 프로젝트에서 해당 컴포넌트를 쓰면 안 된다"는 명시적 금지 규칙 역할을 하며, 다른 문서에 이미 통합된 내용이 없다.

---

Step 6. 완료 보고

생성/갱신된 파일 목록, 삭제된 파일 목록, 수정된 내용, 핵심 전략 결정 사항을 사용자에게 보고한다.

## 완료

### 생성 / 갱신

| 파일 | 발견한 전략 |
|-----|-----------|
| storage/strategies/README.md | JPA + QueryDsl |
| storage/strategies/storage-adapter-convention.md | {Entity}Adapter → JpaRepository + QueryDslRepository |
| app/strategies/README.md | JWT Stateless, Header-based multi-tenant |
| ...  | ... |

### 신규 추가 (디폴트 목록에 없던 패턴)

| 파일 | 발견한 패턴 | 근거 |
|-----|-----------|-----|
| application/strategies/scheduler-convention.md | @Scheduled 작업 공통 구조 | XxxScheduler 클래스 3개 발견 |
| ...  | ... | ... |

### 삭제 (미사용 문서)

| 삭제 파일 | 이유 | 내용 이전 위치 |
|---------|-----|-------------|
| application/strategies/flow-convention.md | Flow 클래스 미사용 | use-case-convention.md |
| ...  | ... | ... |

### 수정 (코드와 불일치하여 교체)

| 수정 전 내용 | 수정 후 내용 | 근거 |
|-----------|-----------|-----|
| storage: QueryDSL 기반 문서 | storage: JOOQ 기반 문서 | DSLContext 사용 확인 |
| ...  | ... | ... |

**추가 확인 필요**:
- {불확실해서 임시로 작성한 항목과 이유}