기술 부채 발견은(는) 무엇을 하나요?
코드베이스의 기술 부채를 분석하고 발견된 사항을 실행 가능한 GitHub 이슈로 전환합니다. 분석은 읽기 전용입니다. 이 스킬을 실행하는 동안에는 코드를 절대 변경하지 마십시오.
옵션
사용자의 요청 또는 명령줄 인자에서 다음을 파싱합니다:
- 범위 경로: 분석할 디렉토리 또는 파일 (예:
src/services lib/). - --full: 저장소 전체를 스캔하되, 의존성, 빌드 및 VCS 디렉토리(
node_modules,vendor,.git,dist,build,target,tmp,log, 가상 환경, 생성된 코드)는 제외합니다. - --dry-run: 이슈를 생성하지 않고 발견된 사항만 보고합니다.
- --all: 20개 이슈 제한을 해제합니다.
- --force: 유사한 오픈 이슈가 있어도 이슈를 생성합니다.
- --yes: 확인 프롬프트를 건너뜁니다(사용자가 명시적으로 전달한 경우에만).
- --categories=X,Y: 다음 카테고리만 실행합니다:
dead-code,duplication,architecture,deferred-work,patterns,tests.
실행 모델
각 카테고리는 독립적으로 분석됩니다. 에이전트가 병렬 하위 에이전트를 생성할 수 있는 경우, 각 카테고리에 자체 하위 에이전트를 할당하고 범위, 감지된 스택 및 references/categories.md의 카테고리 체크리스트를 제공한 후, 각각 아래 JSON 형식을 반환하도록 합니다. 그렇지 않은 경우, 컨텍스트 제한을 넘지 않도록 카테고리를 순차적으로 하나씩 실행합니다.
중간 규모 코드베이스에서 6개 카테고리 전체를 순차적으로 실행하는 데는 약 15분에서 30분이 소요됩니다. 더 빠른 결과를 위해 --categories나 좁은 범위를 제안하십시오.
1단계: 범위 결정
- 경로가 주어지면 해당 경로를 사용합니다.
--full이 주어지면 위의 제외 항목을 적용하여 저장소를 스캔합니다.- 그렇지 않으면 존재하는 주요 소스 및 테스트 디렉토리를 자동으로 감지합니다(일반적인 디렉토리:
src/,app/,lib/,pkg/,internal/,cmd/,test/,tests/,spec/). 다음을 표시합니다:자동 감지된 범위: [디렉토리]. 약 X개 파일. 계속하시겠습니까? (전체 스캔은 --full 사용)
범위 내 소스 파일 수를 저장소가 실제로 사용하는 확장자로 계산합니다(예: git ls-files -- <scope> | grep -E '\.(rb|py|ts|tsx|js|go|java|kt|rs|php|cs)$' | wc -l).
- 1,000개 파일 초과: 실행 시간이 길어질 것이라고 경고하고
--categories를 제안합니다. - 5,000개 파일 초과: 한 번에 하나의 카테고리만 실행할 것을 강력히 권장하고 카테고리별 예상 시간을 알려줍니다.
2단계: 사전 분석 확인
--dry-run이 아닌 경우, GitHub CLI를 확인합니다:
gh auth status
실패하면 gh_available=false로 설정하고 다음과 같이 말합니다: "gh CLI를 찾을 수 없거나 인증되지 않았습니다. 발견된 사항은 이슈를 생성하지 않고 보고됩니다. 이슈 생성을 활성화하려면 gh auth login을 실행하십시오."
사용 가능한 경우, 나중에 필요한 정보를 가져옵니다:
gh issue list --state open --limit 200 --json number,title,body,labels
gh label list --limit 200 --json name,description
중복 감지를 위해 이슈 목록을, 레이블링을 위해 레이블 목록을 유지합니다.
3단계: 스택 감지
저장소에서 언어, 프레임워크 및 테스트 러너를 추측하지 않고 감지합니다. 일반적인 지표:
| 지표 | 스택 |
|---|---|
Gemfile에 rails 또는 config/application.rb | Ruby on Rails |
manage.py 또는 requirements / pyproject.toml에 django | Django |
pyproject.toml / requirements.txt에 fastapi 또는 flask | Python 웹 |
package.json에 next, react, vue, svelte, express, nestjs | JS/TS 프레임워크 |
go.mod | Go |
Cargo.toml | Rust |
pom.xml / build.gradle* | JVM (Spring이 있으면 Spring) |
composer.json에 laravel/framework | Laravel |
*.csproj | .NET |
또한 테스트 프레임워크(RSpec, Minitest, pytest, unittest, Jest, Vitest, Mocha, Go testing, JUnit, PHPUnit 등)와 테스트 디렉토리를 감지합니다.
판단하기 전에 프로젝트 자체 규칙을 읽으십시오: README, CONTRIBUTING, 에이전트 명령 파일(AGENTS.md, CLAUDE.md, GEMINI.md), 린터 설정 및 아키텍처 문서. 프로젝트가 의도적으로 선택한 패턴은 부채가 아닙니다.
보고: 감지된 스택: [언어 / 프레임워크 / 테스트 러너]. 분석 규칙이 이에 맞게 조정되었습니다.
4단계: 카테고리 분석 실행
활성화된 각 카테고리에 대해(기본적으로 6개 모두):
[카테고리] 분석 중... (X / N)을 알립니다.references/categories.md에서 해당 카테고리의 체크리스트를 감지된 스택에 맞게 적용합니다.- 아래 JSON 형식으로 발견 사항을 수집합니다.
[카테고리] 완료: X개 발견을 보고합니다.
어떤 카테고리가 다른 카테고리보다 훨씬 오래 실행되면(약 5분의 활성 분석), 중단하고 보고서에서 불완전(잘림)으로 표시하여 실행이 지연되지 않도록 합니다.
발견 사항 형식
모든 카테고리는 다음을 반환합니다:
{
"category": "Dead Code",
"findings": [
{
"type": "Unused Import",
"severity": "P3",
"location": "src/utils/format.ts:5",
"line_number": 5,
"description": "'date-fns' 가져오기가 이 파일에서 사용되지 않음",
"evidence": "import { format } from 'date-fns'",
"remediation": "사용되지 않는 가져오기 제거",
"complexity": "simple"
}
]
}
중복의 경우, 모든 위치를 쉼표로 구분하여 location에 넣습니다. 아키텍처 발견의 경우, 메트릭을 description에 넣습니다(예: "567줄, 23개의 public 메서드").
심각도 참조
| 패턴 | 심각도 | 카테고리 |
|---|---|---|
| 보안 문제를 숨기는 테스트 | P0 | 테스트 품질 |
| 리소스 접근 시 권한 확인 누락 | P1 | 패턴 위반 |
| 갓 클래스 (>500줄 또는 >20개의 public 메서드) | P1 | 아키텍처 |
| 순환 의존성 | P1 | 아키텍처 |
| 도달할 수 없는 코드 | P1 | 죽은 코드 |
| 목 전용 테스트 (테스트가 테스트 대상을 목 처리) | P1 | 테스트 품질 |
| 주체를 스터빙한 후 단언 | P1 | 테스트 품질 |
| 잉여 논리 테스트 | P1 | 테스트 품질 |
| 빈 테스트 본문 | P1 | 테스트 품질 |
| 과도한 모킹 (테스트의 50% 이상이 설정) | P1 | 테스트 품질 |
| 클래스의 모든 인스턴스 스터빙 | P1 | 테스트 품질 |
| 테스트 간 공유되는 가변 상태 | P1 | 테스트 품질 |
| 긴 함수 (>50줄) | P2 | 아키텍처 |
| 높은 결합도 (>10개의 프로젝트 내 임포트) | P2 | 아키텍처 |
| 정확하거나 거의 정확한 중복 | P2 | 중복 |
| 사용 중단 알림 | P2 | 지연 작업 |
| 임시 또는 해결 방법 표시 | P2 | 지연 작업 |
| 프레임워크 안티패턴 | P2 | 패턴 위반 |
| 구현 결합 테스트 | P2 | 테스트 품질 |
| "예외를 발생시키지 않음"만 단언하는 테스트 | P2 | 테스트 품질 |
| 참조되지 않는 함수, 죽은 분기, 고아 파일 | P2 | 죽은 코드 |
| 깊은 중첩 (>4레벨) | P3 | 아키텍처 |
| 사용되지 않는 임포트 | P3 | 죽은 코드 |
| TODO / FIXME 주석 | P3 | 지연 작업 |
| 주석 처리된 코드 | P3 | 지연 작업 |
| 규칙 위반 | P3 | 패턴 위반 |
| 취약한 테스트 단언 | P3 | 테스트 품질 |
| 티켓을 참조하는 TODO | P4 | 지연 작업 |
복잡성 가이드
- 단순: 10줄 미만, 하나의 파일, 명백한 수정 (사용되지 않는 import 제거).
- 보통: 10
50줄, 23개 파일, 간단한 리팩터링 (함수 추출). - 복잡: 50줄 초과, 아키텍처 결정 필요, 또는 코드베이스 전반에 걸친 변경 (갓 클래스 분할). 구현 전에 설계나 제안이 필요할 가능성이 높다는 점을 remediation에 명시하십시오.
5단계: 수집 및 중복 제거
- 카테고리 + 파일 + 줄(10줄 이내)별로 발견 사항을 그룹화합니다. 각 그룹에서 가장 상세한 증거와 그룹 내 가장 높은 심각도를 가진 발견 사항을 유지합니다.
- 카테고리 간: 죽은 코드와 아키텍처가 동일한 클래스를 지적하는 경우 아키텍처 발견을 유지합니다. 여러 카테고리가 동일한 줄을 지적하는 경우 병합하고 가장 높은 심각도를 유지합니다.
- P0을 먼저 정렬한 다음 P1~P4를 정렬합니다.
6단계: 기존 이슈 확인
--force가 설정된 경우에만 이 단계를 건너뜁니다. 각 발견 사항에 대해 다음 조건을 모두 만족하는 오픈 이슈를 찾습니다:
- 제목이나 본문에 동일한 파일 경로가 언급됨, AND
- 동일한 유형의 문제를 다루거나, 이 발견 사항의 20줄 이내에 있는 줄을 다룸
[TechDebt] 제목이 있거나 기술 부채 레이블이 있는 이슈를 선호하지만, 동일한 문제를 명확히 추적하는 모든 오픈 이슈와 매칭합니다. 매칭 시 발견 사항에 이미 #N으로 추적됨으로 표시하고 이슈로 등록하지 않습니다. 동일한 파일의 다른 문제 유형은 별도의 발견 사항입니다.
7단계: 확인 후 이슈 생성
--dry-run이거나 gh_available=false이면 생성을 건너뛰고 바로 보고서로 이동합니다.
제한: --all이 아니면 최대 20개의 이슈. 다음 순서로 슬롯을 채웁니다: 모든 P0 및 P1, 그 다음 P2(하나의 파일에 많은 이슈보다 여러 파일에 분산 선호), 그 다음 P3, 그 다음 P4. --all이고 50개 이상의 이슈가 있으면 시간이 걸릴 것이라고 경고합니다.
레이블: gh label list에 이미 존재하는 레이블만 사용합니다. 기술 부채에 가장 가까운 레이블(예: tech-debt, technical-debt, debt, refactor, chore)을 선택하고, 저장소에 있는 경우 심각도와 일치하는 우선순위 레이블과 유형 레이블(예: testing)을 선택합니다. 묻지 않고 레이블을 생성하지 마십시오. 적합한 레이블이 없으면 그렇게 말하고 레이블 없이 이슈를 등록하거나 사용자에게 tech-debt 레이블 생성을 요청하십시오.
확인 (필수): 생성하기 전에 전체 목록을 표시하고 사용자의 응답을 기다립니다. --yes를 전달하지 않는 한 절대 이슈를 등록하지 마십시오.
X개의 이슈를 생성합니다 (레이블: tech-debt, P2):
1. [P1] [TechDebt] 아키텍처: OrderService 분할 (612줄, 27개의 public 메서드)
2. [P1] [TechDebt] 테스트 품질: payment_test.py:45의 목 전용 테스트 수정
3. [P2] [TechDebt] 중복: 주소 검증 추출 (user.ts:40, account.ts:88)
...
이미 추적됨 (건너뜀): 3. 제한 초과 (등록되지 않음): 12.
진행하시겠습니까? 번호로 항목을 제거하거나 레이블을 변경할 수도 있습니다.
사용자가 편집한 내용을 적용한 후 각 이슈를 생성합니다. 모든 본문은 이 보고서를 보지 않은 사람이 읽을 수 있도록 독립적이어야 합니다:
gh issue create \
--title "[TechDebt] <카테고리>: <간단한 설명>" \
--label "<기존-레이블>" \
--body "$(cat <<'EOF'
**카테고리:** <카테고리>
**심각도:** P<N>
**위치:** <파일:줄>
## 문제
<설명>
## 증거
```
<증거>
```
## 제안된 수정
<해결 방법>
**복잡성:** <단순|보통|복잡>
## 수락 기준
- <부채가 해결되었음을 확인할 수 있는 관찰 가능한 검사>
- 프로젝트의 전체 테스트 스위트 통과
EOF
)"
제목 예시:
[TechDebt] 죽은 코드: format.ts:5-12에서 사용되지 않는 import 제거[TechDebt] 아키텍처: OrdersController 분할 (567줄, 23개 액션)[TechDebt] 테스트 품질: payment_service_test.go:45의 목 전용 테스트 수정
gh issue create 호출이 실패하면 오류와 명령어를 기록하고 나머지를 계속 진행한 후 마지막에 X개의 이슈 생성됨, Y개 실패를 보고합니다.
저장소가 GitHub 프로젝트 보드에서 작업을 추적하는 경우(에이전트 지침의 Issue tracking 섹션이 Mode: project라고 말하거나 해당 섹션이 없고 gh repo view --json projectsV2가 연결된 보드를 표시하는 경우), 새 이슈에 대해 place-issues 스킬을 실행할 것을 제안합니다.
8단계: 요약 보고서
=== 기술 부채 발견 보고서 ===
범위: [분석된 경로]
분석된 파일 수: [개수]
스택: [언어 / 프레임워크 / 테스트 러너]
소요 시간: [걸린 시간]
## 요약
- 총 발견 사항: X | 생성된 이슈: Y | 이미 추적됨: Z | 제한 초과: W
- 심각도별: P0: A, P1: B, P2: C, P3: D, P4: E
## 카테고리별 발견 사항
### 죽은 코드 (X)
- [ ] #N: format.ts:5-12에서 사용되지 않는 import 제거 (P3)
### 중복 (X)
- [ ] #N: 주소 검증 추출 (user.ts:40, account.ts:88) (P2)
### 아키텍처 (X)
- [ ] #N: OrderService 분할 (612줄, 27개의 public 메서드) (P1)
### 지연 작업 (X)
- [ ] #N: billing.py:123의 TODO 해결 (P3)
### 패턴 위반 (X)
- [ ] #N: OrdersController#index의 N+1 쿼리 위험 수정 (P2)
### 테스트 품질 (X)
- [ ] #N: payment_test.py:45의 목 전용 테스트 수정 (P1)
## 이미 추적됨
- billing.py:100 TODO → #N
## 추가 발견 사항 (제한 초과, 등록되지 않음)
[목록]
나머지 X개의 발견 사항을 등록하려면 --all로 실행하십시오.
## 건너뜀 (거짓 양성 또는 의도적)
- tests/fixtures/** : fixture 제외됨
- conftest.py의 TODO(#42) : 연결된 티켓 있음 (P4)
## 분석 상태
- 죽은 코드: 완료
- ...
- 테스트 품질: 불완전 (잘림)
## 오류
[실패한 gh 명령어]
--dry-run의 경우 이슈 번호를 [생성 예정]으로 바꿉니다.
원칙
- 읽기 전용. 분석 중 코드 변경 금지.
- 보수적. 확실하지 않으면 거짓 양성을 보고하지 말고 건너뜁니다. 소음이 많은 보고서는 무시됩니다.
- 프로젝트 존중. 프레임워크 규칙(콜백, 데코레이터, 의존성 주입, 규칙 기반 라우팅) 및 저장소에 문서화된 선택은 부채가 아닙니다.
- 증거 우선. 모든 발견 사항은 파일, 줄 및 이를 증명하는 코드를 인용합니다.
- 구조화된 출력. 카테고리 분석은 병합 및 중복 제거가 신뢰할 수 있도록 JSON을 반환합니다.
- 사용자가 등록 전 확인. 목록은 항상 먼저 표시됩니다.