Initial commit
This commit is contained in:
Zhongwei Li
158
commands/analyze-dependencies.md
Normal file
158
commands/analyze-dependencies.md
Normal file
@@ -0,0 +1,158 @@
|
||||
## Dependency Analysis
|
||||
|
||||
프로젝트의 의존관계를 분석하고 아키텍처 건전성을 평가합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
/dependency-analysis [옵션]
|
||||
```
|
||||
|
||||
### 옵션
|
||||
|
||||
- `--visual` : 의존관계를 시각적으로 표시
|
||||
- `--circular` : 순환 의존만 감지
|
||||
- `--depth <숫자>` : 분석 깊이 지정(기본값: 3)
|
||||
- `--focus <경로>` : 특정 모듈/디렉토리에 집중
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 프로젝트 전체 의존관계 분석
|
||||
/dependency-analysis
|
||||
|
||||
# 순환 의존 감지
|
||||
/dependency-analysis --circular
|
||||
|
||||
# 특정 모듈의 상세 분석
|
||||
/dependency-analysis --focus src/core --depth 5
|
||||
```
|
||||
|
||||
### 분석 항목
|
||||
|
||||
#### 1. 의존관계 매트릭스
|
||||
|
||||
모듈 간 의존관계를 수치화해서 표시：
|
||||
|
||||
- 직접 의존
|
||||
- 간접 의존
|
||||
- 의존 깊이
|
||||
- 팬인/팬아웃
|
||||
|
||||
#### 2. 아키텍처 위반 감지
|
||||
|
||||
- 레이어 위반(하위층이 상위층에 의존)
|
||||
- 순환 의존
|
||||
- 과도한 결합(높은 의존도)
|
||||
- 고립된 모듈
|
||||
|
||||
#### 3. Clean Architecture 준수 체크
|
||||
|
||||
- 도메인 층의 독립성
|
||||
- 인프라 층의 적절한 분리
|
||||
- 유스케이스 층의 의존 방향
|
||||
- 인터페이스 적용 상황
|
||||
|
||||
### 출력 예시
|
||||
|
||||
```text
|
||||
의존관계 분석 리포트
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
📊 지표 개요
|
||||
├─ 총 모듈 수: 42
|
||||
├─ 평균 의존 수: 3.2
|
||||
├─ 최대 의존 깊이: 5
|
||||
└─ 순환 의존: 2 건 감지
|
||||
|
||||
⚠️ 아키텍처 위반
|
||||
├─ [HIGH] src/domain/user.js → src/infra/database.js
|
||||
│ └─ 도메인 층이 인프라 층에 직접 의존
|
||||
├─ [MED] src/api/auth.js ⟲ src/services/user.js
|
||||
│ └─ 순환 의존 감지됨
|
||||
└─ [LOW] src/utils/helper.js → 12 modules
|
||||
└─ 과도한 팬아웃
|
||||
|
||||
✅ 권장 액션
|
||||
1. UserRepository 인터페이스 도입
|
||||
2. 인증 서비스의 책임 재설계
|
||||
3. 헬퍼 함수를 기능별로 분할
|
||||
|
||||
📈 의존관계 그래프
|
||||
[시각적 의존관계 다이어그램을 ASCII 아트로 표시]
|
||||
```
|
||||
|
||||
### 고급 사용 예시
|
||||
|
||||
```bash
|
||||
# CI/CD 파이프라인에서 자동 체크
|
||||
/dependency-analysis --circular --fail-on-violation
|
||||
|
||||
# 아키텍처 규칙 정의와 검증
|
||||
/dependency-analysis --rules .architecture-rules.yml
|
||||
|
||||
# 시계열로 의존관계 변화 추적
|
||||
/dependency-analysis --compare HEAD~10
|
||||
```
|
||||
|
||||
### 설정 파일 예시 (.dependency-analysis.yml)
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: "Domain Independence"
|
||||
source: "src/domain/**"
|
||||
forbidden: ["src/infra/**", "src/api/**"]
|
||||
|
||||
- name: "API Layer Dependencies"
|
||||
source: "src/api/**"
|
||||
allowed: ["src/domain/**", "src/application/**"]
|
||||
forbidden: ["src/infra/**"]
|
||||
|
||||
thresholds:
|
||||
max_dependencies: 8
|
||||
max_depth: 4
|
||||
coupling_threshold: 0.7
|
||||
|
||||
ignore:
|
||||
- "**/test/**"
|
||||
- "**/mocks/**"
|
||||
```
|
||||
|
||||
### 통합 도구
|
||||
|
||||
- `madge` : JavaScript/TypeScript 의존관계 시각화
|
||||
- `dep-cruiser` : 의존관계 규칙 검증
|
||||
- `nx` : 모노레포 의존관계 관리
|
||||
- `plato` : 복잡도와 의존관계 통합 분석
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# package.json 을 포함한 분석
|
||||
cat package.json
|
||||
/analyze-dependencies
|
||||
"이 프로젝트의 의존관계 문제점을 분석해줘"
|
||||
|
||||
# 특정 모듈의 소스 코드와 조합
|
||||
ls -la src/core/
|
||||
/analyze-dependencies --focus src/core
|
||||
"코어 모듈의 의존관계를 상세히 평가해줘"
|
||||
|
||||
# 아키텍처 문서와의 비교
|
||||
cat docs/architecture.md
|
||||
/analyze-dependencies --visual
|
||||
"설계 문서와 구현의 차이를 확인해줘"
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
- **전제조건**: 프로젝트 루트에서 실행 필요
|
||||
- **제한사항**: 대규모 프로젝트는 분석에 시간이 걸릴 수 있습니다
|
||||
- **권장사항**: 순환 의존이 발견되면 즉시 대처를 검토하세요
|
||||
|
||||
### 베스트 프랙티스
|
||||
|
||||
1. **정기적 분석**: 주간 단위로 의존관계 건전성 체크
|
||||
2. **규칙 명문화**: 아키텍처 규칙을 설정 파일로 관리
|
||||
3. **단계적 개선**: 대규모 리팩터링을 피하고 점진적으로 개선
|
||||
4. **지표 추적**: 의존관계 복잡도를 시계열로 모니터링
|
||||
168
commands/analyze-performance.md
Normal file
168
commands/analyze-performance.md
Normal file
@@ -0,0 +1,168 @@
|
||||
## Analyze Performance
|
||||
|
||||
사용자 경험 관점에서 애플리케이션 성능을 분석하고, 최적화를 통한 체감 속도 향상을 정량화합니다. Core Web Vitals에 기반한 UX 점수를 산출하고, 우선순위가 지정된 최적화 전략을 제안합니다.
|
||||
|
||||
### UX 성능 점수
|
||||
|
||||
```text
|
||||
사용자 경험 점수: B+ (78/100)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
⏱️ Core Web Vitals
|
||||
├─ LCP (로딩): 2.3초 [좋음] 목표<2.5초 ✅
|
||||
├─ FID (반응): 95ms [좋음] 목표<100ms ✅
|
||||
├─ CLS (시각적 안정성): 0.08 [좋음] 목표<0.1 ✅
|
||||
├─ FCP (첫 렌더링): 1.8초 [좋음] 목표<1.8초 ✅
|
||||
├─ TTFB (서버): 450ms [개선 필요] 목표<200ms ⚠️
|
||||
└─ TTI (상호작용 가능): 3.5초 [개선 필요] 목표<3.8초 ⚠️
|
||||
|
||||
📊 사용자 체감 속도
|
||||
├─ 초기 표시: 2.3초 [업계 평균: 3.0초]
|
||||
├─ 페이지 전환: 1.1초 [업계 평균: 1.5초]
|
||||
├─ 검색 결과 표시: 0.8초 [업계 평균: 1.2초]
|
||||
├─ 폼 제출: 1.5초 [업계 평균: 2.0초]
|
||||
└─ 이미지 로딩: 지연 로딩 구현됨 ✅
|
||||
|
||||
😊 사용자 만족도 예측
|
||||
├─ 이탈률 예측: 12% (업계 평균: 20%)
|
||||
├─ 완료율 예측: 78% (목표: 85%)
|
||||
├─ 추천 NPS: +24 (업계 평균: +15)
|
||||
└─ 재방문율: 65% (목표: 70%)
|
||||
|
||||
📊 사용자 경험에 미치는 영향
|
||||
├─ 표시 속도 0.5초 단축 → 이탈률 -7%
|
||||
├─ 이탈률 5% 감소 → 세션 길이 +15%
|
||||
├─ 검색 개선 → 체류 시간 +15%
|
||||
└─ 전반적 UX 개선도: +25%
|
||||
|
||||
🎯 개선 기대 효과 (우선순위 순)
|
||||
├─ [P0] TTFB 개선 (CDN 도입) → LCP -0.3초 = 체감 속도 +15%
|
||||
├─ [P1] JS 번들 최적화 → TTI -0.8초 = 상호작용 시간 -20%
|
||||
├─ [P2] 이미지 최적화 (WebP) → 전송량 -40% = 로드 시간 -25%
|
||||
└─ [P3] 캐시 전략 → 재방문 시 50% 고속화
|
||||
```
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# UX 점수의 포괄적 분석
|
||||
find . -name "*.js" -o -name "*.ts" | xargs wc -l | sort -rn | head -10
|
||||
「UX 성능 점수를 산출하고 Core Web Vitals를 평가해주세요」
|
||||
|
||||
# 성능 병목 지점 검출
|
||||
grep -r "for.*await\|forEach.*await" . --include="*.js"
|
||||
「비동기 처리의 병목을 검출하고 사용자 체감에 미치는 영향을 분석해주세요」
|
||||
|
||||
# 사용자 경험에 미치는 영향 분석
|
||||
grep -r "addEventListener\|setInterval" . --include="*.js" | grep -v "removeEventListener\|clearInterval"
|
||||
「성능 문제가 사용자 경험에 미치는 영향을 분석해주세요」
|
||||
```
|
||||
|
||||
### 기본 예시
|
||||
|
||||
```bash
|
||||
# 번들 크기와 로드 시간
|
||||
npm ls --depth=0 && find ./public -name "*.js" -o -name "*.css" | xargs ls -lh
|
||||
"번들 크기와 에셋 최적화의 개선점을 특정해주세요"
|
||||
|
||||
# 데이터베이스 성능
|
||||
grep -r "SELECT\|findAll\|query" . --include="*.js" | head -20
|
||||
"데이터베이스 쿼리 최적화 포인트를 분석해주세요"
|
||||
|
||||
# 의존성의 성능 영향
|
||||
npm outdated && npm audit
|
||||
"오래된 의존성이 성능에 미치는 영향을 평가해주세요"
|
||||
```
|
||||
|
||||
### 분석 관점
|
||||
|
||||
#### 1. 코드 수준의 문제
|
||||
|
||||
- **O(n²) 알고리즘**: 비효율적인 배열 연산 검출
|
||||
- **동기 I/O**: 블로킹 처리의 특정
|
||||
- **중복 처리**: 불필요한 계산이나 요청의 삭제
|
||||
- **메모리 누수**: 이벤트 리스너와 타이머의 관리
|
||||
|
||||
#### 2. 아키텍처 수준의 문제
|
||||
|
||||
- **N+1 쿼리**: 데이터베이스 액세스 패턴
|
||||
- **캐시 부족**: 반복 계산이나 API 호출
|
||||
- **번들 크기**: 불필요한 라이브러리나 코드 분할
|
||||
- **리소스 관리**: 커넥션 풀이나 스레드 사용량
|
||||
|
||||
#### 3. 기술 부채에 의한 영향
|
||||
|
||||
- **레거시 코드**: 오래된 구현에 의한 성능 저하
|
||||
- **설계 문제**: 책임 분산 부족에 의한 높은 결합도
|
||||
- **테스트 부족**: 성능 회귀 검출 누락
|
||||
- **모니터링 부족**: 문제의 조기 발견 체제
|
||||
|
||||
### 성능 개선 ROI 매트릭스
|
||||
|
||||
```text
|
||||
개선 ROI = (시간 단축 효과 + 품질 향상) ÷ 구현 공수
|
||||
```
|
||||
|
||||
| 우선도 | 사용자 경험 향상 | 구현 난이도 | 시간 단축 효과 | 구체적 예 | 공수 | 효과 |
|
||||
| ----------------------- | ---------------- | ----------- | -------------- | ------------- | ---- | --------- |
|
||||
| **[P0] 즉시 구현** | 높음 | 낮음 | > 50% | CDN 도입 | 8h | 응답 -60% |
|
||||
| **[P1] 조기 구현 권장** | 높음 | 중간 | 20-50% | 이미지 최적화 | 16h | 로드 -30% |
|
||||
| **[P2] 계획적 구현** | 낮음 | 높음 | 10-20% | 코드 분할 | 40h | 초기 -15% |
|
||||
| **[P3] 보류/경과 관찰** | 낮음 | 낮음 | < 10% | 미세한 최적화 | 20h | 부분 -5% |
|
||||
|
||||
#### 우선도 판정 기준
|
||||
|
||||
- **P0 (즉시 구현)**: UX 향상「높음」× 난이도「낮음」= ROI 최대
|
||||
- **P1 (조기 구현)**: UX 향상「높음」× 난이도「중간」= ROI 높음
|
||||
- **P2 (계획적)**: UX 향상「낮음」× 난이도「높음」= ROI 중간
|
||||
- **P3 (보류)**: UX 향상「낮음」× 난이도「낮음」= ROI 낮음
|
||||
|
||||
### 성능 지표와 UX 개선 상관관계
|
||||
|
||||
| 지표 | 개선 폭 | 체감 속도 향상 | 사용자 만족도 | 구현 공수 |
|
||||
| ----------------------- | ------- | -------------- | -------------- | --------- |
|
||||
| **LCP (로딩)** | -0.5초 | +30% | 이탈률 -7% | 16h |
|
||||
| **FID (반응)** | -50ms | +15% | 스트레스 -20% | 8h |
|
||||
| **CLS (시각적 안정성)** | -0.05 | +10% | 오조작 -50% | 4h |
|
||||
| **TTFB (서버)** | -200ms | +25% | 체감 속도 +40% | 24h |
|
||||
| **TTI (상호작용 가능)** | -1.0초 | +35% | 완료율 +15% | 32h |
|
||||
| **번들 크기** | -30% | +20% | 첫 방문 +25% | 16h |
|
||||
|
||||
### 측정과 도구
|
||||
|
||||
#### Node.js / JavaScript
|
||||
|
||||
```bash
|
||||
# 프로파일링
|
||||
node --prof app.js
|
||||
clinic doctor -- node app.js
|
||||
|
||||
# 번들 분석
|
||||
npx webpack-bundle-analyzer
|
||||
lighthouse --chrome-flags="--headless"
|
||||
```
|
||||
|
||||
#### 데이터베이스
|
||||
|
||||
```sql
|
||||
-- 쿼리 분석
|
||||
EXPLAIN ANALYZE SELECT ...
|
||||
SHOW SLOW LOG;
|
||||
```
|
||||
|
||||
#### 프론트엔드
|
||||
|
||||
```bash
|
||||
# React 성능
|
||||
grep -r "useMemo\|useCallback" . --include="*.jsx"
|
||||
|
||||
# 리소스 분석
|
||||
find ./src -name "*.png" -o -name "*.jpg" | xargs ls -lh
|
||||
```
|
||||
|
||||
### 지속적 개선
|
||||
|
||||
- **정기 감사**: 주간 성능 테스트 실행
|
||||
- **메트릭 수집**: 응답 시간, 메모리 사용량 추적
|
||||
- **알림 설정**: 임계값 초과 시 자동 알림
|
||||
- **팀 공유**: 개선 사례와 안티패턴의 문서화
|
||||
104
commands/check-fact.md
Normal file
104
commands/check-fact.md
Normal file
@@ -0,0 +1,104 @@
|
||||
## 팩트 체크
|
||||
|
||||
프로젝트 내 코드베이스, 문서(docs/, README.md 등)를 참조하여 주어진 정보의 정확성을 확인하는 명령어입니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# 기본 사용법
|
||||
/check-fact "Flutter 앱에서 Riverpod 을 사용하고 있다"
|
||||
|
||||
# 여러 정보를 한 번에 확인
|
||||
/check-fact "이 프로젝트는 GraphQL 을 사용하고 auto_route 로 라우팅을 관리한다"
|
||||
|
||||
# 특정 기술 사양에 대한 확인
|
||||
/check-fact "인증에는 JWT 를 사용하고 Firebase Auth 는 사용하지 않는다"
|
||||
```
|
||||
|
||||
### 확인 프로세스
|
||||
|
||||
1. **정보원 우선순위**
|
||||
- 코드베이스 (가장 신뢰도 높음)
|
||||
- README.md, docs/ 내 문서
|
||||
- package.json, pubspec.yaml 등 설정 파일
|
||||
- Issue, Pull Request 토론 기록
|
||||
|
||||
2. **판정 결과 분류**
|
||||
- `✅ 맞음` - 정보가 코드베이스와 완전히 일치
|
||||
- `❌ 틀림` - 정보가 명확히 잘못됨
|
||||
- `⚠️ 부분적으로 맞음` - 부분적으로 정확하지만 불완전
|
||||
- `❓ 판단 불가` - 확인에 필요한 정보 부족
|
||||
|
||||
3. **근거 명시**
|
||||
- 해당 파일명과 라인 번호
|
||||
- 관련 코드 스니펫
|
||||
- 문서의 해당 부분
|
||||
|
||||
### 보고 형식
|
||||
|
||||
```text
|
||||
## 팩트 체크 결과
|
||||
|
||||
### 검증 대상
|
||||
"[사용자가 제공한 정보]"
|
||||
|
||||
### 결론
|
||||
[✅/❌/⚠️/❓] [판정 결과]
|
||||
|
||||
### 근거
|
||||
- **파일**: `path/to/file.dart:123`
|
||||
- **내용**: [해당 코드/문장]
|
||||
- **보충**: [추가 설명]
|
||||
|
||||
### 상세 설명
|
||||
[틀린 경우 올바른 정보 제시]
|
||||
[부분적으로 맞는 경우 부정확한 부분 지적]
|
||||
[판단 불가인 경우 부족한 정보 설명]
|
||||
```
|
||||
|
||||
### 기본 사용 예시
|
||||
|
||||
```bash
|
||||
# 프로젝트 기술 스택 확인
|
||||
/check-fact "이 앱은 Flutter + Riverpod + GraphQL 구성으로 되어있다"
|
||||
|
||||
# 구현 상태 확인
|
||||
/check-fact "다크모드 기능이 구현되어 있고 사용자 설정에서 전환 가능하다"
|
||||
|
||||
# 아키텍처 확인
|
||||
/check-fact "상태관리는 모두 Riverpod 으로 하고 BLoC 은 사용하지 않는다"
|
||||
|
||||
# 보안 구현 확인
|
||||
/check-fact "인증 토큰은 secure storage 에 암호화해서 저장한다"
|
||||
```
|
||||
|
||||
### Claude 와의 연동
|
||||
|
||||
```bash
|
||||
# 코드베이스 전체 분석 후 확인
|
||||
ls -la && find . -name "pubspec.yaml" -exec cat {} \;
|
||||
/check-fact "이 프로젝트에서 사용하는 주요 의존성은..."
|
||||
|
||||
# 특정 기능의 구현 상태 확인
|
||||
grep -r "authentication" . --include="*.dart"
|
||||
/check-fact "인증 기능은 커스텀 구현이고 써드파티 인증은 사용하지 않는다"
|
||||
|
||||
# 문서와의 일치성 확인
|
||||
cat README.md
|
||||
/check-fact "README 에 기재된 기능은 모두 구현되었다"
|
||||
```
|
||||
|
||||
### 활용 시나리오
|
||||
|
||||
- 기술 사양서 작성 시: 기재 내용의 정확성 확인
|
||||
- 프로젝트 인수인계 시: 기존 구현의 이해도 확인
|
||||
- 클라이언트 보고 전: 구현 상황의 사실 확인
|
||||
- 기술 블로그 작성 시: 글 내용의 정확성 검증
|
||||
- 면접·설명 자료 작성 시: 프로젝트 개요의 정확성 확인
|
||||
|
||||
### 주의사항
|
||||
|
||||
- 코드베이스가 가장 신뢰도 높은 정보원입니다
|
||||
- 문서가 오래된 경우 구현을 우선합니다
|
||||
- 판단에 필요한 정보가 부족한 경우 솔직히 "판단 불가"로 합니다
|
||||
- 보안 관련 정보는 특히 신중하게 검증합니다
|
||||
53
commands/check-github-ci.md
Normal file
53
commands/check-github-ci.md
Normal file
@@ -0,0 +1,53 @@
|
||||
## GitHub CI 모니터링
|
||||
|
||||
GitHub Actions CI 상황을 모니터링하고 완료까지 추적합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# CI 체크 상황 확인
|
||||
gh pr checks
|
||||
```
|
||||
|
||||
### 기본 사용 예시
|
||||
|
||||
```bash
|
||||
# PR 생성 후 CI 확인
|
||||
gh pr create --title "새 기능 추가" --body "설명"
|
||||
gh pr checks
|
||||
```
|
||||
|
||||
### Claude 와의 연동
|
||||
|
||||
```bash
|
||||
# CI 확인부터 수정까지의 흐름
|
||||
gh pr checks
|
||||
"CI 체크 결과를 분석하고, 실패 항목이 있다면 수정 방법을 제안하세요"
|
||||
|
||||
# 수정 후 재확인
|
||||
git push origin feature-branch
|
||||
gh pr checks
|
||||
"수정 후 CI 결과를 확인하고, 문제가 없는지 확인하세요"
|
||||
```
|
||||
|
||||
### 실행 결과 예시
|
||||
|
||||
```text
|
||||
All checks were successful
|
||||
0 cancelled, 0 failing, 8 successful, 3 skipped, and 0 pending checks
|
||||
|
||||
NAME DESCRIPTION ELAPSED URL
|
||||
○ Build/test (pull_request) 5m20s https://github.com/user/repo/actions/runs/123456789
|
||||
○ Build/lint (pull_request) 2m15s https://github.com/user/repo/actions/runs/123456789
|
||||
○ Security/scan (pull_request) 1m30s https://github.com/user/repo/actions/runs/123456789
|
||||
○ Type Check (pull_request) 45s https://github.com/user/repo/actions/runs/123456789
|
||||
○ Commit Messages (pull_request) 12s https://github.com/user/repo/actions/runs/123456789
|
||||
- Deploy Preview (pull_request) https://github.com/user/repo/actions/runs/123456789
|
||||
- Visual Test (pull_request) https://github.com/user/repo/actions/runs/123456789
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
- 실패 시 상세 확인
|
||||
- 모든 체크 완료 후 병합
|
||||
- 필요에 따라 `gh pr checks` 재실행
|
||||
461
commands/check-prompt.md
Normal file
461
commands/check-prompt.md
Normal file
@@ -0,0 +1,461 @@
|
||||
## 프롬프트 품질 검사
|
||||
|
||||
AI Agent 용 프롬프트의 품질을 평가·개선하기 위한 포괄적 베스트 프랙티스 모음집입니다. 실제 프롬프트 개선 프로세스에서 쌓은 지식을 체계화하고, 애매함 제거·정보 통합·강제력 강화·추적 시스템·지속적 개선 등 모든 중요 관점을 망라합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# 프롬프트 파일의 품질 체크
|
||||
cat your-prompt.md
|
||||
/check-prompt
|
||||
"이 프롬프트의 품질을 체크하고 개선안을 제시하세요"
|
||||
```
|
||||
|
||||
### 옵션
|
||||
|
||||
- 없음 : 현재 파일 또는 선택한 텍스트 분석
|
||||
- `--category <name>` : 특정 카테고리만 체크 (structure/execution/restrictions/quality/roles/improvement)
|
||||
- `--score` : 품질 점수만 산출
|
||||
- `--fix` : 검출된 문제를 자동 수정 제안
|
||||
- `--deep` : 심층 분석 모드 (애매함·정보 분산·강제력을 중점 체크)
|
||||
|
||||
### 기본 사용 예시
|
||||
|
||||
```bash
|
||||
# 프롬프트 전체 품질 평가
|
||||
cat devin/playbooks/code-review.md
|
||||
/check-prompt
|
||||
"이 프롬프트의 품질을 6 개 카테고리로 평가하고, 문제점과 개선안을 제시하세요"
|
||||
|
||||
# 심층 분석 모드
|
||||
/check-prompt --deep
|
||||
"애매함·정보 분산·강제력 부족을 중점적으로 체크하고 근본적인 개선안을 제시하세요"
|
||||
|
||||
# 특정 카테고리 체크
|
||||
/check-prompt --category structure
|
||||
"구조와 명확성 관점으로 이 프롬프트를 체크하세요"
|
||||
|
||||
# 애매한 표현 검출 및 수정
|
||||
/check-prompt --fix
|
||||
"애매한 표현을 검출하고 명확한 표현으로 수정 제안하세요"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 핵심 설계 원칙
|
||||
|
||||
### 원칙 1: 해석의 여지를 완전히 배제
|
||||
|
||||
- **절대 금지**: "원칙적으로" "권장" "가능하면" "상황에 따라" "적절히 판단"
|
||||
- **필수 사용**: "반드시" "절대로" "엄수" "예외 없이" "강제"
|
||||
- **예외 조건**: 수치로 엄격하게 한정 ("다음 3 가지 조건만" "이 2 가지 경우를 제외하고")
|
||||
|
||||
### 원칙 2: 정보의 전략적 통합
|
||||
|
||||
- 관련된 중요 정보는 하나의 섹션에 완전 통합
|
||||
- 실행 체크리스트에 전체상 요약
|
||||
- 참조의 순환이나 분산을 철저히 배제
|
||||
|
||||
### 원칙 3: 단계적 강제력 구축
|
||||
|
||||
- 🔴 (실행 중지 레벨) → 🟡 (품질 중요) → 🟢 (권장사항)의 명확한 계층
|
||||
- 권장 레벨에서 필수 레벨로의 점진적 승격
|
||||
- 위반 시 영향도와 대처법 명시
|
||||
|
||||
### 원칙 4: 추적 가능성 확보
|
||||
|
||||
- 모든 실행 결과를 기록·검증 가능
|
||||
- 허위 보고를 기술적으로 방지
|
||||
- 성공/실패의 객관적 판단 기준
|
||||
|
||||
### 원칙 5: 피드백 주도 개선
|
||||
|
||||
- 실제 실패 사례로부터 학습
|
||||
- 지속적인 효과성 검증
|
||||
- 새로운 패턴의 자동 검출
|
||||
|
||||
---
|
||||
|
||||
## 📋 포괄적 체크 항목
|
||||
|
||||
### 1. 📐 구조와 명확성 (배점: 25 점)
|
||||
|
||||
#### 1.1 지시사항 우선순위 표시 (8 점)
|
||||
|
||||
- [ ] 🔴🟡🟢 우선순위가 모든 중요 지시사항에 명시되어 있음
|
||||
- [ ] 실행 중지 레벨 조건이 구체적이고 명확하게 정의됨
|
||||
- [ ] 각 우선순위의 판단 기준이 객관적이고 검증 가능함
|
||||
- [ ] 우선순위 계층이 일관되게 적용됨
|
||||
|
||||
#### 1.2 애매한 표현의 완전 배제 (9 점)
|
||||
|
||||
- [ ] **치명적 애매 표현**: "원칙적으로" "권장" "가능하면"이 0 개
|
||||
- [ ] **강제 표현 사용**: "반드시" "절대로" "엄수" "예외 없이"를 적절히 사용
|
||||
- [ ] **예외 조건의 수치 한정**: "3 가지 조건만" 등 명확한 경계선
|
||||
- [ ] **판단 여지 배제**: 여러 해석이 불가능한 표현만 사용
|
||||
- [ ] **그레이존 박멸**: 모든 상황에서 명확한 판단 기준
|
||||
|
||||
#### 1.3 정보의 전략적 통합 (8 점)
|
||||
|
||||
- [ ] 중요 정보의 여러 곳 분산이 완전히 해소됨
|
||||
- [ ] 관련 지시사항이 논리적으로 하나의 섹션에 통합됨
|
||||
- [ ] 실행 체크리스트에 전체상이 빠짐없이 요약됨
|
||||
- [ ] 참조의 순환이나 무한 루프가 존재하지 않음
|
||||
|
||||
### 2. 🎯 실행 가능성 (배점: 20 점)
|
||||
|
||||
#### 2.1 구체적 절차의 완전성 (7 점)
|
||||
|
||||
- [ ] 모든 명령어 예시가 실제로 실행 가능하고 검증됨
|
||||
- [ ] 환경변수·전제조건·의존성이 빠짐없이 명기됨
|
||||
- [ ] 오류 시 대처법이 구체적이고 실행 가능함
|
||||
- [ ] 절차 순서가 논리적이고 필연성이 있음
|
||||
|
||||
#### 2.2 검증 가능성 확보 (7 점)
|
||||
|
||||
- [ ] 실행 결과의 성공/실패가 객관적으로 판단 가능함
|
||||
- [ ] 출력 예시·로그 형식·기대값이 구체적으로 제시됨
|
||||
- [ ] 테스트 방법·검증 절차가 구현 가능함
|
||||
- [ ] 중간 결과 확인 포인트가 적절히 배치됨
|
||||
|
||||
#### 2.3 자동화 적응성 (6 점)
|
||||
|
||||
- [ ] 스크립트화·CI/CD 통합이 용이한 형식
|
||||
- [ ] 인간 판단 부분과 AI 실행 부분의 명확한 분리
|
||||
- [ ] 배치 처리·병렬 실행 대응
|
||||
|
||||
### 3. 🚫 금지사항의 명확화 (배점: 15 점)
|
||||
|
||||
#### 3.1 절대 금지사항의 체계화 (8 점)
|
||||
|
||||
- [ ] 실행해서는 안 되는 조작의 완전한 목록화
|
||||
- [ ] 각 금지사항의 위반 시 영향도 (경미/심각/치명적) 명시
|
||||
- [ ] 대안 수단·회피 방법의 구체적 제시
|
||||
- [ ] 금지사항의 기술적 근거 설명
|
||||
|
||||
#### 3.2 예외 조건의 엄격한 한정 (7 점)
|
||||
|
||||
- [ ] 예외를 인정하는 조건이 구체적이고 한정적 (수치 지정)
|
||||
- [ ] "완전히 중복" "명시적으로 기재" 등 객관적 판단 기준
|
||||
- [ ] 그레이존을 남기지 않는 명확한 경계선
|
||||
- [ ] 예외 적용 시 추가 조건·제약 명시
|
||||
|
||||
### 4. 📊 품질 보증 메커니즘 (배점: 20 점)
|
||||
|
||||
#### 4.1 추적 시스템의 완전성 (8 점)
|
||||
|
||||
- [ ] 전체 실행 결과의 자동 기록·통계 획득 기능
|
||||
- [ ] 허위 보고를 기술적으로 방지하는 검증 기능
|
||||
- [ ] 실시간 모니터링·알림 기능
|
||||
- [ ] 감사 로그의 변조 방지 기능
|
||||
|
||||
#### 4.2 템플릿 준수의 강제 (7 점)
|
||||
|
||||
- [ ] 필수 요소의 명확한 정의와 체크 기능
|
||||
- [ ] 커스터마이즈 금지 부분의 기술적 제한
|
||||
- [ ] 준수 확인의 자동화된 체크포인트
|
||||
- [ ] 위반 시 자동 수정·경고 기능
|
||||
|
||||
#### 4.3 오류 처리의 망라성 (5 점)
|
||||
|
||||
- [ ] 예상 오류 패턴의 완전한 카탈로그화
|
||||
- [ ] 오류 시의 단계적 대처 프로세스
|
||||
- [ ] 실패를 성공으로 보고하는 것의 기술적 방지
|
||||
|
||||
### 5. 🎭 역할과 책임의 명확화 (배점: 10 점)
|
||||
|
||||
#### 5.1 AI Agent 의 권한 범위 (5 점)
|
||||
|
||||
- [ ] 실행 가능 조작과 금지 조작의 명확한 경계선
|
||||
- [ ] 판단 권한의 구체적 범위와 제약
|
||||
- [ ] 인간 확인이 필요한 조작의 명확한 분리
|
||||
|
||||
#### 5.2 분류 시스템의 통일 (5 점)
|
||||
|
||||
- [ ] 분류 정의의 명확성·유일성·배타성
|
||||
- [ ] 분류 간 중요도 오해를 방지하는 명시적 설명
|
||||
- [ ] 각 분류의 구체적 사용 예시와 판단 플로차트
|
||||
|
||||
### 6. 🔄 지속적 개선 (배점: 10 점)
|
||||
|
||||
#### 6.1 피드백 수집의 자동화 (5 점)
|
||||
|
||||
- [ ] 실행 로그로부터의 자동 개선점 추출
|
||||
- [ ] 실패 패턴의 머신러닝 기반 분석
|
||||
- [ ] 베스트 프랙티스의 자동 업데이트 메커니즘
|
||||
|
||||
#### 6.2 학습 기능의 구현 (5 점)
|
||||
|
||||
- [ ] 새로운 패턴의 자동 검출·분류
|
||||
- [ ] 기존 규칙의 효과성 지속 모니터링
|
||||
- [ ] 단계적 개선의 자동 제안
|
||||
|
||||
---
|
||||
|
||||
## 🚨 치명적 문제 패턴 (즉시 수정 요함)
|
||||
|
||||
### ❌ 레벨 1: 치명적 애매함 (실행 중지 레벨)
|
||||
|
||||
- **여러 해석 가능한 지시**: "적절히 판단해서" "상황에 따라" "원칙적으로"
|
||||
- **애매한 예외 조건**: "특별한 경우는" "필요에 따라"
|
||||
- **주관적 판단 기준**: "적절히" "충분히" "가능한 한"
|
||||
- **미정의 중요 개념**: "표준적인" "일반적인" "기본적인"
|
||||
|
||||
### ❌ 레벨 2: 구조적 결함 (품질 중요 레벨)
|
||||
|
||||
- **정보 분산**: 관련 중요 정보가 3 곳 이상에 산재
|
||||
- **순환 참조**: 섹션 A→B→C→A 의 무한 루프
|
||||
- **모순되는 지시**: 다른 섹션에서 상반되는 지시
|
||||
- **실행 순서 불명확**: 의존관계가 불분명한 절차
|
||||
|
||||
### ❌ 레벨 3: 품질 저하 (권장 개선 레벨)
|
||||
|
||||
- **검증 불가능성**: 성공/실패 판단 기준이 불명
|
||||
- **자동화 곤란**: 인간의 주관적 판단에 의존하는 설계
|
||||
- **보수 곤란**: 업데이트 시 영향 범위를 예측할 수 없는 구조
|
||||
- **학습 곤란**: 신입이 이해하기까지 오랜 시간이 걸리는 복잡함
|
||||
|
||||
---
|
||||
|
||||
## 🎯 실증된 개선 기법
|
||||
|
||||
### ✅ 단계적 강화 접근법
|
||||
|
||||
1. **현황 분석**: 문제 분류·우선순위·영향도 평가
|
||||
2. **치명적 문제 우선**: 레벨 1 문제의 완전 해결을 최우선
|
||||
3. **단계적 구현**: 한 번에 모든 변경을 하지 말고 검증 가능한 단위로 실시
|
||||
4. **효과 측정**: 개선 전후의 정량적 비교
|
||||
5. **지속적 모니터링**: 개선 효과의 지속성 확인
|
||||
|
||||
### ✅ 애매함 제거의 실천 기법
|
||||
|
||||
```markdown
|
||||
# ❌ 개선 전 (애매함)
|
||||
|
||||
"지적사항은 원칙적으로 GitHub 상의 해당 변경 부분에 인라인 코멘트로 작성하세요"
|
||||
|
||||
# ✅ 개선 후 (명확함)
|
||||
|
||||
"지적사항은 GitHub 상의 해당 변경 부분에 인라인 코멘트로 반드시 작성하세요. 예외는 섹션 3.3 에서 정의된 3 가지 조건만입니다"
|
||||
```
|
||||
|
||||
### ✅ 정보 통합의 실천 기법
|
||||
|
||||
```markdown
|
||||
# ❌ 개선 전 (분산)
|
||||
|
||||
섹션 2.1: "필수 6 섹션 사용"
|
||||
섹션 3.5: "📊 종합평가, 📋 지적사항..."
|
||||
섹션 4.2: "섹션 삭제 금지"
|
||||
|
||||
# ✅ 개선 후 (통합)
|
||||
|
||||
실행 체크리스트:
|
||||
□ 10. 요약 코멘트를 투고 (필수 6 섹션 사용)
|
||||
🔴 필수 6 섹션: 1) 📊 종합평가 2) 📋 지적사항의 분류별 집계 3) ⚠️ 주요 우려사항 4) ✅ 평가할 수 있는 점 5) 🎯 결론 6) 🤖 AI 리뷰 품질의 자기평가
|
||||
❌ 절대 금지: 섹션 삭제·추가·이름 변경
|
||||
```
|
||||
|
||||
### ✅ 추적 시스템의 구현 패턴
|
||||
|
||||
```bash
|
||||
# 실행 결과의 엄격한 추적
|
||||
POSTED_COMMENTS=0
|
||||
FAILED_COMMENTS=0
|
||||
TOTAL_COMMENTS=0
|
||||
|
||||
# 각 조작의 결과 기록
|
||||
if [ $? -eq 0 ]; then
|
||||
echo "✅ 성공: $OPERATION" >> /tmp/execution_log.txt
|
||||
POSTED_COMMENTS=$((POSTED_COMMENTS + 1))
|
||||
else
|
||||
echo "❌ 실패: $OPERATION" >> /tmp/execution_log.txt
|
||||
FAILED_COMMENTS=$((FAILED_COMMENTS + 1))
|
||||
fi
|
||||
|
||||
# 허위 보고 방지
|
||||
if [ $POSTED_COMMENTS -ne $REPORTED_COMMENTS ]; then
|
||||
echo "🚨 경고: 보고 수와 실제 투고 수가 불일치"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📈 품질 점수 계산 (개선판)
|
||||
|
||||
### 종합 점수 산출
|
||||
|
||||
```text
|
||||
기본 점수 = Σ(각 카테고리 점수 × 배점) / 100
|
||||
|
||||
치명적 문제 페널티:
|
||||
- 레벨 1 문제: -20 점/건
|
||||
- 레벨 2 문제: -10 점/건
|
||||
- 레벨 3 문제: -5 점/건
|
||||
|
||||
보너스 요소:
|
||||
- 자동화 대응: +5 점
|
||||
- 학습 기능 구현: +5 점
|
||||
- 실증된 개선 사례: +5 점
|
||||
|
||||
최종 점수 = 기본 점수 + 보너스 - 페널티
|
||||
```
|
||||
|
||||
### 품질 레벨 판정
|
||||
|
||||
```text
|
||||
95-100 점: 세계 최고 수준 (업계 표준으로 추천 가능)
|
||||
90-94 점: 우수 (프로덕션 운용 가능)
|
||||
80-89 점: 양호 (경미한 개선으로 운용 가능)
|
||||
70-79 점: 보통 (개선 필요)
|
||||
60-69 점: 개선 요망 (대폭 수정 필요)
|
||||
50-59 점: 대폭 수정 요망 (근본적 재검토 필요)
|
||||
49 점 이하: 사용 금지 (완전한 재설계 필요)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 실천적 개선 프로세스
|
||||
|
||||
### 페이즈 1: 진단·분석 (1-2 일)
|
||||
|
||||
1. **전체 구조 파악**: 섹션 구성·정보 플로·의존관계 시각화
|
||||
2. **애매함 검출**: 해석 여지가 있는 표현의 전건 추출
|
||||
3. **정보 분산 분석**: 관련 정보의 산재 패턴 매핑
|
||||
4. **강제력 평가**: 권장/필수의 분류와 실효성 평가
|
||||
5. **추적 가능성 확인**: 실행 결과의 기록·검증 기능 평가
|
||||
|
||||
### 페이즈 2: 우선순위·계획 (반나절)
|
||||
|
||||
1. **치명도 분류**: 레벨 1-3 의 문제 분류와 영향도 평가
|
||||
2. **개선 순서 결정**: 상호 의존관계를 고려한 최적 순서
|
||||
3. **리소스 배분**: 개선 효과와 비용의 균형 최적화
|
||||
4. **위험 평가**: 개선 시 부작용·호환성 문제 예측
|
||||
|
||||
### 페이즈 3: 단계적 구현 (2-5 일)
|
||||
|
||||
1. **레벨 1 문제 해결**: 치명적 애매함의 완전 배제
|
||||
2. **정보 통합 실시**: 분산 정보의 전략적 집약
|
||||
3. **강제력 강화**: 권장 → 필수로의 단계적 승격
|
||||
4. **추적 시스템 구현**: 실행 결과의 자동 기록·검증 기능
|
||||
5. **템플릿 강화**: 필수 요소의 명확화와 준수 강제
|
||||
|
||||
### 페이즈 4: 검증·조정 (1-2 일)
|
||||
|
||||
1. **기능 테스트**: 모든 변경점의 동작 확인
|
||||
2. **통합 테스트**: 시스템 전체의 정합성 확인
|
||||
3. **성능 테스트**: 실행 효율·응답 확인
|
||||
4. **사용성 테스트**: 실제 사용 시나리오에서의 검증
|
||||
|
||||
### 페이즈 5: 운영·모니터링 (지속)
|
||||
|
||||
1. **효과 측정**: 개선 전후의 정량적 비교
|
||||
2. **지속적 모니터링**: 품질 저하의 조기 검출
|
||||
3. **피드백 수집**: 실제 운영에서의 문제점 추출
|
||||
4. **최적화 지속**: 지속적인 개선 사이클
|
||||
|
||||
---
|
||||
|
||||
## 📊 실제 개선 사례 (상세판)
|
||||
|
||||
### 케이스 스터디: 대규모 프롬프트의 품질 개선
|
||||
|
||||
#### 개선 전 상황
|
||||
|
||||
```bash
|
||||
품질 점수: 70 점/100 점
|
||||
- 애매 표현: 15 곳 발견
|
||||
- 정보 분산: 6 곳에 중요 정보 산재
|
||||
- 강제력 부족: 권장 레벨 표현이 80%
|
||||
- 추적 기능: 실행 결과 기록 없음
|
||||
- 오류 처리: 실패 시 대처법 불분명
|
||||
```
|
||||
|
||||
#### 실시한 개선 내용
|
||||
|
||||
```bash
|
||||
# 1. 애매함 배제 (2 일간)
|
||||
- "원칙적으로" → "예외는 섹션 3.3 의 3 가지 조건만"
|
||||
- "권장" → "필수" (중요도 레벨 2 이상)
|
||||
- "적절히" → 구체적인 판단 기준 명시
|
||||
|
||||
# 2. 정보 통합 (1 일간)
|
||||
- 분산되었던 필수 6 섹션 정보 → 실행 체크리스트로 통합
|
||||
- 관련 금지사항 → 하나의 섹션으로 집약
|
||||
- 참조의 순환 해소 → 선형 정보 플로
|
||||
|
||||
# 3. 추적 시스템 구현 (1 일간)
|
||||
- 실행 결과의 자동 로그 기록
|
||||
- 허위 보고 방지 검증 기능
|
||||
- 실시간 통계 표시
|
||||
|
||||
# 4. 오류 처리 강화 (반나절)
|
||||
- 예상 오류 패턴의 완전한 카탈로그화
|
||||
- 단계적 대처 프로세스 명문화
|
||||
- 자동 복구 기능 구현
|
||||
```
|
||||
|
||||
#### 개선 후 결과
|
||||
|
||||
```bash
|
||||
품질 점수: 90 점/100 점 (+20 점 향상)
|
||||
- 애매 표현: 0 곳 (완전 배제)
|
||||
- 정보 통합: 중요 정보를 3 곳으로 집약
|
||||
- 강제력: 필수 레벨 표현 95%
|
||||
- 추적 기능: 완전 자동화
|
||||
- 오류 처리: 90%의 문제를 자동 해결
|
||||
|
||||
실제 개선 효과:
|
||||
- 판단 실수: 85% 감소
|
||||
- 실행 시간: 40% 단축
|
||||
- 오류 발생률: 70% 감소
|
||||
- 사용자 만족도: 95% 향상
|
||||
```
|
||||
|
||||
### 교훈·베스트 프랙티스
|
||||
|
||||
#### 성공 요인
|
||||
|
||||
1. **단계적 접근법**: 한 번에 모든 변경을 하지 말고 검증 가능한 단위로 실시
|
||||
2. **데이터 주도**: 주관적 판단이 아닌 실측 데이터기반의 개선
|
||||
3. **지속적 모니터링**: 개선 효과의 지속성을 정기적으로 확인
|
||||
4. **피드백 중시**: 실제 사용자의 의견을 적극적으로 수집
|
||||
|
||||
#### 실패 회피책
|
||||
|
||||
1. **과도한 완벽주의**: 90 점 도달로 일단 운영 시작, 지속적 개선으로 100 점 목표
|
||||
2. **일괄 변경의 위험성**: 대규모 변경은 반드시 단계적으로 실시
|
||||
3. **후방 호환성**: 기존 워크플로에 대한 영향을 최소한으로 억제
|
||||
4. **문서화 부족**: 모든 변경을 상세히 기록·공유
|
||||
|
||||
---
|
||||
|
||||
### Claude 와의 연동
|
||||
|
||||
```bash
|
||||
# 프롬프트 파일과 조합한 품질 체크
|
||||
cat your-prompt.md
|
||||
/check-prompt
|
||||
"이 프롬프트의 품질을 평가하고 개선점을 제안하세요"
|
||||
|
||||
# 여러 프롬프트 파일의 비교
|
||||
cat prompt-v1.md && echo "---" && cat prompt-v2.md
|
||||
/check-prompt
|
||||
"두 버전을 비교하고 개선된 점과 남은 과제를 분석하세요"
|
||||
|
||||
# 실제 오류 로그와 조합한 분석
|
||||
cat execution-errors.log
|
||||
/check-prompt --deep
|
||||
"이 오류를 일으켰을 가능성이 있는 프롬프트의 문제점을 파악하세요"
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
- **전제조건**: 프롬프트 파일은 Markdown 형식으로 작성되어 있을 것을 권장
|
||||
- **제한사항**: 대규모 프롬프트 (1 만 행 이상)의 경우 분할해서 분석할 것을 권장
|
||||
- **권장사항**: 정기적으로 프롬프트의 품질 체크를 수행하고 지속적으로 개선하세요
|
||||
|
||||
---
|
||||
|
||||
_이 체크리스트는 실제 프롬프트 개선 프로젝트에서 실증된 지식의 완전판이고, 지속적으로 진화하고 있습니다._
|
||||
354
commands/commit-message.md
Normal file
354
commands/commit-message.md
Normal file
@@ -0,0 +1,354 @@
|
||||
## Commit Message
|
||||
|
||||
스테이징된 변경사항(git diff --staged)에서 적절한 커밋 메시지를 생성합니다. git 명령은 실행하지 않고, 메시지 생성과 클립보드 복사만 수행합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
/commit-message [옵션]
|
||||
```
|
||||
|
||||
### 옵션
|
||||
|
||||
- `--format <형식>` : 메시지 형식 지정(conventional, gitmoji, angular)
|
||||
- `--lang <언어>` : 메시지 언어 강제 지정(en, ko)
|
||||
- `--breaking` : Breaking Change 감지 및 표시
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 스테이징된 변경사항을 기반으로 메시지 생성(언어 자동 판별)
|
||||
# 메인 후보가 자동으로 클립보드에 복사됩니다
|
||||
/commit-message
|
||||
|
||||
# 언어를 강제로 지정
|
||||
/commit-message --lang ko
|
||||
/commit-message --lang en
|
||||
|
||||
# Breaking Change 감지
|
||||
/commit-message --breaking
|
||||
```
|
||||
|
||||
### 전제 조건
|
||||
|
||||
**중요**: 이 명령어는 스테이징된 변경사항만 분석합니다. 먼저 `git add`로 변경사항을 스테이징해야 합니다.
|
||||
|
||||
```bash
|
||||
# 스테이징되지 않은 경우 경고가 표시됩니다
|
||||
$ /commit-message
|
||||
스테이징된 변경사항이 없습니다. 먼저 git add 를 실행하세요.
|
||||
```
|
||||
|
||||
### 자동 클립보드 기능
|
||||
|
||||
생성된 메인 후보는 `git commit -m "메시지"`의 완전한 형태로 자동으로 클립보드에 복사됩니다. 터미널에서 바로 붙여넣기해서 실행할 수 있습니다.
|
||||
|
||||
**구현 시 주의사항**:
|
||||
|
||||
- 커밋 명령을 `pbcopy`에 전달할 때는 메시지 출력과는 별도 프로세스로 실행할 것
|
||||
- `echo` 대신 `printf`를 사용해서 끝의 개행을 피할 것
|
||||
|
||||
### 프로젝트 규약 자동 감지
|
||||
|
||||
**중요**: 프로젝트별 규약이 있으면 그것을 우선 적용합니다.
|
||||
|
||||
#### 1. CommitLint 설정 확인
|
||||
|
||||
다음 파일에서 설정을 자동 감지：
|
||||
|
||||
- `commitlint.config.js`
|
||||
- `commitlint.config.mjs`
|
||||
- `commitlint.config.cjs`
|
||||
- `commitlint.config.ts`
|
||||
- `.commitlintrc.js`
|
||||
- `.commitlintrc.json`
|
||||
- `.commitlintrc.yml`
|
||||
- `.commitlintrc.yaml`
|
||||
- `package.json`의 `commitlint` 섹션
|
||||
|
||||
```bash
|
||||
# 설정 파일 검색
|
||||
find . -name "commitlint.config.*" -o -name ".commitlintrc.*" | head -1
|
||||
```
|
||||
|
||||
#### 2. 커스텀 타입 감지
|
||||
|
||||
프로젝트별 타입 예시：
|
||||
|
||||
```javascript
|
||||
// commitlint.config.mjs
|
||||
export default {
|
||||
extends: ["@commitlint/config-conventional"],
|
||||
rules: {
|
||||
"type-enum": [
|
||||
2,
|
||||
"always",
|
||||
[
|
||||
"feat",
|
||||
"fix",
|
||||
"docs",
|
||||
"style",
|
||||
"refactor",
|
||||
"test",
|
||||
"chore",
|
||||
"wip", // 작업중
|
||||
"hotfix", // 긴급 수정
|
||||
"release", // 릴리스
|
||||
"deps", // 의존성 업데이트
|
||||
"config", // 설정 변경
|
||||
],
|
||||
],
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
#### 3. 언어 설정 감지
|
||||
|
||||
```javascript
|
||||
// 프로젝트가 한국어 메시지를 사용하는 경우
|
||||
export default {
|
||||
rules: {
|
||||
"subject-case": [0], // 한국어 대응을 위해 비활성화
|
||||
"subject-max-length": [2, "always", 72], // 한국어는 글자수 제한 조정
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
#### 4. 기존 커밋 히스토리 분석
|
||||
|
||||
```bash
|
||||
# 최근 커밋에서 사용 패턴 학습
|
||||
git log --oneline -50 --pretty=format:"%s"
|
||||
|
||||
# 사용 타입 통계
|
||||
git log --oneline -100 --pretty=format:"%s" | \
|
||||
grep -oE '^[a-z]+(\([^)]+\))?' | \
|
||||
sort | uniq -c | sort -nr
|
||||
```
|
||||
|
||||
### 언어 자동 판별
|
||||
|
||||
다음 조건으로 자동으로 한국어/영어를 전환합니다：
|
||||
|
||||
1. **CommitLint 설정**에서 언어 설정 확인
|
||||
2. **git log 분석**을 통한 자동 판별
|
||||
3. **프로젝트 파일**의 언어 설정
|
||||
4. **변경 파일 내**의 주석・문자열 분석
|
||||
|
||||
기본값은 영어. 한국어 프로젝트로 판별되면 한국어로 생성.
|
||||
|
||||
### 메시지 형식
|
||||
|
||||
#### Conventional Commits (기본값)
|
||||
|
||||
```text
|
||||
<type>: <description>
|
||||
```
|
||||
|
||||
**중요**: 항상 1 줄 커밋 메시지를 생성합니다. 여러 줄 메시지는 생성하지 않습니다.
|
||||
|
||||
**주의**: 프로젝트별 규약이 있으면 그것을 우선합니다.
|
||||
|
||||
### 표준 타입
|
||||
|
||||
**필수 타입**:
|
||||
|
||||
- `feat`: 새로운 기능(사용자가 볼 수 있는 기능 추가)
|
||||
- `fix`: 버그 수정
|
||||
|
||||
**선택 타입**:
|
||||
|
||||
- `build`: 빌드 시스템이나 외부 의존성 변경
|
||||
- `chore`: 기타 변경사항(릴리스에 영향 없음)
|
||||
- `ci`: CI 설정 파일이나 스크립트 변경
|
||||
- `docs`: 문서만 변경
|
||||
- `style`: 코드 의미에 영향 없는 변경(공백, 포맷, 세미콜론 등)
|
||||
- `refactor`: 버그 수정이나 기능 추가 없는 코드 변경
|
||||
- `perf`: 성능 개선
|
||||
- `test`: 테스트 추가나 수정
|
||||
|
||||
### 출력 예시(영어 프로젝트)
|
||||
|
||||
```bash
|
||||
$ /commit-message
|
||||
|
||||
📝 커밋 메시지 제안
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
✨ 메인 후보:
|
||||
feat: implement JWT-based authentication system
|
||||
|
||||
📋 대안:
|
||||
1. feat: add user authentication with JWT tokens
|
||||
2. fix: resolve token validation error in auth middleware
|
||||
3. refactor: extract auth logic into separate module
|
||||
|
||||
✅ `git commit -m "feat: implement JWT-based authentication system"` 클립보드에 복사됨
|
||||
```
|
||||
|
||||
**구현 예시(수정판)**:
|
||||
|
||||
```bash
|
||||
# 커밋 명령을 먼저 클립보드에 복사(개행 없이)
|
||||
printf 'git commit -m "%s"' "$COMMIT_MESSAGE" | pbcopy
|
||||
|
||||
# 그 다음 메시지 표시
|
||||
cat << EOF
|
||||
📝 커밋 메시지 제안
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
✨ 메인 후보:
|
||||
$COMMIT_MESSAGE
|
||||
|
||||
📋 대안:
|
||||
1. ...
|
||||
2. ...
|
||||
3. ...
|
||||
|
||||
✅ \`git commit -m "$COMMIT_MESSAGE"\` 클립보드에 복사됨
|
||||
EOF
|
||||
```
|
||||
|
||||
### 출력 예시(한국어 프로젝트)
|
||||
|
||||
```bash
|
||||
$ /commit-message
|
||||
|
||||
📝 커밋 메시지 제안
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
✨ 메인 후보:
|
||||
feat: JWT 인증 시스템 구현
|
||||
|
||||
📋 대안:
|
||||
1. feat: JWT 토큰으로 사용자 인증 추가
|
||||
2. fix: 인증 미들웨어 토큰 검증 오류 해결
|
||||
3. docs: 인증 로직을 별도 모듈로 분리
|
||||
|
||||
✅ `git commit -m "feat: JWT 인증 시스템 구현"` 클립보드에 복사됨
|
||||
```
|
||||
|
||||
### 동작 개요
|
||||
|
||||
1. **분석**: `git diff --staged`의 내용 분석
|
||||
2. **생성**: 적절한 커밋 메시지 생성
|
||||
3. **복사**: 메인 후보를 자동으로 클립보드에 복사
|
||||
|
||||
**주의**: 이 명령어는 git add 나 git commit 을 실행하지 않습니다. 커밋 메시지 생성과 클립보드 복사만 수행합니다.
|
||||
|
||||
### 스마트 기능
|
||||
|
||||
#### 1. 변경 내용 자동 분류(스테이징된 파일만)
|
||||
|
||||
- 새 파일 추가 → `feat`
|
||||
- 에러 수정 패턴 → `fix`
|
||||
- 테스트 파일만 → `test`
|
||||
- 설정 파일 변경 → `chore`
|
||||
- README/docs 업데이트 → `docs`
|
||||
|
||||
#### 2. 프로젝트 규약 자동 감지
|
||||
|
||||
- `.gitmessage` 파일
|
||||
- `CONTRIBUTING.md` 내의 규약
|
||||
- 과거 커밋 히스토리 패턴
|
||||
|
||||
#### 3. 언어 판별 상세(스테이징된 변경사항만)
|
||||
|
||||
```bash
|
||||
# 판별 기준(우선순위)
|
||||
1. git diff --staged 의 내용에서 언어 판별
|
||||
2. 스테이징된 파일의 주석 분석
|
||||
3. git log --oneline -20 의 언어 분석
|
||||
4. 프로젝트의 메인 언어 설정
|
||||
```
|
||||
|
||||
#### 4. 스테이징 분석 상세
|
||||
|
||||
분석에 사용하는 정보(읽기 전용):
|
||||
|
||||
- `git diff --staged --name-only` - 변경 파일 목록
|
||||
- `git diff --staged` - 실제 변경 내용
|
||||
- `git status --porcelain` - 파일 상태
|
||||
|
||||
### Breaking Change 감지 시
|
||||
|
||||
API 의 파괴적 변경이 있는 경우：
|
||||
|
||||
**영어**:
|
||||
|
||||
```bash
|
||||
feat!: change user API response format
|
||||
|
||||
BREAKING CHANGE: user response now includes additional metadata
|
||||
```
|
||||
|
||||
또는
|
||||
|
||||
```bash
|
||||
feat(api)!: change authentication flow
|
||||
```
|
||||
|
||||
**한국어**:
|
||||
|
||||
```bash
|
||||
feat!: 사용자 API 응답 형식 변경
|
||||
|
||||
BREAKING CHANGE: 응답에 추가 메타데이터가 포함되도록 변경됨
|
||||
```
|
||||
|
||||
또는
|
||||
|
||||
```bash
|
||||
feat(api)!: 인증 플로우 변경
|
||||
```
|
||||
|
||||
### 베스트 프랙티스
|
||||
|
||||
1. **프로젝트에 맞추기**: 기존 커밋 언어를 따름
|
||||
2. **간결성**: 50 자 이내로 명확하게
|
||||
3. **일관성**: 언어를 섞지 않음(영어면 영어로 통일)
|
||||
4. **OSS**: 오픈소스라면 영어 권장
|
||||
5. **1 줄 엄수**: 항상 1 줄 커밋 메시지로 작성(자세한 설명이 필요하면 PR 에서 보충)
|
||||
|
||||
### 자주 쓰는 패턴
|
||||
|
||||
**영어**:
|
||||
|
||||
```text
|
||||
feat: add user registration endpoint
|
||||
fix: resolve memory leak in cache manager
|
||||
docs: update API documentation
|
||||
```
|
||||
|
||||
**한국어**:
|
||||
|
||||
```text
|
||||
feat: 사용자 등록 엔드포인트 추가
|
||||
fix: 캐시 매니저 메모리 누수 해결
|
||||
docs: API 문서 업데이트
|
||||
```
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# 스테이징된 변경사항과 함께 사용
|
||||
git add -p # 인터랙티브하게 스테이징
|
||||
/commit-message
|
||||
"최적의 커밋 메시지를 생성해줘"
|
||||
|
||||
# 특정 파일만 스테이징해서 분석
|
||||
git add src/auth/*.js
|
||||
/commit-message --lang en
|
||||
"인증 관련 변경에 적합한 메시지를 생성해줘"
|
||||
|
||||
# Breaking Change 감지와 대응
|
||||
git add -A
|
||||
/commit-message --breaking
|
||||
"파괴적 변경이 있으면 적절히 마킹해줘"
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
- **전제조건**: 변경사항은 먼저 `git add`로 스테이징되어야 합니다
|
||||
- **제한사항**: 스테이징되지 않은 변경사항은 분석 대상이 아닙니다
|
||||
- **권장사항**: 프로젝트의 기존 커밋 규약을 먼저 확인하세요
|
||||
50
commands/context7.md
Normal file
50
commands/context7.md
Normal file
@@ -0,0 +1,50 @@
|
||||
## Context7
|
||||
|
||||
MCP 의 Context7 로 기술 문서를 검색합니다.
|
||||
|
||||
### 사용 방법
|
||||
|
||||
```bash
|
||||
# Claude 에게 의뢰하는 형식
|
||||
「context7 에서 [검색 키워드]에 대해 검색하세요」
|
||||
```
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# React hooks 조사
|
||||
「context7 에서 React hooks 에 대해 검색하세요」
|
||||
|
||||
# 오류 해결 방법 검색
|
||||
「context7 에서 TypeScript 의 타입 오류에 대해 조사하세요」
|
||||
```
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# 기술 조사 의뢰
|
||||
「context7 에서 Rust 의 소유권 시스템에 대해 조사하고, 초보자를 위해 설명하세요」
|
||||
|
||||
# 오류 해결 의뢰
|
||||
「context7 에서 Python ImportError 의 일반적인 원인과 해결 방법을 검색하세요」
|
||||
|
||||
# 베스트 프랙티스 확인
|
||||
「context7 에서 React 성능 최적화의 베스트 프랙티스를 찾아 주세요」
|
||||
```
|
||||
|
||||
### 세부 예제
|
||||
|
||||
```bash
|
||||
# 여러 관점으로 조사
|
||||
「context7 에서 GraphQL 에 대해 다음 관점으로 조사하세요:
|
||||
1. 기본적인 개념과 REST API 와의 차이점
|
||||
2. 구현 방법과 베스트 프랙티스
|
||||
3. 자주 발생하는 문제와 해결 방법」
|
||||
|
||||
# 특정 버전이나 환경에서의 조사
|
||||
「context7 에서 Next.js 14 의 새로운 기능에 대해 검색하고, App Router 사용법을 중심으로 설명하세요」
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
Context7 에서 정보를 찾을 수 없는 경우, Claude 가 자동으로 웹 검색 등 다른 방법을 제안합니다.
|
||||
186
commands/design-patterns.md
Normal file
186
commands/design-patterns.md
Normal file
@@ -0,0 +1,186 @@
|
||||
## 디자인 패턴
|
||||
|
||||
코드베이스에 적용 가능한 디자인 패턴을 제안하고 SOLID 원칙의 준수 여부을 평가합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
/design-patterns [분석대상] [옵션]
|
||||
```
|
||||
|
||||
### 옵션
|
||||
|
||||
- `--suggest` : 적용 가능한 패턴 제안 (기본값)
|
||||
- `--analyze` : 기존 패턴의 사용 현황 분석
|
||||
- `--refactor` : 리팩터링 안 생성
|
||||
- `--solid` : SOLID 원칙 준수 여부 체크
|
||||
- `--anti-patterns` : 안티패턴 검출
|
||||
|
||||
### 기본 사용 예시
|
||||
|
||||
```bash
|
||||
# 프로젝트 전체의 패턴 분석
|
||||
/design-patterns
|
||||
|
||||
# 특정 파일에 대한 패턴 제안
|
||||
/design-patterns src/services/user.js --suggest
|
||||
|
||||
# SOLID 원칙 체크
|
||||
/design-patterns --solid
|
||||
|
||||
# 안티패턴 검출
|
||||
/design-patterns --anti-patterns
|
||||
```
|
||||
|
||||
### 분석 카테고리
|
||||
|
||||
#### 1. 생성 관련 패턴
|
||||
|
||||
- **Factory Pattern**: 객체 생성의 추상화
|
||||
- **Builder Pattern**: 복잡한 객체의 단계적 구축
|
||||
- **Singleton Pattern**: 인스턴스의 유일성 보장
|
||||
- **Prototype Pattern**: 객체의 클론 생성
|
||||
|
||||
#### 2. 구조 관련 패턴
|
||||
|
||||
- **Adapter Pattern**: 인터페이스의 변환
|
||||
- **Decorator Pattern**: 기능의 동적 추가
|
||||
- **Facade Pattern**: 복잡한 서브시스템의 단순화
|
||||
- **Proxy Pattern**: 객체에 대한 접근 제어
|
||||
|
||||
#### 3. 행동 관련 패턴
|
||||
|
||||
- **Observer Pattern**: 이벤트 통지 구현
|
||||
- **Strategy Pattern**: 알고리즘의 전환
|
||||
- **Command Pattern**: 조작의 캡슐화
|
||||
- **Iterator Pattern**: 컬렉션의 순회
|
||||
|
||||
### SOLID 원칙 체크 항목
|
||||
|
||||
```text
|
||||
S - Single Responsibility Principle (단일 책임 원칙)
|
||||
O - Open/Closed Principle (개방 폐쇄 원칙)
|
||||
L - Liskov Substitution Principle (리스코프 치환 원칙)
|
||||
I - Interface Segregation Principle (인터페이스 분리 원칙)
|
||||
D - Dependency Inversion Principle (의존성 역전 원칙)
|
||||
```
|
||||
|
||||
### 출력 예시
|
||||
|
||||
```text
|
||||
디자인 패턴 분석 리포트
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
현재 사용 중인 패턴
|
||||
├─ Observer Pattern: EventEmitter (12 곳)
|
||||
├─ Factory Pattern: UserFactory (3 곳)
|
||||
├─ Singleton Pattern: DatabaseConnection (1 곳)
|
||||
└─ Strategy Pattern: PaymentProcessor (5 곳)
|
||||
|
||||
권장 패턴
|
||||
├─ [HIGH] Repository Pattern
|
||||
│ └─ 대상: src/models/*.js
|
||||
│ └─ 이유: 데이터 접근 로직의 분리
|
||||
│ └─ 예시:
|
||||
│ class UserRepository {
|
||||
│ async findById(id) { ... }
|
||||
│ async save(user) { ... }
|
||||
│ }
|
||||
│
|
||||
├─ [MED] Command Pattern
|
||||
│ └─ 대상: src/api/handlers/*.js
|
||||
│ └─ 이유: 요청 처리의 통일화
|
||||
│
|
||||
└─ [LOW] Decorator Pattern
|
||||
└─ 대상: src/middleware/*.js
|
||||
└─ 이유: 기능 조합 개선
|
||||
|
||||
SOLID 원칙 위반
|
||||
├─ [S] UserService: 인증과 권한 관리 모두 담당
|
||||
├─ [O] PaymentGateway: 새 결제수단 추가 시 수정 필요
|
||||
├─ [D] EmailService: 구상 클래스에 직접 의존
|
||||
└─ [I] IDataStore: 사용되지 않는 메서드 포함
|
||||
|
||||
리팩터링 제안
|
||||
1. UserService 를 인증과 권한 관리로 분할
|
||||
2. PaymentStrategy 인터페이스 도입
|
||||
3. EmailService 인터페이스 정의
|
||||
4. IDataStore 를 용도별로 분리
|
||||
```
|
||||
|
||||
### 고급 사용 예시
|
||||
|
||||
```bash
|
||||
# 패턴 적용의 영향 분석
|
||||
/design-patterns --impact-analysis Repository
|
||||
|
||||
# 특정 패턴의 구현 예시 생성
|
||||
/design-patterns --generate Factory --for src/models/Product.js
|
||||
|
||||
# 패턴의 조합 제안
|
||||
/design-patterns --combine --context "API with caching"
|
||||
|
||||
# 아키텍처 패턴의 평가
|
||||
/design-patterns --architecture MVC
|
||||
```
|
||||
|
||||
### 패턴 적용 예시
|
||||
|
||||
#### Before (문제가 있는 코드)
|
||||
|
||||
```javascript
|
||||
class OrderService {
|
||||
processOrder(order, paymentType) {
|
||||
if (paymentType === "credit") {
|
||||
// 신용카드 처리
|
||||
} else if (paymentType === "paypal") {
|
||||
// PayPal 처리
|
||||
}
|
||||
// 기타 결제 방법...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### After (Strategy Pattern 적용)
|
||||
|
||||
```javascript
|
||||
// 전략 인터페이스
|
||||
class PaymentStrategy {
|
||||
process(amount) {
|
||||
throw new Error("Must implement process method");
|
||||
}
|
||||
}
|
||||
|
||||
// 구상 전략
|
||||
class CreditCardPayment extends PaymentStrategy {
|
||||
process(amount) {
|
||||
/* 구현 */
|
||||
}
|
||||
}
|
||||
|
||||
// 컨텍스트
|
||||
class OrderService {
|
||||
constructor(paymentStrategy) {
|
||||
this.paymentStrategy = paymentStrategy;
|
||||
}
|
||||
|
||||
processOrder(order) {
|
||||
this.paymentStrategy.process(order.total);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 안티패턴 검출
|
||||
|
||||
- **God Object**: 과도하게 많은 책무를 가진 클래스
|
||||
- **Spaghetti Code**: 제어 흐름이 복잡하게 얽힌 코드
|
||||
- **Copy-Paste Programming**: 중복 코드의 과도한 사용
|
||||
- **Magic Numbers**: 하드코딩된 상수
|
||||
- **Callback Hell**: 깊게 중첩된 콜백
|
||||
|
||||
### 베스트 프랙티스
|
||||
|
||||
1. **점진적 적용**: 한 번에 많은 패턴을 적용하지 않기
|
||||
2. **필요성 검증**: 패턴은 문제 해결의 수단이지 목적이 아님
|
||||
3. **팀 합의**: 패턴 적용 전에 팀에서 논의
|
||||
4. **문서화**: 적용한 패턴의 의도를 기록
|
||||
75
commands/explain-code.md
Normal file
75
commands/explain-code.md
Normal file
@@ -0,0 +1,75 @@
|
||||
## 코드 설명
|
||||
|
||||
코드의 동작을 상세히 해설합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# 파일 내용을 표시하고 Claude 에게 의뢰
|
||||
cat <file>
|
||||
"이 코드의 동작을 설명하세요"
|
||||
```
|
||||
|
||||
### 기본 사용 예시
|
||||
|
||||
```bash
|
||||
# Rust 의 소유권 이해
|
||||
cat main.rs
|
||||
"Rust 의 소유권과 라이프타임 관점으로 설명하세요"
|
||||
|
||||
# 알고리즘 해설
|
||||
grep -A 50 "quicksort" sort.rs
|
||||
"이 정렬 알고리즘의 원리와 계산 복잡도를 설명하세요"
|
||||
|
||||
# 디자인 패턴 설명
|
||||
cat factory.rs
|
||||
"사용된 디자인 패턴과 그 장점을 설명하세요"
|
||||
```
|
||||
|
||||
### Claude 와의 연동
|
||||
|
||||
```bash
|
||||
# 초보자 대상 해설
|
||||
cat complex_function.py
|
||||
"이 코드를 초보자도 이해하기 쉽게 한 줄씩 설명하세요"
|
||||
|
||||
# 성능 분석
|
||||
cat algorithm.rs
|
||||
"이 코드의 성능상 문제점과 개선안을 제시하세요"
|
||||
|
||||
# 도식 설명 포함
|
||||
cat state_machine.js
|
||||
"이 코드의 처리 흐름을 ASCII 아트 도식과 함께 설명하세요"
|
||||
|
||||
# 보안 검토
|
||||
cat auth_handler.go
|
||||
"이 코드의 보안상 우려점을 지적하세요"
|
||||
```
|
||||
|
||||
### 상세 사용 예시
|
||||
|
||||
```bash
|
||||
# 복잡한 로직 해설
|
||||
cat recursive_parser.rs
|
||||
"이 재귀 파서의 동작을 다음 관점으로 설명해주세요:
|
||||
1. 전체 처리 플로
|
||||
2. 각 함수의 역할과 책임
|
||||
3. 엣지 케이스 처리
|
||||
4. 개선 가능한 점"
|
||||
|
||||
# 비동기 처리 해설
|
||||
cat async_handler.ts
|
||||
"이 비동기 처리에 대해 다음을 설명해주세요:
|
||||
1. Promise 체인의 흐름
|
||||
2. 에러 핸들링 메커니즘
|
||||
3. 병렬 처리 여부
|
||||
4. 데드락 가능성"
|
||||
|
||||
# 아키텍처 설명
|
||||
ls -la src/ && cat src/main.rs src/lib.rs
|
||||
"이 프로젝트의 아키텍처와 모듈 구성을 설명하세요"
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
코드 해설에서는 단순히 동작을 설명하는 것뿐만 아니라, 왜 그러한 구현이 되었는지, 어떤 장점이 있는지, 잠재적 문제점은 무엇인지 등 깊이 있는 통찰도 제공합니다.
|
||||
311
commands/fix-error.md
Normal file
311
commands/fix-error.md
Normal file
@@ -0,0 +1,311 @@
|
||||
## Error Fix
|
||||
|
||||
에러 메시지에서 근본 원인을 파악하고, 해결 시간을 예측하여 검증된 해결책을 제안합니다. 유사 에러의 패턴을 학습하여 즉시 적절한 대처법을 제시합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
/fix-error [옵션]
|
||||
```
|
||||
|
||||
### 옵션
|
||||
|
||||
- 없음 : 표준 에러 분석
|
||||
- `--deep` : 심층 분석 모드(의존성・환경 요인 포함)
|
||||
- `--preventive` : 예방책 중심 분석
|
||||
- `--quick` : 즉시 적용 가능한 수정만 제시
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 표준 에러 분석
|
||||
npm run build 2>&1
|
||||
/fix-error
|
||||
"빌드 에러를 분석해서 수정 방법을 제시해줘"
|
||||
|
||||
# 심층 분석 모드
|
||||
python app.py 2>&1
|
||||
/fix-error --deep
|
||||
"에러의 근본 원인을 환경 요인까지 포함해서 분석해줘"
|
||||
|
||||
# 즉시 수정 중심
|
||||
cargo test 2>&1
|
||||
/fix-error --quick
|
||||
"바로 적용할 수 있는 수정 방법을 제시해줘"
|
||||
|
||||
# 예방책 중심
|
||||
./app 2>&1 | tail -50
|
||||
/fix-error --preventive
|
||||
"에러 수정과 향후 예방책을 제시해줘"
|
||||
```
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# 에러 로그 분석
|
||||
cat error.log
|
||||
/fix-error
|
||||
"에러의 근본 원인을 파악하고 수정 방법을 제안해줘"
|
||||
|
||||
# 테스트 실패 해결
|
||||
npm test 2>&1
|
||||
/fix-error --quick
|
||||
"실패한 테스트를 분석하고 즉시 적용 가능한 수정안을 제시해줘"
|
||||
|
||||
# 스택 트레이스 해석
|
||||
python script.py 2>&1
|
||||
/fix-error --deep
|
||||
"이 스택 트레이스에서 문제 지점을 파악하고 환경 요인까지 포함해서 분석해줘"
|
||||
|
||||
# 여러 에러를 한번에 해결
|
||||
grep -E "ERROR|WARN" app.log | tail -20
|
||||
/fix-error
|
||||
"이 에러와 경고를 우선순위별로 분류하고 각각의 해결 방법을 제안해줘"
|
||||
```
|
||||
|
||||
### 에러 해결 시간 예측
|
||||
|
||||
```text
|
||||
🚀 즉시 수정(5 분 이내)
|
||||
├─ 오타, import 누락
|
||||
├─ 환경 변수 미설정
|
||||
├─ 미정의 변수 참조
|
||||
└─ 예측 시간: 2-5 분
|
||||
|
||||
⚡ 빠른 수정(30 분 이내)
|
||||
├─ 의존성 불일치
|
||||
├─ 설정 파일 에러
|
||||
├─ 타입 불일치
|
||||
└─ 예측 시간: 10-30 분
|
||||
|
||||
🔧 조사 필요(2 시간 이내)
|
||||
├─ 복잡한 로직 에러
|
||||
├─ 비동기 처리 경합
|
||||
├─ API 통합 문제
|
||||
└─ 예측 시간: 30 분-2 시간
|
||||
|
||||
🔬 심층 분석(반나절 이상)
|
||||
├─ 아키텍처 기인
|
||||
├─ 다중 시스템 연계
|
||||
├─ 성능 저하
|
||||
└─ 예측 시간: 4 시간-며칠
|
||||
```
|
||||
|
||||
### 유사 에러 패턴 DB
|
||||
|
||||
```text
|
||||
빈발 에러와 즉시 해결책
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
📊 "Cannot read property 'X' of undefined/null" (빈도: 극고)
|
||||
├─ 주요 원인: 객체의 null 체크 부족
|
||||
├─ 해결 시간: 5-10 분
|
||||
└─ 대처법: Optional chaining (?.) 또는 null 체크 추가
|
||||
|
||||
📊 "ECONNREFUSED" / "ENOTFOUND" (빈도: 고)
|
||||
├─ 주요 원인: 서비스 미기동 또는 URL 설정 오류
|
||||
├─ 해결 시간: 5-15 분
|
||||
└─ 대처법: 서비스 기동 확인, 환경 변수 체크
|
||||
|
||||
📊 "Module not found" / "Cannot resolve" (빈도: 고)
|
||||
├─ 주요 원인: 패키지 미설치, 경로 지정 오류
|
||||
├─ 해결 시간: 2-5 분
|
||||
└─ 대처법: npm install 실행, 상대 경로 확인
|
||||
|
||||
📊 "Unexpected token" / "SyntaxError" (빈도: 중)
|
||||
├─ 주요 원인: 괄호・인용부호 불일치, 예약어 사용
|
||||
├─ 해결 시간: 2-10 분
|
||||
└─ 대처법: 신택스 하이라이트 확인, Linter 실행
|
||||
|
||||
📊 "CORS policy" / "Access-Control-Allow-Origin" (빈도: 중)
|
||||
├─ 주요 원인: 서버 측 CORS 설정 부족
|
||||
├─ 해결 시간: 15-30 분
|
||||
└─ 대처법: 서버 CORS 설정, 프록시 설정
|
||||
|
||||
📊 "Maximum call stack size exceeded" (빈도: 저)
|
||||
├─ 주요 원인: 무한 루프・재귀, 순환 참조
|
||||
├─ 해결 시간: 30 분-2 시간
|
||||
└─ 대처법: 재귀 종료 조건 확인, 순환 참조 해소
|
||||
```
|
||||
|
||||
### 에러 분석의 우선순위 매트릭스
|
||||
|
||||
| 우선순위 | 아이콘 | 영향 범위 | 해결 난이도 | 대응 기한 | 설명 |
|
||||
| ----------------- | ------------ | --------- | ----------- | ---------------- | ----------------------------------- |
|
||||
| **Critical** | 🔴 긴급 대응 | 넓음 | 낮음 | 15 분 이내 착수 | 시스템 전체 정지, 데이터 손실 위험 |
|
||||
| **High Priority** | 🟠 조기 대응 | 넓음 | 높음 | 1 시간 이내 착수 | 주요 기능 정지, 다수 사용자 영향 |
|
||||
| **Medium** | 🟡 계획 대응 | 좁음 | 높음 | 당일 중 대응 | 일부 기능 제한, 회피책 있음 |
|
||||
| **Low** | 🟢 경과 관찰 | 좁음 | 낮음 | 다음 수정 시 | 경미한 불량, UX 에 미치는 영향 적음 |
|
||||
|
||||
### 분석 프로세스
|
||||
|
||||
#### Phase 1: 에러 정보 수집
|
||||
|
||||
```bash
|
||||
🔴 필수 실행:
|
||||
- 에러 메시지의 완전한 취득
|
||||
- 스택 트레이스 확인
|
||||
- 발생 조건 파악(재현 가능성)
|
||||
|
||||
🟡 조기 실행:
|
||||
- 환경 정보 수집(OS, 버전, 의존관계)
|
||||
- 직전 변경 이력(git log, 최근 커밋)
|
||||
- 관련 로그 확인
|
||||
|
||||
🟢 추가 실행:
|
||||
- 시스템 리소스 상황
|
||||
- 네트워크 상태
|
||||
- 외부 서비스 상태
|
||||
```
|
||||
|
||||
#### Phase 2: 근본 원인 분석
|
||||
|
||||
1. **표면적 증상 정리**
|
||||
- 에러 메시지의 정확한 내용
|
||||
- 발생 타이밍과 패턴
|
||||
- 영향 범위 파악
|
||||
|
||||
2. **심층 원인 파악**
|
||||
- 5 Whys 분석의 적용
|
||||
- 의존관계 추적
|
||||
- 환경 차이 확인
|
||||
|
||||
3. **가설 검증**
|
||||
- 최소 재현 코드 작성
|
||||
- 격리 테스트 실행
|
||||
- 원인 좁혀가기
|
||||
|
||||
#### Phase 3: 해결책 구현
|
||||
|
||||
```bash
|
||||
🔴 즉시 대처(핫픽스):
|
||||
- 증상을 억제하는 최소한의 수정
|
||||
- 임시 회피책 적용
|
||||
- 긴급 배포 준비
|
||||
|
||||
🟡 근본적 해결:
|
||||
- 원인에 대한 본질적 수정
|
||||
- 테스트 케이스 추가
|
||||
- 문서 업데이트
|
||||
|
||||
🟢 예방책 구현:
|
||||
- 에러 핸들링 강화
|
||||
- 모니터링・알림 설정
|
||||
- CI/CD 파이프라인 개선
|
||||
```
|
||||
|
||||
### 출력 예시
|
||||
|
||||
```text
|
||||
🚨 에러 분석 리포트
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
📍 에러 개요
|
||||
├─ 종류: [컴파일/런타임/논리/환경]
|
||||
├─ 긴급도: 🔴 높음 / 🟡 중간 / 🟢 낮음
|
||||
├─ 영향 범위: [기능명/컴포넌트]
|
||||
└─ 재현성: [100% / 간헐적 / 특정 조건]
|
||||
|
||||
🔍 근본 원인
|
||||
├─ 직접 원인: [구체적인 원인]
|
||||
├─ 배경 요인: [환경/설정/의존관계]
|
||||
└─ 트리거: [발생 조건]
|
||||
|
||||
💡 해결책
|
||||
🔴 즉시 대처:
|
||||
1. [구체적인 수정 명령/코드]
|
||||
2. [임시 회피책]
|
||||
|
||||
🟡 근본적 해결:
|
||||
1. [본질적인 수정 방법]
|
||||
2. [필요한 리팩터링]
|
||||
|
||||
🟢 예방책:
|
||||
1. [에러 핸들링 개선]
|
||||
2. [테스트 추가]
|
||||
3. [모니터링 설정]
|
||||
|
||||
📝 검증 절차
|
||||
1. [수정 적용 후 확인 방법]
|
||||
2. [테스트 실행 명령]
|
||||
3. [동작 확인 항목]
|
||||
```
|
||||
|
||||
### 에러 타입별 분석 기법
|
||||
|
||||
#### 컴파일/빌드 에러
|
||||
|
||||
```bash
|
||||
# TypeScript 타입 에러
|
||||
필수 확인(높음):
|
||||
- tsconfig.json 설정
|
||||
- 타입 정의 파일(.d.ts)의 존재
|
||||
- import 문의 정확성
|
||||
|
||||
# Rust 라이프타임 에러
|
||||
필수 확인(높음):
|
||||
- 소유권 이동
|
||||
- 참조의 유효 기간
|
||||
- 가변성 충돌
|
||||
```
|
||||
|
||||
#### 런타임 에러
|
||||
|
||||
```bash
|
||||
# Null/Undefined 참조
|
||||
필수 확인(높음):
|
||||
- 옵셔널 체이닝 부족
|
||||
- 초기화 타이밍
|
||||
- 비동기 처리의 완료 대기
|
||||
|
||||
# 메모리 관련 에러
|
||||
필수 확인(높음):
|
||||
- 힙 덤프 취득
|
||||
- GC 로그 분석
|
||||
- 순환 참조 감지
|
||||
```
|
||||
|
||||
#### 의존관계 에러
|
||||
|
||||
```bash
|
||||
# 버전 충돌
|
||||
필수 확인(높음):
|
||||
- lock 파일의 정합성
|
||||
- peer dependencies 요건
|
||||
- 전이적 의존관계
|
||||
|
||||
# 모듈 해결 에러
|
||||
필수 확인(높음):
|
||||
- NODE_PATH 설정
|
||||
- 경로 별칭 설정
|
||||
- 심볼릭 링크
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
- **절대 금지**: 에러 메시지의 일부만으로 판단, 검증 없이 Stack Overflow 해결책 적용
|
||||
- **예외 조건**: 임시 회피책은 다음 3 가지 조건에서만 허용
|
||||
1. 프로덕션 환경의 긴급 대응(24 시간 이내에 근본 해결 필수)
|
||||
2. 외부 서비스 장애(복구 대기 중의 대체 수단)
|
||||
3. 알려진 프레임워크 버그(수정 버전 릴리스 대기)
|
||||
- **권장사항**: 근본 원인의 파악을 최우선으로 하고 표면적 수정을 회피
|
||||
|
||||
### 베스트 프랙티스
|
||||
|
||||
1. **완전한 정보 수집**: 에러 메시지의 처음부터 끝까지 확인
|
||||
2. **재현성 확인**: 최소 재현 코드 작성을 최우선
|
||||
3. **단계적 어프로치**: 작은 수정부터 시작해서 검증
|
||||
4. **문서화**: 해결 과정을 기록해서 지식 공유
|
||||
|
||||
#### 자주 하는 실수
|
||||
|
||||
- **증상에 대한 대처**: 근본 원인을 놓치는 표면적 수정
|
||||
- **과도한 일반화**: 특정 케이스의 해결책을 광범위하게 적용
|
||||
- **검증 생략**: 수정 후의 부작용을 확인하지 않음
|
||||
- **지식의 속인화**: 해결 방법을 문서화하지 않음
|
||||
|
||||
### 관련 명령어
|
||||
|
||||
- `/design-patterns` : 코드 구조의 문제를 분석해서 패턴 제안
|
||||
- `/tech-debt` : 기술적 부채의 관점에서 에러의 근본 원인을 분석
|
||||
- `/analyzer` : 더 깊은 근본 원인 분석이 필요한 경우
|
||||
314
commands/multi-role.md
Normal file
314
commands/multi-role.md
Normal file
@@ -0,0 +1,314 @@
|
||||
## Multi Role
|
||||
|
||||
여러 역할로 동일한 대상을 병렬 분석하여 통합 보고서를 생성하는 명령어입니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
/multi-role <역할 1>,<역할 2> [--agent|-a] [분석 대상]
|
||||
/multi-role <역할 1>,<역할 2>,<역할 3> [--agent|-a] [분석 대상]
|
||||
```
|
||||
|
||||
### 사용 가능한 역할
|
||||
|
||||
#### 전문 분석 역할
|
||||
|
||||
- `security` : 보안 감사 전문가
|
||||
- `performance` : 성능 최적화 전문가
|
||||
- `analyzer` : 근본 원인 분석 전문가
|
||||
- `frontend` : 프론트엔드·UI/UX 전문가
|
||||
- `mobile` : 모바일 개발 전문가
|
||||
- `backend` : 백엔드·서버사이드 전문가
|
||||
|
||||
#### 개발 지원 역할
|
||||
|
||||
- `reviewer` : 코드 리뷰 전문가
|
||||
- `architect` : 시스템 아키텍트
|
||||
- `qa` : 테스트 엔지니어
|
||||
|
||||
**중요**:
|
||||
|
||||
- `--agent` 옵션은 역할 지정 직후에 배치하세요
|
||||
- 메시지는 `--agent` 뒤에 작성하세요
|
||||
- 올바른 예: `/multi-role qa,architect --agent 계획을 평가하세요`
|
||||
- 잘못된 예: `/multi-role qa,architect 계획을 평가하세요 --agent`
|
||||
|
||||
### 옵션
|
||||
|
||||
- `--agent` 또는 `-a` : 각 역할을 서브에이전트로 병렬 실행 (대규모 분석 시 권장)
|
||||
- 이 옵션을 사용하면 각 역할의 description 에 자동 위임 촉진 문구("use PROACTIVELY" 등)가 포함된 경우, 더 적극적인 자동 위임이 활성화됩니다
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 보안과 성능 양면 분석 (일반)
|
||||
/multi-role security,performance
|
||||
「이 API 엔드포인트를 평가하세요」
|
||||
|
||||
# 대규모 시스템의 병렬 분석 (서브에이전트)
|
||||
/multi-role security,performance --agent
|
||||
「시스템 전체의 보안과 성능을 포괄적으로 분석」
|
||||
|
||||
# 프론트엔드·모바일·성능의 통합 분석
|
||||
/multi-role frontend,mobile,performance
|
||||
「이 화면의 최적화 방안을 검토하세요」
|
||||
|
||||
# 아키텍처 설계의 다각적 평가 (서브에이전트)
|
||||
/multi-role architect,security,performance --agent
|
||||
「마이크로서비스화 설계를 평가하세요」
|
||||
```
|
||||
|
||||
### 분석 프로세스
|
||||
|
||||
### Phase 1: 병렬 분석
|
||||
|
||||
각 역할이 독립적으로 동일한 대상을 분석
|
||||
|
||||
- 전문 관점으로의 평가 실행
|
||||
- 역할별 고유 기준으로 판정
|
||||
- 독립적인 권장사항 생성
|
||||
|
||||
### Phase 2: 통합 분석
|
||||
|
||||
결과를 구조화하여 통합
|
||||
|
||||
- 각 역할의 평가 결과 정리
|
||||
- 중복·모순점 식별
|
||||
- 보완 관계 명확화
|
||||
|
||||
### Phase 3: 통합 보고서
|
||||
|
||||
최종적인 권장사항 생성
|
||||
|
||||
- 우선순위가 부여된 액션 플랜
|
||||
- 트레이드오프 명시
|
||||
- 구현 로드맵 제시
|
||||
|
||||
### 출력 형식 예제
|
||||
|
||||
### 2 역할 분석의 경우
|
||||
|
||||
```text
|
||||
멀티역할 분석: Security + Performance
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
분석 대상: API 엔드포인트 /api/users
|
||||
|
||||
Security 분석 결과:
|
||||
인증: JWT 검증이 적절히 구현됨
|
||||
인가: 역할 기반 접근 제어가 불완전함
|
||||
암호화: API 키가 평문으로 로그 출력됨
|
||||
|
||||
평가 점수: 65/100
|
||||
중요도: High (기밀 데이터 접근을 위해)
|
||||
|
||||
Performance 분석 결과:
|
||||
응답 시간: 평균 180ms (목표 200ms 이내)
|
||||
데이터베이스 쿼리: N+1 문제 검출됨
|
||||
캐시: Redis 캐시 미구현
|
||||
|
||||
평가 점수: 70/100
|
||||
중요도: Medium (현재 상태는 허용 범위 내)
|
||||
|
||||
상호 관련 분석:
|
||||
시너지 효과의 기회:
|
||||
- Redis 캐시 구현 시 암호화도 동시 고려
|
||||
- 로그 출력 개선으로 보안 + 성능 향상
|
||||
|
||||
트레이드오프 포인트:
|
||||
- 인가 체크 강화 ↔ 응답 시간에 미치는 영향
|
||||
- 로그 암호화 ↔ 디버그 효율성 저하
|
||||
|
||||
통합 우선순위:
|
||||
Critical: API 키 평문 출력 수정
|
||||
High: N+1 쿼리 해결
|
||||
Medium: Redis 캐시 + 암호화 구현
|
||||
Low: 인가 제어 상세화
|
||||
|
||||
구현 로드맵:
|
||||
1 주차: API 키 마스킹 구현
|
||||
2 주차: 데이터베이스 쿼리 최적화
|
||||
3-4 주차: 캐시 레이어 설계·구현
|
||||
2 개월차: 인가 제어의 단계적 강화
|
||||
```
|
||||
|
||||
### 3 역할 분석의 경우
|
||||
|
||||
```text
|
||||
멀티역할 분석: Frontend + Mobile + Performance
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
분석 대상: 사용자 프로필 화면
|
||||
|
||||
Frontend 분석 결과:
|
||||
사용성: 직관적인 레이아웃
|
||||
접근성: WCAG 2.1 준수율 85%
|
||||
반응형: 태블릿 표시에 과제 있음
|
||||
|
||||
Mobile 분석 결과:
|
||||
터치 타겟: 44pt 이상 확보
|
||||
한 손 조작: 중요 버튼이 상단에 배치됨
|
||||
오프라인 대응: 미구현
|
||||
|
||||
Performance 분석 결과:
|
||||
초기 표시: LCP 2.1 초 (양호)
|
||||
이미지 최적화: WebP 미지원
|
||||
지연 로딩: 미구현
|
||||
|
||||
통합 권장사항:
|
||||
1. 모바일 최적화 (한 손 조작 + 오프라인 대응)
|
||||
2. 이미지 최적화 (WebP + 지연 로딩)
|
||||
3. 태블릿 UI 개선
|
||||
|
||||
우선순위: Mobile > Performance > Frontend
|
||||
구현 기간: 3-4 주
|
||||
```
|
||||
|
||||
### 효과적인 조합 패턴
|
||||
|
||||
### 보안 중심
|
||||
|
||||
```bash
|
||||
/multi-role security,architect
|
||||
「인증 시스템 설계」
|
||||
|
||||
/multi-role security,frontend
|
||||
「로그인 화면의 보안」
|
||||
|
||||
/multi-role security,mobile
|
||||
「모바일 앱의 데이터 보호」
|
||||
```
|
||||
|
||||
### 성능 중심
|
||||
|
||||
```bash
|
||||
/multi-role performance,architect
|
||||
「확장성 설계」
|
||||
|
||||
/multi-role performance,frontend
|
||||
「웹 페이지 고속화」
|
||||
|
||||
/multi-role performance,mobile
|
||||
「앱 동작 최적화」
|
||||
```
|
||||
|
||||
### 사용자 경험 중심
|
||||
|
||||
```bash
|
||||
/multi-role frontend,mobile
|
||||
「크로스 플랫폼 UI」
|
||||
|
||||
/multi-role frontend,performance
|
||||
「UX 와 성능의 균형」
|
||||
|
||||
/multi-role mobile,performance
|
||||
「모바일 UX 최적화」
|
||||
```
|
||||
|
||||
### 포괄적 분석
|
||||
|
||||
```bash
|
||||
/multi-role architect,security,performance
|
||||
「시스템 전체 평가」
|
||||
|
||||
/multi-role frontend,mobile,performance
|
||||
「사용자 경험의 종합 평가」
|
||||
|
||||
/multi-role security,performance,mobile
|
||||
「모바일 앱의 종합 진단」
|
||||
```
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# 파일 분석 및 조합
|
||||
cat src/components/UserProfile.tsx
|
||||
/multi-role frontend,mobile
|
||||
「이 컴포넌트를 여러 관점으로 평가하세요」
|
||||
|
||||
# 설계 문서 평가
|
||||
cat architecture-design.md
|
||||
/multi-role architect,security,performance
|
||||
「이 설계를 여러 전문 분야에서 평가하세요」
|
||||
|
||||
# 에러 분석
|
||||
cat performance-issues.log
|
||||
/multi-role performance,analyzer
|
||||
「성능 문제를 다각적으로 분석하세요」
|
||||
```
|
||||
|
||||
### multi-role vs role-debate 사용 구분
|
||||
|
||||
### multi-role 을 사용할 때
|
||||
|
||||
- 각 전문 분야의 독립적인 평가가 필요한 경우
|
||||
- 통합적인 개선 계획을 세우고 싶은 경우
|
||||
- 모순이나 중복을 정리하고 싶은 경우
|
||||
- 구현 우선순위를 정하고 싶은 경우
|
||||
|
||||
### role-debate 를 사용할 때
|
||||
|
||||
- 전문 분야 간 트레이드오프가 있는 경우
|
||||
- 기술 선정에서 의견이 갈릴 것 같은 경우
|
||||
- 설계 방침을 토론으로 정하고 싶은 경우
|
||||
- 다양한 관점의 토론을 듣고 싶은 경우
|
||||
|
||||
### 서브에이전트 병렬 실행 (--agent)
|
||||
|
||||
`--agent` 옵션을 사용하면 각 역할이 독립된 서브에이전트로 병렬 실행됩니다.
|
||||
|
||||
#### 자동 위임의 촉진
|
||||
|
||||
역할 파일의 description 필드에 다음과 같은 문구가 포함된 경우, `--agent` 사용 시 더 적극적인 자동 위임이 활성화됩니다:
|
||||
|
||||
- "use PROACTIVELY"
|
||||
- "MUST BE USED"
|
||||
- 기타 강조 표현
|
||||
|
||||
#### 실행 플로우
|
||||
|
||||
```text
|
||||
일반 실행:
|
||||
역할 1 → 역할 2 → 역할 3 → 통합
|
||||
(순차 실행, 약 3-5 분)
|
||||
|
||||
--agent 실행:
|
||||
역할 1 ─┐
|
||||
역할 2 ─┼→ 통합
|
||||
역할 3 ─┘
|
||||
(병렬 실행, 약 1-2 분)
|
||||
```
|
||||
|
||||
#### 효과적인 사용 예제
|
||||
|
||||
```bash
|
||||
# 대규모 시스템의 종합 평가
|
||||
/multi-role architect,security,performance,qa --agent
|
||||
「신규 시스템을 포괄적으로 평가」
|
||||
|
||||
# 다중 관점의 상세 분석
|
||||
/multi-role frontend,mobile,performance --agent
|
||||
「전체 화면의 UX 최적화 분석」
|
||||
```
|
||||
|
||||
#### 성능 비교
|
||||
|
||||
| 역할 수 | 일반 실행 | --agent 실행 | 단축률 |
|
||||
| ------- | --------- | ------------ | ------ |
|
||||
| 2 역할 | 2-3 분 | 1 분 | 50% |
|
||||
| 3 역할 | 3-5 분 | 1-2 분 | 60% |
|
||||
| 4 역할 | 5-8 분 | 2-3 분 | 65% |
|
||||
|
||||
### 주의사항
|
||||
|
||||
- 3 개 이상의 역할을 동시 실행하면 출력이 길어집니다
|
||||
- 복잡한 분석일수록 실행 시간이 길어질 수 있습니다
|
||||
- 상호 모순되는 권장사항이 나온 경우 role-debate 도 검토하세요
|
||||
- 최종적인 판단은 통합 결과를 참고하여 사용자가 수행하세요
|
||||
- **--agent 사용 시**: 더 많은 리소스를 사용하지만, 대규모 분석에서는 효율적입니다
|
||||
|
||||
### 롤 설정 상세
|
||||
|
||||
- 각 롤의 상세 설정·전문 지식·토론 특성은 `.claude/agents/roles/` 디렉터리에 정의되어 있습니다
|
||||
- Evidence-First 기법과 인지 편향 대응이 포함되어 있습니다
|
||||
- 롤별 트리거 문구가 입력되면 자동으로 특화 모드가 활성화됩니다
|
||||
134
commands/plan.md
Normal file
134
commands/plan.md
Normal file
@@ -0,0 +1,134 @@
|
||||
## 계획 수립
|
||||
|
||||
구현 전 계획 수립 모드를 시작해서 상세한 구현 전략을 수립합니다. 코드 구현 전에 구조화된 계획을 세움으로써 효율적인 개발을 지원합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# Claude 에게 Plan Mode 의뢰
|
||||
"[구현 내용] 구현 계획을 세워주세요"
|
||||
```
|
||||
|
||||
### 기본 사용 예시
|
||||
|
||||
```bash
|
||||
# 새 기능의 구현 계획
|
||||
"사용자 인증 기능 구현 계획을 세워주세요"
|
||||
|
||||
# 시스템 설계 계획
|
||||
"마이크로서비스 분할 구현 계획을 세워주세요"
|
||||
|
||||
# 리팩터링 계획
|
||||
"레거시 코드 리팩터링 계획을 세워주세요"
|
||||
```
|
||||
|
||||
### Claude 와의 연동
|
||||
|
||||
```bash
|
||||
# 복잡한 기능 구현
|
||||
"채팅 기능 구현 계획을 세워주세요. WebSocket, 실시간 알림, 기록 관리를 포함해서"
|
||||
|
||||
# 데이터베이스 설계
|
||||
"쇼핑몰 데이터베이스 설계 계획을 세워주세요. 상품, 주문, 사용자 관리를 포함해서"
|
||||
|
||||
# API 설계
|
||||
"GraphQL API 구현 계획을 세워주세요. 인증, 캐시, 레이트 제한을 포함해서"
|
||||
|
||||
# 인프라 설계
|
||||
"Docker 화 구현 계획을 세워주세요. 개발 환경, 프로덕션 환경, CI/CD 를 포함해서"
|
||||
```
|
||||
|
||||
### Plan Mode 의 특징
|
||||
|
||||
**자동 시작**
|
||||
|
||||
- 구현 작업을 감지하면 자동으로 Plan Mode 시작
|
||||
- "구현 계획을 세워주세요" 등의 키워드로 명시적 시작 가능
|
||||
|
||||
**구조화된 명세서**
|
||||
|
||||
- 요구사항 정의 (사용자 스토리·수용 기준)
|
||||
- 설계서 (아키텍처·데이터 설계·UI 설계)
|
||||
- 구현 계획 (작업 분해·진행 추적·품질 보증)
|
||||
- 위험 분석 및 대책
|
||||
|
||||
**승인 프로세스**
|
||||
|
||||
- `exit_plan_mode` 도구로 계획 제시
|
||||
- **중요**: 도구의 반환 값과 관계없이 반드시 사용자의 명시적 승인 대기
|
||||
- 승인 없는 구현 시작 금지
|
||||
- 계획의 수정·조정 가능
|
||||
- 승인 후에만 TodoWrite 로 작업 관리 시작
|
||||
|
||||
### 상세 사용 예시
|
||||
|
||||
```bash
|
||||
# 복잡한 시스템 구현
|
||||
"온라인 결제 시스템 구현 계획을 세워주세요. Stripe 연동, 보안, 오류 처리를 포함해서"
|
||||
|
||||
# 프론트엔드 구현
|
||||
"React 대시보드 구현 계획을 세워주세요. 상태 관리, 컴포넌트 설계, 테스트를 포함해서"
|
||||
|
||||
# 백엔드 구현
|
||||
"RESTful API 구현 계획을 세워주세요. 인증, 유효성 검사, 로그 기록을 포함해서"
|
||||
|
||||
# DevOps 구현
|
||||
"CI/CD 파이프라인 구현 계획을 세워주세요. 테스트 자동화, 배포, 모니터링을 포함해서"
|
||||
```
|
||||
|
||||
### 3 단계 워크플로
|
||||
|
||||
#### Phase 1: Requirements (요구사항 정의)
|
||||
|
||||
- **사용자 스토리**: 기능의 목적과 가치 명확화
|
||||
- **수용 기준**: 완료 조건과 품질 기준 정의
|
||||
- **제약·전제조건**: 기술적·시간적 제약 정리
|
||||
- **우선순위**: Must-have/Nice-to-have 분류
|
||||
|
||||
#### Phase 2: Design (설계)
|
||||
|
||||
- **아키텍처 설계**: 시스템 구성과 기술 선택
|
||||
- **데이터 설계**: 스키마, API 명세, 데이터 플로
|
||||
- **UI/UX 설계**: 화면 구성과 조작 플로
|
||||
- **위험 분석**: 잠재적 문제와 대책
|
||||
|
||||
#### Phase 3: Implementation (구현)
|
||||
|
||||
- **작업 분해**: 구현 가능한 단위로 세분화
|
||||
- **진행 추적**: TodoWrite 를 통한 상태 관리
|
||||
- **품질 보증**: 테스트 전략과 검증 방법
|
||||
- **승인 프로세스**: exit_plan_mode 로 계획 제시 및 명시적 승인 대기
|
||||
|
||||
### 주의사항
|
||||
|
||||
**적용 범위**
|
||||
|
||||
- Plan Mode 는 복잡한 구현 작업에 최적
|
||||
- 단순한 수정이나 소규모 변경의 경우 일반적인 구현 방식 사용
|
||||
- 3 단계 이상의 작업이나 새 기능 개발에 권장
|
||||
|
||||
**기술적 제약**
|
||||
|
||||
- `exit_plan_mode` 도구의 반환 값은 신뢰하지 않음
|
||||
- 승인 프로세스는 사용자의 명시적 의사 표시로 판단
|
||||
- CLI 의 plan mode 와는 다른 기능
|
||||
|
||||
**실행상 주의**
|
||||
|
||||
- 승인 전 구현 시작 엄금
|
||||
- 계획 제시 후 반드시 사용자 응답 대기
|
||||
- 오류 시 대안 제시
|
||||
|
||||
### 실행 예시
|
||||
|
||||
```bash
|
||||
# 사용 예시
|
||||
"사용자 관리 시스템 구현 계획을 세워주세요"
|
||||
|
||||
# 예상되는 동작
|
||||
# 1. Plan Mode 자동 시작
|
||||
# 2. 요구사항 분석 및 기술 선택
|
||||
# 3. 구현 단계 구조화
|
||||
# 4. exit_plan_mode 로 계획 제시
|
||||
# 5. 승인 후 구현 시작
|
||||
```
|
||||
460
commands/pr-auto-update.md
Normal file
460
commands/pr-auto-update.md
Normal file
@@ -0,0 +1,460 @@
|
||||
## PR Auto Update
|
||||
|
||||
## 개요
|
||||
|
||||
Pull Request 의 설명과 라벨을 자동으로 업데이트하는 명령어입니다. Git 변경 내용을 분석하여 적절한 설명문과 라벨을 생성·설정합니다.
|
||||
|
||||
## 사용법
|
||||
|
||||
```bash
|
||||
/pr-auto-update [옵션] [PR 번호]
|
||||
```
|
||||
|
||||
### 옵션
|
||||
|
||||
- `--pr <번호>` : 대상 PR 번호 지정 (생략 시 현재 브랜치에서 자동 검출)
|
||||
- `--description-only` : 설명문만 업데이트 (라벨은 변경하지 않음)
|
||||
- `--labels-only` : 라벨만 업데이트 (설명문은 변경하지 않음)
|
||||
- `--dry-run` : 실제 업데이트는 하지 않고 생성될 내용만 표시
|
||||
- `--lang <언어>` : 언어 지정 (ko, en)
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 현재 브랜치의 PR 을 자동 업데이트
|
||||
/pr-auto-update
|
||||
|
||||
# 특정 PR 업데이트
|
||||
/pr-auto-update --pr 1234
|
||||
|
||||
# 설명문만 업데이트
|
||||
/pr-auto-update --description-only
|
||||
|
||||
# 드라이런으로 확인
|
||||
/pr-auto-update --dry-run
|
||||
```
|
||||
|
||||
## 기능 상세
|
||||
|
||||
### 1. PR 자동 검출
|
||||
|
||||
현재 브랜치에서 해당하는 PR 을 자동 검출:
|
||||
|
||||
```bash
|
||||
# 브랜치에서 PR 검색
|
||||
gh pr list --head $(git branch --show-current) --json number,title,url
|
||||
```
|
||||
|
||||
### 2. 변경 내용 분석
|
||||
|
||||
다음 정보를 수집·분석:
|
||||
|
||||
- **파일 변경**: 추가·삭제·변경된 파일
|
||||
- **코드 분석**: import 문, 함수 정의, 클래스 정의의 변경
|
||||
- **테스트**: 테스트 파일의 유무와 내용
|
||||
- **문서**: README, docs 의 업데이트
|
||||
- **설정**: package.json, pubspec.yaml, 설정 파일의 변경
|
||||
- **CI/CD**: GitHub Actions, workflow 의 변경
|
||||
|
||||
### 3. 설명문 자동 생성
|
||||
|
||||
#### 템플릿 처리의 우선순위
|
||||
|
||||
1. **기존 PR 설명**: 이미 작성된 내용을 **완전히 준수**
|
||||
2. **프로젝트 템플릿**: `.github/PULL_REQUEST_TEMPLATE.md`에서 구조 가져오기
|
||||
3. **기본 템플릿**: 위의 것들이 존재하지 않는 경우의 폴백
|
||||
|
||||
#### 기존 내용 보존 규칙
|
||||
|
||||
**중요**: 기존 내용은 변경하지 않음
|
||||
|
||||
- 작성된 섹션은 보존
|
||||
- 빈 섹션만 보완
|
||||
- 기능적 코멘트 (Copilot review rule 등)는 보존
|
||||
|
||||
#### 프로젝트 템플릿 사용
|
||||
|
||||
```bash
|
||||
# .github/PULL_REQUEST_TEMPLATE.md 의 구조 분석
|
||||
parse_template_structure() {
|
||||
local template_file="$1"
|
||||
|
||||
if [ -f "$template_file" ]; then
|
||||
# 섹션 구조 추출
|
||||
grep -E '^##|^###' "$template_file"
|
||||
|
||||
# 코멘트 플레이스홀더 식별
|
||||
grep -E '<!--.*-->' "$template_file"
|
||||
|
||||
# 기존 템플릿 구조를 완전히 준수
|
||||
cat "$template_file"
|
||||
fi
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 라벨 자동 설정
|
||||
|
||||
#### 라벨 취득 메커니즘
|
||||
|
||||
**우선순위**:
|
||||
|
||||
1. **`.github/labels.yml`**: 프로젝트 고유의 라벨 정의에서 취득
|
||||
2. **GitHub API**: `gh api repos/{OWNER}/{REPO}/labels --jq '.[].name'`로 기존 라벨 취득
|
||||
|
||||
#### 자동 판정 규칙
|
||||
|
||||
**파일 패턴 기반**:
|
||||
|
||||
- 문서: `*.md`, `README`, `docs/` → `documentation|docs|doc`를 포함하는 라벨
|
||||
- 테스트: `test`, `spec` → `test|testing`을 포함하는 라벨
|
||||
- CI/CD: `.github/`, `*.yml`, `Dockerfile` → `ci|build|infra|ops`를 포함하는 라벨
|
||||
- 종속성: `package.json`, `pubspec.yaml`, `requirements.txt` → `dependencies|deps`를 포함하는 라벨
|
||||
|
||||
**변경 내용 기반**:
|
||||
|
||||
- 버그 수정: `fix|bug|error|crash|수정` → `bug|fix`를 포함하는 라벨
|
||||
- 신규 기능: `feat|feature|add|implement|신규기능|구현` → `feature|enhancement|feat`를 포함하는 라벨
|
||||
- 리팩터링: `refactor|clean|리팩토` → `refactor|cleanup|clean`을 포함하는 라벨
|
||||
- 성능: `performance|perf|optimize|성능` → `performance|perf`를 포함하는 라벨
|
||||
- 보안: `security|secure|보안` → `security`를 포함하는 라벨
|
||||
|
||||
#### 제약
|
||||
|
||||
- **최대 3 개까지**: 자동 선택되는 라벨 수의 상한
|
||||
- **기존 라벨만**: 새로운 라벨 생성은 금지
|
||||
- **부분 매치**: 라벨명에 키워드가 포함되어 있는지로 판정
|
||||
|
||||
#### 실제 사용 예제
|
||||
|
||||
**`.github/labels.yml`이 존재하는 경우**:
|
||||
|
||||
```bash
|
||||
# 라벨 정의에서 자동 취득
|
||||
grep "^- name:" .github/labels.yml | sed "s/^- name: '\?\([^']*\)'\?/\1/"
|
||||
|
||||
# 예: 프로젝트 고유의 라벨 체계 사용
|
||||
```
|
||||
|
||||
**GitHub API 에서 취득하는 경우**:
|
||||
|
||||
```bash
|
||||
# 기존 라벨 목록 취득
|
||||
gh api repos/{OWNER}/{REPO}/labels --jq '.[].name'
|
||||
|
||||
# 예: bug, enhancement, documentation 등의 표준적인 라벨 사용
|
||||
```
|
||||
|
||||
### 5. 실행 플로우
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# 1. PR 검출·취득
|
||||
detect_pr() {
|
||||
if [ -n "$PR_NUMBER" ]; then
|
||||
echo $PR_NUMBER
|
||||
else
|
||||
gh pr list --head $(git branch --show-current) --json number --jq '.[0].number'
|
||||
fi
|
||||
}
|
||||
|
||||
# 2. 변경 내용 분석
|
||||
analyze_changes() {
|
||||
local pr_number=$1
|
||||
|
||||
# 파일 변경 취득
|
||||
gh pr diff $pr_number --name-only
|
||||
|
||||
# 내용 분석
|
||||
gh pr diff $pr_number | head -1000
|
||||
}
|
||||
|
||||
# 3. 설명문 생성
|
||||
generate_description() {
|
||||
local pr_number=$1
|
||||
local changes=$2
|
||||
|
||||
# 현재 PR 설명 취득
|
||||
local current_body=$(gh pr view $pr_number --json body --jq -r .body)
|
||||
|
||||
# 기존 내용이 있으면 그대로 사용
|
||||
if [ -n "$current_body" ]; then
|
||||
echo "$current_body"
|
||||
else
|
||||
# 템플릿에서 신규 생성
|
||||
local template_file=".github/PULL_REQUEST_TEMPLATE.md"
|
||||
if [ -f "$template_file" ]; then
|
||||
generate_from_template "$(cat "$template_file")" "$changes"
|
||||
else
|
||||
generate_from_template "" "$changes"
|
||||
fi
|
||||
fi
|
||||
}
|
||||
|
||||
# 템플릿에서 생성
|
||||
generate_from_template() {
|
||||
local template="$1"
|
||||
local changes="$2"
|
||||
|
||||
if [ -n "$template" ]; then
|
||||
# 템플릿을 그대로 사용 (HTML 코멘트 보존)
|
||||
echo "$template"
|
||||
else
|
||||
# 기본 형식으로 생성
|
||||
echo "## What does this change?"
|
||||
echo ""
|
||||
echo "$changes"
|
||||
fi
|
||||
}
|
||||
|
||||
# 4. 라벨 결정
|
||||
determine_labels() {
|
||||
local changes=$1
|
||||
local file_list=$2
|
||||
local pr_number=$3
|
||||
|
||||
# 사용 가능한 라벨 취득
|
||||
local available_labels=()
|
||||
if [ -f ".github/labels.yml" ]; then
|
||||
# labels.yml 에서 라벨명 추출
|
||||
available_labels=($(grep "^- name:" .github/labels.yml | sed "s/^- name: '\?\([^']*\)'\?/\1/"))
|
||||
else
|
||||
# GitHub API 에서 라벨 취득
|
||||
local repo_info=$(gh repo view --json owner,name)
|
||||
local owner=$(echo "$repo_info" | jq -r .owner.login)
|
||||
local repo=$(echo "$repo_info" | jq -r .name)
|
||||
available_labels=($(gh api "repos/$owner/$repo/labels" --jq '.[].name'))
|
||||
fi
|
||||
|
||||
local suggested_labels=()
|
||||
|
||||
# 범용적인 패턴 매칭
|
||||
analyze_change_patterns "$file_list" "$changes" available_labels suggested_labels
|
||||
|
||||
# 최대 3 개로 제한
|
||||
echo "${suggested_labels[@]:0:3}"
|
||||
}
|
||||
|
||||
# 변경 패턴에서 라벨 결정
|
||||
analyze_change_patterns() {
|
||||
local file_list="$1"
|
||||
local changes="$2"
|
||||
local -n available_ref=$3
|
||||
local -n suggested_ref=$4
|
||||
|
||||
# 파일 타입별 판정
|
||||
if echo "$file_list" | grep -q "\.md$\|README\|docs/"; then
|
||||
add_matching_label "documentation\|docs\|doc" available_ref suggested_ref
|
||||
fi
|
||||
|
||||
if echo "$file_list" | grep -q "test\|spec"; then
|
||||
add_matching_label "test\|testing" available_ref suggested_ref
|
||||
fi
|
||||
|
||||
# 변경 내용별 판정
|
||||
if echo "$changes" | grep -iq "fix\|bug\|error\|crash\|수정"; then
|
||||
add_matching_label "bug\|fix" available_ref suggested_ref
|
||||
fi
|
||||
|
||||
if echo "$changes" | grep -iq "feat\|feature\|add\|implement\|신규기능\|구현"; then
|
||||
add_matching_label "feature\|enhancement\|feat" available_ref suggested_ref
|
||||
fi
|
||||
}
|
||||
|
||||
# 매치하는 라벨 추가
|
||||
add_matching_label() {
|
||||
local pattern="$1"
|
||||
local -n available_ref=$2
|
||||
local -n suggested_ref=$3
|
||||
|
||||
# 이미 3 개 있는 경우 스킵
|
||||
if [ ${#suggested_ref[@]} -ge 3 ]; then
|
||||
return
|
||||
fi
|
||||
|
||||
# 패턴에 매치하는 첫 번째 라벨 추가
|
||||
for available_label in "${available_ref[@]}"; do
|
||||
if echo "$available_label" | grep -iq "$pattern"; then
|
||||
# 중복 체크
|
||||
local already_exists=false
|
||||
for existing in "${suggested_ref[@]}"; do
|
||||
if [ "$existing" = "$available_label" ]; then
|
||||
already_exists=true
|
||||
break
|
||||
fi
|
||||
done
|
||||
|
||||
if [ "$already_exists" = false ]; then
|
||||
suggested_ref+=("$available_label")
|
||||
return
|
||||
fi
|
||||
fi
|
||||
done
|
||||
}
|
||||
|
||||
# 구 함수의 호환성을 위해 남겨둠
|
||||
find_and_add_label() {
|
||||
add_matching_label "$@"
|
||||
}
|
||||
|
||||
# 5. PR 업데이트
|
||||
update_pr() {
|
||||
local pr_number=$1
|
||||
local description="$2"
|
||||
local labels="$3"
|
||||
|
||||
if [ "$DRY_RUN" = "true" ]; then
|
||||
echo "=== DRY RUN ==="
|
||||
echo "Description:"
|
||||
echo "$description"
|
||||
echo "Labels: $labels"
|
||||
else
|
||||
# 리포지토리 정보 취득
|
||||
local repo_info=$(gh repo view --json owner,name)
|
||||
local owner=$(echo "$repo_info" | jq -r .owner.login)
|
||||
local repo=$(echo "$repo_info" | jq -r .name)
|
||||
|
||||
# GitHub API 를 사용하여 본문 업데이트 (HTML 코멘트 보존)
|
||||
# JSON 이스케이프를 적절히 처리
|
||||
local escaped_body=$(echo "$description" | jq -R -s .)
|
||||
gh api \
|
||||
--method PATCH \
|
||||
"/repos/$owner/$repo/pulls/$pr_number" \
|
||||
--field body="$description"
|
||||
|
||||
# 라벨은 일반적인 gh 명령으로 문제없음
|
||||
if [ -n "$labels" ]; then
|
||||
gh pr edit $pr_number --add-label "$labels"
|
||||
fi
|
||||
fi
|
||||
}
|
||||
```
|
||||
|
||||
## 설정 파일 (향후 확장용)
|
||||
|
||||
`~/.claude/pr-auto-update.config`:
|
||||
|
||||
```json
|
||||
{
|
||||
"language": "ko",
|
||||
"max_labels": 3
|
||||
}
|
||||
```
|
||||
|
||||
## 자주 사용하는 패턴
|
||||
|
||||
### Flutter 프로젝트
|
||||
|
||||
```markdown
|
||||
## What does this change?
|
||||
|
||||
{기능명}을 구현했습니다. 사용자의 {과제}를 해결합니다.
|
||||
|
||||
### 주요 변경 내용
|
||||
|
||||
- **UI 구현**: {화면명}을 신규 생성
|
||||
- **상태 관리**: Riverpod 프로바이더 추가
|
||||
- **API 통합**: GraphQL 쿼리·뮤테이션 구현
|
||||
- **테스트**: 위젯 테스트·단위 테스트 추가
|
||||
|
||||
### 기술 사양
|
||||
|
||||
- **아키텍처**: {사용 패턴}
|
||||
- **종속성**: {신규 추가한 패키지}
|
||||
- **성능**: {최적화 내용}
|
||||
```
|
||||
|
||||
### Node.js 프로젝트
|
||||
|
||||
```markdown
|
||||
## What does this change?
|
||||
|
||||
{API 명} 엔드포인트를 구현했습니다. {유스케이스}에 대응합니다.
|
||||
|
||||
### 주요 변경 내용
|
||||
|
||||
- **API 구현**: {엔드포인트}를 신규 생성
|
||||
- **검증**: 요청 검증 로직 추가
|
||||
- **데이터베이스**: {테이블명}에 대한 조작 구현
|
||||
- **테스트**: 통합 테스트·단위 테스트 추가
|
||||
|
||||
### 보안
|
||||
|
||||
- **인증**: JWT 토큰 검증
|
||||
- **인가**: 역할 기반 접근 제어
|
||||
- **입력 검증**: SQL 인젝션 대책
|
||||
```
|
||||
|
||||
### CI/CD 개선
|
||||
|
||||
```markdown
|
||||
## What does this change?
|
||||
|
||||
GitHub Actions 워크플로우를 개선했습니다. {효과}를 실현합니다.
|
||||
|
||||
### 개선 내용
|
||||
|
||||
- **성능**: 빌드 시간을 {시간} 단축
|
||||
- **신뢰성**: 오류 처리 강화
|
||||
- **보안**: 시크릿 관리 개선
|
||||
|
||||
### 기술 세부사항
|
||||
|
||||
- **병렬화**: {작업명}을 병렬 실행
|
||||
- **캐시**: {캐시 대상}의 캐시 전략 최적화
|
||||
- **모니터링**: {지표}의 모니터링 추가
|
||||
```
|
||||
|
||||
## 주의사항
|
||||
|
||||
1. **기존 내용의 완전 보존**:
|
||||
- 이미 작성된 내용은 **한 글자도 변경하지 않음**
|
||||
- 빈 코멘트 부분과 플레이스홀더만 보완
|
||||
- 사용자가 의도적으로 작성한 내용을 존중
|
||||
|
||||
2. **템플릿 우선순위**:
|
||||
- 기존 PR 설명 > `.github/PULL_REQUEST_TEMPLATE.md` > 기본값
|
||||
- 프로젝트 고유의 템플릿 구조를 완전 준수
|
||||
|
||||
3. **라벨 제약**:
|
||||
- `.github/labels.yml`이 존재하면 우선 사용
|
||||
- 존재하지 않는 경우 GitHub API 에서 기존 라벨 취득
|
||||
- 새로운 라벨 생성은 금지
|
||||
- 최대 3 개까지 자동 선택
|
||||
|
||||
4. **안전한 업데이트**:
|
||||
- `--dry-run`으로 사전 확인 권장
|
||||
- 기밀 정보를 포함한 변경의 경우 경고 표시
|
||||
- 백업으로 원래 설명 저장
|
||||
|
||||
5. **일관성 유지**:
|
||||
- 프로젝트의 기존 PR 스타일에 맞춤
|
||||
- 언어(한국어/영어) 통일
|
||||
- 라벨링 규칙 계승
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 자주 발생하는 문제
|
||||
|
||||
1. **PR 을 찾을 수 없음**: 브랜치명과 PR 의 연관성 확인
|
||||
2. **권한 오류**: GitHub CLI 의 인증 상태 확인
|
||||
3. **라벨 설정 불가**: 리포지토리 권한 확인
|
||||
4. **HTML 코멘트가 이스케이프됨**: GitHub CLI 사양으로 `<!-- -->`가 `<!-- -->`로 변환됨
|
||||
|
||||
### GitHub CLI 의 HTML 코멘트 이스케이프 문제
|
||||
|
||||
**중요**: GitHub CLI (`gh pr edit`)는 HTML 코멘트를 자동 이스케이프합니다. 또한 셸의 리다이렉트 처리에서 `EOF < /dev/null` 등의 부정한 문자열이 혼입되는 경우가 있습니다.
|
||||
|
||||
#### 근본적 해결책
|
||||
|
||||
1. **GitHub API 의 --field 옵션 사용**: `--field`를 사용하여 적절한 이스케이프 처리
|
||||
2. **셸 처리 단순화**: 복잡한 리다이렉트나 파이프 처리 회피
|
||||
3. **템플릿 처리 단순화**: HTML 코멘트 제거 처리를 폐지하고 완전 보존
|
||||
4. **JSON 이스케이프의 적절한 처리**: 특수 문자를 올바르게 처리
|
||||
|
||||
### 디버그 옵션
|
||||
|
||||
```bash
|
||||
# 상세 로그 출력 (구현 시 추가)
|
||||
/pr-auto-update --verbose
|
||||
```
|
||||
249
commands/pr-create.md
Normal file
249
commands/pr-create.md
Normal file
@@ -0,0 +1,249 @@
|
||||
## PR 생성
|
||||
|
||||
Git 변경 분석기반의 자동 PR 생성으로 효율적인 Pull Request 워크플로를 실현합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# 변경 분석을 통한 자동 PR 생성
|
||||
git add . && git commit -m "feat: 사용자 인증 기능 구현"
|
||||
"변경 내용을 분석해서 적절한 설명문과 라벨로 Draft PR 을 생성하세요"
|
||||
|
||||
# 기존 템플릿 유지하며 업데이트
|
||||
cp .github/PULL_REQUEST_TEMPLATE.md pr_body.md
|
||||
"템플릿 구조를 완전히 유지하고 변경 내용을 보완하세요"
|
||||
|
||||
# 단계적 품질 향상
|
||||
gh pr ready
|
||||
"품질 확인 완료 후 Ready for Review 로 변경하세요"
|
||||
```
|
||||
|
||||
### 기본 예시
|
||||
|
||||
```bash
|
||||
# 1. 브랜치 생성과 커밋
|
||||
git checkout main && git pull
|
||||
git checkout -b feat-user-profile
|
||||
git add . && git commit -m "feat: 사용자 프로필 기능 구현"
|
||||
git push -u origin feat-user-profile
|
||||
|
||||
# 2. PR 생성
|
||||
"다음 순서로 PR 을 생성해주세요:
|
||||
1. git diff --cached 로 변경 내용을 확인
|
||||
2. .github/PULL_REQUEST_TEMPLATE.md 를 사용해서 설명문 작성
|
||||
3. 변경 내용에서 적절한 라벨을 최대 3 개 선택
|
||||
4. Draft PR 로 생성 (HTML 코멘트 유지)"
|
||||
|
||||
# 3. CI 확인 후 Ready 화
|
||||
"CI 가 통과하면 PR 을 Ready for Review 로 변경하세요"
|
||||
```
|
||||
|
||||
### 실행 절차
|
||||
|
||||
#### 1. 브랜치 생성
|
||||
|
||||
```bash
|
||||
# 가이드라인을 준수한 네이밍 규칙: {type}-{subject}
|
||||
git checkout main
|
||||
git pull
|
||||
git checkout -b feat-user-authentication
|
||||
|
||||
# 브랜치 확인 (현재 브랜치명 표시)
|
||||
git branch --show-current
|
||||
```
|
||||
|
||||
#### 2. 커밋
|
||||
|
||||
```bash
|
||||
# 변경사항 스테이징
|
||||
git add .
|
||||
|
||||
# 가이드라인을 준수한 커밋 메시지
|
||||
git commit -m "feat: 사용자 인증 API 구현"
|
||||
```
|
||||
|
||||
#### 3. 리모트에 Push
|
||||
|
||||
```bash
|
||||
# 첫 번째 Push (upstream 설정)
|
||||
git push -u origin feat-user-authentication
|
||||
|
||||
# 두 번째부터
|
||||
git push
|
||||
```
|
||||
|
||||
#### 4. 자동 분석을 통한 Draft PR 생성
|
||||
|
||||
**Step 1: 변경 내용 분석**
|
||||
|
||||
```bash
|
||||
# 파일 변경 사항 취득 (스테이지된 변경 확인)
|
||||
git diff --cached --name-only
|
||||
|
||||
# 내용 분석 (최대 1000 행)
|
||||
git diff --cached | head -1000
|
||||
```
|
||||
|
||||
**Step 2: 설명문 자동 생성**
|
||||
|
||||
```bash
|
||||
# 템플릿 처리 우선순위
|
||||
# 1. 기존 PR 설명 (완전 보존)
|
||||
# 2. .github/PULL_REQUEST_TEMPLATE.md
|
||||
# 3. 기본 템플릿
|
||||
|
||||
cp .github/PULL_REQUEST_TEMPLATE.md pr_body.md
|
||||
# HTML 코멘트·구분선을 유지하며 빈 섹션만 보완
|
||||
```
|
||||
|
||||
**Step 3: 라벨 자동 선택**
|
||||
|
||||
```bash
|
||||
# 사용 가능한 라벨 취득 (비대화형)
|
||||
".github/labels.yml 또는 GitHub 저장소에서 사용 가능한 라벨을 취득해서, 변경 내용에 기반해 적절한 라벨을 자동 선택하세요"
|
||||
|
||||
# 패턴 매칭을 통한 자동 선택 (최대 3 개)
|
||||
# - 문서: *.md, docs/ → documentation|docs
|
||||
# - 테스트: test, spec → test|testing
|
||||
# - 버그 수정: fix|bug → bug|fix
|
||||
# - 새 기능: feat|feature → feature|enhancement
|
||||
```
|
||||
|
||||
**Step 4: GitHub API 로 PR 생성 (HTML 코멘트 유지)**
|
||||
|
||||
```bash
|
||||
# PR 생성
|
||||
"다음 정보로 Draft PR 을 생성해주세요:
|
||||
- 제목: 커밋 메시지에서 자동 생성
|
||||
- 설명문: .github/PULL_REQUEST_TEMPLATE.md 를 사용해서 적절히 작성
|
||||
- 라벨: 변경 내용에서 자동 선택 (최대 3 개)
|
||||
- 기본 브랜치: main
|
||||
- HTML 코멘트는 완전히 보존"
|
||||
```
|
||||
|
||||
**방법 B: GitHub MCP (폴백)**
|
||||
|
||||
```javascript
|
||||
// HTML 코멘트 유지하며 PR 생성
|
||||
mcp_github_create_pull_request({
|
||||
owner: "organization",
|
||||
repo: "repository",
|
||||
base: "main",
|
||||
head: "feat-user-authentication",
|
||||
title: "feat: 사용자 인증 구현",
|
||||
body: prBodyContent, // HTML 코멘트를 포함한 전체 내용
|
||||
draft: true,
|
||||
maintainer_can_modify: true,
|
||||
});
|
||||
```
|
||||
|
||||
### 자동 라벨 선택 시스템
|
||||
|
||||
#### 파일 패턴 기반 판정
|
||||
|
||||
- **문서**: `*.md`, `README`, `docs/` → `documentation|docs|doc`
|
||||
- **테스트**: `test`, `spec` → `test|testing`
|
||||
- **CI/CD**: `.github/`, `*.yml`, `Dockerfile` → `ci|build|infra|ops`
|
||||
- **의존성**: `package.json`, `pubspec.yaml` → `dependencies|deps`
|
||||
|
||||
#### 변경 내용 기반 판정
|
||||
|
||||
- **버그 수정**: `fix|bug|error|crash|수정` → `bug|fix`
|
||||
- **새 기능**: `feat|feature|add|implement|새기능|구현` → `feature|enhancement|feat`
|
||||
- **리팩터링**: `refactor|clean|리팩터링` → `refactor|cleanup|clean`
|
||||
- **성능**: `performance|perf|optimize` → `performance|perf`
|
||||
- **보안**: `security|secure` → `security`
|
||||
|
||||
#### 제약 사항
|
||||
|
||||
- **최대 3 개까지**: 자동 선택의 상한
|
||||
- **기존 라벨만**: 신규 생성 금지
|
||||
- **부분 매치**: 키워드 포함을 통한 판정
|
||||
|
||||
### 프로젝트 가이드라인
|
||||
|
||||
#### 기본 자세
|
||||
|
||||
1. **반드시 Draft 로 시작**: 모든 PR 은 Draft 상태로 생성
|
||||
2. **단계적 품질 향상**: Phase 1 (기본 구현) → Phase 2 (테스트 추가) → Phase 3 (문서 업데이트)
|
||||
3. **적절한 라벨**: 최대 3 종류의 라벨을 반드시 부여
|
||||
4. **템플릿 사용**: `.github/PULL_REQUEST_TEMPLATE.md`를 반드시 사용
|
||||
5. **한국어 스페이스**: 한국어와 반각 영숫자 사이에 반드시 반각 스페이스
|
||||
|
||||
#### 브랜치 네이밍 규칙
|
||||
|
||||
```text
|
||||
{type}-{subject}
|
||||
|
||||
예시:
|
||||
- feat-user-profile
|
||||
- fix-login-error
|
||||
- refactor-api-client
|
||||
```
|
||||
|
||||
#### 커밋 메시지
|
||||
|
||||
```text
|
||||
{type}: {description}
|
||||
|
||||
예시:
|
||||
- feat: 사용자 인증 API 구현
|
||||
- fix: 로그인 오류 수정
|
||||
- docs: README 업데이트
|
||||
```
|
||||
|
||||
### 템플릿 처리 시스템
|
||||
|
||||
#### 처리 우선순위
|
||||
|
||||
1. **기존 PR 설명**: 이미 기술된 내용을 **완전히 보존**
|
||||
2. **프로젝트 템플릿**: `.github/PULL_REQUEST_TEMPLATE.md` 구조 유지
|
||||
3. **기본 템플릿**: 위가 존재하지 않는 경우
|
||||
|
||||
#### 기존 내용 보존 규칙
|
||||
|
||||
- **한 글자도 변경하지 않음**: 이미 기술된 내용
|
||||
- **빈 섹션만 보완**: 플레이스홀더 부분을 변경 내용으로 채움
|
||||
- **기능적 코멘트 유지**: `<!-- Copilot review rule -->` 등을 유지
|
||||
- **HTML 코멘트 유지**: `<!-- ... -->`를 완전히 보존
|
||||
- **구분선 유지**: `---` 등의 구조를 유지
|
||||
|
||||
#### HTML 코멘트 보존 대처법
|
||||
|
||||
**중요**: GitHub CLI (`gh pr edit`)는 HTML 코멘트를 자동 이스케이프하고, 셸 처리에서 `EOF < /dev/null` 등의 불법 문자열이 혼입되는 경우가 있습니다.
|
||||
|
||||
**근본적 해결책**:
|
||||
|
||||
1. **GitHub API 의 --field 옵션 사용**: 적절한 이스케이프 처리로 HTML 코멘트 보존
|
||||
2. **템플릿 처리 단순화**: 복잡한 파이프 처리나 리다이렉트를 피함
|
||||
3. **완전 보존 접근**: HTML 코멘트 삭제 처리를 폐지하고 템플릿을 완전 보존
|
||||
|
||||
### 리뷰 코멘트 대응
|
||||
|
||||
```bash
|
||||
# 변경 후 재커밋
|
||||
git add .
|
||||
git commit -m "fix: 리뷰 피드백기반의 수정"
|
||||
git push
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
#### HTML 코멘트 보존의 중요성
|
||||
|
||||
- **GitHub CLI 제한**: `gh pr edit`는 HTML 코멘트를 이스케이프하고 불법 문자열 혼입
|
||||
- **근본적 회피책**: GitHub API 의 `--field` 옵션으로 적절한 이스케이프 처리
|
||||
- **템플릿 완전 보존**: HTML 코멘트 삭제 처리를 폐지하고 구조를 완전 유지
|
||||
|
||||
#### 자동화 제약
|
||||
|
||||
- **신규 라벨 금지**: `.github/labels.yml` 정의 외 라벨 생성 불가
|
||||
- **최대 3 라벨**: 자동 선택의 상한
|
||||
- **기존 내용 우선**: 수동으로 기술된 내용은 일체 변경하지 않음
|
||||
|
||||
#### 단계적 품질 향상
|
||||
|
||||
- **Draft 필수**: 모든 PR 은 Draft 로 시작
|
||||
- **CI 확인**: `gh pr checks`로 상태 확인
|
||||
- **Ready 이행**: 품질 확인 완료 후 `gh pr ready`
|
||||
- **템플릿 완전 준수**: 프로젝트별 구조를 유지
|
||||
143
commands/pr-feedback.md
Normal file
143
commands/pr-feedback.md
Normal file
@@ -0,0 +1,143 @@
|
||||
## PR Feedback
|
||||
|
||||
Pull Request 의 리뷰 코멘트를 효율적으로 대응하고, 에러 분석 3 단계 접근법으로 근본 해결을 도모합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# 리뷰 코멘트 취득과 분석
|
||||
gh pr view --comments
|
||||
「리뷰 코멘트를 우선순위별로 분류하여 대응 계획을 작성하세요」
|
||||
|
||||
# 에러 관련 코멘트의 상세 분석
|
||||
gh pr checks
|
||||
「CI 에러를 3 단계 접근법으로 분석하여 근본 원인을 특정하세요」
|
||||
|
||||
# 수정 완료 후 품질 확인
|
||||
npm test && npm run lint
|
||||
「수정이 완료되었으므로 회귀 테스트와 코드 품질을 체크하세요」
|
||||
```
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 코멘트 분류 실행
|
||||
gh pr view 123 --comments | head -20
|
||||
"리뷰 코멘트를 must/imo/nits/q 로 분류하여 대응 순서를 정하세요"
|
||||
|
||||
# 에러 정보 수집
|
||||
npm run build 2>&1 | tee error.log
|
||||
"빌드 에러의 근본 원인을 특정하고 적절한 수정 방법을 제안하세요"
|
||||
|
||||
# 수정 구현 확인
|
||||
git diff HEAD~1
|
||||
"이 수정이 리뷰 지적 사항을 적절히 해결하고 있는지 평가하세요"
|
||||
```
|
||||
|
||||
### 코멘트 분류 체계
|
||||
|
||||
```text
|
||||
🔴 must: 수정 필수
|
||||
├─ 보안 문제
|
||||
├─ 기능 버그
|
||||
├─ 설계 원칙 위반
|
||||
└─ 규약 위반
|
||||
|
||||
🟡 imo: 개선 제안
|
||||
├─ 더 나은 구현 방법
|
||||
├─ 성능 개선
|
||||
├─ 가독성 향상
|
||||
└─ 리팩터링 제안
|
||||
|
||||
🟢 nits: 경미한 지적
|
||||
├─ 오타 수정
|
||||
├─ 인덴트 조정
|
||||
├─ 코멘트 추가
|
||||
└─ 명명의 미조정
|
||||
|
||||
🔵 q: 질문·확인
|
||||
├─ 구현 의도 확인
|
||||
├─ 사양 명확화
|
||||
├─ 설계 판단 배경
|
||||
└─ 대안 검토
|
||||
```
|
||||
|
||||
### 에러 분석 3 단계 접근법
|
||||
|
||||
#### Stage 1: 정보 수집
|
||||
|
||||
**필수 실행**
|
||||
|
||||
- 에러 메시지의 완전 취득
|
||||
- 스택 트레이스 확인
|
||||
- 재현 조건 특정
|
||||
|
||||
**권장 실행**
|
||||
|
||||
- 환경 정보 수집
|
||||
- 최근 변경 이력
|
||||
- 관련 로그 확인
|
||||
|
||||
#### Stage 2: 근본 원인 분석
|
||||
|
||||
- 5 Whys 분석 적용
|
||||
- 종속성 추적
|
||||
- 환경 차이 확인
|
||||
- 최소 재현 코드 작성
|
||||
|
||||
#### Stage 3: 해결책 구현
|
||||
|
||||
- 즉시 대처 (핫픽스)
|
||||
- 근본적 해결 (본질 수정)
|
||||
- 예방책 (재발 방지)
|
||||
|
||||
### 대응 플로우
|
||||
|
||||
1. **코멘트 분석**: 우선순위별 분류
|
||||
2. **수정 계획**: 대응 순서 결정
|
||||
3. **단계적 수정**: Critical → High → Medium → Low
|
||||
4. **품질 확인**: 테스트·린트·빌드
|
||||
5. **진행 보고**: 구체적인 수정 내용 설명
|
||||
|
||||
### 수정 후 확인
|
||||
|
||||
```bash
|
||||
# 기본 체크
|
||||
npm test
|
||||
npm run lint
|
||||
npm run build
|
||||
|
||||
# 회귀 테스트
|
||||
npm run test:e2e
|
||||
|
||||
# 코드 품질
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
### 답변 템플릿
|
||||
|
||||
**수정 완료 보고**
|
||||
|
||||
```markdown
|
||||
@reviewer 지적해 주셔서 감사합니다.
|
||||
수정 완료했습니다:
|
||||
|
||||
- [구체적 수정 내용]
|
||||
- [테스트 결과]
|
||||
- [확인 방법]
|
||||
```
|
||||
|
||||
**기술 판단 설명**
|
||||
|
||||
```markdown
|
||||
구현 배경: [이유]
|
||||
검토한 대안: [선택지와 판단 근거]
|
||||
채용안의 장점: [메리트]
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
- **우선순위 준수**: Critical → High → Medium → Low 순으로 대응
|
||||
- **테스트 퍼스트**: 수정 전 회귀 테스트 확인
|
||||
- **명확한 보고**: 수정 내용과 확인 방법을 구체적으로 기술
|
||||
- **건설적 대화**: 기술적 근거기반의 정중한 커뮤니케이션
|
||||
78
commands/pr-issue.md
Normal file
78
commands/pr-issue.md
Normal file
@@ -0,0 +1,78 @@
|
||||
## Issue List
|
||||
|
||||
현재 리포지토리의 오픈 Issue 목록을 우선순위와 함께 표시합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# Claude 에 의뢰
|
||||
「오픈 Issue 목록을 우선순위와 함께 표시하세요」
|
||||
```
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 리포지토리 정보 취득
|
||||
gh repo view --json nameWithOwner | jq -r '.nameWithOwner'
|
||||
|
||||
# 오픈 Issue 정보 취득하여 Claude 에 의뢰
|
||||
gh issue list --state open --json number,title,author,createdAt,updatedAt,labels,assignees,comments --limit 30
|
||||
|
||||
「위의 Issue 를 우선순위별로 정리하여, 각 Issue 의 2 행 개요도 포함해서 표시하세요. URL 은 위에서 취득한 리포지토리명을 사용하여 생성하세요」
|
||||
```
|
||||
|
||||
### 표시 형식
|
||||
|
||||
```text
|
||||
오픈 Issue 목록 (우선순위순)
|
||||
|
||||
### 고우선순위
|
||||
#번호 제목 [라벨] | 작성자 | 오픈부터 경과 시간 | 코멘트 수 | 담당자
|
||||
├─ 개요 1 행째
|
||||
└─ 개요 2 행째
|
||||
https://github.com/owner/repo/issues/번호
|
||||
|
||||
### 중우선순위
|
||||
(동일한 형식)
|
||||
|
||||
### 저우선순위
|
||||
(동일한 형식)
|
||||
```
|
||||
|
||||
### 우선순위 판정 기준
|
||||
|
||||
**고우선순위**
|
||||
|
||||
- `bug` 라벨이 붙은 Issue
|
||||
- `critical`이나 `urgent` 라벨이 붙은 Issue
|
||||
- `security` 라벨이 붙은 Issue
|
||||
|
||||
**중우선순위**
|
||||
|
||||
- `enhancement` 라벨이 붙은 Issue
|
||||
- `feature` 라벨이 붙은 Issue
|
||||
- 담당자가 설정된 Issue
|
||||
|
||||
**저우선순위**
|
||||
|
||||
- `documentation` 라벨이 붙은 Issue
|
||||
- `good first issue` 라벨이 붙은 Issue
|
||||
- `wontfix`나 `duplicate` 라벨이 붙은 Issue
|
||||
|
||||
### 라벨을 통한 필터링
|
||||
|
||||
```bash
|
||||
# 특정 라벨의 Issue 만 취득
|
||||
gh issue list --state open --label "bug" --json number,title,author,createdAt,labels,comments --limit 30
|
||||
|
||||
# 복수 라벨로 필터링 (AND 조건)
|
||||
gh issue list --state open --label "bug,high-priority" --json number,title,author,createdAt,labels,comments --limit 30
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
- GitHub CLI (`gh`)가 필요합니다
|
||||
- 오픈 상태의 Issue 만 표시합니다
|
||||
- 최대 30 개의 Issue 를 표시합니다
|
||||
- 경과 시간은 Issue 가 오픈된 시점부터의 시간입니다
|
||||
- Issue 의 URL 은 실제 리포지토리명에서 자동 생성됩니다
|
||||
66
commands/pr-list.md
Normal file
66
commands/pr-list.md
Normal file
@@ -0,0 +1,66 @@
|
||||
## PR List
|
||||
|
||||
현재 리포지토리의 오픈 PR 목록을 우선순위와 함께 표시합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# Claude 에 의뢰
|
||||
「오픈 PR 목록을 우선순위와 함께 표시하세요」
|
||||
```
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 리포지토리 정보 취득
|
||||
gh repo view --json nameWithOwner | jq -r '.nameWithOwner'
|
||||
|
||||
# 오픈 PR 정보 취득하여 Claude 에 의뢰
|
||||
gh pr list --state open --draft=false --json number,title,author,createdAt,additions,deletions,reviews --limit 30
|
||||
|
||||
「위의 PR 을 우선순위별로 정리하여, 각 PR 의 2 행 개요도 포함해서 표시하세요. URL 은 위에서 취득한 리포지토리명을 사용하여 생성하세요」
|
||||
```
|
||||
|
||||
### 표시 형식
|
||||
|
||||
```text
|
||||
오픈 PR 목록 (우선순위순)
|
||||
|
||||
### 고우선순위
|
||||
#번호 제목 [Draft/DNM] | 작성자 | 오픈부터 경과 시간 | Approved 수 | +추가/-삭제
|
||||
├─ 개요 1 행째
|
||||
└─ 개요 2 행째
|
||||
https://github.com/owner/repo/pull/번호
|
||||
|
||||
### 중우선순위
|
||||
(동일한 형식)
|
||||
|
||||
### 저우선순위
|
||||
(동일한 형식)
|
||||
```
|
||||
|
||||
### 우선순위 판정 기준
|
||||
|
||||
**고우선순위**
|
||||
|
||||
- `fix:` 버그 수정
|
||||
- `release:` 릴리스 작업
|
||||
|
||||
**중우선순위**
|
||||
|
||||
- `feat:` 신규 기능
|
||||
- `update:` 기능 개선
|
||||
- 기타 일반적인 PR
|
||||
|
||||
**저우선순위**
|
||||
|
||||
- DO NOT MERGE 를 포함하는 PR
|
||||
- Draft 이면서 `test:`, `build:`, `perf:`인 PR
|
||||
|
||||
### 주의사항
|
||||
|
||||
- GitHub CLI (`gh`)가 필요합니다
|
||||
- 오픈 상태의 PR 만 표시합니다 (Draft 는 제외)
|
||||
- 최대 30 개의 PR 을 표시합니다
|
||||
- 경과 시간은 PR 이 오픈된 시점부터의 시간입니다
|
||||
- PR 의 URL 은 실제 리포지토리명에서 자동 생성됩니다
|
||||
176
commands/pr-review.md
Normal file
176
commands/pr-review.md
Normal file
@@ -0,0 +1,176 @@
|
||||
## PR 리뷰
|
||||
|
||||
Pull Request 의 체계적 리뷰로 코드 품질과 아키텍처 건전성을 확보합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# PR 을 포괄적으로 리뷰
|
||||
gh pr view 123 --comments
|
||||
"이 PR 을 체계적으로 리뷰해서 코드 품질, 보안, 아키텍처 관점으로 피드백하세요"
|
||||
|
||||
# 보안 특화 리뷰
|
||||
gh pr diff 123
|
||||
"보안 리스크와 취약점에 초점을 맞춰서 리뷰하세요"
|
||||
|
||||
# 아키텍처 관점의 리뷰
|
||||
gh pr checkout 123 && find . -name "*.js" | head -10
|
||||
"레이어 분리, 의존관계, SOLID 원칙 관점으로 아키텍처를 평가하세요"
|
||||
```
|
||||
|
||||
### 기본 예시
|
||||
|
||||
```bash
|
||||
# 코드 품질의 정량적 평가
|
||||
find . -name "*.js" -exec wc -l {} + | sort -rn | head -5
|
||||
"코드의 복잡도, 함수 크기, 중복도를 평가해서 개선점을 지적하세요"
|
||||
|
||||
# 보안 취약점 체크
|
||||
grep -r "password\|secret\|token" . --include="*.js" | head -10
|
||||
"기밀정보 누출, 하드코딩, 인증 우회 리스크를 체크하세요"
|
||||
|
||||
# 아키텍처 위반 탐지
|
||||
grep -r "import.*from.*\.\./\.\." . --include="*.js"
|
||||
"레이어 위반, 순환 의존, 결합도 문제를 평가하세요"
|
||||
```
|
||||
|
||||
### 코멘트 분류 체계
|
||||
|
||||
```text
|
||||
🔴 critical.must: 치명적 문제
|
||||
├─ 보안 취약점
|
||||
├─ 데이터 정합성 문제
|
||||
└─ 시스템 장애 리스크
|
||||
|
||||
🟡 high.imo: 높은 우선도 개선
|
||||
├─ 기능 불량 리스크
|
||||
├─ 성능 문제
|
||||
└─ 유지보수성 대폭 저하
|
||||
|
||||
🟢 medium.imo: 중간 우선도 개선
|
||||
├─ 가독성 향상
|
||||
├─ 코드 구조 개선
|
||||
└─ 테스트 품질 향상
|
||||
|
||||
🟢 low.nits: 경미한 지적
|
||||
├─ 스타일 통일
|
||||
├─ 오타 수정
|
||||
└─ 주석 추가
|
||||
|
||||
🔵 info.q: 질문·정보 제공
|
||||
├─ 구현 의도 확인
|
||||
├─ 설계 판단 배경
|
||||
└─ 베스트 프랙티스 공유
|
||||
```
|
||||
|
||||
### 리뷰 관점
|
||||
|
||||
#### 1. 코드 정확성
|
||||
|
||||
- **로직 에러**: 경계값, Null 체크, 예외 처리
|
||||
- **데이터 정합성**: 타입 안전성, 밸리데이션
|
||||
- **에러 핸들링**: 망라성, 적절한 처리
|
||||
|
||||
#### 2. 보안
|
||||
|
||||
- **인증·인가**: 적절한 체크, 권한 관리
|
||||
- **입력 검증**: SQL 인젝션, XSS 대책
|
||||
- **기밀정보**: 로그 출력 금지, 암호화
|
||||
|
||||
#### 3. 성능
|
||||
|
||||
- **알고리즘**: 시간 계산 복잡도, 메모리 효율성
|
||||
- **데이터베이스**: N+1 쿼리, 인덱스 최적화
|
||||
- **리소스**: 메모리 누수, 캐시 활용
|
||||
|
||||
#### 4. 아키텍처
|
||||
|
||||
- **레이어 분리**: 의존 방향, 적절한 분리
|
||||
- **결합도**: 느슨한 결합, 인터페이스 활용
|
||||
- **SOLID 원칙**: 단일 책임, 개방 폐쇄, 의존성 역전
|
||||
|
||||
### 리뷰 플로
|
||||
|
||||
1. **사전 확인**: PR 정보, 변경 차분, 관련 Issue
|
||||
2. **체계적 체크**: 보안 → 정확성 → 성능 → 아키텍처
|
||||
3. **건설적 피드백**: 구체적인 개선안과 코드 예시
|
||||
4. **팔로우업**: 수정 확인, CI 상태, 최종 승인
|
||||
|
||||
### 효과적인 코멘트 예시
|
||||
|
||||
#### 보안 문제 템플릿
|
||||
|
||||
**포맷**:
|
||||
|
||||
```text
|
||||
**critical.must.** [문제점 요약]
|
||||
|
||||
[구체적인 위험 설명]
|
||||
|
||||
권장 해결방안:
|
||||
[해결 방법]
|
||||
```
|
||||
|
||||
**예시**:
|
||||
|
||||
```text
|
||||
**critical.must.** 패스워드가 평문으로 저장되고 있습니다
|
||||
|
||||
보안 리스크를 방지하기 위해 해싱화가 필수입니다.
|
||||
|
||||
권장 해결방안:
|
||||
const bcrypt = require('bcrypt');
|
||||
const hashedPassword = await bcrypt.hash(password, 12);
|
||||
```
|
||||
|
||||
#### 성능 개선 템플릿
|
||||
|
||||
**포맷**:
|
||||
|
||||
```text
|
||||
**high.imo.** [성능 문제점]
|
||||
|
||||
[문제 상황 설명]
|
||||
|
||||
개선안:
|
||||
[최적화 방법]
|
||||
```
|
||||
|
||||
**예시**:
|
||||
|
||||
```text
|
||||
**high.imo.** N+1 쿼리 문제가 발생합니다
|
||||
|
||||
쿼리 수를 대폭 줄일 수 있습니다.
|
||||
|
||||
개선안:
|
||||
// Eager Loading 사용
|
||||
const users = await User.findAll({ include: [Post] });
|
||||
```
|
||||
|
||||
#### 아키텍처 위반 템플릿
|
||||
|
||||
**포맷**:
|
||||
|
||||
```text
|
||||
**high.must.** [아키텍처 문제점]
|
||||
|
||||
[위반 내용 설명]
|
||||
[개선 방향 제시]
|
||||
```
|
||||
|
||||
**예시**:
|
||||
|
||||
```text
|
||||
**high.must.** 레이어 위반이 발생하고 있습니다
|
||||
|
||||
도메인 레이어가 인프라 레이어에 직접 의존하고 있습니다.
|
||||
의존성 역전 원칙으로 인터페이스를 도입하세요.
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
- **건설적 톤**: 공격적이 아닌 협조적인 커뮤니케이션
|
||||
- **구체적 제안**: 문제 지적뿐만 아니라 해결안 제시
|
||||
- **우선순위**: Critical → High → Medium → Low 순으로 대응
|
||||
- **지속적 개선**: 리뷰 결과를 지식베이스화
|
||||
305
commands/refactor.md
Normal file
305
commands/refactor.md
Normal file
@@ -0,0 +1,305 @@
|
||||
## Refactor
|
||||
|
||||
안전하고 단계적인 코드 리팩터링을 실시하며, SOLID 원칙의 준수 상황을 정량적으로 평가합니다. 기술적 부채를 가시화하고, 개선의 우선순위를 명확히 합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# 복잡한 코드의 특정과 리팩터링 계획
|
||||
find . -name "*.js" -exec wc -l {} + | sort -rn | head -10
|
||||
「큰 파일을 리팩터링해서 복잡도를 삭감해 주세요」
|
||||
|
||||
# 중복 코드의 검출과 통합
|
||||
grep -r "function processUser" . --include="*.js"
|
||||
「중복된 함수를 Extract Method로 공통화해 주세요」
|
||||
|
||||
# SOLID 원칙 위반의 검출
|
||||
grep -r "class.*Service" . --include="*.js" | head -10
|
||||
「이러한 클래스가 단일 책임의 원칙에 따르고 있는지 평가해 주세요」
|
||||
```
|
||||
|
||||
### 기본 예
|
||||
|
||||
```bash
|
||||
# 긴 메서드의 검출
|
||||
grep -A 50 "function" src/*.js | grep -B 50 -A 50 "return" | wc -l
|
||||
"50 행 이상의 메서드를 Extract Method로 분할해 주세요"
|
||||
|
||||
# 조건 분기의 복잡도
|
||||
grep -r "if.*if.*if" . --include="*.js"
|
||||
"중첩된 조건문을 Strategy 패턴으로 개선해 주세요"
|
||||
|
||||
# 코드의 냄새 검출
|
||||
grep -r "TODO\|FIXME\|HACK" . --exclude-dir=node_modules
|
||||
"기술적 부채가 되고 있는 코멘트를 해결해 주세요"
|
||||
```
|
||||
|
||||
### 리팩터링 기법
|
||||
|
||||
#### Extract Method(메서드 추출)
|
||||
|
||||
```javascript
|
||||
// Before: 장대한 메서드
|
||||
function processOrder(order) {
|
||||
// 50 행의 복잡한 처리
|
||||
}
|
||||
|
||||
// After: 책임 분리
|
||||
function processOrder(order) {
|
||||
validateOrder(order);
|
||||
calculateTotal(order);
|
||||
saveOrder(order);
|
||||
}
|
||||
```
|
||||
|
||||
#### Replace Conditional with Polymorphism
|
||||
|
||||
```javascript
|
||||
// Before: switch 문
|
||||
function getPrice(user) {
|
||||
switch (user.type) {
|
||||
case "premium":
|
||||
return basePrice * 0.8;
|
||||
case "regular":
|
||||
return basePrice;
|
||||
}
|
||||
}
|
||||
|
||||
// After: Strategy 패턴
|
||||
class PremiumPricing {
|
||||
calculate(basePrice) {
|
||||
return basePrice * 0.8;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### SOLID 원칙 스코어링(0-100 점)
|
||||
|
||||
#### 평가 기준과 배점
|
||||
|
||||
```text
|
||||
S - Single Responsibility(20 점)
|
||||
├─ 클래스의 책임 수: 1 개(20 점) | 2 개(15 점) | 3 개(10 점) | 4 개 이상(5 점)
|
||||
├─ 메서드 수: <7 개(+5 점) | 7-15 개(+3 점) | >15 개(0 점)
|
||||
├─ 변경 이유의 명확성: 명확(+5 점) | 모호(0 점)
|
||||
└─ 스코어 예: UserService(인증+데이터 처리) = 10 점
|
||||
|
||||
O - Open/Closed(20 점)
|
||||
├─ 확장 포인트: Strategy/Template Method(20 점) | 상속만(10 점) | 없음(5 점)
|
||||
├─ 신기능 추가 시의 기존 코드 변경: 불필요(+5 점) | 최소한(+3 점) | 필요(0 점)
|
||||
├─ 인터페이스 이용: 적절(+5 점) | 부분적(+3 점) | 없음(0 점)
|
||||
└─ 스코어 예: PaymentProcessor(Strategy) = 20 점
|
||||
|
||||
L - Liskov Substitution(20 점)
|
||||
├─ 파생 클래스의 계약 준수: 완전(20 점) | 부분적(10 점) | 위반(0 점)
|
||||
├─ 사전 조건의 강화: 없음(+5 점) | 있음(-5 점)
|
||||
├─ 사후 조건의 약화: 없음(+5 점) | 있음(-5 점)
|
||||
└─ 스코어 예: Square extends Rectangle = 0 점(위반)
|
||||
|
||||
I - Interface Segregation(20 점)
|
||||
├─ 인터페이스 크기: 1-3 메서드(20 점) | 4-7(15 점) | 8+(5 점)
|
||||
├─ 미사용 메서드 구현: 없음(+5 점) | 1-2 개(+2 점) | 3 개 이상(0 점)
|
||||
├─ 역할의 명확성: 단일 역할(+5 점) | 복수 역할(0 점)
|
||||
└─ 스코어 예: Readable/Writable 분리 = 20 점
|
||||
|
||||
D - Dependency Inversion(20 점)
|
||||
├─ 의존 방향: 추상만(20 점) | 혼재(10 점) | 구상만(5 점)
|
||||
├─ DI 이용: Constructor Injection(+5 점) | Setter(+3 점) | 없음(0 점)
|
||||
├─ 테스트 가능성: Mock 가능(+5 점) | 곤란(0 점)
|
||||
└─ 스코어 예: Repository Pattern = 20 점
|
||||
|
||||
총합 스코어 = S + O + L + I + D
|
||||
├─ 90-100 점: Excellent(SOLID 완전 준수)
|
||||
├─ 70-89 점: Good(경미한 개선 여지)
|
||||
├─ 50-69 점: Fair(리팩터링 권장)
|
||||
├─ 30-49 점: Poor(대규모 개선 필요)
|
||||
└─ 0-29 점: Critical(설계 재검토 필수)
|
||||
```
|
||||
|
||||
### 기술적 부채의 정량화
|
||||
|
||||
#### 부채 계산식
|
||||
|
||||
```text
|
||||
기술적 부채(시간) = 복잡도 스코어 × 영향 범위 × 수정 난이도
|
||||
|
||||
복잡도 스코어:
|
||||
├─ 순환적 복잡도: 1-5(낮음) | 6-10(중간) | 11-20(높음) | 21+(위험)
|
||||
├─ 인지적 복잡도: 중첩 깊이 × 조건 분기 수
|
||||
├─ 코드 행수: <50(1 점) | 50-200(2 점) | 200-500(3 점) | 500+(5 점)
|
||||
└─ 중복률: 0-10%(1 점) | 10-30%(2 점) | 30-50%(3 점) | 50%+(5 점)
|
||||
|
||||
영향 범위:
|
||||
├─ 의존 모듈 수: 직접 의존 + 간접 의존 × 0.5
|
||||
├─ 이용 빈도: API 호출 횟수/일
|
||||
├─ 비즈니스 중요도: Critical(×3) | High(×2) | Medium(×1) | Low(×0.5)
|
||||
└─ 팀 지식: 이해자 1 명(×3) | 2-3 명(×2) | 4 명 이상(×1)
|
||||
|
||||
수정 난이도:
|
||||
├─ 테스트 커버리지: 0%(×3) | <50%(×2) | 50-80%(×1.5) | >80%(×1)
|
||||
├─ 문서: 없음(×2) | 불충분(×1.5) | 충분(×1)
|
||||
├─ 의존 관계: 밀결합(×3) | 중간 정도(×2) | 소결합(×1)
|
||||
└─ 변경 위험: Breaking Change(×3) | 호환성 고려(×2) | 안전(×1)
|
||||
|
||||
비용 환산:
|
||||
├─ 시간 비용: 부채 시간 × 개발자 시급
|
||||
├─ 기회 손실: 신기능 개발 지연 일수 × 일차 매출 영향
|
||||
├─ 품질 비용: 버그 발생 확률 × 수정 비용 × 발생 빈도
|
||||
└─ 총 비용: 시간 + 기회 손실 + 품질 비용
|
||||
```
|
||||
|
||||
#### 우선순위 매트릭스
|
||||
|
||||
| 우선도 | 영향도 | 수정 비용 | 대응 기한 | 구체예 | 권장 액션 |
|
||||
| -------------------------- | ------ | --------- | ----------- | ------------------------------- | --------------------------- |
|
||||
| **Critical(즉시 대응)** | 높음 | 낮음 | 1 주일 이내 | God Object、순환 의존 | 즉시 리팩터링 시작 |
|
||||
| **Important(계획적 대응)** | 높음 | 높음 | 1 개월 이내 | 대규모 책임 분리、아키텍처 변경 | 스프린트 계획에 포함 |
|
||||
| **Watch(감시 대상)** | 낮음 | 높음 | 3 개월 이내 | 복잡도가 높은 내부 처리 | 메트릭스 감시、악화 시 대응 |
|
||||
| **Acceptable(허용 범위)** | 낮음 | 낮음 | 대응 불요 | 경미한 코드의 냄새 | 통상 리팩터링으로 대응 |
|
||||
|
||||
### 리팩터링 수순
|
||||
|
||||
1. **현상 분석과 측정**
|
||||
- 복잡도 측정(순환적・인지적)
|
||||
- SOLID 스코어 산출(0-100 점)
|
||||
- 기술적 부채의 정량화(시간/비용)
|
||||
- 우선순위 매트릭스 작성
|
||||
|
||||
2. **단계적 실행**
|
||||
- 작은 스텝(15-30 분 단위)
|
||||
- 각 변경 후의 테스트 실행
|
||||
- 빈번한 커밋
|
||||
- SOLID 스코어의 계속 측정
|
||||
|
||||
3. **품질 확인**
|
||||
- 테스트 커버리지 유지
|
||||
- 퍼포먼스 측정
|
||||
- 기술적 부채의 삭감 확인
|
||||
- 코드 리뷰
|
||||
|
||||
### 자주 있는 코드의 냄새와 부채 스코어
|
||||
|
||||
| 코드의 냄새 | 검출 기준 | 부채 스코어 | 개선 기법 |
|
||||
| ----------------------- | --------------------------- | ------------- | ----------------------- |
|
||||
| **God Object** | 책임 >3, 메서드 >20 | 높음 (15-20h) | Extract Class, SRP 적용 |
|
||||
| **Long Method** | 행수 >50, 복잡도 >10 | 중간 (5-10h) | Extract Method |
|
||||
| **Duplicate Code** | 중복률 >30% | 높음 (10-15h) | Extract Method/Class |
|
||||
| **Large Class** | 행수 >300, 메서드 >15 | 높음 (10-20h) | Extract Class |
|
||||
| **Long Parameter List** | 파라미터 >4 | 낮음 (2-5h) | Parameter Object |
|
||||
| **Feature Envy** | 다른 클래스 참조 >5 | 중간 (5-10h) | Move Method |
|
||||
| **Data Clumps** | 같은 인수군의 반복 | 낮음 (3-5h) | Extract Class |
|
||||
| **Primitive Obsession** | 프리미티브 타입의 과도 사용 | 중간 (5-8h) | Replace with Object |
|
||||
| **Switch Statements** | case >5 | 중간 (5-10h) | Strategy Pattern |
|
||||
| **Shotgun Surgery** | 변경 시의 영향 개소 >3 | 높음 (10-15h) | Move Method/Field |
|
||||
|
||||
### 실천 예：SOLID 스코어 평가
|
||||
|
||||
```javascript
|
||||
// 평가 대상: UserService 클래스
|
||||
class UserService {
|
||||
constructor(db, cache, logger, emailService) { // 4 개의 의존
|
||||
this.db = db;
|
||||
this.cache = cache;
|
||||
this.logger = logger;
|
||||
this.emailService = emailService;
|
||||
}
|
||||
|
||||
// 책임 1: 인증
|
||||
authenticate(username, password) { /* ... */ }
|
||||
refreshToken(token) { /* ... */ }
|
||||
|
||||
// 책임 2: 사용자 관리
|
||||
createUser(data) { /* ... */ }
|
||||
updateUser(id, data) { /* ... */ }
|
||||
deleteUser(id) { /* ... */ }
|
||||
|
||||
// 책임 3: 알림
|
||||
sendWelcomeEmail(user) { /* ... */ }
|
||||
sendPasswordReset(email) { /* ... */ }
|
||||
}
|
||||
|
||||
// SOLID 스코어 평가 결과
|
||||
S: 10 점 (책임 3 개: 인증、CRUD、알림)
|
||||
O: 5 점 (확장 포인트 없음、직접 구현)
|
||||
L: 15 점 (상속 없음、해당 없음)
|
||||
I: 10 점 (인터페이스 미분리)
|
||||
D: 10 점 (구상 클래스 의존)
|
||||
총합: 50 점 (Fair - 리팩터링 권장)
|
||||
|
||||
// 기술적 부채
|
||||
복잡도: 15 (메서드 7 개、책임 3 개)
|
||||
영향 범위: 8 (인증은 전 기능에서 사용)
|
||||
수정 난이도: 2 (테스트 있음、문서 부족)
|
||||
부채 시간: 15 × 8 × 2 = 240 시간
|
||||
우선도: Critical (인증계는 즉시 대응)
|
||||
```
|
||||
|
||||
### 개선 후의 구현 예
|
||||
|
||||
```javascript
|
||||
// SOLID 원칙 적용 후 (스코어: 90 점)
|
||||
|
||||
// S: 단일 책임 (20 점)
|
||||
class AuthenticationService {
|
||||
authenticate(credentials) { /* ... */ }
|
||||
refreshToken(token) { /* ... */ }
|
||||
}
|
||||
|
||||
// O: 개방 폐쇄 (20 점)
|
||||
class UserRepository {
|
||||
constructor(storage) { // Strategy Pattern
|
||||
this.storage = storage;
|
||||
}
|
||||
save(user) { return this.storage.save(user); }
|
||||
}
|
||||
|
||||
// I: 인터페이스 분리 (20 점)
|
||||
interface Readable {
|
||||
find(id);
|
||||
findAll();
|
||||
}
|
||||
interface Writable {
|
||||
save(entity);
|
||||
delete(id);
|
||||
}
|
||||
|
||||
// D: 의존성 역전 (20 점)
|
||||
class UserService {
|
||||
constructor(
|
||||
private auth: IAuthService,
|
||||
private repo: IUserRepository,
|
||||
private notifier: INotificationService
|
||||
) {}
|
||||
}
|
||||
|
||||
// 부채 삭감: 240 시간 → 20 시간 (92% 삭감)
|
||||
```
|
||||
|
||||
### 자동화 지원
|
||||
|
||||
```bash
|
||||
# SOLID 스코어 측정
|
||||
npx solid-analyzer src/ --output report.json
|
||||
|
||||
# 복잡도 분석
|
||||
npx complexity-report src/ --format json
|
||||
sonar-scanner -Dsonar.javascript.lcov.reportPaths=coverage/lcov.info
|
||||
|
||||
# 기술적 부채의 가시화
|
||||
npx code-debt-analyzer --config .debt.yml
|
||||
|
||||
# 코드 포맷
|
||||
npm run lint:fix
|
||||
prettier --write src/
|
||||
|
||||
# 테스트 실행과 커버리지
|
||||
npm test -- --coverage
|
||||
npm run test:mutation # 변이 테스트
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
- **기능 변경의 금지**: 외부 동작을 바꾸지 않음
|
||||
- **테스트 퍼스트**: 리팩터링 전에 테스트 추가
|
||||
- **단계적 접근**: 한번에 큰 변경을 하지 않음
|
||||
- **계속적 검증**: 각 스텝에서의 테스트 실행
|
||||
571
commands/role-debate.md
Normal file
571
commands/role-debate.md
Normal file
@@ -0,0 +1,571 @@
|
||||
## Role Debate
|
||||
|
||||
다양한 전문성을 가진 역할이 토론하여 트레이드오프를 검토하고 최적해를 도출하는 명령어입니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
/role-debate <역할 1>,<역할 2> [안건]
|
||||
/role-debate <역할 1>,<역할 2>,<역할 3> [안건]
|
||||
```
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 보안 vs 성능의 트레이드오프
|
||||
/role-debate security,performance
|
||||
「JWT 토큰의 유효기간 설정에 대해서」
|
||||
|
||||
# 사용성 vs 보안의 균형
|
||||
/role-debate frontend,security
|
||||
「2 단계 인증의 UX 최적화에 대해서」
|
||||
|
||||
# 기술 선정 토론
|
||||
/role-debate architect,mobile
|
||||
「React Native vs Flutter 선택에 대해서」
|
||||
|
||||
# 3 자 토론
|
||||
/role-debate architect,security,performance
|
||||
「마이크로서비스화의 찬반에 대해서」
|
||||
```
|
||||
|
||||
### 토론의 기본 원칙
|
||||
|
||||
#### 건설적 토론의 자세
|
||||
|
||||
- **상호 존중**: 다른 역할의 전문성과 관점을 존중
|
||||
- **사실 기반**: 감정적 반박이 아닌 데이터·근거기반의 토론
|
||||
- **해결 지향**: 비판을 위한 비판이 아닌 더 나은 해결책을 목표
|
||||
- **구현 중시**: 이상론이 아닌 실현 가능성을 고려한 제안
|
||||
|
||||
#### 논거의 질적 요건
|
||||
|
||||
- **공식 문서**: 표준·가이드라인·공식 문서에 대한 언급
|
||||
- **실증 사례**: 성공 사례·실패 사례의 구체적 인용
|
||||
- **정량 평가**: 가능한 한 수치·지표를 통한 비교
|
||||
- **시계열 고려**: 단기·중기·장기에서의 영향 평가
|
||||
|
||||
#### 토론 윤리
|
||||
|
||||
- **성실성**: 자신의 전문 분야의 한계도 인정
|
||||
- **개방성**: 새로운 정보·관점에 대한 유연성
|
||||
- **투명성**: 판단 근거·전제 조건의 명시
|
||||
- **책임성**: 제안의 구현 리스크도 포함하여 언급
|
||||
|
||||
### 토론 프로세스
|
||||
|
||||
### Phase 1: 초기 입장 표명
|
||||
|
||||
각 역할이 전문 관점으로 독립적으로 의견 표명
|
||||
|
||||
- 권장안 제시
|
||||
- 근거가 되는 표준·문서의 명시
|
||||
- 예상되는 리스크·과제 설명
|
||||
- 성공 지표의 정의
|
||||
|
||||
### Phase 2: 상호 토론·반박
|
||||
|
||||
역할 간의 크로스 토론
|
||||
|
||||
- 다른 역할 제안에 대한 건설적 반박
|
||||
- 간과된 관점의 지적
|
||||
- 트레이드오프의 명확화
|
||||
- 대안 제시
|
||||
|
||||
### Phase 3: 타협점 모색
|
||||
|
||||
구현 가능한 해결책의 모색
|
||||
|
||||
- 각 관점의 중요도 평가
|
||||
- Win-Win 해결책 검토
|
||||
- 단계별 구현 접근법
|
||||
- 리스크 경감책 검토
|
||||
|
||||
### Phase 4: 통합 결론
|
||||
|
||||
최종적인 권장사항 결정
|
||||
|
||||
- 합의된 해결책
|
||||
- 구현 로드맵
|
||||
- 성공 지표·측정 방법
|
||||
- 향후 검토 포인트
|
||||
|
||||
### 출력 형식 예제
|
||||
|
||||
### 2 역할 토론의 경우
|
||||
|
||||
```text
|
||||
역할 토론: Security vs Performance
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
안건: JWT 토큰의 유효기간 설정
|
||||
|
||||
Security 역할의 주장:
|
||||
「15 분의 단기 유효기간을 권장합니다」
|
||||
|
||||
근거:
|
||||
- OWASP JWT Security Cheat Sheet 준수
|
||||
- 토큰 유출 시 피해 시간 창을 최소화
|
||||
- 공격자의 이용 가능 시간을 제한
|
||||
|
||||
우려 사항:
|
||||
- 장기 유효기간은 공격 리스크가 지수함수적으로 증대
|
||||
- 규정 준수 요건(금융계)에서는 단기가 필수
|
||||
|
||||
성공 지표:
|
||||
- 보안 인시던트 발생률 < 0.1%
|
||||
- 평균 공격 탐지 시간 < 5 분
|
||||
|
||||
Performance 역할의 반박:
|
||||
「2 시간의 유효기간을 권장합니다」
|
||||
|
||||
근거:
|
||||
- Google OAuth 2.0 Best Practices 참고
|
||||
- 빈번한 재인증으로 인한 서버 부하 증가 회피
|
||||
- 사용자 경험(작업 중단)의 최소화
|
||||
|
||||
우려 사항:
|
||||
- 15 분 간격의 재인증은 API 부하 8 배 증가
|
||||
- 모바일 환경에서 연결 끊김이 빈발
|
||||
|
||||
성공 지표:
|
||||
- API 응답 시간 < 200ms 유지
|
||||
- 서버 CPU 사용률 < 60%
|
||||
|
||||
상호 토론:
|
||||
Security → Performance:
|
||||
「서버 부하보다도 보안 침해의 비즈니스 손실이 더 심각합니다.
|
||||
예: Equifax 사건에서는 7 억 달러의 손실」
|
||||
|
||||
Performance → Security:
|
||||
「리프레시 토큰 메커니즘으로 양립 가능합니다.
|
||||
백그라운드 업데이트로 UX 를 손상시키지 않고 보안 확보」
|
||||
|
||||
Security → Performance:
|
||||
「리프레시 토큰도 공격 대상입니다. 적절한 구현이 전제」
|
||||
|
||||
Performance → Security:
|
||||
「단계적 접근법을 제안합니다. 일반 조작 30 분, 기밀 조작 15 분」
|
||||
|
||||
타협점 모색:
|
||||
공통 이해:
|
||||
- 사용자 경험과 보안의 양립이 필요
|
||||
- 리스크 레벨에 따른 유연한 대응
|
||||
- 구현·운용 비용의 현실적 고려
|
||||
|
||||
Win-Win 요소:
|
||||
- 리프레시 토큰 메커니즘의 활용
|
||||
- 리스크 기반 인증의 단계적 도입
|
||||
- 자동 로그아웃 기능을 통한 보완
|
||||
|
||||
통합 결론:
|
||||
「30 분 유효기간 + 리프레시 토큰 + 리스크 기반 인증」
|
||||
|
||||
구현 세부사항:
|
||||
1. 액세스 토큰: 30 분 유효기간
|
||||
2. 리프레시 토큰: 7 일 유효기간
|
||||
3. 고위험 조작: 15 분에 강제 재인증
|
||||
4. 무조작 30 분에 자동 로그아웃
|
||||
|
||||
단계적 구현:
|
||||
1-2 주차: 기본적인 30 분 토큰 구현
|
||||
3-4 주차: 리프레시 토큰 메커니즘 추가
|
||||
2 개월차: 리스크 기반 인증의 도입
|
||||
|
||||
성공 지표:
|
||||
- 보안: 인시던트 발생률 < 0.1%
|
||||
- 성능: API 부하 증가율 < 20%
|
||||
- UX: 사용자 만족도 > 85%
|
||||
|
||||
향후 검토:
|
||||
- 3 개월 후: 실제 공격 패턴·부하 상황 평가
|
||||
- 6 개월 후: 더 정교한 리스크 기반 인증으로의 이전 검토
|
||||
```
|
||||
|
||||
### 3 역할 토론의 경우
|
||||
|
||||
```text
|
||||
역할 토론: Architect vs Security vs Performance
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
안건: 마이크로서비스화의 찬반
|
||||
|
||||
Architect 역할의 주장:
|
||||
「단계적 마이크로서비스화를 권장」
|
||||
근거: 도메인 경계 명확화, 독립적인 배포, 기술 선택의 자유도
|
||||
|
||||
Security 역할의 우려:
|
||||
「서비스 간 통신의 보안 복잡화」
|
||||
근거: API Gateway, mTLS, 분산 인증의 관리 비용
|
||||
|
||||
Performance 역할의 우려:
|
||||
「네트워크 통신을 통한 지연시간 증가」
|
||||
근거: 내부 API 호출을 통한 N+1 문제, 분산 트랜잭션
|
||||
|
||||
3 자 토론:
|
||||
Architect → Security: 「API Gateway 로 집중 관리에 의해 통제 가능」
|
||||
Security → Architect: 「단일 장애점이 되는 리스크」
|
||||
Performance → Architect: 「서비스 분할의 세분화가 중요」
|
||||
...(토론 계속)
|
||||
|
||||
통합 결론:
|
||||
「도메인 주도 설계를 통한 단계적 분할 + 보안 우선 설계」
|
||||
```
|
||||
|
||||
### 효과적인 토론 패턴
|
||||
|
||||
### 기술 선정
|
||||
|
||||
```bash
|
||||
/role-debate architect,performance
|
||||
「데이터베이스 선택: PostgreSQL vs MongoDB」
|
||||
|
||||
/role-debate frontend,mobile
|
||||
「UI 프레임워크: React vs Vue」
|
||||
|
||||
/role-debate security,architect
|
||||
「인증 방식: JWT vs Session Cookie」
|
||||
```
|
||||
|
||||
### 설계 판단
|
||||
|
||||
```bash
|
||||
/role-debate security,frontend
|
||||
「사용자 인증의 UX 설계」
|
||||
|
||||
/role-debate performance,mobile
|
||||
「데이터 동기화 전략의 최적화」
|
||||
|
||||
/role-debate architect,qa
|
||||
「테스트 전략과 아키텍처 설계」
|
||||
```
|
||||
|
||||
### 트레이드오프 문제
|
||||
|
||||
```bash
|
||||
/role-debate security,performance
|
||||
「암호화 레벨 vs 처리 속도」
|
||||
|
||||
/role-debate frontend,performance
|
||||
「리치 UI vs 페이지 로딩 속도」
|
||||
|
||||
/role-debate mobile,security
|
||||
「편의성 vs 데이터 보호 레벨」
|
||||
```
|
||||
|
||||
### 역할별 토론 특성
|
||||
|
||||
#### 🔒 Security 역할
|
||||
|
||||
```yaml
|
||||
토론 스탠스:
|
||||
- 보수적 접근법 (리스크 최소화)
|
||||
- 규칙 준수 중시 (표준에서의 일탈에 신중)
|
||||
- 최악 케이스 가정 (공격자 관점)
|
||||
- 장기적 영향 중시 (기술적 부채로서의 보안)
|
||||
|
||||
전형적 논점:
|
||||
- "보안 vs 편의성"의 트레이드오프
|
||||
- "규정 준수 요건의 필달"
|
||||
- "공격 비용 vs 방어 비용의 비교"
|
||||
- "프라이버시 보호의 철저화"
|
||||
|
||||
논거 소스:
|
||||
- OWASP 가이드라인
|
||||
- NIST 프레임워크
|
||||
- 업계 표준 (ISO 27001, SOC 2)
|
||||
- 실제 공격 사례·통계
|
||||
|
||||
토론에서의 강점:
|
||||
- 리스크 평가의 정확성
|
||||
- 규제 요건의 지식
|
||||
- 공격 기법에 대한 이해
|
||||
|
||||
주의해야 할 편견:
|
||||
- 과도한 보수성 (이노베이션 저해)
|
||||
- UX 에 대한 배려 부족
|
||||
- 구현 비용의 경시
|
||||
```
|
||||
|
||||
#### ⚡ Performance 역할
|
||||
|
||||
```yaml
|
||||
토론 스탠스:
|
||||
- 데이터 주도 판단 (측정 기반)
|
||||
- 효율성 중시 (비용 대비 효과의 최적화)
|
||||
- 사용자 경험 우선 (체감 속도 중시)
|
||||
- 지속적 개선 (단계적 최적화)
|
||||
|
||||
전형적 논점:
|
||||
- "성능 vs 보안"
|
||||
- "최적화 비용 vs 효과의 투자 대비 효과"
|
||||
- "현재 vs 미래의 확장성"
|
||||
- "사용자 경험 vs 시스템 효율"
|
||||
|
||||
논거 소스:
|
||||
- Core Web Vitals 지표
|
||||
- 벤치마크 결과·통계
|
||||
- 사용자 행동에 대한 영향 데이터
|
||||
- 업계 성능 표준
|
||||
|
||||
토론에서의 강점:
|
||||
- 정량적 평가 능력
|
||||
- 병목 지점 특정
|
||||
- 최적화 기법의 지식
|
||||
|
||||
주의해야 할 편견:
|
||||
- 보안의 경시
|
||||
- 보수성에 대한 배려 부족
|
||||
- 성급한 최적화
|
||||
```
|
||||
|
||||
#### 🏗️ Architect 역할
|
||||
|
||||
```yaml
|
||||
토론 스탠스:
|
||||
- 장기 관점 중시 (시스템 진화에 대한 배려)
|
||||
- 균형 추구 (전체 최적화)
|
||||
- 단계적 변경 (리스크 관리)
|
||||
- 표준 준수 (검증된 패턴 우선)
|
||||
|
||||
전형적 논점:
|
||||
- "단기 효율 vs 장기 보수성"
|
||||
- "기술적 부채 vs 개발 속도"
|
||||
- "마이크로서비스 vs 모놀리스"
|
||||
- "신기술 채택 vs 안정성"
|
||||
|
||||
논거 소스:
|
||||
- 아키텍처 패턴집
|
||||
- 설계 원칙 (SOLID, DDD)
|
||||
- 대규모 시스템 사례
|
||||
- 기술 진화의 트렌드
|
||||
|
||||
토론에서의 강점:
|
||||
- 전체 조망 능력
|
||||
- 설계 패턴의 지식
|
||||
- 장기 영향의 예측
|
||||
|
||||
주의해야 할 편견:
|
||||
- 과도한 일반화
|
||||
- 신기술에 대한 보수성
|
||||
- 구현 세부사항에 대한 이해 부족
|
||||
```
|
||||
|
||||
#### 🎨 Frontend 역할
|
||||
|
||||
```yaml
|
||||
토론 스탠스:
|
||||
- 사용자 중심 설계 (UX 최우선)
|
||||
- 포용적 접근법 (다양성 배려)
|
||||
- 직관성 중시 (학습 비용 최소화)
|
||||
- 접근성 표준 (WCAG 준수)
|
||||
|
||||
전형적 논점:
|
||||
- "사용성 vs 보안"
|
||||
- "디자인 통일 vs 플랫폼 최적화"
|
||||
- "기능성 vs 단순함"
|
||||
- "성능 vs 리치한 경험"
|
||||
|
||||
논거 소스:
|
||||
- UX 연구·사용성 테스트 결과
|
||||
- 접근성 가이드라인
|
||||
- 디자인 시스템 표준
|
||||
- 사용자 행동 데이터
|
||||
|
||||
토론에서의 강점:
|
||||
- 사용자 관점의 대변
|
||||
- 디자인 원칙의 지식
|
||||
- 접근성 요건
|
||||
|
||||
주의해야 할 편견:
|
||||
- 기술 제약에 대한 이해 부족
|
||||
- 보안 요건의 경시
|
||||
- 성능 영향의 과소평가
|
||||
```
|
||||
|
||||
#### 📱 Mobile 역할
|
||||
|
||||
```yaml
|
||||
토론 스탠스:
|
||||
- 플랫폼 특화 (iOS/Android 차이 고려)
|
||||
- 컨텍스트 적응 (이동 중·한 손 조작)
|
||||
- 리소스 제약 (배터리·메모리·통신)
|
||||
- 스토어 준수 (심사 가이드라인)
|
||||
|
||||
전형적 논점:
|
||||
- "네이티브 vs 크로스 플랫폼"
|
||||
- "오프라인 대응 vs 실시간 동기화"
|
||||
- "배터리 효율 vs 기능성"
|
||||
- "플랫폼 통일 vs 최적화"
|
||||
|
||||
논거 소스:
|
||||
- iOS HIG / Android Material Design
|
||||
- App Store / Google Play 가이드라인
|
||||
- 모바일 UX 연구
|
||||
- 디바이스 성능 통계
|
||||
|
||||
토론에서의 강점:
|
||||
- 모바일 특유 제약의 이해
|
||||
- 플랫폼 차이의 지식
|
||||
- 터치 인터페이스 설계
|
||||
|
||||
주의해야 할 편견:
|
||||
- 웹 플랫폼에 대한 이해 부족
|
||||
- 서버 사이드 제약의 경시
|
||||
- 데스크톱 환경에 대한 배려 부족
|
||||
```
|
||||
|
||||
#### 🔍 Analyzer 역할
|
||||
|
||||
```yaml
|
||||
토론 스탠스:
|
||||
- 증거 중시 (데이터 우선)
|
||||
- 가설 검증 (과학적 접근법)
|
||||
- 구조적 사고 (시스템 사고)
|
||||
- 바이어스 제거 (객관성 추구)
|
||||
|
||||
전형적 논점:
|
||||
- "상관관계 vs 인과관계"
|
||||
- "증상 대증요법 vs 근본 해결"
|
||||
- "가설 vs 사실의 구분"
|
||||
- "단기 증상 vs 구조적 문제"
|
||||
|
||||
논거 소스:
|
||||
- 실측 데이터·로그 분석
|
||||
- 통계적 기법·분석 결과
|
||||
- 시스템 사고 이론
|
||||
- 인지 바이어스 연구
|
||||
|
||||
토론에서의 강점:
|
||||
- 논리적 분석 능력
|
||||
- 증거 평가의 객관성
|
||||
- 구조적 문제의 발견
|
||||
|
||||
주의해야 할 편견:
|
||||
- 분석 마비 (행동력 부족)
|
||||
- 완벽주의 (실용성 경시)
|
||||
- 데이터 만능주의
|
||||
```
|
||||
|
||||
### 토론 진행 템플릿
|
||||
|
||||
#### Phase 1: 입장 표명 템플릿
|
||||
|
||||
```text
|
||||
【역할명】의 권장안:
|
||||
「[구체적인 제안]」
|
||||
|
||||
근거:
|
||||
- [공식 문서·표준에 대한 언급]
|
||||
- [실증 사례·데이터]
|
||||
- [전문 분야의 원칙]
|
||||
|
||||
예상 효과:
|
||||
- [단기적 효과]
|
||||
- [중장기적 효과]
|
||||
|
||||
우려·리스크:
|
||||
- [구현 리스크]
|
||||
- [운용 리스크]
|
||||
- [다른 분야에 대한 영향]
|
||||
|
||||
성공 지표:
|
||||
- [측정 가능한 지표 1]
|
||||
- [측정 가능한 지표 2]
|
||||
```
|
||||
|
||||
#### Phase 2: 반박 템플릿
|
||||
|
||||
```text
|
||||
[대상 역할]에 대한 반박:
|
||||
「[대상 제안에 대한 구체적 반박]」
|
||||
|
||||
반박 근거:
|
||||
- [간과된 관점]
|
||||
- [대립하는 증거·사례]
|
||||
- [전문 분야에서의 우려]
|
||||
|
||||
대안:
|
||||
「[개선된 제안]」
|
||||
|
||||
타협 가능한 포인트:
|
||||
- [수용 가능한 조건]
|
||||
- [단계적 구현의 가능성]
|
||||
```
|
||||
|
||||
#### Phase 3: 통합 해결 템플릿
|
||||
|
||||
```text
|
||||
통합 해결안:
|
||||
「[각 역할의 우려를 고려한 최종 제안]」
|
||||
|
||||
각 역할에 대한 배려:
|
||||
- [Security]: [보안 요건의 충족 방법]
|
||||
- [Performance]: [성능 요건의 충족 방법]
|
||||
- [기타]: [기타 요건의 충족 방법]
|
||||
|
||||
구현 로드맵:
|
||||
- 페이즈 1 (즉시): [긴급 대응 사항]
|
||||
- 페이즈 2 (단기): [기본 구현]
|
||||
- 페이즈 3 (중기): [완전 구현]
|
||||
|
||||
성공 지표·측정 방법:
|
||||
- [통합적인 성공 지표]
|
||||
- [측정 방법·빈도]
|
||||
- [재검토 타이밍]
|
||||
```
|
||||
|
||||
### 토론 품질 체크리스트
|
||||
|
||||
#### 논거의 질
|
||||
|
||||
- [ ] 공식 문서·표준에 대한 언급이 있다
|
||||
- [ ] 구체적인 사례·데이터가 제시되고 있다
|
||||
- [ ] 추측과 사실이 명확히 구분되어 있다
|
||||
- [ ] 정보원이 명시되어 있다
|
||||
|
||||
#### 토론의 건설성
|
||||
|
||||
- [ ] 상대의 제안을 정확히 이해하고 있다
|
||||
- [ ] 감정적이 아닌 논리적 반박
|
||||
- [ ] 대안도 제시하고 있다
|
||||
- [ ] Win-Win 의 가능성을 모색하고 있다
|
||||
|
||||
#### 구현 가능성
|
||||
|
||||
- [ ] 기술적 실현 가능성을 고려
|
||||
- [ ] 구현 비용·기간을 견적
|
||||
- [ ] 단계적 구현의 가능성을 검토
|
||||
- [ ] 리스크 경감책을 제시
|
||||
|
||||
#### 통합성
|
||||
|
||||
- [ ] 다른 분야에 대한 영향을 고려
|
||||
- [ ] 전체 최적화를 추구
|
||||
- [ ] 장기적 관점을 포함
|
||||
- [ ] 측정 가능한 성공 지표를 설정
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# 설계 문서를 바탕으로 한 토론
|
||||
cat system-design.md
|
||||
/role-debate architect,security
|
||||
「이 설계의 보안 측면에서의 과제를 토론하세요」
|
||||
|
||||
# 문제를 바탕으로 한 해결책 토론
|
||||
cat performance-issues.md
|
||||
/role-debate performance,architect
|
||||
「성능 문제의 근본적 해결책을 토론하세요」
|
||||
|
||||
# 요건을 바탕으로 한 기술 선정 토론
|
||||
/role-debate mobile,frontend
|
||||
「iOS·Android·Web 의 통일 UI 전략에 대해 토론하세요」
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
- 토론은 시간이 걸릴 수 있습니다 (복잡한 주제일수록 장시간)
|
||||
- 3 개 이상의 역할에서는 토론이 발산할 가능성이 있습니다
|
||||
- 최종 판단은 토론 결과를 참고하여 사용자가 수행하세요
|
||||
- 긴급성이 높은 문제에서는 single role 이나 multi-role 을 먼저 검토하세요
|
||||
276
commands/role-help.md
Normal file
276
commands/role-help.md
Normal file
@@ -0,0 +1,276 @@
|
||||
## Role Help
|
||||
|
||||
어떤 역할을 사용해야 할지 고민될 때의 선택 가이드와 도움말 시스템입니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
/role-help # 전반적인 역할 선택 가이드
|
||||
/role-help <상황/문제> # 특정 상황에서의 권장 역할
|
||||
/role-help compare <역할 1>,<역할 2> # 역할 비교
|
||||
```
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 일반적인 가이던스
|
||||
/role-help
|
||||
→ 이용 가능한 역할과 특징의 목록 표시
|
||||
|
||||
# 상황별 권장
|
||||
/role-help "API 의 보안이 걱정"
|
||||
→ security 역할의 권장과 사용 방법
|
||||
|
||||
# 역할 비교
|
||||
/role-help compare frontend,mobile
|
||||
→ frontend 와 mobile 의 차이와 사용 구분
|
||||
```
|
||||
|
||||
### 상황별 역할 선택 가이드
|
||||
|
||||
### 🔒 보안 관련
|
||||
|
||||
```text
|
||||
이런 때는 security 역할:
|
||||
✅ 로그인·인증 기능의 구현
|
||||
✅ API 의 보안 취약점 체크
|
||||
✅ 데이터 암호화·프라이버시 보호
|
||||
✅ 보안 규정 준수 확인
|
||||
✅ 침입 테스트·펜테스팅
|
||||
|
||||
사용법: /role security
|
||||
```
|
||||
|
||||
### 🏗️ 아키텍처·설계
|
||||
|
||||
```text
|
||||
이런 때는 architect 역할:
|
||||
✅ 시스템 전체의 설계 평가
|
||||
✅ 마이크로서비스 vs 모노리스 판단
|
||||
✅ 데이터베이스 설계·기술 선정
|
||||
✅ 확장성·스케일링 검토
|
||||
✅ 기술적 부채의 평가·개선 계획
|
||||
|
||||
사용법: /role architect
|
||||
```
|
||||
|
||||
### ⚡ 성능 문제
|
||||
|
||||
```text
|
||||
이런 때는 performance 역할:
|
||||
✅ 애플리케이션이 느림
|
||||
✅ 데이터베이스 쿼리 최적화
|
||||
✅ 웹 페이지의 로딩 속도 개선
|
||||
✅ 메모리·CPU 사용량 최적화
|
||||
✅ 스케일링·부하 대책
|
||||
|
||||
사용법: /role performance
|
||||
```
|
||||
|
||||
### 🔍 문제의 원인 조사
|
||||
|
||||
```text
|
||||
이런 때는 analyzer 역할:
|
||||
✅ 버그·에러의 근본 원인 분석
|
||||
✅ 시스템 장애의 원인 규명
|
||||
✅ 복잡한 문제의 구조적 분석
|
||||
✅ 데이터 분석·통계적 조사
|
||||
✅ 왜 이 문제가 발생했는지 해명
|
||||
|
||||
사용법: /role analyzer
|
||||
```
|
||||
|
||||
### 🎨 프론트엔드·UI/UX
|
||||
|
||||
```text
|
||||
이런 때는 frontend 역할:
|
||||
✅ 사용자 인터페이스의 개선
|
||||
✅ 접근성 대응
|
||||
✅ 반응형 디자인
|
||||
✅ 사용성·편의성 향상
|
||||
✅ 웹 프론트엔드 기술 전반
|
||||
|
||||
사용법: /role frontend
|
||||
```
|
||||
|
||||
### 📱 모바일 앱 개발
|
||||
|
||||
```text
|
||||
이런 때는 mobile 역할:
|
||||
✅ iOS·Android 앱의 최적화
|
||||
✅ 모바일 특유의 UX 설계
|
||||
✅ 터치 인터페이스 최적화
|
||||
✅ 오프라인 대응·동기화 기능
|
||||
✅ App Store·Google Play 대응
|
||||
|
||||
사용법: /role mobile
|
||||
```
|
||||
|
||||
### 👀 코드 리뷰·품질
|
||||
|
||||
```text
|
||||
이런 때는 reviewer 역할:
|
||||
✅ 코드의 품질 체크
|
||||
✅ 가독성·유지보수성의 평가
|
||||
✅ 코딩 규약 확인
|
||||
✅ 리팩터링 제안
|
||||
✅ PR·커밋의 리뷰
|
||||
|
||||
사용법: /role reviewer
|
||||
```
|
||||
|
||||
### 🧪 테스트·품질 보증
|
||||
|
||||
```text
|
||||
이런 때는 qa 역할:
|
||||
✅ 테스트 전략 수립
|
||||
✅ 테스트 커버리지 평가
|
||||
✅ 자동 테스트의 구현 방침
|
||||
✅ 버그 방지·품질 향상책
|
||||
✅ CI/CD 에서의 테스트 자동화
|
||||
|
||||
사용법: /role qa
|
||||
```
|
||||
|
||||
### 복수 역할이 필요한 경우
|
||||
|
||||
### 🔄 multi-role (병행 분석)
|
||||
|
||||
```text
|
||||
이런 때는 multi-role:
|
||||
✅ 복수의 전문 관점으로 평가가 필요
|
||||
✅ 통합적인 개선 계획을 세우고 싶음
|
||||
✅ 각 분야의 평가를 비교하고 싶음
|
||||
✅ 모순·중복을 정리하고 싶음
|
||||
|
||||
예: /multi-role security,performance
|
||||
```
|
||||
|
||||
### 🗣️ role-debate (토론)
|
||||
|
||||
```text
|
||||
이런 때는 role-debate:
|
||||
✅ 전문 분야 간 트레이드오프가 있음
|
||||
✅ 기술 선정에서 의견이 갈림
|
||||
✅ 설계 방침을 토론으로 정하고 싶음
|
||||
✅ 다양한 관점의 토론을 듣고 싶음
|
||||
|
||||
예: /role-debate security,performance
|
||||
```
|
||||
|
||||
### 🤖 smart-review (자동 제안)
|
||||
|
||||
```text
|
||||
이런 때는 smart-review:
|
||||
✅ 어떤 역할을 사용해야 할지 모르겠음
|
||||
✅ 현재 상황에 최적인 접근법을 알고 싶음
|
||||
✅ 복수의 선택지 중에서 선택하고 싶음
|
||||
✅ 초보자로서 판단에 고민됨
|
||||
|
||||
예: /smart-review
|
||||
```
|
||||
|
||||
### 역할 비교표
|
||||
|
||||
### 보안계
|
||||
|
||||
| 역할 | 주요 용도 | 장점 분야 | 약점 분야 |
|
||||
| -------- | ---------------- | ---------------------- | ----------------- |
|
||||
| security | 취약점·공격 대책 | 위협 분석, 인증 설계 | UX, 성능 |
|
||||
| analyzer | 근본 원인 분석 | 논리적 분석, 증거 수집 | 예방책, 미래 계획 |
|
||||
|
||||
### 설계계
|
||||
|
||||
| 역할 | 주요 용도 | 장점 분야 | 약점 분야 |
|
||||
| --------- | ----------- | ---------------------- | -------------------- |
|
||||
| architect | 시스템 설계 | 장기 관점, 전체 최적화 | 세부 구현, 단기 해결 |
|
||||
| reviewer | 코드 품질 | 구현 레벨, 유지보수성 | 비즈니스 요건, UX |
|
||||
|
||||
### 성능계
|
||||
|
||||
| 역할 | 주요 용도 | 장점 분야 | 약점 분야 |
|
||||
| ----------- | ------------- | --------------- | -------------- |
|
||||
| performance | 고속화·최적화 | 측정, 병목 지점 | 보안, UX |
|
||||
| qa | 품질 보증 | 테스트, 자동화 | 설계, 아키텍처 |
|
||||
|
||||
### 사용자 경험계
|
||||
|
||||
| 역할 | 주요 용도 | 장점 분야 | 약점 분야 |
|
||||
| -------- | --------- | ------------------- | -------------- |
|
||||
| frontend | Web UI/UX | 브라우저, 접근성 | 서버사이드, DB |
|
||||
| mobile | 모바일 UX | 터치, 오프라인 대응 | 서버사이드, 웹 |
|
||||
|
||||
### 고민될 때의 플로우차트
|
||||
|
||||
```text
|
||||
문제의 성격은?
|
||||
├─ 보안 관련 → security
|
||||
├─ 성능 문제 → performance
|
||||
├─ 버그·장애 조사 → analyzer
|
||||
├─ UI/UX 개선 → frontend or mobile
|
||||
├─ 설계·아키텍처 → architect
|
||||
├─ 코드 품질 → reviewer
|
||||
├─ 테스트 관련 → qa
|
||||
└─ 복합적·복잡 → smart-review 로 제안
|
||||
|
||||
복수 분야에 걸쳐 있는가?
|
||||
├─ 통합 분석하고 싶음 → multi-role
|
||||
├─ 토론·트레이드오프 → role-debate
|
||||
└─ 판단에 고민됨 → smart-review
|
||||
```
|
||||
|
||||
### 자주 묻는 질문
|
||||
|
||||
### Q: frontend 와 mobile 의 차이는?
|
||||
|
||||
```text
|
||||
A:
|
||||
frontend: 웹 브라우저 중심, HTML/CSS/JavaScript
|
||||
mobile: 모바일 앱 중심, iOS/Android 네이티브·React Native 등
|
||||
|
||||
둘 다 관련된 경우는 multi-role frontend,mobile 이 권장
|
||||
```
|
||||
|
||||
### Q: security 와 analyzer 의 사용 구분은?
|
||||
|
||||
```text
|
||||
A:
|
||||
security: 공격·위협의 예방, 보안 설계
|
||||
analyzer: 이미 발생한 문제의 원인 분석, 조사
|
||||
|
||||
보안 인시던트의 조사라면 multi-role security,analyzer
|
||||
```
|
||||
|
||||
### Q: architect 와 performance 의 차이는?
|
||||
|
||||
```text
|
||||
A:
|
||||
architect: 시스템 전체의 장기적 설계, 확장성
|
||||
performance: 구체적인 속도·효율의 개선
|
||||
|
||||
대규모 시스템의 성능 설계라면 multi-role architect,performance
|
||||
```
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# 상황 설명과 조합
|
||||
/role-help
|
||||
「React 앱의 페이지 로딩이 느려서 사용자로부터 불만이 들어오고 있다」
|
||||
|
||||
# 파일 내용과 조합
|
||||
cat problem-description.md
|
||||
/role-help
|
||||
「이 문제에 최적인 역할을 추천하세요」
|
||||
|
||||
# 특정 선택지로 고민하는 경우
|
||||
/role-help compare security,performance
|
||||
「JWT 토큰의 유효기간 문제에서 어느 역할이 적절한가?」
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
- 복잡한 문제일수록 복수 역할의 조합이 효과적입니다
|
||||
- 긴급성이 높은 경우는 single role 로 신속하게 대응
|
||||
- 고민될 때는 smart-review 로 자동 제안을 받는 것을 권장합니다
|
||||
- 최종적인 판단은 사용자가 문제의 성질을 고려하여 결정하세요
|
||||
367
commands/role.md
Normal file
367
commands/role.md
Normal file
@@ -0,0 +1,367 @@
|
||||
## Role
|
||||
|
||||
특정 역할(Role)로 전환하여 전문적인 분석이나 작업을 실행합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
/role <역할명> [--agent|-a]
|
||||
```
|
||||
|
||||
### 옵션
|
||||
|
||||
- `--agent` 또는 `-a` : 서브에이전트로 독립 실행 (대규모 분석 시 권장)
|
||||
- 이 옵션을 사용하면 역할의 description 에 자동 위임 촉진 문구("use PROACTIVELY" 등)가 포함된 경우, 더 적극적인 자동 위임이 활성화됩니다
|
||||
|
||||
### 이용 가능한 역할
|
||||
|
||||
#### 전문 분석 역할 (Evidence-First 통합)
|
||||
|
||||
- `security` : 보안 감사 전문가 (OWASP Top 10·위협 모델링·Zero Trust 원칙·CVE 조회)
|
||||
- `performance` : 성능 최적화 전문가 (Core Web Vitals·RAIL 모델·단계적 최적화·ROI 분석)
|
||||
- `analyzer` : 근본 원인 분석 전문가 (5 Whys·시스템 사고·가설 주도·인지 바이어스 대책)
|
||||
- `frontend` : 프론트엔드·UI/UX 전문가 (WCAG 2.1·디자인 시스템·사용자 중심 설계)
|
||||
- `mobile` : 모바일 개발 전문가 (iOS HIG·Android Material Design·크로스 플랫폼 전략)
|
||||
- `backend` : 백엔드·서버사이드 전문가 (RESTful 설계·확장성·데이터베이스 최적화)
|
||||
|
||||
#### 개발 지원 역할
|
||||
|
||||
- `reviewer` : 코드 리뷰 전문가 (가독성·유지보수성·성능·리팩터링 제안)
|
||||
- `architect` : 시스템 아키텍트 (Evidence-First 설계·MECE 분석·진화적 아키텍처)
|
||||
- `qa` : 테스트 엔지니어 (테스트 커버리지·E2E/통합/단위 전략·자동화 제안)
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 보안 감사 모드로 전환 (일반)
|
||||
/role security
|
||||
「이 프로젝트의 보안 취약점을 체크하세요」
|
||||
|
||||
# 보안 감사를 서브에이전트로 실행 (대규모 분석)
|
||||
/role security --agent
|
||||
「프로젝트 전체의 보안 감사를 실행하세요」
|
||||
|
||||
# 코드 리뷰 모드로 전환
|
||||
/role reviewer
|
||||
「최근 변경사항을 리뷰하여 개선점을 지적하세요」
|
||||
|
||||
# 성능 최적화 모드로 전환
|
||||
/role performance
|
||||
「애플리케이션의 병목 지점을 분석하세요」
|
||||
|
||||
# 근본 원인 분석 모드로 전환
|
||||
/role analyzer
|
||||
「이 장애의 근본 원인을 조사하세요」
|
||||
|
||||
# 프론트엔드 전문 모드로 전환
|
||||
/role frontend
|
||||
「UI/UX 의 개선점을 평가하세요」
|
||||
|
||||
# 모바일 개발 전문 모드로 전환
|
||||
/role mobile
|
||||
「이 앱의 모바일 최적화를 평가하세요」
|
||||
|
||||
# 일반 모드로 복귀
|
||||
/role default
|
||||
「일반적인 Claude 로 돌아갑니다」
|
||||
```
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# 보안 특화 분석
|
||||
/role security
|
||||
cat app.js
|
||||
「이 코드의 잠재적 보안 리스크를 상세히 분석하세요」
|
||||
|
||||
# 아키텍처 관점으로의 평가
|
||||
/role architect
|
||||
ls -la src/
|
||||
「현재 구조의 문제점과 개선안을 제시하세요」
|
||||
|
||||
# 테스트 전략 수립
|
||||
/role qa
|
||||
「이 프로젝트에 최적인 테스트 전략을 제안하세요」
|
||||
```
|
||||
|
||||
### 상세 예제
|
||||
|
||||
```bash
|
||||
# 복수 역할에서의 분석
|
||||
/role security
|
||||
「먼저 보안 관점으로 체크」
|
||||
git diff HEAD~1
|
||||
|
||||
/role reviewer
|
||||
「다음으로 일반적인 코드 품질을 리뷰」
|
||||
|
||||
/role architect
|
||||
「마지막으로 아키텍처 관점으로 평가」
|
||||
|
||||
# 역할별 고유 출력 형식
|
||||
/role security
|
||||
보안 분석 결과
|
||||
━━━━━━━━━━━━━━━━━━━━━
|
||||
취약점: SQL 인젝션
|
||||
심각도: High
|
||||
해당 부분: db.js:42
|
||||
수정안: 매개변수화 쿼리 사용
|
||||
```
|
||||
|
||||
### Evidence-First 통합 기능
|
||||
|
||||
#### 핵심 이념
|
||||
|
||||
각 역할은 **Evidence-First(근거 기반)** 접근법을 채택하여, 추측이 아닌 **검증된 기법·공식 가이드라인·객관적 데이터**에 기반하여 분석·제안을 수행합니다.
|
||||
|
||||
#### 공통 특징
|
||||
|
||||
- **공식 문서 준수**: 각 분야의 권위 있는 공식 가이드라인을 우선 참조
|
||||
- **MECE 분석**: 빠짐없이 중복없이 체계적인 문제 분해
|
||||
- **다각적 평가**: 기술·비즈니스·운용·사용자의 복수 관점
|
||||
- **인지 바이어스 대책**: 확증 바이어스 등의 배제 메커니즘
|
||||
- **토론 특성**: 역할별 고유 전문적 토론 스탠스
|
||||
|
||||
### 전문 분석 역할의 상세
|
||||
|
||||
#### security(보안 감사 전문가)
|
||||
|
||||
**Evidence-Based 보안 감사**
|
||||
|
||||
- OWASP Top 10 · Testing Guide · SAMM 을 통한 체계적 평가
|
||||
- CVE · NVD 데이터베이스 조회를 통한 기지 취약점 체크
|
||||
- STRIDE · Attack Tree · PASTA 을 통한 위협 모델링
|
||||
- Zero Trust 원칙 · 최소 권한을 통한 설계 평가
|
||||
|
||||
**전문적 보고 형식**
|
||||
|
||||
```text
|
||||
Evidence-Based 보안 감사 결과
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
OWASP Top 10 준수도: XX% / CVE 조회: 완료
|
||||
위협 모델링: STRIDE 분석 완료
|
||||
```
|
||||
|
||||
#### performance(성능 최적화 전문가)
|
||||
|
||||
**Evidence-First 성능 최적화**
|
||||
|
||||
- Core Web Vitals(LCP · FID · CLS) · RAIL 모델 준수
|
||||
- Google PageSpeed Insights 권장사항의 구현
|
||||
- 단계적 최적화 프로세스(측정→분석→우선순위→구현)
|
||||
- ROI 분석을 통한 투자 대비 효과의 정량 평가
|
||||
|
||||
**전문적 보고 형식**
|
||||
|
||||
```text
|
||||
Evidence-First 성능 분석
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Core Web Vitals: LCP[XXXms] FID[XXXms] CLS[X.XX]
|
||||
Performance Budget: XX% / ROI 분석: XX% 개선 예측
|
||||
```
|
||||
|
||||
#### analyzer(근본 원인 분석 전문가)
|
||||
|
||||
**Evidence-First 근본 원인 분석**
|
||||
|
||||
- 5 Whys + α기법(반증 검토 포함)
|
||||
- 시스템 사고를 통한 구조 분석(Peter Senge 원칙)
|
||||
- 인지 바이어스 대책(확증 바이어스·앵커링 등의 배제)
|
||||
- 가설 주도 분석의 철저화(복수 가설의 병행 검증)
|
||||
|
||||
**전문적 보고 형식**
|
||||
|
||||
```text
|
||||
Evidence-First 근본 원인 분석
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
분석 신뢰도: 높음 / 바이어스 대책: 실시 완료
|
||||
가설 검증 매트릭스: XX% 확신도
|
||||
```
|
||||
|
||||
#### frontend(프론트엔드 · UI/UX 전문가)
|
||||
|
||||
**Evidence-First 프론트엔드 개발**
|
||||
|
||||
- WCAG 2.1 접근성 준수
|
||||
- Material Design · iOS HIG 공식 가이드라인 준수
|
||||
- 사용자 중심 설계 · 디자인 시스템 표준 적용
|
||||
- A/B 테스트 · 사용자 행동 분석을 통한 검증
|
||||
|
||||
### 개발 지원 역할의 상세
|
||||
|
||||
#### reviewer(코드 리뷰 전문가)
|
||||
|
||||
- 가독성 · 유지보수성 · 성능의 다각적 평가
|
||||
- 코딩 규약 준수 체크 · 리팩터링 제안
|
||||
- 보안 · 접근성의 횡단적 확인
|
||||
|
||||
#### architect(시스템 아키텍트)
|
||||
|
||||
- Evidence-First 설계 원칙 · MECE 분석을 통한 단계적 사고
|
||||
- 진화적 아키텍처 · 복수 관점 평가(기술 · 비즈니스 · 운용 · 사용자)
|
||||
- 공식 아키텍처 패턴 · 베스트 프랙티스 참조
|
||||
|
||||
#### qa(테스트 엔지니어)
|
||||
|
||||
- 테스트 커버리지 분석 · E2E/통합/단위 테스트 전략
|
||||
- 테스트 자동화 제안 · 품질 지표 설계
|
||||
|
||||
#### mobile(모바일 개발 전문가)
|
||||
|
||||
- iOS HIG · Android Material Design 공식 가이드라인 준수
|
||||
- 크로스 플랫폼 전략 · Touch-First 설계
|
||||
- 스토어 심사 가이드라인 · 모바일 특화 UX 최적화
|
||||
|
||||
#### backend (백엔드·서버사이드 전문가)
|
||||
|
||||
- RESTful/GraphQL API 설계·도메인 주도 설계·클린 아키텍처
|
||||
- 확장성·장애 내성·성능 최적화
|
||||
- 데이터베이스 최적화·캐시 전략·신뢰성 향상
|
||||
|
||||
### 역할별 고유 토론 특성
|
||||
|
||||
각 역할은 전문 분야에 따른 독자적인 토론 스탠스 · 논거 소스 · 강점을 갖습니다.
|
||||
|
||||
#### security 역할의 토론 특성
|
||||
|
||||
- **스탠스**: 보수적 접근법 · 리스크 최소화 우선 · 최악의 경우 가정
|
||||
- **논거**: OWASP 가이드라인 · NIST 프레임워크 · 실제 공격 사례
|
||||
- **강점**: 리스크 평가의 정확성 · 규제 요건의 깊은 지식 · 공격 기법을 포괄적으로 이해
|
||||
- **주의**: 과도한 보수성 · UX 에 대한 배려 부족 · 구현 비용의 경시
|
||||
|
||||
#### performance 역할의 토론 특성
|
||||
|
||||
- **스탠스**: 데이터 주도 판단 · 효율성 중시 · 사용자 경험 우선 · 지속적 개선
|
||||
- **논거**: Core Web Vitals · 벤치마크 결과 · 사용자 행동 데이터 · 업계 표준
|
||||
- **강점**: 정량적 평가 능력 · 병목 지점 특정의 정확성 · ROI 분석
|
||||
- **주의**: 보안의 경시 · 유지보수성에 대한 배려 부족 · 측정 편중
|
||||
|
||||
#### analyzer 역할의 토론 특성
|
||||
|
||||
- **스탠스**: 증거 중시 · 가설 검증 · 구조적 사고 · 바이어스 제거
|
||||
- **논거**: 실측 데이터 · 통계적 기법 · 시스템 사고 이론 · 인지 바이어스 연구
|
||||
- **강점**: 논리적 분석 능력 · 증거 평가의 객관성 · 구조적 문제의 발견력
|
||||
- **주의**: 분석 마비 · 완벽주의 · 데이터 만능주의 · 과도한 회의주의
|
||||
|
||||
#### frontend 역할의 토론 특성
|
||||
|
||||
- **스탠스**: 사용자 중심 · 접근성 중시 · 디자인 원칙 준수 · 경험 가치 우선
|
||||
- **논거**: UX 조사 · 접근성 표준 · 디자인 시스템 · 사용성 테스트
|
||||
- **강점**: 사용자 관점 · 디자인 원칙 · 접근성 · 경험 설계
|
||||
- **주의**: 기술 제약의 경시 · 성능에 대한 배려 부족 · 구현 복잡성
|
||||
|
||||
### 멀티 역할 협조의 효과
|
||||
|
||||
다양한 토론 특성을 가진 역할의 조합으로 균형잡힌 분석이 가능:
|
||||
|
||||
#### 전형적인 협조 패턴
|
||||
|
||||
- **security + frontend**: 보안과 사용성의 균형
|
||||
- **performance + security**: 속도와 안전성의 양립
|
||||
- **analyzer + architect**: 문제 분석 및 구조 설계의 통합
|
||||
- **reviewer + qa**: 코드 품질과 테스트 전략의 연계
|
||||
|
||||
## 고급 역할 기능
|
||||
|
||||
### 지능적 역할 선택
|
||||
|
||||
- `/smart-review` : 프로젝트 분석을 통한 자동 역할 제안
|
||||
- `/role-help` : 상황에 따른 최적 역할 선택 가이드
|
||||
|
||||
### 멀티 역할 협조
|
||||
|
||||
- `/multi-role <역할 1>,<역할 2>` : 복수 역할 동시 분석
|
||||
- `/role-debate <역할 1>,<역할 2>` : 역할 간 토론
|
||||
|
||||
### 사용 예제
|
||||
|
||||
#### 자동 역할 제안
|
||||
|
||||
```bash
|
||||
/smart-review
|
||||
→ 현재 상황을 분석하여 최적인 역할을 제안
|
||||
|
||||
/smart-review src/auth/
|
||||
→ 인증 관련 파일에서 security 역할을 권장
|
||||
```
|
||||
|
||||
#### 복수 역할 분석
|
||||
|
||||
```bash
|
||||
/multi-role security,performance
|
||||
「이 API 를 여러 관점으로 평가하세요」
|
||||
→ 보안과 성능 양면에서 통합 분석
|
||||
|
||||
/role-debate frontend,security
|
||||
「2 단계 인증의 UX 에 대해 토론하세요」
|
||||
→ 사용성과 보안 관점으로 토론
|
||||
```
|
||||
|
||||
#### 역할 선택에 고민될 때
|
||||
|
||||
```bash
|
||||
/role-help "API 가 느리고 보안도 걱정"
|
||||
→ 적절한 접근법(multi-role 이나 debate)을 제안
|
||||
|
||||
/role-help compare frontend,mobile
|
||||
→ 프론트엔드와 모바일 역할의 차이와 사용 구분
|
||||
```
|
||||
|
||||
## 주의사항
|
||||
|
||||
### 역할 동작에 대해
|
||||
|
||||
- 역할을 전환하면 Claude 의 **행동·우선사항·분석 기법·보고 형식**이 전문 특화됩니다
|
||||
- 각 역할은 **Evidence-First 접근법**으로 공식 가이드라인·검증된 기법을 우선 적용
|
||||
- `default`로 일반 모드로 돌아갑니다(역할 특화가 해제됩니다)
|
||||
- 역할은 현재 세션 내에서만 유효합니다
|
||||
|
||||
### 효과적인 활용 방법
|
||||
|
||||
- **단순한 문제**: 단일 역할로 충분한 전문 분석
|
||||
- **복잡한 문제**: multi-role 이나 role-debate 로 다각적 분석이 효과적
|
||||
- **고민될 때**: smart-review 나 role-help 를 이용하세요
|
||||
- **지속적 개선**: 같은 역할이라도 새로운 증거·기법으로 분석 정확도가 향상
|
||||
|
||||
### 서브에이전트 기능 (--agent 옵션)
|
||||
|
||||
대규모 분석이나 독립적인 전문 처리가 필요한 경우, `--agent` 옵션을 사용하여 역할을 서브에이전트로 실행할 수 있습니다.
|
||||
|
||||
#### 메리트
|
||||
|
||||
- **독립 컨텍스트**: 메인 대화를 방해하지 않음
|
||||
- **병렬 실행**: 복수 분석을 동시 실행 가능
|
||||
- **전문 특화**: 더 깊은 분석 및 상세한 보고서
|
||||
- **자동 위임의 촉진**: 역할의 description 에 "use PROACTIVELY"나 "MUST BE USED"가 포함된 경우, 더 적극적인 자동 위임이 활성화
|
||||
|
||||
#### 권장되는 사용 상황
|
||||
|
||||
```bash
|
||||
# 보안: OWASP 전 항목 체크, CVE 조회
|
||||
/role security --agent
|
||||
「전체 코드베이스의 보안 감사」
|
||||
|
||||
# 애널라이저: 대량 로그의 근본 원인 분석
|
||||
/role analyzer --agent
|
||||
「지난 1 주간의 에러 로그를 분석」
|
||||
|
||||
# 리뷰어: 대규모 PR 의 상세 리뷰
|
||||
/role reviewer --agent
|
||||
「PR #500 의 1000 행 변경사항을 리뷰」
|
||||
```
|
||||
|
||||
#### 일반 역할 vs 서브에이전트
|
||||
|
||||
| 상황 | 권장 | 명령어 |
|
||||
| ------------- | ------------ | ------------------------ |
|
||||
| 간단한 확인 | 일반 역할 | `/role security` |
|
||||
| 대규모 분석 | 서브에이전트 | `/role security --agent` |
|
||||
| 대화형 작업 | 일반 역할 | `/role frontend` |
|
||||
| 독립적인 감사 | 서브에이전트 | `/role qa --agent` |
|
||||
|
||||
### 역할 설정의 상세
|
||||
|
||||
- 각 역할의 상세 설정·전문 지식·토론 특성은 `.claude/agents/roles/` 디렉터리 내에서 정의
|
||||
- Evidence-First 기법·인지 바이어스 대책도 포함
|
||||
- 역할별 고유 트리거 문구로 자동적으로 특화 모드가 활성화
|
||||
- 실제 역할 파일은 200 행 초과의 전문적 내용으로 구성
|
||||
103
commands/screenshot.md
Normal file
103
commands/screenshot.md
Normal file
@@ -0,0 +1,103 @@
|
||||
## Screenshot
|
||||
|
||||
macOS 에서 스크린샷을 촬영하고 이미지를 분석합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
/screenshot [옵션]
|
||||
```
|
||||
|
||||
### 옵션
|
||||
|
||||
- 없음 : 윈도우를 선택 (Claude 가 옵션을 확인)
|
||||
- `--window` : 윈도우를 지정하여 촬영
|
||||
- `--full` : 화면 전체를 촬영
|
||||
- `--crop` : 범위를 선택하여 촬영
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 윈도우를 촬영하여 분석
|
||||
/screenshot --window
|
||||
「촬영한 화면을 분석하세요」
|
||||
|
||||
# 범위를 선택하여 분석
|
||||
/screenshot --crop
|
||||
「선택한 범위의 내용을 설명하세요」
|
||||
|
||||
# 전체 화면을 촬영하여 분석
|
||||
/screenshot --full
|
||||
「화면 전체의 구성을 분석하세요」
|
||||
```
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# 특정 문제 없음 - 상황 분석
|
||||
/screenshot --crop
|
||||
(Claude 가 자동으로 화면 내용을 분석하여 요소나 구성을 설명)
|
||||
|
||||
# UI/UX 문제 분석
|
||||
/screenshot --window
|
||||
「이 UI 의 문제점과 개선안을 제안하세요」
|
||||
|
||||
# 에러 분석
|
||||
/screenshot --window
|
||||
「이 에러 메시지의 원인과 해결 방법을 알려주세요」
|
||||
|
||||
# 디자인 리뷰
|
||||
/screenshot --full
|
||||
「이 디자인을 UX 관점으로 평가하세요」
|
||||
|
||||
# 코드 분석
|
||||
/screenshot --crop
|
||||
「이 코드의 문제점을 지적하세요」
|
||||
|
||||
# 데이터 시각화 분석
|
||||
/screenshot --crop
|
||||
「이 그래프에서 읽을 수 있는 경향을 분석하세요」
|
||||
```
|
||||
|
||||
### 상세 예제
|
||||
|
||||
```bash
|
||||
# 여러 관점으로 분석
|
||||
/screenshot --window
|
||||
「이 화면에 대해 다음을 분석하세요:
|
||||
1. UI 의 일관성
|
||||
2. 접근성 문제
|
||||
3. 개선 제안」
|
||||
|
||||
# 비교 분석용으로 복수 촬영
|
||||
/screenshot --window
|
||||
# (before 이미지를 저장)
|
||||
# 변경을 가함
|
||||
/screenshot --window
|
||||
# (after 이미지를 저장)
|
||||
「before 와 after 이미지를 비교하여 변경점과 개선 효과를 분석하세요」
|
||||
|
||||
# 특정 요소에 포커스
|
||||
/screenshot --crop
|
||||
「선택한 버튼의 디자인이 다른 요소와 조화를 이루고 있는지 평가하세요」
|
||||
```
|
||||
|
||||
### 금지 사항
|
||||
|
||||
- **스크린샷을 촬영하지 않았는데 「촬영했습니다」라고 말하는 것은 금지**
|
||||
- **존재하지 않는 이미지 파일의 분석을 시도하는 것은 금지**
|
||||
- **`/screenshot` 명령어는 실제 스크린샷 촬영을 수행하지 않음**
|
||||
|
||||
### 주의사항
|
||||
|
||||
- 옵션을 지정하지 않은 경우, 다음 선택지를 제시하세요:
|
||||
|
||||
```
|
||||
「어떤 방법으로 스크린샷을 촬영하시겠습니까?
|
||||
1. 윈도우를 선택 (--window) → screencapture -W
|
||||
2. 화면 전체 (--full) → screencapture -x
|
||||
3. 범위를 선택 (--crop) → screencapture -i」
|
||||
```
|
||||
|
||||
- 사용자가 screencapture 명령을 실행한 후에 이미지 분석을 시작하세요
|
||||
- 구체적인 문제나 관점을 지정하면 더 집중된 분석이 가능합니다
|
||||
66
commands/search-gemini.md
Normal file
66
commands/search-gemini.md
Normal file
@@ -0,0 +1,66 @@
|
||||
## Gemini Web Search
|
||||
|
||||
Gemini CLI 로 웹 검색을 실행하여 최신 정보를 취득합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# Gemini CLI 경유로 웹 검색 (필수)
|
||||
gemini --prompt "WebSearch: <검색 쿼리>"
|
||||
```
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# Gemini CLI 사용
|
||||
gemini --prompt "WebSearch: React 19 신기능"
|
||||
gemini --prompt "WebSearch: TypeError Cannot read property of undefined 해결방법"
|
||||
```
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# 문서 검색과 요약
|
||||
gemini --prompt "WebSearch: Next.js 14 App Router 공식 문서"
|
||||
「검색 결과를 요약하여 주요 기능을 설명하세요」
|
||||
|
||||
# 에러 조사
|
||||
cat error.log
|
||||
gemini --prompt "WebSearch: [에러메시지] 해결방법"
|
||||
「검색 결과에서 가장 적절한 해결방법을 제안하세요」
|
||||
|
||||
# 기술 비교
|
||||
gemini --prompt "WebSearch: Rust vs Go performance benchmark 2024"
|
||||
「검색 결과에서 성능 차이를 정리하세요」
|
||||
```
|
||||
|
||||
### 상세 예제
|
||||
|
||||
```bash
|
||||
# 복수 소스로부터 정보 수집
|
||||
gemini --prompt "WebSearch: GraphQL best practices 2024 multiple sources"
|
||||
「검색 결과에서 복수의 신뢰할 수 있는 소스의 정보를 정리하세요」
|
||||
|
||||
# 시계열 변화를 조사
|
||||
gemini --prompt "WebSearch: JavaScript ES2015 ES2016 ES2017 ES2018 ES2019 ES2020 ES2021 ES2022 ES2023 ES2024 features"
|
||||
「각 버전의 주요 변경사항을 시계열로 정리하세요」
|
||||
|
||||
# 특정 도메인으로 한정한 검색
|
||||
gemini --prompt "WebSearch: site:github.com Rust WebAssembly projects stars:>1000"
|
||||
「스타 수가 많은 순으로 10 개 프로젝트를 리스트업하세요」
|
||||
|
||||
# 최신 보안 정보
|
||||
gemini --prompt "WebSearch: CVE-2024 Node.js vulnerabilities"
|
||||
「발견된 취약점의 영향과 대책을 정리하세요」
|
||||
```
|
||||
|
||||
### 금지 사항
|
||||
|
||||
- **Claude 의 내장 WebSearch 도구 사용은 금지**
|
||||
- 웹 검색이 필요한 경우는 반드시 `gemini --prompt "WebSearch: ..."`를 사용할 것
|
||||
|
||||
### 주의사항
|
||||
|
||||
- **Gemini CLI 가 이용 가능한 경우는 반드시 `gemini --prompt "WebSearch: ..."`를 사용하세요**
|
||||
- 웹 검색 결과는 항상 최신이라고 할 수 없습니다
|
||||
- 중요한 정보는 공식 문서나 신뢰할 수 있는 소스에서 확인하는 것을 권장합니다
|
||||
1137
commands/semantic-commit.md
Normal file
1137
commands/semantic-commit.md
Normal file
File diff suppressed because it is too large
Load Diff
90
commands/sequential-thinking.md
Normal file
90
commands/sequential-thinking.md
Normal file
@@ -0,0 +1,90 @@
|
||||
## Sequential Thinking
|
||||
|
||||
동적이고 반복적인 사고 프로세스를 통해 복잡한 문제를 단계적으로 해결합니다. 사고 도중에 방향 전환이나 재검토가 가능한 유연한 접근법입니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# Claude 에 단계적 사고를 의뢰
|
||||
「[과제]에 대해 sequential-thinking 으로 검토하세요」
|
||||
```
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 알고리즘 설계
|
||||
「효율적인 캐시 전략을 sequential-thinking 으로 설계하세요」
|
||||
|
||||
# 문제 해결
|
||||
「데이터베이스 성능 문제를 sequential-thinking 으로 해결하세요」
|
||||
|
||||
# 설계 검토
|
||||
「실시간 알림 시스템의 설계를 sequential-thinking 으로 검토하세요」
|
||||
```
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# 복잡한 구현 방침
|
||||
「인증 시스템의 구현 방침을 sequential-thinking 으로 검토하세요. OAuth2, JWT, 세션 관리를 고려해서」
|
||||
|
||||
# 버그 원인 분석
|
||||
「메모리 누수의 원인을 sequential-thinking 으로 분석하세요. 코드 리뷰와 프로파일링 결과를 포함해서」
|
||||
|
||||
# 리팩터링 전략
|
||||
cat src/complex_module.js
|
||||
「이 모듈의 리팩터링 전략을 sequential-thinking 으로 수립하세요」
|
||||
|
||||
# 기술 선정
|
||||
「프론트엔드 프레임워크의 선택을 sequential-thinking 으로 분석하세요. 프로젝트 요건과 제약을 고려해서」
|
||||
```
|
||||
|
||||
### 사고 프로세스
|
||||
|
||||
1. **초기 분석** - 문제의 기본적인 이해와 분해
|
||||
2. **가설 생성** - 해결안의 가설을 세움
|
||||
3. **검증과 수정** - 가설을 검증하고 필요에 따라 수정
|
||||
4. **분기와 탐색** - 복수의 해결 경로를 탐색
|
||||
5. **통합과 결론** - 최적해를 도출
|
||||
|
||||
### 특징
|
||||
|
||||
- **동적 조정** - 사고 도중에 방향 전환 가능
|
||||
- **가설 검증** - 가설을 세우고 검증하는 사이클
|
||||
- **분기 사고** - 복수의 사고 경로를 동시에 탐색
|
||||
- **단계적 세련화** - 단계적으로 해결안을 세련화
|
||||
- **유연성** - 새로운 정보기반의 방침 변경
|
||||
|
||||
### 상세 예제
|
||||
|
||||
```bash
|
||||
# 복잡한 시스템 설계
|
||||
「EC 사이트의 마이크로서비스 설계를 sequential-thinking 으로 검토하세요. 주문 처리, 재고 관리, 결제의 연계를 포함해서」
|
||||
|
||||
# 보안 설계
|
||||
「API 보안의 설계를 sequential-thinking 으로 검토하세요. 인증, 인가, 레이트 제한, 감사 로그를 포함해서」
|
||||
|
||||
# 성능 최적화
|
||||
「대규모 데이터 처리의 최적화를 sequential-thinking 으로 검토하세요. 메모리 사용량, 처리 속도, 확장성을 고려해서」
|
||||
|
||||
# 종속성 관리
|
||||
「모노레포의 종속성 관리 전략을 sequential-thinking 으로 검토하세요. 빌드 시간, 배포, 테스트 실행을 포함해서」
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
sequential-thinking 은 단계적으로 사고를 심화시킬 필요가 있는 복잡한 문제에 최적입니다. 단순한 질문이나 명확한 답이 있는 경우는 일반적인 질문 형식을 사용하세요.
|
||||
|
||||
### 실행 예제
|
||||
|
||||
```bash
|
||||
# 사용 예제
|
||||
「GraphQL 스키마의 설계를 sequential-thinking 으로 검토하세요」
|
||||
|
||||
# 예상되는 동작
|
||||
# 1. 초기 분석: GraphQL 스키마의 기본 요건을 분석
|
||||
# 2. 가설 생성: 복수의 설계 패턴을 검토
|
||||
# 3. 검증: 각 패턴의 장점·단점을 검증
|
||||
# 4. 분기: 필요에 따라 새로운 접근법을 탐색
|
||||
# 5. 통합: 최적인 스키마 설계를 제안
|
||||
```
|
||||
59
commands/show-plan.md
Normal file
59
commands/show-plan.md
Normal file
@@ -0,0 +1,59 @@
|
||||
## Show Plan
|
||||
|
||||
현재 세션에서 실행 중이거나 실행한 계획을 표시합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
/show-plan
|
||||
```
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 현재 계획을 확인
|
||||
/show-plan
|
||||
「실행 중인 계획을 표시」
|
||||
|
||||
# 계획이 없는 경우
|
||||
/show-plan
|
||||
「현재 세션에 계획이 없습니다」
|
||||
```
|
||||
|
||||
### 기능
|
||||
|
||||
- exit_plan_mode 로 생성된 계획을 검출
|
||||
- 실행계획, 실행내용, 플랜 등의 키워드를 포함하는 제목을 탐색
|
||||
- 계획의 내용을 정리하여 표시
|
||||
- 계획이 없는 경우 명확히 그 취지를 알림
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# 구현 도중에 계획을 확인
|
||||
「뭘 구현하고 있었지?」
|
||||
/show-plan
|
||||
|
||||
# 복수의 작업을 실행 중
|
||||
「지금 계획을 다시 한번 확인시켜줘」
|
||||
/show-plan
|
||||
|
||||
# 계획 실행 후 회고
|
||||
「아까 실행한 계획의 내용을 보여줘」
|
||||
/show-plan
|
||||
```
|
||||
|
||||
### 검출 패턴
|
||||
|
||||
exit_plan_mode 로 생성되는 계획의 형식에 기반하여 다음 패턴을 검출:
|
||||
|
||||
- `##`로 시작하는 제목 (계획, 플랜, Plan 을 포함)
|
||||
- `### 변경 내용`
|
||||
- `### 구현 내용`
|
||||
- `### 실행 계획`
|
||||
- `### 1.` 등의 번호 부여 제목
|
||||
|
||||
### 주의사항
|
||||
|
||||
- 현재 세션 내의 계획만 표시 (과거 세션은 포함하지 않음)
|
||||
- 최신 계획을 우선적으로 표시
|
||||
174
commands/smart-review.md
Normal file
174
commands/smart-review.md
Normal file
@@ -0,0 +1,174 @@
|
||||
## Smart Review
|
||||
|
||||
현재 상황을 분석하여 최적인 역할·접근법을 자동 제안하는 명령어입니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
/smart-review # 현재 디렉터리를 분석
|
||||
/smart-review <파일/디렉터리> # 특정 대상을 분석
|
||||
```
|
||||
|
||||
### 자동 판정 로직
|
||||
|
||||
### 파일 확장자를 통한 판정
|
||||
|
||||
- `package.json`, `*.tsx`, `*.jsx`, `*.css`, `*.scss` → **frontend**
|
||||
- `Dockerfile`, `docker-compose.yml`, `*.yaml` → **architect**
|
||||
- `*.test.js`, `*.spec.ts`, `test/`, `__tests__/` → **qa**
|
||||
- `*.rs`, `Cargo.toml`, `performance/` → **performance**
|
||||
|
||||
### 보안 관련 파일 검출
|
||||
|
||||
- `auth.js`, `security.yml`, `.env`, `config/auth/` → **security**
|
||||
- `login.tsx`, `signup.js`, `jwt.js` → **security + frontend**
|
||||
- `api/auth/`, `middleware/auth/` → **security + architect**
|
||||
|
||||
### 복합 판정 패턴
|
||||
|
||||
- `mobile/` + `*.swift`, `*.kt`, `react-native/` → **mobile**
|
||||
- `webpack.config.js`, `vite.config.js`, `large-dataset/` → **performance**
|
||||
- `components/` + `responsive.css` → **frontend + mobile**
|
||||
- `api/` + `auth/` → **security + architect**
|
||||
|
||||
### 에러·문제 분석
|
||||
|
||||
- 스택 트레이스, `error.log`, `crash.log` → **analyzer**
|
||||
- `memory leak`, `high CPU`, `slow query` → **performance + analyzer**
|
||||
- `SQL injection`, `XSS`, `CSRF` → **security + analyzer**
|
||||
|
||||
### 제안 패턴
|
||||
|
||||
### 단일 역할 제안
|
||||
|
||||
```bash
|
||||
$ /smart-review src/auth/login.js
|
||||
→ 「인증 파일을 검출했습니다」
|
||||
→ 「security 역할에서의 분석을 권장합니다」
|
||||
→ 「실행하시겠습니까? [y]es / [n]o / [m]ore options」
|
||||
```
|
||||
|
||||
### 복수 역할 제안
|
||||
|
||||
```bash
|
||||
$ /smart-review src/mobile/components/
|
||||
→ 「📱🎨 모바일 + 프론트엔드 요소를 검출」
|
||||
→ 「권장 접근법:」
|
||||
→ 「[1] mobile 역할 단체」
|
||||
→ 「[2] frontend 역할 단체」
|
||||
→ 「[3] multi-role mobile,frontend」
|
||||
→ 「[4] role-debate mobile,frontend」
|
||||
```
|
||||
|
||||
### 문제 분석 시 제안
|
||||
|
||||
```bash
|
||||
$ /smart-review error.log
|
||||
→ 「⚠️ 에러 로그를 검출했습니다」
|
||||
→ 「analyzer 역할로 근본 원인 분석을 시작합니다」
|
||||
→ 「[자동 실행] /role analyzer」
|
||||
|
||||
$ /smart-review slow-api.log
|
||||
→ 「🐌 성능 문제를 검출」
|
||||
→ 「권장: [1]/role performance [2]/role-debate performance,analyzer」
|
||||
```
|
||||
|
||||
### 복잡한 설계 결정 시 제안
|
||||
|
||||
```bash
|
||||
$ /smart-review architecture-design.md
|
||||
→ 「🏗️🔒⚡ 아키텍처 + 보안 + 성능 요소 검출」
|
||||
→ 「복잡한 설계 결정을 위해 토론 형식을 권장합니다」
|
||||
→ 「[권장] /role-debate architect,security,performance」
|
||||
→ 「[대안] /multi-role architect,security,performance」
|
||||
```
|
||||
|
||||
### 제안 로직의 상세
|
||||
|
||||
### 우선순위 판정
|
||||
|
||||
1. **Security** - 인증·인가·암호화 관련은 최우선
|
||||
2. **Critical Errors** - 시스템 정지·데이터 손실은 긴급
|
||||
3. **Architecture** - 대규모 변경·기술 선정은 신중 검토
|
||||
4. **Performance** - 사용자 경험에 직결
|
||||
5. **Frontend/Mobile** - UI/UX 개선
|
||||
6. **QA** - 품질 보증·테스트 관련
|
||||
|
||||
### 토론 권장 조건
|
||||
|
||||
- 3 개 이상의 역할이 관련된 경우
|
||||
- 보안 vs 성능의 트레이드오프가 있는 경우
|
||||
- 아키텍처의 대폭 변경이 포함된 경우
|
||||
- 모바일 + 웹 양쪽에 영향이 있는 경우
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 현재 디렉터리를 분석
|
||||
/smart-review
|
||||
「최적인 역할과 접근법을 제안하세요」
|
||||
|
||||
# 특정 파일을 분석
|
||||
/smart-review src/auth/login.js
|
||||
「이 파일에 최적인 리뷰 방법을 제안하세요」
|
||||
|
||||
# 에러 로그를 분석
|
||||
/smart-review error.log
|
||||
「이 에러의 해결에 최적인 접근법을 제안하세요」
|
||||
```
|
||||
|
||||
### 실제 예제
|
||||
|
||||
### 프로젝트 전체의 분석
|
||||
|
||||
```bash
|
||||
$ /smart-review
|
||||
→ 「📊 프로젝트 분석 중...」
|
||||
→ 「React + TypeScript 프로젝트를 검출」
|
||||
→ 「인증 기능 + API + 모바일 대응을 확인」
|
||||
→ 「」
|
||||
→ 「💡 권장 워크플로우:」
|
||||
→ 「1. security 로 인증계 체크」
|
||||
→ 「2. frontend 로 UI/UX 평가」
|
||||
→ 「3. mobile 로 모바일 최적화 확인」
|
||||
→ 「4. architect 로 전체 설계 리뷰」
|
||||
→ 「」
|
||||
→ 「자동 실행하시겠습니까? [y]es / [s]elect role / [c]ustom」
|
||||
```
|
||||
|
||||
### 특정 문제의 분석
|
||||
|
||||
```bash
|
||||
$ /smart-review "JWT 의 유효기간을 어떻게 설정해야 할까"
|
||||
→ 「🤔 기술적인 설계 판단을 검출」
|
||||
→ 「복수의 전문 관점이 필요한 문제입니다」
|
||||
→ 「」
|
||||
→ 「권장 접근법:」
|
||||
→ 「/role-debate security,performance,frontend」
|
||||
→ 「이유: 보안·성능·UX 의 균형이 중요」
|
||||
```
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# 파일 내용과 조합한 분석
|
||||
cat src/auth/middleware.js
|
||||
/smart-review
|
||||
「이 파일의 내용을 포함해서 보안 관점으로 분석하세요」
|
||||
|
||||
# 에러와 조합한 분석
|
||||
npm run build 2>&1 | tee build-error.log
|
||||
/smart-review build-error.log
|
||||
「빌드 에러의 해결방법을 제안하세요」
|
||||
|
||||
# 설계 상담
|
||||
/smart-review
|
||||
「React Native 와 Progressive Web App 중 어느 것을 선택해야 할지 토론하세요」
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
- 제안은 참고 정보입니다. 최종적인 판단은 사용자가 수행하세요
|
||||
- 복잡한 문제일수록 토론 형식(role-debate)을 권장합니다
|
||||
- 단순한 문제는 single role 로 충분한 경우가 많습니다
|
||||
- 보안 관련은 반드시 전문 역할에서의 확인을 권장합니다
|
||||
549
commands/spec.md
Normal file
549
commands/spec.md
Normal file
@@ -0,0 +1,549 @@
|
||||
## 스펙 작성
|
||||
|
||||
**"코드를 작성하기 전에 구조를 부여한다"** - Kiro 의 spec-driven development 에 완전 준수
|
||||
|
||||
기존의 코드 생성 도구와 달리, 개발의 혼돈에 구조를 부여하는 것에 중점을 둔 Kiro 의 사양 주도 개발을 실현. 최소한의 요구사항 입력에서 프로덕트 매니저 수준의 상세한 사양과 구현 가능한 설계까지 단계적으로 전개하여, **프로토타입부터 프로덕션 환경**까지 일관된 품질을 보장합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# Claude 에게 Spec Mode 의뢰 (최소한의 요구사항 입력)
|
||||
"[기능 설명]의 spec 을 만들어주세요"
|
||||
|
||||
# Kiro 식 단계적 전개:
|
||||
# 1. 간단한 요구사항 → 상세한 사용자 스토리 자동 생성
|
||||
# 2. EARS 표기법을 통한 구조화된 요구사항 기술
|
||||
# 3. 단계적 대화를 통한 사양의 정교화
|
||||
# 4. 3 개의 독립적인 파일을 생성:
|
||||
# - requirements.md: EARS 표기법을 통한 요구사항 정의
|
||||
# - design.md: Mermaid 다이어그램·TypeScript 인터페이스 포함 설계
|
||||
# - tasks.md: 베스트 프랙티스 자동 적용의 구현 계획
|
||||
```
|
||||
|
||||
### 실증된 효과 (Kiro 실적)
|
||||
|
||||
**2 일 만에 보안 파일 공유 앱**
|
||||
|
||||
```bash
|
||||
"파일 공유 시스템(암호화 대응)의 spec 을 만들어주세요"
|
||||
→ 2 일 만에 프로덕션 수준의 암호화 파일 공유 애플리케이션 완성
|
||||
→ 보안 베스트 프랙티스 자동 적용
|
||||
→ 추가 프롬프트 불필요
|
||||
```
|
||||
|
||||
**하룻밤에 게임 개발 (미경험자)**
|
||||
|
||||
```bash
|
||||
"2D 퍼즐 게임의 spec 을 만들어주세요"
|
||||
→ 게임 개발 미경험의 오픈소스 개발자
|
||||
→ 하룻밤에 게임 작성 완료
|
||||
→ 구현 로직은 Kiro 가 처리, 개발자는 창조성에 집중
|
||||
```
|
||||
|
||||
**주말에 프로토타입→프로덕션**
|
||||
|
||||
```bash
|
||||
"쇼핑몰 상품 관리 시스템의 spec 을 만들어주세요"
|
||||
→ 한 주말에 컨셉부터 동작하는 프로토타입까지
|
||||
→ 프로토타입부터 프로덕션 환경까지의 일관된 품질
|
||||
→ spec-driven development 을 통한 구조화된 접근
|
||||
```
|
||||
|
||||
### 기본 예시
|
||||
|
||||
```bash
|
||||
# 새 기능의 spec 작성 (최소한 입력)
|
||||
"상품 리뷰 시스템
|
||||
- 별점 기능
|
||||
- 댓글 게시
|
||||
- 이미지 업로드"
|
||||
|
||||
# 시스템 기능의 spec 작성
|
||||
"사용자 인증
|
||||
- OAuth 대응
|
||||
- 다중 인증"
|
||||
|
||||
# API 기능의 spec 작성
|
||||
"결제 시스템 API
|
||||
- Stripe 연동
|
||||
- 보안 중시"
|
||||
```
|
||||
|
||||
### Claude 와의 연동
|
||||
|
||||
```bash
|
||||
# 복잡한 기능 spec
|
||||
"채팅 기능의 spec 을 만들어주세요. WebSocket, 실시간 알림, 히스토리 관리를 포함해서"
|
||||
|
||||
# 데이터베이스 연동 기능 spec
|
||||
"쇼핑몰의 재고 관리 기능의 spec 을 만들어주세요. 상품 추가, 재고 업데이트, 알림 기능을 포함해서"
|
||||
|
||||
# 프론트엔드 기능 spec
|
||||
"React 대시보드의 spec 을 만들어주세요. 그래프 표시, 필터, 내보내기 기능을 포함해서"
|
||||
|
||||
# 백엔드 기능 spec
|
||||
"RESTful API 의 spec 을 만들어주세요. 인증, 유효성 검사, 로그 기록을 포함해서"
|
||||
```
|
||||
|
||||
### Spec Mode 의 특징
|
||||
|
||||
**단계적 대화 워크플로**
|
||||
|
||||
- Kiro 의 본래 가치인 단계적 논의를 완전 재현
|
||||
- 각 페이즈에서 사용자와 협력적으로 사양을 세련화
|
||||
- 의문점 해소, 선택지 논의, 승인 프로세스를 거쳐 파일 생성
|
||||
|
||||
**3 단계의 대화형 전개**
|
||||
|
||||
- **Phase 1**: Requirements Discovery → 논의 → 승인 → `requirements.md` 생성
|
||||
- **Phase 2**: Design Exploration → 논의 → 승인 → `design.md` 생성
|
||||
- **Phase 3**: Implementation Planning → 논의 → 승인 → `tasks.md` 생성
|
||||
|
||||
**동적 사양 책정**
|
||||
|
||||
- 요구사항의 애매함을 대화로 해소
|
||||
- 기술 선택지의 제시와 논의
|
||||
- 트레이드오프의 설명과 판단 확인
|
||||
|
||||
### 상세 예시
|
||||
|
||||
```bash
|
||||
# 복잡한 시스템 기능
|
||||
"온라인 결제 시스템의 spec 을 만들어주세요. Stripe 연동, 보안, 오류 처리를 포함해서"
|
||||
|
||||
# 프론트엔드 기능
|
||||
"React 컴포넌트의 spec 을 만들어주세요. 상태 관리, 속성 설계, 테스트를 포함해서"
|
||||
|
||||
# 백엔드 기능
|
||||
"GraphQL API 의 spec 을 만들어주세요. 스키마 설계, 리졸버, 인증을 포함해서"
|
||||
|
||||
# DevOps 기능
|
||||
"CI/CD 파이프라인의 spec 을 만들어주세요. 테스트 자동화, 배포, 모니터링을 포함해서"
|
||||
```
|
||||
|
||||
### 단계별 대화 워크플로 (Phase by Phase)
|
||||
|
||||
#### Phase 1: Requirements Discovery & Discussion
|
||||
|
||||
**1. 최소한 입력에서 자동 확장 (Kiro 식)**
|
||||
|
||||
```text
|
||||
사용자: "사용자 관리 시스템
|
||||
- 로그인 기능
|
||||
- 프로필 편집
|
||||
- 관리자 권한"
|
||||
|
||||
Claude: "요구사항에서 상세한 사용자 스토리를 생성합니다.
|
||||
이 이해가 맞습니까?
|
||||
|
||||
자동 생성된 사용자 스토리:
|
||||
- 사용자 등록·인증 기능(OAuth 대응)
|
||||
- 프로필 관리 기능(아바타, 설정)
|
||||
- 권한 관리 기능(RBAC)
|
||||
- 비밀번호 재설정 기능
|
||||
- 보안 감사 로그
|
||||
|
||||
명시되지 않은 세부사항을 보완했습니다. 다른 필요한 기능이 있습니까?"
|
||||
```
|
||||
|
||||
**2. EARS 표기법을 통한 구조화 요구사항 기술**
|
||||
|
||||
```text
|
||||
Claude: "Kiro 의 EARS 표기법으로 요구사항을 구조화합니다:
|
||||
|
||||
EARS 표기법을 통한 요구사항 정의:
|
||||
|
||||
WHEN 사용자가 로그인을 시도할 때
|
||||
GIVEN 올바른 이메일 주소와 비밀번호를 입력한 경우
|
||||
THEN 시스템은 인증을 확인한다
|
||||
AND 성공 시 대시보드로 리다이렉트한다
|
||||
|
||||
WHILE 사용자가 프로필 편집 화면에 있는 동안
|
||||
THE SYSTEM SHALL 실시간으로 유효성 검사를 실행한다
|
||||
AND 변경 내용을 미리보기 표시한다
|
||||
|
||||
WHERE 관리자 권한이 필요한 기능에
|
||||
IS 액세스가 시도된 경우
|
||||
THE SYSTEM SHALL 권한 레벨을 확인한다
|
||||
AND 부족한 경우 액세스 거부한다"
|
||||
```
|
||||
|
||||
**3. 엣지 케이스·보안 요구사항의 자동 보완**
|
||||
|
||||
```text
|
||||
Claude: "Kiro 의 베스트 프랙티스에 기반해 다음 케이스도 고려했습니다:
|
||||
|
||||
보안 요구사항 (자동 보완):
|
||||
- 브루트 포스 공격 대책
|
||||
- 세션 관리와 타임아웃
|
||||
- CSRF 보호와 XSS 대책
|
||||
- 비밀번호 강도 요구사항
|
||||
|
||||
엣지 케이스 (자동 감지):
|
||||
- 동시 로그인 제한
|
||||
- 계정 잠금 기능
|
||||
- 데이터 마이그레이션 시 정합성 확보
|
||||
- 대량 요청 시 부하 분산
|
||||
|
||||
이러한 요구사항이 적절합니까?"
|
||||
```
|
||||
|
||||
**5. Phase 1 완료와 승인**
|
||||
|
||||
```text
|
||||
Claude: "Requirements Phase 가 완료되었습니다.
|
||||
requirements.md 를 생성해도 되겠습니까?"
|
||||
→ "다음으로 진행하세요" → requirements.md 생성
|
||||
```
|
||||
|
||||
#### Phase 2: Design Exploration & Discussion
|
||||
|
||||
**1. 코드베이스 분석 + 자동 설계 제안 (Kiro 식)**
|
||||
|
||||
```text
|
||||
Claude: "기존 코드베이스를 분석해서 최적의 아키텍처를 제안합니다:
|
||||
|
||||
코드베이스 분석 결과:
|
||||
- 인증: JWT + Express.js(v4.18.x)
|
||||
- 데이터베이스: PostgreSQL(v14+)
|
||||
- 프론트엔드: React + TypeScript(v18+)
|
||||
- 기존 패턴: Repository 패턴, Service 계층 분리
|
||||
|
||||
Kiro 권장 아키텍처:
|
||||
- Clean Architecture 준수
|
||||
- Domain-Driven Design 요소
|
||||
- CQRS 패턴의 부분적 적용
|
||||
- 자동화된 보안 베스트 프랙티스
|
||||
|
||||
이 설계로 진행하겠습니까?"
|
||||
```
|
||||
|
||||
**2. Mermaid 다이어그램을 통한 시각적 설계**
|
||||
|
||||
```text
|
||||
Claude: "시스템 설계를 Mermaid 다이어그램으로 자동 생성했습니다:
|
||||
|
||||
자동 생성된 아키텍처 다이어그램:
|
||||
|
||||
graph TB
|
||||
Client[React Client] --> API[Express API Gateway]
|
||||
API --> Auth[Auth Service]
|
||||
API --> User[User Service]
|
||||
API --> Profile[Profile Service]
|
||||
|
||||
Auth --> AuthDB[(Auth Database)]
|
||||
User --> UserDB[(User Database)]
|
||||
Profile --> ProfileDB[(Profile Database)]
|
||||
|
||||
Auth --> JWT[JWT Service]
|
||||
Auth --> OAuth[OAuth Provider]
|
||||
|
||||
데이터 플로 다이어그램도 생성하겠습니까?"
|
||||
```
|
||||
|
||||
**3. TypeScript 인터페이스 자동 생성**
|
||||
|
||||
```text
|
||||
Claude: "설계에 기반해 TypeScript 인터페이스를 자동 생성합니다:
|
||||
|
||||
자동 생성 TypeScript 인터페이스:
|
||||
|
||||
// Domain entities
|
||||
interface User {
|
||||
readonly id: UserId;
|
||||
readonly email: Email;
|
||||
readonly profile: UserProfile;
|
||||
readonly auth: AuthSettings;
|
||||
readonly permissions: Permission[];
|
||||
readonly createdAt: Date;
|
||||
readonly updatedAt: Date;
|
||||
}
|
||||
|
||||
interface UserProfile {
|
||||
readonly displayName: string;
|
||||
readonly avatar: AvatarUrl;
|
||||
readonly preferences: UserPreferences;
|
||||
}
|
||||
|
||||
interface AuthSettings {
|
||||
readonly passwordHash: PasswordHash;
|
||||
readonly mfaEnabled: boolean;
|
||||
readonly lastLoginAt: Date;
|
||||
readonly failedAttempts: number;
|
||||
}
|
||||
|
||||
// Use cases
|
||||
interface UserRepository {
|
||||
findById(id: UserId): Promise<User | null>;
|
||||
findByEmail(email: Email): Promise<User | null>;
|
||||
save(user: User): Promise<void>;
|
||||
}
|
||||
|
||||
interface AuthenticationService {
|
||||
authenticate(credentials: LoginCredentials): Promise<AuthResult>;
|
||||
refreshToken(token: RefreshToken): Promise<AccessToken>;
|
||||
}
|
||||
|
||||
이 인터페이스 설계로 진행하겠습니까?"
|
||||
```
|
||||
|
||||
**4. Phase 2 완료와 승인**
|
||||
|
||||
```text
|
||||
Claude: "Design Phase 가 완료되었습니다.
|
||||
design.md 를 생성해도 되겠습니까?"
|
||||
→ "다음으로 진행하세요" → design.md 생성
|
||||
```
|
||||
|
||||
#### Phase 3: Implementation Planning & Discussion
|
||||
|
||||
**1. 베스트 프랙티스 자동 적용 (Kiro 식)**
|
||||
|
||||
```text
|
||||
Claude: "Kiro 의 베스트 프랙티스를 자동 적용한 구현 계획을 생성했습니다:
|
||||
|
||||
자동 생성된 구현 전략:
|
||||
|
||||
1. 보안 퍼스트 개발
|
||||
- OWASP Top 10 대책의 자동 조합
|
||||
- 암호화·해싱화의 자동 구현
|
||||
- 보안 테스트의 자동 생성
|
||||
|
||||
2. 클린 아키텍처의 강제
|
||||
- 레이어 분리의 자동 구현
|
||||
- 의존성 역전의 자동 적용
|
||||
- 테스트 가능한 설계의 강제
|
||||
|
||||
3. 성능 최적화
|
||||
- 캐시 전략의 자동 구현
|
||||
- 데이터베이스 최적화
|
||||
- 비동기 처리의 활용
|
||||
|
||||
이 접근법으로 진행하겠습니까?"
|
||||
```
|
||||
|
||||
**2. 품질 체크포인트 자동 설정**
|
||||
|
||||
```text
|
||||
Claude: "각 구현 단계의 품질 체크포인트를 자동 설정했습니다:
|
||||
|
||||
자동 품질 보증 프로세스:
|
||||
|
||||
Phase 3a: 백엔드 구현
|
||||
|
||||
- [ ] 보안 스캔(SAST/DAST)
|
||||
- [ ] API 사양 테스트(OpenAPI 준수)
|
||||
- [ ] 성능 테스트(부하·응답)
|
||||
- [ ] 취약점 스캔(의존관계·CVE)
|
||||
|
||||
Phase 3b: 프론트엔드 구현
|
||||
|
||||
- [ ] 접근성 테스트(WCAG 2.1 AA)
|
||||
- [ ] 브라우저 호환성 테스트
|
||||
- [ ] 반응형 디자인 검증
|
||||
- [ ] 보안 헤더 확인
|
||||
|
||||
Phase 3c: 통합·배포
|
||||
|
||||
- [ ] E2E 테스트 스위트
|
||||
- [ ] CI/CD 파이프라인 설정
|
||||
- [ ] 모니터링·로그 설정
|
||||
- [ ] 프로덕션 환경 보안 감사
|
||||
|
||||
모든 것이 자동 실행됩니다. 추가 품질 기준이 있습니까?"
|
||||
```
|
||||
|
||||
**3. 의존 관계와 위험 완화의 자동 분석**
|
||||
|
||||
```text
|
||||
Claude: "구현 순서와 위험 완화책을 자동 분석했습니다:
|
||||
|
||||
최적화된 구현 순서:
|
||||
|
||||
Week 1: 인프라·보안 기반
|
||||
|
||||
- 데이터베이스 설계·스키마 생성
|
||||
- 인증 기반(JWT + 세션 관리)
|
||||
- 보안 미들웨어 구현
|
||||
- 기본적인 API 엔드포인트
|
||||
|
||||
Week 2: 핵심 기능 구현
|
||||
|
||||
- 사용자 관리 기능
|
||||
- 프로필 관리 기능
|
||||
- 권한 관리 시스템
|
||||
- 유효성 검사·오류 처리
|
||||
|
||||
Week 3: 고급 기능·최적화
|
||||
|
||||
- 다중 인증 구현
|
||||
- 감사 로그 기능
|
||||
- 성능 최적화
|
||||
- 프론트엔드 통합
|
||||
|
||||
자동 감지된 위험 완화책:
|
||||
|
||||
- 다중 인증: 단계적 도입(SMS→앱 인증)
|
||||
- 세션 관리: Redis 클러스터 구성
|
||||
- 대량 액세스: 레이트 제한 + CDN 활용
|
||||
- 데이터 정합성: 트랜잭션 관리 강화
|
||||
|
||||
이 계획에 문제없습니까?"
|
||||
```
|
||||
|
||||
**4. Phase 3 완료와 승인**
|
||||
|
||||
```text
|
||||
Claude: "Implementation Planning Phase 가 완료되었습니다.
|
||||
tasks.md 를 생성해도 되겠습니까?"
|
||||
→ "다음으로 진행하세요" → tasks.md 생성
|
||||
```
|
||||
|
||||
### Kiro 고유 기능
|
||||
|
||||
**EARS 표기법 (Easy Approach to Requirements Syntax)**
|
||||
|
||||
```markdown
|
||||
# Kiro 표준 EARS 표기법 패턴
|
||||
|
||||
WHEN [상황·트리거]
|
||||
GIVEN [전제 조건]
|
||||
THEN [시스템의 동작]
|
||||
AND [추가 동작]
|
||||
|
||||
WHILE [상태·프로세스]
|
||||
THE SYSTEM SHALL [필수 동작]
|
||||
AND [관련 동작]
|
||||
|
||||
WHERE [기능·컴포넌트]
|
||||
IS [조건·상태]
|
||||
THE SYSTEM SHALL [대응 동작]
|
||||
```
|
||||
|
||||
**자동 생성 기능**
|
||||
|
||||
- **Mermaid 다이어그램**: 아키텍처·데이터 플로 다이어그램의 자동 생성
|
||||
- **TypeScript 인터페이스**: 설계기반의 타입 정의 자동 작성
|
||||
- **베스트 프랙티스**: 보안·성능 대책의 자동 조합
|
||||
- **품질 체크포인트**: 단계별 품질 기준의 자동 설정
|
||||
|
||||
**hooks 연동**
|
||||
|
||||
- 파일 저장 시 자동 품질 체크
|
||||
- 코드 표준의 자동 적용
|
||||
- 보안 스캔의 자동 실행
|
||||
- OWASP Top 10 대책의 자동 검증
|
||||
|
||||
**프로토타입→프로덕션 품질 보증**
|
||||
|
||||
- 구조화된 접근을 통한 일관된 설계
|
||||
- 보안 퍼스트 개발의 강제
|
||||
- 확장 가능한 아키텍처의 자동 적용
|
||||
- 지속적 품질 관리의 조합
|
||||
|
||||
### 주의사항
|
||||
|
||||
**적용 범위**
|
||||
|
||||
- Spec Mode 는 기능 구현에 최적화
|
||||
- 단순한 수정이나 소규모 변경의 경우 일반적인 구현 방식 사용
|
||||
- 새 기능 개발이나 복잡한 기능 개수에 권장
|
||||
|
||||
**품질 보증**
|
||||
|
||||
- 각 단계의 완료 기준을 명확화
|
||||
- 구현 전 설계 리뷰
|
||||
- 테스트와 접근성을 포함한 포괄적 품질 기준
|
||||
|
||||
**실행상 주의**
|
||||
|
||||
- 요구사항의 애매함을 해소한 후 설계 단계로
|
||||
- 설계 완료 후 구현 작업을 생성
|
||||
- 각 단계의 승인 프로세스를 중시
|
||||
|
||||
### 트리거 문구와 컨트롤
|
||||
|
||||
#### 단계별 워크플로 제어
|
||||
|
||||
**시작 트리거**
|
||||
|
||||
- "[기능명]의 spec 을 만들어주세요"
|
||||
- "spec 주도로 [기능명]을 개발하고 싶습니다"
|
||||
- "사양서부터 [기능명]을 설계하세요"
|
||||
|
||||
**페이즈 진행 제어**
|
||||
|
||||
- **"다음으로 진행하세요"**: 현재 페이즈를 완료해서 파일 생성, 다음 페이즈로
|
||||
- **"수정하세요"**: 현재 페이즈 내에서 내용을 조정·개선
|
||||
- **"다시 하세요"**: 현재 페이즈를 처음부터 다시
|
||||
- **"자세히 설명하세요"**: 더 상세한 설명이나 선택지를 제시
|
||||
- **"건너뛰어주세요"**: 현 페이즈를 건너뛰고 다음으로 (비권장)
|
||||
|
||||
**파일 생성 타이밍**
|
||||
|
||||
```text
|
||||
Phase 1 완료 → "다음으로 진행하세요" → requirements.md 생성
|
||||
Phase 2 완료 → "다음으로 진행하세요" → design.md 생성
|
||||
Phase 3 완료 → "다음으로 진행하세요" → tasks.md 생성
|
||||
```
|
||||
|
||||
### 실행 예시 (단계별 플로)
|
||||
|
||||
```bash
|
||||
# 사용 예시
|
||||
사용자: "사용자 관리 시스템의 spec 을 만들어주세요"
|
||||
|
||||
# Phase 1: Requirements Discovery
|
||||
Claude: [요구사항 확인과 논의 시작]
|
||||
사용자: [응답·논의·수정]
|
||||
Claude: "Requirements Phase 가 완료되었습니다. 다음으로 진행해도 되겠습니까?"
|
||||
사용자: "다음으로 진행하세요"
|
||||
→ requirements.md 생성
|
||||
|
||||
# Phase 2: Design Exploration
|
||||
Claude: [설계 제안과 논의 시작]
|
||||
사용자: [기술 선택·아키텍처 논의]
|
||||
Claude: "Design Phase 가 완료되었습니다. 다음으로 진행해도 되겠습니까?"
|
||||
사용자: "다음으로 진행하세요"
|
||||
→ design.md 생성
|
||||
|
||||
# Phase 3: Implementation Planning
|
||||
Claude: [구현 계획의 논의 시작]
|
||||
사용자: [우선순위·위험·공수 논의]
|
||||
Claude: "Implementation Phase 가 완료되었습니다. 다음으로 진행해도 되겠습니까?"
|
||||
사용자: "다음으로 진행하세요"
|
||||
→ tasks.md 생성
|
||||
|
||||
# 완료
|
||||
Claude: "spec 주도 개발의 준비가 완료되었습니다. 구현을 시작할 수 있습니다."
|
||||
```
|
||||
|
||||
### /plan 과의 차이점
|
||||
|
||||
| 특징 | /plan | /spec |
|
||||
| ------------- | ---------------------- | -------------------------------------------------------- |
|
||||
| 대상 | 일반적인 구현 계획 | 기능 사양 주도 개발 |
|
||||
| 출력 형식 | 단일 계획 문서 | 3 개의 독립적 파일(requirements.md, design.md, tasks.md) |
|
||||
| 요구사항 정의 | 기본적인 요구사항 정리 | EARS 표기법을 통한 상세한 수용 기준 |
|
||||
| 설계 | 기술 선정 중심 | 코드베이스 분석 기반 |
|
||||
| 구현 | 일반적인 작업 분해 | 의존관계를 고려한 시퀀스 |
|
||||
| 품질 보증 | 기본적인 테스트 전략 | 포괄적인 품질 요구사항(테스트, 접근성, 성능) |
|
||||
| 동기화 | 정적인 계획 | 동적인 spec 업데이트 |
|
||||
|
||||
### 권장 사용 사례
|
||||
|
||||
**spec 사용 권장**
|
||||
|
||||
- 새 기능 개발
|
||||
- 복잡한 기능 개수
|
||||
- API 설계
|
||||
- 데이터베이스 설계
|
||||
- UI/UX 구현
|
||||
|
||||
**plan 사용 권장**
|
||||
|
||||
- 시스템 전체의 설계
|
||||
- 인프라 구축
|
||||
- 리팩터링
|
||||
- 기술 선정
|
||||
- 아키텍처 변경
|
||||
186
commands/style-ai-writing.md
Normal file
186
commands/style-ai-writing.md
Normal file
@@ -0,0 +1,186 @@
|
||||
## AI Writing Check
|
||||
|
||||
AI 가 생성한 문장의 기계적인 패턴을 검출하고, 더 자연스러운 한국어로의 개선 제안을 수행합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
/ai-writing-check [옵션]
|
||||
```
|
||||
|
||||
### 옵션
|
||||
|
||||
- 없음 : 현재 파일 또는 선택한 텍스트를 분석
|
||||
- `--file <path>` : 특정 파일을 분석
|
||||
- `--dir <path>` : 디렉터리 내의 파일을 일괄 분석
|
||||
- `--severity <level>` : 검출 레벨 (all/high/medium)
|
||||
- `--fix` : 검출된 패턴을 자동 수정
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 파일의 AI 냄새를 체크
|
||||
cat README.md
|
||||
/ai-writing-check
|
||||
「이 문서의 AI 냄새를 체크해서 개선안을 제시하세요」
|
||||
|
||||
# 특정 파일의 분석
|
||||
/ai-writing-check --file docs/guide.md
|
||||
「AI 같은 표현을 검출해서 자연스러운 표현으로 수정 제안하세요」
|
||||
|
||||
# 프로젝트 전체의 스캔
|
||||
/ai-writing-check --dir . --severity high
|
||||
「프로젝트 내의 중요한 AI 냄새 문제만 보고하세요」
|
||||
```
|
||||
|
||||
### 검출 패턴
|
||||
|
||||
#### 1. 리스트 서식의 기계적 패턴
|
||||
|
||||
```markdown
|
||||
검출되는 예:
|
||||
|
||||
- **중요**: 이는 중요한 항목입니다
|
||||
- 완료된 항목 (체크마크 포함)
|
||||
- 핫한 화제 (불꽃 이모지 포함)
|
||||
- 시작 준비 완료 (로켓 이모지 포함)
|
||||
|
||||
개선 예:
|
||||
|
||||
- 중요한 항목: 이는 중요한 항목입니다
|
||||
- 완료된 항목
|
||||
- 주목받는 화제
|
||||
- 시작 준비 완료
|
||||
```
|
||||
|
||||
#### 2. 과장적·하이프 표현
|
||||
|
||||
```markdown
|
||||
검출되는 예:
|
||||
혁신적인 기술로 업계를 변화시킵니다.
|
||||
이것은 완전히 문제를 해결합니다.
|
||||
마법처럼 작동합니다.
|
||||
|
||||
개선 예:
|
||||
효과적인 기술로 업계에 변화를 가져다줍니다.
|
||||
많은 문제를 해결합니다.
|
||||
부드럽게 작동합니다.
|
||||
```
|
||||
|
||||
#### 3. 기계적인 강조 패턴
|
||||
|
||||
```markdown
|
||||
검출되는 예:
|
||||
**아이디어**: 새로운 제안이 있습니다 (전구 이모지 포함)
|
||||
**주의**: 중요한 경고 사항 (경고 이모지 포함)
|
||||
|
||||
개선 예:
|
||||
아이디어: 새로운 제안이 있습니다
|
||||
주의사항: 중요한 경고 사항
|
||||
```
|
||||
|
||||
#### 4. 장황한 테크니컬 라이팅
|
||||
|
||||
```markdown
|
||||
검출되는 예:
|
||||
먼저 처음에 설정을 수행합니다.
|
||||
이 도구를 사용할 수 있습니다.
|
||||
대폭 성능이 향상됩니다.
|
||||
|
||||
개선 예:
|
||||
먼저 설정을 수행합니다.
|
||||
이 도구를 사용 가능합니다.
|
||||
성능이 30% 향상됩니다.
|
||||
```
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# 문서 전체의 AI 냄새 분석
|
||||
cat article.md
|
||||
/ai-writing-check
|
||||
「다음 관점으로 분석해서 개선안을 제시하세요:
|
||||
1. 기계적인 표현의 검출
|
||||
2. 자연스러운 한국어로의 수정 제안
|
||||
3. 우선순위별 개선 리스트」
|
||||
|
||||
# 특정 패턴에 포커스
|
||||
/ai-writing-check --file blog.md
|
||||
「특히 과장 표현과 장황한 표현에 주목해서 개선 제안하세요」
|
||||
|
||||
# 복수 파일의 일괄 체크
|
||||
find . -name "*.md" -type f
|
||||
/ai-writing-check --dir docs/
|
||||
「문서 전체의 AI 냄새를 분석해서 요약을 작성하세요」
|
||||
```
|
||||
|
||||
### 상세 예제
|
||||
|
||||
```bash
|
||||
# 개선 전후의 비교
|
||||
/ai-writing-check --file draft.md
|
||||
「AI 냄새 나는 표현을 검출해서 다음 형식으로 제시하세요:
|
||||
- 문제 부분 (행번호 포함)
|
||||
- 문제의 종류와 이유
|
||||
- 구체적인 개선안
|
||||
- 개선을 통한 효과」
|
||||
|
||||
# 자동 수정 모드
|
||||
/ai-writing-check --file report.md --fix
|
||||
「검출된 패턴을 자동 수정해서 결과를 보고하세요」
|
||||
|
||||
# 프로젝트의 AI 냄새 리포트
|
||||
/ai-writing-check --dir . --severity all
|
||||
「프로젝트 전체의 AI 냄새를 분석해서:
|
||||
1. 통계 정보 (패턴별 검출 수)
|
||||
2. 가장 문제가 있는 파일 TOP 5
|
||||
3. 개선 우선순위 매트릭스
|
||||
4. 단계적인 개선 계획」
|
||||
```
|
||||
|
||||
### 고급 사용 예제
|
||||
|
||||
```bash
|
||||
# 커스텀 룰의 적용
|
||||
/ai-writing-check --file spec.md
|
||||
「기술 사양서로서 다음 추가 기준으로 체크하세요:
|
||||
- 애매한 표현 (적절한, 필요에 따라)
|
||||
- 구체성의 결여 (고속인 → 구체적인 수치)
|
||||
- 일관성 없는 용어 사용」
|
||||
|
||||
# CI/CD 통합용 체크
|
||||
/ai-writing-check --dir docs/ --severity high
|
||||
「GitHub Actions 에서 실행 가능한 형식으로 결과를 출력하세요:
|
||||
- 에러 수와 파일명
|
||||
- 수정이 필요한 행번호
|
||||
- exit code 설정」
|
||||
|
||||
# 스타일 가이드 준수 체크
|
||||
/ai-writing-check --file manual.md
|
||||
「회사 스타일 가이드에 기반해서 추가 체크하세요:
|
||||
- 존댓말 사용 (합니다·습니다체 통일)
|
||||
- 전문용어의 적절한 사용
|
||||
- 독자에 대한 배려」
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
- AI 냄새의 판정은 문맥에 따라 다르므로, 제안은 참고로 취급하세요
|
||||
- 기술 문서, 블로그, 매뉴얼 등 문서의 종류에 따라 기준을 조정합니다
|
||||
- 모든 제안을 받아들일 필요는 없으며, 적절한 것을 선택하세요
|
||||
- `--fix` 옵션은 검출된 패턴을 자동으로 수정합니다
|
||||
|
||||
### 명령 실행 시의 동작
|
||||
|
||||
`/ai-writing-check` 명령을 실행하면 Claude 는 다음 처리를 수행합니다:
|
||||
|
||||
1. **패턴 검출**: 지정된 파일이나 텍스트에서 AI 냄새 나는 패턴을 검출
|
||||
2. **구체적인 수정 제안**: 각 문제에 대해 행번호와 함께 수정안을 제시
|
||||
3. **--fix 모드**: 검출된 패턴을 자동 수정하고 결과를 요약 표시
|
||||
4. **리포트 생성**: 검출 수, 개선 우선순위, 수정 전후 비교를 제공
|
||||
|
||||
Claude 는 실제 파일 내용을 읽어들여 textlint-rule-preset-ai-writing 의 규칙에 기반하여 분석을 실행합니다.
|
||||
|
||||
### 참고
|
||||
|
||||
이 명령어는 [textlint-rule-preset-ai-writing](https://github.com/textlint-ja/textlint-rule-preset-ai-writing)의 룰셋을 참고하여 작성되었습니다. AI 가 생성한 문장의 기계적인 패턴을 검출하고 더 자연스러운 표현을 촉진하기 위한 textlint 규칙 프리셋입니다.
|
||||
223
commands/task.md
Normal file
223
commands/task.md
Normal file
@@ -0,0 +1,223 @@
|
||||
## Task
|
||||
|
||||
전용 에이전트를 기동해서 복잡한 검색·조사·분석 작업을 자율적으로 실행합니다. 여러 도구를 조합한 대규모 정보 처리로 컨텍스트 효율성을 중시합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# Claude 에게 Task 의뢰
|
||||
"[과제]를 Task 로 조사하세요"
|
||||
```
|
||||
|
||||
### Task 의 특징
|
||||
|
||||
**자율적 실행**
|
||||
|
||||
- 여러 도구를 조합해서 자동 실행
|
||||
- 단계적 정보 수집과 분석
|
||||
- 결과의 통합과 구조화된 보고
|
||||
|
||||
**효율적 정보 처리**
|
||||
|
||||
- 컨텍스트 소비의 최적화
|
||||
- 대규모 파일 검색·해석
|
||||
- 외부 정보원에서의 데이터 수집
|
||||
|
||||
**품질 보증**
|
||||
|
||||
- 정보원의 신뢰성 체크
|
||||
- 다중 관점으로의 검증
|
||||
- 누락 정보의 자동 보완
|
||||
|
||||
### 기본 예시
|
||||
|
||||
```bash
|
||||
# 복잡한 코드베이스 조사
|
||||
"이 기능이 어느 파일에 구현되어 있는지 Task 로 조사하세요"
|
||||
|
||||
# 대규모 파일 검색
|
||||
"설정 파일의 불일치를 Task 로 특정하세요"
|
||||
|
||||
# 외부 정보 수집
|
||||
"최신 AI 기술 트렌드를 Task 로 조사하세요"
|
||||
```
|
||||
|
||||
### Claude 와의 연동
|
||||
|
||||
```bash
|
||||
# 복잡한 문제 분석
|
||||
"메모리 누수의 원인을 Task 로 분석하세요. 프로파일링 결과와 로그를 포함해서"
|
||||
|
||||
# 의존관계 조사
|
||||
"이 npm 패키지의 취약점을 Task 로 조사하세요"
|
||||
|
||||
# 경쟁 분석
|
||||
"경쟁 서비스의 API 사양을 Task 로 조사하세요"
|
||||
|
||||
# 아키텍처 분석
|
||||
"이 마이크로서비스의 의존관계를 Task 로 분석하세요"
|
||||
```
|
||||
|
||||
### 다른 명령어와의 구분
|
||||
|
||||
#### Task vs 다른 명령어
|
||||
|
||||
| 명령어 | 주요 용도 | 실행 방식 | 정보 수집 |
|
||||
| ------------------- | -------------- | ------------- | -------------- |
|
||||
| **Task** | 조사·분석·검색 | 자율적 실행 | 복수 소스 |
|
||||
| ultrathink | 깊은 사고·판단 | 구조화 사고 | 기존 지식 중심 |
|
||||
| sequential-thinking | 문제 해결·설계 | 단계적 사고 | 필요에 따라 |
|
||||
| plan | 구현 계획 수립 | 승인 프로세스 | 요구사항 분석 |
|
||||
|
||||
#### 판단 플로우차트
|
||||
|
||||
```text
|
||||
정보 수집이 필요한가?
|
||||
├─ Yes → 복수 소스·대규모?
|
||||
│ ├─ Yes → **Task**
|
||||
│ └─ No → 일반적인 질문
|
||||
└─ No → 깊은 사고가 필요한가?
|
||||
├─ Yes → ultrathink/sequential-thinking
|
||||
└─ No → 일반적인 질문
|
||||
```
|
||||
|
||||
### 유효한 케이스·불필요한 케이스
|
||||
|
||||
**유효한 케이스**
|
||||
|
||||
- 복잡한 코드베이스 조사 (의존관계, 아키텍처 분석)
|
||||
- 대규모 파일 검색 (특정 구현 패턴, 설정 파일)
|
||||
- 외부 정보 수집과 정리 (기술 트렌드, 라이브러리 조사)
|
||||
- 여러 소스의 정보 통합 (로그 해석, 지표 분석)
|
||||
- 반복적 조사 작업 (보안 감사, 기술 부채 조사)
|
||||
- 컨텍스트 소비를 피하고 싶은 대규모 분석
|
||||
|
||||
**불필요한 케이스**
|
||||
|
||||
- 단순한 질문이나 기존 지식으로 답변 가능한 내용
|
||||
- 단시간에 완료되는 단발성 작업
|
||||
- 대화형 확인·상담이 필요한 작업
|
||||
- 구현이나 설계 판단 (plan 이나 사고계 명령어가 적절)
|
||||
|
||||
### 카테고리별 상세 예시
|
||||
|
||||
#### 시스템 분석·조사
|
||||
|
||||
```bash
|
||||
# 복잡한 시스템 분석
|
||||
"쇼핑몰의 병목을 Task 로 특정하세요. 데이터베이스, API, 프론트엔드 전체를 조사"
|
||||
|
||||
# 아키텍처 분석
|
||||
"이 마이크로서비스의 의존관계를 Task 로 분석하세요. API 통신과 데이터 플로를 포함해서"
|
||||
|
||||
# 기술 부채 조사
|
||||
"레거시 코드의 기술 부채를 Task 로 분석하세요. 리팩터링 우선순위를 포함해서"
|
||||
```
|
||||
|
||||
#### 보안·규정 준수
|
||||
|
||||
```bash
|
||||
# 보안 감사
|
||||
"이 애플리케이션의 취약점을 Task 로 조사하세요. OWASP Top 10 에 기반해서"
|
||||
|
||||
# 라이선스 조사
|
||||
"프로젝트의 의존관계 라이선스 문제를 Task 로 조사하세요"
|
||||
|
||||
# 설정 파일 감사
|
||||
"보안 설정의 불일치를 Task 로 특정하세요. 환경별 차이를 포함해서"
|
||||
```
|
||||
|
||||
#### 성능·최적화
|
||||
|
||||
```bash
|
||||
# 성능 분석
|
||||
"애플리케이션의 무거운 쿼리를 Task 로 특정하세요. 실행 계획과 최적화안을 포함해서"
|
||||
|
||||
# 리소스 사용량 조사
|
||||
"메모리 누수의 원인을 Task 로 조사하세요. 프로파일링 결과와 코드 해석을 포함해서"
|
||||
|
||||
# 번들 크기 분석
|
||||
"프론트엔드의 번들 크기 문제를 Task 로 조사하세요. 최적화 제안을 포함해서"
|
||||
```
|
||||
|
||||
#### 외부 정보 수집
|
||||
|
||||
```bash
|
||||
# 기술 트렌드 조사
|
||||
"2024 년 JavaScript 프레임워크 동향을 Task 로 조사하세요"
|
||||
|
||||
# 경쟁사 분석
|
||||
"경쟁 서비스의 API 사양을 Task 로 조사하세요. 기능 비교표를 포함해서"
|
||||
|
||||
# 라이브러리 평가
|
||||
"State 관리 라이브러리 비교를 Task 로 조사하세요. 성능과 학습 비용을 포함해서"
|
||||
```
|
||||
|
||||
### 실행 플로와 품질 보증
|
||||
|
||||
#### Task 실행 플로
|
||||
|
||||
```text
|
||||
1. 초기 분석
|
||||
├─ 과제의 분해와 조사 범위 특정
|
||||
├─ 필요한 도구와 정보원 선정
|
||||
└─ 실행 계획 수립
|
||||
|
||||
2. 정보 수집
|
||||
├─ 파일 검색·코드 해석
|
||||
├─ 외부 정보 수집
|
||||
└─ 데이터의 구조화
|
||||
|
||||
3. 분석·통합
|
||||
├─ 수집한 정보의 관련성 분석
|
||||
├─ 패턴이나 문제점 특정
|
||||
└─ 가설의 검증
|
||||
|
||||
4. 보고·제안
|
||||
├─ 결과의 구조화
|
||||
├─ 개선 제안 작성
|
||||
└─ 다음 액션 제시
|
||||
```
|
||||
|
||||
#### 품질 보증
|
||||
|
||||
- **정보원의 신뢰성 체크**: 다중 소스에서의 사실 확인
|
||||
- **망라성 확인**: 조사 대상의 누락이 없는지 체크
|
||||
- **일관성 검증**: 모순되는 정보의 정합성 확인
|
||||
- **실용성 평가**: 제안의 실현 가능성과 효과 평가
|
||||
|
||||
### 에러 핸들링과 제약사항
|
||||
|
||||
#### 자주 있는 제약
|
||||
|
||||
- **외부 API 이용 제한**: 레이트 제한이나 인증 에러
|
||||
- **대용량 파일 처리 제한**: 메모리나 타임아웃 제약
|
||||
- **접근 권한 문제**: 파일이나 디렉토리 접근 제한
|
||||
|
||||
#### 에러 시 대처
|
||||
|
||||
- **부분적 결과 보고**: 취득 가능한 정보만으로 분석
|
||||
- **대체 수단 제안**: 제약 하에서의 대체 조사 방법
|
||||
- **단계적 실행**: 대규모 태스크의 분할 실행
|
||||
|
||||
### 주의사항
|
||||
|
||||
- Task 는 복잡하고 자율적인 조사·분석 작업에 최적입니다
|
||||
- 단순한 질문이나 즉석 답변이 필요한 경우는 일반적인 질문 형식을 사용해주세요
|
||||
- 조사 결과는 참고 정보로 취급하고, 중요한 판단은 반드시 검증해주세요
|
||||
- 외부 정보 수집 시는 정보의 최신성과 정확성에 주의해주세요
|
||||
|
||||
### 실행 예시
|
||||
|
||||
```bash
|
||||
# 사용 예시
|
||||
"GraphQL 스키마의 문제점을 Task 로 조사하세요"
|
||||
|
||||
# 기대되는 동작
|
||||
# 1. 전용 에이전트 기동
|
||||
# 2. GraphQL 관련 파일 검색
|
||||
# 3. 스키마 정의 해석
|
||||
# 4. 베스트 프랙티스와 비교
|
||||
# 5. 문제점 특정과 개선 제안
|
||||
# 6. 구조화된 보고서 작성
|
||||
```
|
||||
185
commands/tech-debt.md
Normal file
185
commands/tech-debt.md
Normal file
@@ -0,0 +1,185 @@
|
||||
## Tech Debt
|
||||
|
||||
프로젝트의 기술적 부채를 정량적으로 분석하고, 건전성 스코어와 개발 효율성에의 영향을 가시화합니다. 트렌드 분석을 통해 개선 상황을 추적하고, 시간적 비용을 산출하여 우선순위가 매겨진 개선 계획을 작성합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# 프로젝트의 구성을 확인해서 기술적 부채를 분석
|
||||
ls -la
|
||||
"이 프로젝트의 기술적 부채를 분석해서 개선 계획을 작성해줘"
|
||||
```
|
||||
|
||||
### 프로젝트 건전성 대시보드
|
||||
|
||||
```text
|
||||
프로젝트 건전성 스코어: 72/100
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
📊 카테고리별 스코어
|
||||
├─ 의존관계의 신선도: ████████░░ 82% (최신: 45/55)
|
||||
├─ 문서 충실도: ███░░░░░░░ 35% (README, API 문서 부족)
|
||||
├─ 테스트 커버리지: ██████░░░░ 65% (목표: 80%)
|
||||
├─ 보안: ███████░░░ 78% (취약점: 2건 Medium)
|
||||
├─ 아키텍처: ██████░░░░ 60% (순환 의존: 3곳)
|
||||
└─ 코드 품질: ███████░░░ 70% (복잡도 높음: 12파일)
|
||||
|
||||
📈 트렌드 (과거 30일)
|
||||
├─ 종합 스코어: 68 → 72 (+4) ↗️
|
||||
├─ 개선 항목: 12건 ✅
|
||||
├─ 신규 부채: 3건 ⚠️
|
||||
├─ 해소 부채: 8건 🎉
|
||||
└─ 개선 속도: +0.13/일
|
||||
|
||||
⏱️ 부채의 시간적 영향
|
||||
├─ 개발 속도 저하: -20% (신기능 개발이 통상의 1.25배 시간)
|
||||
├─ 버그 수정 시간: +15% (평균 수정 시간 2h → 2.3h)
|
||||
├─ 코드 리뷰: +30% (복잡성에 의한 이해 시간 증가)
|
||||
├─ 온보딩: +50% (신규 멤버가 이해에 필요한 시간)
|
||||
└─ 누적 지연 시간: 주 40시간 상당
|
||||
|
||||
🎯 개선에 의한 기대 효과 (시간 베이스)
|
||||
├─ 즉시 효과: 개발 속도 +10% (1주후)
|
||||
├─ 단기 효과: 버그율 -25% (1개월후)
|
||||
├─ 중기 효과: 개발 속도 +30% (3개월후)
|
||||
├─ 장기 효과: 메인터넌스 시간 -50% (6개월후)
|
||||
└─ ROI: 투자 40시간 → 회수 120시간 (3개월)
|
||||
```
|
||||
|
||||
### 기본 예
|
||||
|
||||
```bash
|
||||
# 건전성 스코어의 상세 분석
|
||||
find . -name "*.js" -o -name "*.ts" | xargs wc -l | sort -rn | head -10
|
||||
"프로젝트 건전성 스코어를 산출해서, 카테고리별로 평가해줘"
|
||||
|
||||
# TODO/FIXME의 부채 임팩트 분석
|
||||
grep -r "TODO\|FIXME\|HACK\|XXX\|WORKAROUND" . --exclude-dir=node_modules --exclude-dir=.git
|
||||
"이 TODO들을 부채 임팩트 (시간×중요도)로 평가해줘"
|
||||
|
||||
# 의존관계의 건전성 체크
|
||||
ls -la | grep -E "package.json|Cargo.toml|pubspec.yaml|go.mod|requirements.txt"
|
||||
"의존관계의 신선도 스코어를 산출하고, 업데이트의 리스크와 효과를 분석해줘"
|
||||
```
|
||||
|
||||
### Claude와의 연계
|
||||
|
||||
```bash
|
||||
# 포괄적인 기술적 부채 분석
|
||||
ls -la && find . -name "*.md" -maxdepth 2 -exec head -20 {} \;
|
||||
"이 프로젝트의 기술적 부채를 다음 관점에서 분석해줘:
|
||||
1. 코드 품질 (복잡도, 중복, 보수성)
|
||||
2. 의존관계의 건전성
|
||||
3. 보안 리스크
|
||||
4. 성능 문제
|
||||
5. 테스트 커버리지 부족"
|
||||
|
||||
# 아키텍처의 부채 분석
|
||||
find . -type d -name "src" -o -name "lib" -o -name "app" | head -10 | xargs ls -la
|
||||
"아키텍처 레벨의 기술적 부채를 특정하고, 리팩터링 계획을 제안해줘"
|
||||
|
||||
# 우선순위가 매겨진 개선 계획
|
||||
"기술적 부채를 다음 기준으로 평가해서 표 형식으로 제시해줘:
|
||||
- 영향도 (높음/중간/낮음)
|
||||
- 수정 비용 (시간)
|
||||
- 기술적 리스크 (시스템 장애, 데이터 손실 가능성)
|
||||
- 개선에 의한 시간 삭감 효과
|
||||
- 추천 실시 시기"
|
||||
```
|
||||
|
||||
### 상세 예
|
||||
|
||||
```bash
|
||||
# 프로젝트 타입의 자동 검출과 분석
|
||||
find . -maxdepth 2 -type f \( -name "package.json" -o -name "Cargo.toml" -o -name "pubspec.yaml" -o -name "go.mod" -o -name "pom.xml" \)
|
||||
"검출된 프로젝트 타입에 기반해서, 다음을 분석해줘:
|
||||
1. 언어・프레임워크 고유의 기술적 부채
|
||||
2. 베스트 프랙티스로부터의 일탈
|
||||
3. 모던화의 기회
|
||||
4. 단계적인 개선 전략"
|
||||
|
||||
# 코드의 품질 메트릭스 분석
|
||||
find . -type f -name "*" | grep -E "\.(js|ts|py|rs|go|dart|kotlin|swift|java)$" | wc -l
|
||||
"프로젝트의 코드 품질을 분석하고, 다음 메트릭스를 제시해줘:
|
||||
- 순환 복잡도가 높은 함수
|
||||
- 중복 코드의 검출
|
||||
- 너무 긴 파일/함수
|
||||
- 적절한 에러 핸들링의 결여"
|
||||
|
||||
# 보안 부채의 검출
|
||||
grep -r "password\|secret\|key\|token" . --exclude-dir=.git --exclude-dir=node_modules | grep -v ".env.example"
|
||||
"보안에 관한 기술적 부채를 검출하고, 수정 우선도와 대책을 제안해줘"
|
||||
|
||||
# 테스트 부족의 분석
|
||||
find . -type f \( -name "*test*" -o -name "*spec*" \) | wc -l && find . -type f -name "*.md" | xargs grep -l "test"
|
||||
"테스트 커버리지의 기술적 부채를 분석하고, 테스트 전략을 제안해줘"
|
||||
```
|
||||
|
||||
### 부채의 우선순위 매트릭스
|
||||
|
||||
```text
|
||||
우선도 = (영향도 × 발생빈도) ÷ 수정 비용
|
||||
```
|
||||
|
||||
| 우선도 | 개발에의 영향 | 수정 비용 | 시간 삭감 효과 | 투자 대 효과 | 대응 기한 |
|
||||
| ----------------------- | ------------- | --------- | -------------- | ----------------- | ---------- |
|
||||
| **[P0] 지금 당장 대응** | 높음 | 낮음 | > 5배 | 투자 1h→삭감 5h+ | 즉시 |
|
||||
| **[P1] 이번 주중** | 높음 | 중간 | 2-5배 | 투자 1h→삭감 2-5h | 1주일 이내 |
|
||||
| **[P2] 이번 달중** | 낮음 | 높음 | 1-2배 | 투자 1h→삭감 1-2h | 1개월 이내 |
|
||||
| **[P3] 분기중** | 낮음 | 낮음 | < 1배 | 투자=삭감시간 | 3개월 이내 |
|
||||
|
||||
### 부채 타입별의 평가 기준
|
||||
|
||||
| 부채 타입 | 검출 방법 | 개발에의 영향 | 수정 시간 |
|
||||
| ------------------ | -------------------------- | ------------------------------- | --------- |
|
||||
| **아키텍처 부채** | 순환 의존, 밀결합 | 변경시 영향범위 대, 테스트 곤란 | 40-80h |
|
||||
| **보안 부채** | CVE 스캔, OWASP | 취약성 리스크, 컴플라이언스 | 8-40h |
|
||||
| **성능 부채** | N+1, 메모리 리크 | 응답시간 증가, 리소스 소비 | 16-40h |
|
||||
| **테스트 부채** | 커버리지 < 60% | 버그 검출 지연, 품질 불안정 | 20-60h |
|
||||
| **문서 부채** | README 부족, API 문서 없음 | 온보딩 시간 증가 | 8-24h |
|
||||
| **의존관계 부채** | 2년 이상 미업데이트 | 보안 리스크, 호환성 문제 | 4-16h |
|
||||
| **코드 품질 부채** | 복잡도 > 10 | 이해・수정 시간 증가 | 2-8h |
|
||||
|
||||
### 기술적 부채의 영향도 산출
|
||||
|
||||
```text
|
||||
영향도 = Σ(각 요소의 가중치 × 측정값)
|
||||
|
||||
📊 측정 가능한 영향 지표:
|
||||
├─ 개발 속도에의 영향
|
||||
│ ├─ 코드 이해 시간: +X% (복잡도에 비례)
|
||||
│ ├─ 변경시의 영향 범위: Y파일 (결합도로 측정)
|
||||
│ └─ 테스트 실행 시간: Z분 (CI/CD 파이프라인)
|
||||
│
|
||||
├─ 품질에의 영향
|
||||
│ ├─ 버그 발생률: 복잡도 10마다 +25%
|
||||
│ ├─ 리뷰 시간: 행수 × 복잡도 계수
|
||||
│ └─ 테스트 부족 리스크: 커버리지 60% 미만에서 고리스크
|
||||
│
|
||||
└─ 팀 효율에의 영향
|
||||
├─ 온보딩 시간: 문서 부족으로 +100%
|
||||
├─ 지식의 속인화: 단일 기여자율 >80%에서 요주의
|
||||
└─ 코드 중복에 의한 수정 개소: 중복률 × 변경 빈도
|
||||
```
|
||||
|
||||
### 시간 베이스의 ROI 계산
|
||||
|
||||
```text
|
||||
ROI = (삭감 시간 - 투자 시간) ÷ 투자 시간 × 100
|
||||
|
||||
예: 순환 의존의 해소
|
||||
├─ 투자 시간: 16시간 (리팩터링)
|
||||
├─ 삭감 효과 (월차):
|
||||
│ ├─ 컴파일 시간: -10분/일 × 20일 = 200분
|
||||
│ ├─ 디버그 시간: -2시간/주 × 4주 = 8시간
|
||||
│ └─ 신기능 추가: -30% 시간 단축 = 12시간
|
||||
├─ 월차 삭감 시간: 23.3시간
|
||||
└─ 3개월 ROI: (70 - 16) ÷ 16 × 100 = 337%
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
- 프로젝트의 언어나 프레임워크를 자동 검출하고, 그에 따른 분석을 실행합니다
|
||||
- 건전성 스코어는 0-100점으로 평가하고, 70점 이상을 건전, 50점 이하를 요개선으로 합니다
|
||||
- 시간적 비용과 개선 효과를 구체적으로 산출하고, 데이터에 기반한 의사결정을 지원합니다
|
||||
- 금전 환산이 필요한 경우는, 팀의 평균 시급이나 프로젝트 고유의 계수를 별도 지정해 주세요
|
||||
242
commands/token-efficient.md
Normal file
242
commands/token-efficient.md
Normal file
@@ -0,0 +1,242 @@
|
||||
# Token Efficiency Mode
|
||||
|
||||
AI 응답을 압축하여 컨텍스트 사용량을 30-50% 절감하는 효율화 모드입니다.
|
||||
|
||||
## 개요
|
||||
|
||||
Token Efficiency Mode 는 시각적 심볼과 약어 시스템을 활용하여 Claude 의 응답을 압축합니다.
|
||||
**생성되는 코드의 품질이나 내용은 전혀 변경되지 않습니다**. 바뀌는 것은 설명 방식뿐입니다.
|
||||
|
||||
## 사용법
|
||||
|
||||
```bash
|
||||
# 모드 활성화
|
||||
「Token Efficiency Mode 로 응답해주세요」
|
||||
「--uc 모드로」
|
||||
「간결 모드로」
|
||||
```
|
||||
|
||||
## 동작 원리
|
||||
|
||||
### 1. 심볼 체계
|
||||
|
||||
#### 로직 & 플로우
|
||||
|
||||
| 심볼 | 의미 | 사용 예시 |
|
||||
| ---- | -------------------------- | ------------------------------ |
|
||||
| → | ~로 이어지는, ~을 야기하는 | `auth.js:45 → 🛡️ 보안 위험` |
|
||||
| ⇒ | ~로 변환 | `input ⇒ validated_output` |
|
||||
| ← | 롤백, 되돌리기 | `migration ← rollback` |
|
||||
| ⇄ | 양방향 | `sync ⇄ remote` |
|
||||
| & | 그리고, 결합 | `🛡️ security & ⚡ performance` |
|
||||
| \| | 또는, 구분 | `react\|vue\|angular` |
|
||||
| : | 정의, 지정 | `scope: file\|module` |
|
||||
| » | 다음, 시퀀스 | `build » test » deploy` |
|
||||
| ∴ | 따라서 | `tests ❌ ∴ code broken` |
|
||||
| ∵ | 왜냐하면 | `slow ∵ O(n²) algorithm` |
|
||||
|
||||
#### 상태 & 진행
|
||||
|
||||
| 심볼 | 의미 | 용도 |
|
||||
| ---- | ---------- | ---------------- |
|
||||
| ✅ | 완료, 성공 | 작업 정상 종료 |
|
||||
| ❌ | 실패, 에러 | 즉시 대응 필요 |
|
||||
| ⚠️ | 경고 | 리뷰 권장 |
|
||||
| 🔄 | 진행 중 | 현재 활성 |
|
||||
| ⏳ | 대기 중 | 나중에 실행 예정 |
|
||||
| 🚨 | 긴급, 중요 | 고우선순위 |
|
||||
|
||||
#### 기술 도메인
|
||||
|
||||
| 심볼 | 분야 | 용도 |
|
||||
| ---- | ------------ | -------------- |
|
||||
| ⚡ | 성능 | 속도, 최적화 |
|
||||
| 🔍 | 분석 | 검색, 조사 |
|
||||
| 🔧 | 설정 | 셋업, 도구 |
|
||||
| 🛡️ | 보안 | 보호, 안전성 |
|
||||
| 📦 | 배포 | 패키지, 번들 |
|
||||
| 🎨 | 디자인 | UI, 프런트엔드 |
|
||||
| 🏗️ | 아키텍처 | 시스템 구조 |
|
||||
| 🗄️ | 데이터베이스 | 데이터 지속성 |
|
||||
| ⚙️ | 백엔드 | 서버 처리 |
|
||||
| 🧪 | 테스트 | 품질 보증 |
|
||||
|
||||
### 2. 약어 시스템
|
||||
|
||||
#### 시스템 & 아키텍처
|
||||
|
||||
- `cfg` → configuration (설정)
|
||||
- `impl` → implementation (구현)
|
||||
- `arch` → architecture (아키텍처)
|
||||
- `perf` → performance (성능)
|
||||
- `ops` → operations (운영)
|
||||
- `env` → environment (환경)
|
||||
|
||||
#### 개발 프로세스
|
||||
|
||||
- `req` → requirements (요구사항)
|
||||
- `deps` → dependencies (의존성)
|
||||
- `val` → validation (검증)
|
||||
- `auth` → authentication (인증)
|
||||
- `docs` → documentation (문서)
|
||||
- `std` → standards (표준)
|
||||
|
||||
#### 품질 & 분석
|
||||
|
||||
- `qual` → quality (품질)
|
||||
- `sec` → security (보안)
|
||||
- `err` → error (에러)
|
||||
- `rec` → recovery (복구)
|
||||
- `sev` → severity (심각도)
|
||||
- `opt` → optimization (최적화)
|
||||
|
||||
## 실제 비교 예시
|
||||
|
||||
### 예시 1: 에러 보고
|
||||
|
||||
**일반 모드 (92 자)**
|
||||
|
||||
```text
|
||||
인증 시스템의 사용자 검증 함수 45 행에서 보안 취약점이 발견되었습니다.
|
||||
```
|
||||
|
||||
**Token Efficient (39 자)**
|
||||
|
||||
```text
|
||||
auth.js:45 → 🛡️ sec vuln in user val()
|
||||
```
|
||||
|
||||
### 예시 2: 빌드 상황
|
||||
|
||||
**일반 모드 (145 자)**
|
||||
|
||||
```text
|
||||
빌드 프로세스가 정상적으로 완료되었습니다. 현재 테스트를 실행 중이며, 그 후 배포를 진행합니다.
|
||||
```
|
||||
|
||||
**Token Efficient (35 자)**
|
||||
|
||||
```text
|
||||
build ✅ » test 🔄 » deploy ⏳
|
||||
```
|
||||
|
||||
### 예시 3: 성능 분석
|
||||
|
||||
**일반 모드 (98 자)**
|
||||
|
||||
```text
|
||||
성능 분석 결과, 알고리즘이 O(n²) 의 복잡도로 인해 처리가 느린 것으로 판명되었습니다.
|
||||
```
|
||||
|
||||
**Token Efficient (42 자)**
|
||||
|
||||
```text
|
||||
⚡ perf: slow ∵ O(n²) → optimize to O(n)
|
||||
```
|
||||
|
||||
## 활용 시나리오
|
||||
|
||||
### ✅ 효과적인 상황
|
||||
|
||||
- **장시간 디버깅 세션**: 이력을 유지하면서 효율적으로
|
||||
- **대규모 코드 리뷰**: 다수의 파일을 간결하게 분석
|
||||
- **CI/CD 모니터링**: 실시간 상태 업데이트
|
||||
- **프로젝트 진행 상황 보고**: 여러 작업 상태를 한눈에 정리
|
||||
- **에러 추적**: 문제의 연쇄를 시각적으로 표현
|
||||
|
||||
### ❌ 피해야 할 상황
|
||||
|
||||
- 초보자에게 설명할 때
|
||||
- 상세한 문서 작성
|
||||
- 최초 요구사항 정의
|
||||
- 비기술자와의 소통
|
||||
|
||||
## 구현 예시
|
||||
|
||||
### 디버깅 세션
|
||||
|
||||
```text
|
||||
[14:23] breakpoint → vars: {user: null, token: expired}
|
||||
[14:24] step → auth.validate() ❌
|
||||
[14:25] check → token.exp < Date.now() ∴ expired
|
||||
[14:26] fix → refresh() → ✅
|
||||
[14:27] continue → main flow 🔄
|
||||
```
|
||||
|
||||
### 파일 분석 결과
|
||||
|
||||
```text
|
||||
/src/auth/: 🛡️ issues × 3
|
||||
/src/api/: ⚡ bottleneck in handler()
|
||||
/src/db/: ✅ clean
|
||||
/src/utils/: ⚠️ deprecated methods
|
||||
/tests/: 🧪 coverage 78%
|
||||
```
|
||||
|
||||
### 프로젝트 상태
|
||||
|
||||
```text
|
||||
Frontend: 🎨 ✅ 100%
|
||||
Backend: ⚙️ 🔄 75%
|
||||
Database: 🗄️ ✅ migrated
|
||||
Tests: 🧪 ⚠️ 68% (target: 80%)
|
||||
Deploy: 📦 ⏳ scheduled
|
||||
Security: 🛡️ 🚨 1 critical
|
||||
```
|
||||
|
||||
## 설정 옵션
|
||||
|
||||
```javascript
|
||||
// 압축 레벨
|
||||
--uc; // Ultra Compressed: 최대 압축
|
||||
--mc; // Moderate Compressed: 중간 압축
|
||||
--lc; // Light Compressed: 경량 압축
|
||||
|
||||
// 도메인 특화
|
||||
--dev; // 개발용 압축
|
||||
--ops; // 운영용 압축
|
||||
--sec; // 보안용 압축
|
||||
```
|
||||
|
||||
## 장점
|
||||
|
||||
1. **컨텍스트 절약**: 30-50% 의 토큰 절감
|
||||
2. **시각적 이해**: 심볼로 직관적 파악
|
||||
3. **정보 밀도 향상**: 같은 공간에 더 많은 정보
|
||||
4. **이력 유지**: 더 긴 대화 이력 보존
|
||||
5. **패턴 인식**: 시각적 패턴으로 문제 발견 용이
|
||||
|
||||
## 주의사항
|
||||
|
||||
- 이 모드는 **AI 의 응답 스타일**만을 변경합니다
|
||||
- 생성되는 **코드의 품질**은 변하지 않습니다
|
||||
- 필요 시 "일반 모드로 설명해주세요"로 전환 가능
|
||||
- 초보자나 비기술자에게는 일반 모드를 권장
|
||||
|
||||
## 명령어 예시
|
||||
|
||||
```bash
|
||||
# 활성화
|
||||
「Token Efficient Mode on」
|
||||
「간결하게 응답해주세요」
|
||||
「--uc 로 분석」
|
||||
|
||||
# 비활성화
|
||||
「일반 모드로 돌아가세요」
|
||||
「자세히 설명해주세요」
|
||||
「Token Efficient Mode off」
|
||||
```
|
||||
|
||||
## 구현에 미치는 영향
|
||||
|
||||
| 항목 | 영향 |
|
||||
| --------------- | -------------- |
|
||||
| 생성 코드 품질 | 변경 없음 ✅ |
|
||||
| 구현 정확성 | 변경 없음 ✅ |
|
||||
| 기능성 | 변경 없음 ✅ |
|
||||
| AI 설명 방식 | 압축됨 🔄 |
|
||||
| 컨텍스트 사용량 | 30-50% 절감 ⚡ |
|
||||
|
||||
---
|
||||
|
||||
💡 **Pro Tip**: 장시간 작업 세션에서는 처음에는 일반 모드로 이해를 높이고, 그 후 Token Efficient Mode 로 전환하여 효율성과 컨텍스트 보존의 균형을 최적화할 수 있습니다.
|
||||
65
commands/ultrathink.md
Normal file
65
commands/ultrathink.md
Normal file
@@ -0,0 +1,65 @@
|
||||
## Ultrathink
|
||||
|
||||
복잡한 과제나 중요한 결정에 대해 단계적이고 구조화된 사고 프로세스를 실행합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# Claude 에 깊은 사고를 의뢰
|
||||
「[과제]에 대해 ultrathink 로 검토하세요」
|
||||
```
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 아키텍처 설계의 검토
|
||||
「마이크로서비스와 모놀리스 중 어느 것을 선택해야 할지 ultrathink 로 검토하세요」
|
||||
|
||||
# 기술 선정의 분석
|
||||
「이 프로젝트에 Rust 와 TypeScript 중 어느 것이 적합한지 ultrathink 로 분석하세요」
|
||||
|
||||
# 문제 해결의 심화
|
||||
「애플리케이션의 성능이 나쁜 원인과 개선 방법을 ultrathink 로 검토하세요」
|
||||
```
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# 비즈니스 판단
|
||||
「신기능의 우선순위 부여를 ultrathink 로 검토하세요. 사용자 가치, 개발 비용, 기술적 리스크 관점으로」
|
||||
|
||||
# 시스템 설계
|
||||
「인증 시스템의 설계를 ultrathink 로 검토하세요. 보안, 확장성, 유지보수성을 고려해서」
|
||||
|
||||
# 트레이드오프 분석
|
||||
「GraphQL vs REST API 선택을 ultrathink 로 분석하세요. 프로젝트 요건에 기반해서」
|
||||
|
||||
# 리팩터링 전략
|
||||
cat src/legacy_code.js
|
||||
「이 레거시 코드의 리팩터링 전략을 ultrathink 로 수립하세요」
|
||||
```
|
||||
|
||||
### 사고 프로세스
|
||||
|
||||
1. **문제의 분해** - 과제를 구성 요소로 분해
|
||||
2. **MECE 분석** - 빠짐없이 중복없이 정리
|
||||
3. **복수 관점 검토** - 기술·비즈니스·사용자 관점으로 분석
|
||||
4. **대화형 확인** - 중요한 판단 포인트에서 사용자에게 확인
|
||||
5. **근거 기반 제안** - 데이터와 논리기반의 결론
|
||||
|
||||
### 상세 예제
|
||||
|
||||
```bash
|
||||
# 복잡한 기술적 부채의 해소
|
||||
「10 년간의 레거시 시스템을 모던화하는 전략을 ultrathink 로 검토하세요. 단계적 이전, 리스크, ROI 를 포함해서」
|
||||
|
||||
# 조직적인 과제
|
||||
「개발팀의 스케일링 전략을 ultrathink 로 검토하세요. 현재 5 명에서 20 명으로의 확대를 가정」
|
||||
|
||||
# 데이터베이스 이전
|
||||
「PostgreSQL 에서 DynamoDB 로의 이전을 ultrathink 로 분석하세요. 비용, 성능, 운용 측면을 고려해서」
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
ultrathink 는 시간을 들여 깊이 생각해야 하는 과제에 최적입니다. 단순한 질문이나 즉시 답변이 필요한 경우는 일반적인 질문 형식을 사용하세요.
|
||||
202
commands/update-dart-doc.md
Normal file
202
commands/update-dart-doc.md
Normal file
@@ -0,0 +1,202 @@
|
||||
## Update Dart Doc
|
||||
|
||||
Dart 파일의 DartDoc 코멘트를 체계적으로 관리하고, 고품질 한국어 문서를 유지합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# 신규 추가와 업데이트를 동시에 실행
|
||||
「DartDoc 코멘트가 없는 클래스에 추가하고, 기준을 만족하지 않는 코멘트를 업데이트하세요」
|
||||
|
||||
# PR 의 변경 파일을 확인
|
||||
「PR #4308 에서 변경된 파일의 DartDoc 에 Claude 마커가 있는지 확인하세요」
|
||||
|
||||
# 특정 디렉터리의 문서 정비
|
||||
「packages/app/lib/ui/screen/ 하위의 Widget 클래스에 DartDoc 을 추가하세요」
|
||||
|
||||
# 마커 없이 실행
|
||||
/update-dart-doc --marker false
|
||||
「기존 프로젝트의 DartDoc 을 개선 (Claude 마커는 붙이지 않음)」
|
||||
```
|
||||
|
||||
### 옵션
|
||||
|
||||
- `--marker <true|false>` : Claude 마커를 부여할지 (기본값: true)
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 1. 대상 파일 분석
|
||||
find . -name "*.dart" -not -path "*/.*" | grep -v "_test.dart" | grep -v "_vrt.dart"
|
||||
「DartDoc 이 부족한 클래스 (코멘트 행수 0 또는 30 자 미만)를 특정하세요」
|
||||
|
||||
# 2. 문서 추가
|
||||
「특정된 클래스에 필수 요소를 포함하는 DartDoc 코멘트를 추가하세요」
|
||||
|
||||
# 3. 마커 확인
|
||||
「추가·업데이트한 모든 DartDoc 에 Claude 마커가 있는지 확인하세요」
|
||||
```
|
||||
|
||||
### 실행 절차
|
||||
|
||||
#### 1. 대상 요소의 우선순위
|
||||
|
||||
1. 🔴 **최우선**: DartDoc 코멘트가 없는 요소 (코멘트 행수 0)
|
||||
2. 🟡 **차순위**: 기준을 만족하지 않는 요소 (30 자 미만 또는 필수 요소 결여)
|
||||
3. 🟢 **확인 대상**: Claude 마커가 없는 기존 코멘트
|
||||
|
||||
**대상 요소**:
|
||||
|
||||
- Class (모든 클래스 정의)
|
||||
- Enum (열거형)
|
||||
- Extension (확장 메서드)
|
||||
- 중요한 함수 (톱레벨 함수, 옵션)
|
||||
|
||||
#### 2. DartDoc 기술 규칙
|
||||
|
||||
**기본 구조**:
|
||||
|
||||
```dart
|
||||
/// {요소의 개요 설명} (30-60 자, 필수)
|
||||
///
|
||||
/// {상세 설명} (역할, 사용 컨텍스트, 주의점을 반드시 포함, 50-200 자)
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
@어노테이션 // 기존 어노테이션은 변경하지 않음
|
||||
class 클래스명 {
|
||||
```
|
||||
|
||||
**문장 스타일**:
|
||||
|
||||
- 정중어 (합니다체): 「표시합니다」「관리하는 클래스입니다」
|
||||
- 구두점은 「。」「、」 사용
|
||||
- 한국어와 반각 영숫자 간에 반각 스페이스
|
||||
- 기술 용어는 영어 표기: 「Authentication 상태」
|
||||
- 각 행은 80 자 이내
|
||||
|
||||
#### 3. 클래스 카테고리별 기술 예제
|
||||
|
||||
**상태 관리 클래스 (Riverpod)**:
|
||||
|
||||
```dart
|
||||
/// 수평 스와이프 제스처의 무효화 상태를 관리하는 State 입니다.
|
||||
///
|
||||
/// 특정 화면이나 조작 중에 수평 스와이프를 무효화할 필요가 있는 경우에
|
||||
/// 사용합니다. 예를 들어 캐러셀 표시 중이나 특정 입력 중 등.
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
@Riverpod(keepAlive: true, dependencies: [])
|
||||
class HorizontalDragGestureIgnoreState extends _$HorizontalDragGestureIgnoreState {
|
||||
```
|
||||
|
||||
**Widget 클래스**:
|
||||
|
||||
```dart
|
||||
/// 사용자 프로필을 표시하는 Widget 입니다.
|
||||
///
|
||||
/// 아바타 이미지, 사용자명, 상태 정보를 세로로 배치하고,
|
||||
/// 탭 시 프로필 상세 화면으로 전환합니다.
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
class UserProfileWidget extends HookConsumerWidget {
|
||||
```
|
||||
|
||||
#### 4. 기존 콘텐츠 보존 규칙
|
||||
|
||||
1. **기존 코멘트가 기준을 만족하는 경우**: 그대로 보존 (신규 추가하지 않음)
|
||||
- 기준: 30 자 이상이고 필수 요소 (개요·상세·마커)를 포함
|
||||
2. **기존 코멘트가 기준을 만족하지 않는 경우**: 완전히 교체 (중복시키지 않음)
|
||||
3. **기존 코멘트가 없는 경우**: 새로운 코멘트를 추가
|
||||
|
||||
**보존해야 할 중요 정보**:
|
||||
|
||||
- URL 이나 링크: `See also:`로 시작하는 참조
|
||||
- TODO 코멘트: `TODO(user_name):` 형식
|
||||
- 주의사항: `주의:` 나 `Warning:` 등의 경고
|
||||
- 사용 예: `예:` 나 `Example:`로 시작하는 코드
|
||||
- 기술적 제약: 성능이나 제한의 기술
|
||||
|
||||
### Claude 마커 관리
|
||||
|
||||
```bash
|
||||
# 마커 형식
|
||||
/// Generated by Claude 🤖
|
||||
|
||||
# PR 의 변경 파일에서 마커 확인
|
||||
gh pr diff 4308 --name-only | grep "\.dart$" | xargs grep -l "Generated by Claude"
|
||||
「마커가 없는 파일에 추가하세요」
|
||||
```
|
||||
|
||||
### 품질 체크리스트
|
||||
|
||||
- ✅ **글자 수**: 개요 30-60 자, 상세 50-200 자를 엄수
|
||||
- ✅ **필수 요소**: 개요·상세 설명·Claude 마커의 3 요소를 반드시 포함
|
||||
- ✅ **완전성**: 역할·사용 컨텍스트·주의점을 기재
|
||||
- ✅ **일관성**: 문체를 정중어 (합니다체)로 통일
|
||||
- ✅ **서식**: 한국어와 영어 간에 반각 스페이스
|
||||
- ✅ **정확성**: 구현을 분석하고 사실기반의 기술만
|
||||
- ✅ **구조**: 어노테이션 보존, 코멘트는 위에 배치
|
||||
- ✅ **길이**: 각 행을 80 자 이내
|
||||
- ✅ **마커**: Claude 을 통한 변경에는 반드시 마커 부여
|
||||
|
||||
### 주의사항
|
||||
|
||||
**🔴 절대 금지사항**:
|
||||
|
||||
- ❌ 문서 코멘트 이외의 코드 변경
|
||||
- ❌ 구현 세부사항에 관한 추측 (사실만 기재)
|
||||
- ❌ 영어와 한국어의 부자연스러운 혼재
|
||||
- ❌ 기존 어노테이션의 삭제·변경
|
||||
- ❌ 기존 코멘트와의 중복
|
||||
- ❌ 테스트 파일 (`*_test.dart`)에 글자 수 기준 미만의 코멘트
|
||||
- ❌ VRT 파일 (`*_vrt.dart`)에 글자 수 기준 미만의 코멘트
|
||||
|
||||
**정적 분석 및 커밋**:
|
||||
|
||||
```bash
|
||||
# 실행 결과의 기록
|
||||
ADDED_COMMENTS=0
|
||||
UPDATED_COMMENTS=0
|
||||
ERRORS=0
|
||||
|
||||
# 변경 후 확인
|
||||
melos analyze
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "🔴 에러: 정적 분석이 실패했습니다"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 실행 요약의 출력
|
||||
echo "📊 실행 결과:"
|
||||
echo "- 추가한 코멘트: $ADDED_COMMENTS 건"
|
||||
echo "- 업데이트한 코멘트: $UPDATED_COMMENTS 건"
|
||||
echo "- 에러 발생 수: $ERRORS 건"
|
||||
|
||||
# 커밋 예
|
||||
git commit -m "docs: DartDoc 코멘트를 추가·업데이트
|
||||
|
||||
- 기준을 만족하지 않는 클래스, enum, extension 에 DartDoc 을 추가
|
||||
- 30 자 미만의 코멘트를 기준에 맞게 업데이트
|
||||
- Claude 마커를 통일적으로 부여
|
||||
|
||||
실행 결과:
|
||||
- 추가: $ADDED_COMMENTS 건
|
||||
- 업데이트: $UPDATED_COMMENTS 건
|
||||
|
||||
Generated by Claude 🤖"
|
||||
```
|
||||
|
||||
### 실행 성공 기준
|
||||
|
||||
1. **완료 판정**: 다음을 모두 만족하는 경우에 성공
|
||||
- `melos analyze`가 PASSED
|
||||
- 에러 발생 수가 0
|
||||
- 추가·업데이트한 코멘트가 모두 기준을 만족
|
||||
|
||||
2. **부분 성공**: 다음의 경우
|
||||
- 에러 발생 수가 5 건 미만
|
||||
- 전체의 90% 이상이 기준을 만족
|
||||
|
||||
3. **실패**: 다음의 경우
|
||||
- `melos analyze`가 FAILED
|
||||
- 에러 발생 수가 5 건 이상
|
||||
306
commands/update-doc-string.md
Normal file
306
commands/update-doc-string.md
Normal file
@@ -0,0 +1,306 @@
|
||||
## Update Doc String
|
||||
|
||||
다언어 지원 docstring/코멘트를 체계적으로 관리하고, 고품질 문서를 유지합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# 언어를 자동 검출해서 실행
|
||||
「docstring 이 없는 클래스·함수에 추가하고, 기준을 만족하지 않는 코멘트를 업데이트하세요」
|
||||
|
||||
# 언어를 지정해서 실행
|
||||
/update-doc-string --lang python
|
||||
「Python 파일의 docstring 을 PEP 257 준수로 업데이트하세요」
|
||||
|
||||
# 특정 디렉터리의 문서 정비
|
||||
「src/components/ 하위의 함수에 JSDoc 을 추가하세요」
|
||||
```
|
||||
|
||||
### 옵션
|
||||
|
||||
- `--lang <en|ko>` : 문서의 기술 언어(기본값: 기존 코멘트에서 자동 판정, 없으면 en)
|
||||
- `--style <스타일>` : 문서 스타일을 지정(언어 고유의 기본값 있음)
|
||||
- `--marker <true|false>` : Claude 마커를 부여할지(기본값: true)
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 1. 대상 파일의 분석(프로그래밍 언어는 자동 검출)
|
||||
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.dart" -o -name "*.go" -o -name "*.rs" \) | grep -v test
|
||||
「docstring 이 부족한 요소(코멘트 행수 0 또는 30 자 미만)를 특정하세요」
|
||||
|
||||
# 2. 문서 추가(언어 자동 판정)
|
||||
「특정된 요소에 언어 고유의 필수 요소를 포함하는 docstring 을 추가하세요」
|
||||
# → 기존 코멘트에 한국어가 있으면 한국어로, 없으면 영어로 기술
|
||||
|
||||
# 3. 문서 추가(명시적으로 영어 지정)
|
||||
/update-doc-string --lang en
|
||||
「Add docstrings with required elements to the identified elements」
|
||||
|
||||
# 4. 마커 확인
|
||||
「추가·업데이트한 모든 docstring 에 Claude 마커가 있는지 확인하세요」
|
||||
```
|
||||
|
||||
### 실행 절차
|
||||
|
||||
#### 1. 대상 요소의 우선순위
|
||||
|
||||
1. 🔴 **최우선**: docstring/코멘트가 없는 요소(코멘트 행수 0)
|
||||
2. 🟡 **차순위**: 기준을 만족하지 않는 요소(30 자 미만 또는 필수 요소 결여)
|
||||
3. 🟢 **확인 대상**: Claude 마커가 없는 기존 코멘트
|
||||
|
||||
**대상 요소(언어 공통)**:
|
||||
|
||||
- Class/클래스 정의
|
||||
- Function/함수·메서드
|
||||
- Module/모듈(Python, Go)
|
||||
- Enum/열거형
|
||||
- Interface/인터페이스(TypeScript, Go)
|
||||
|
||||
#### 2. 언어별 기술 규칙
|
||||
|
||||
**Python (PEP 257)**:
|
||||
|
||||
```python
|
||||
# 한국어판(기본값)
|
||||
def calculate_total(items: List[Item]) -> float:
|
||||
"""아이템 리스트의 합계 금액을 계산합니다.(30-60 자)
|
||||
|
||||
각 아이템의 가격과 수량을 곱하여, 세금 포함 합계를 반환합니다.
|
||||
빈 리스트의 경우 0.0 을 반환합니다.(50-200 자)
|
||||
|
||||
Args:
|
||||
items: 계산 대상의 아이템 리스트
|
||||
|
||||
Returns:
|
||||
세금 포함 합계 금액
|
||||
|
||||
Generated by Claude 🤖
|
||||
"""
|
||||
|
||||
# 영어판(--lang en)
|
||||
def calculate_total(items: List[Item]) -> float:
|
||||
"""Calculate the total amount for a list of items. (30-60 chars)
|
||||
|
||||
Multiplies the price and quantity of each item and returns
|
||||
the total with tax. Returns 0.0 for empty lists. (50-200 chars)
|
||||
|
||||
Args:
|
||||
items: List of items to calculate
|
||||
|
||||
Returns:
|
||||
Total amount with tax
|
||||
|
||||
Generated by Claude 🤖
|
||||
"""
|
||||
```
|
||||
|
||||
**JavaScript/TypeScript (JSDoc)**:
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* 사용자 프로필을 표시하는 컴포넌트입니다.(30-60 자)
|
||||
*
|
||||
* 아바타 이미지, 사용자명, 상태 정보를 표시하고,
|
||||
* 클릭 시 프로필 상세 화면으로 전환합니다.(50-200 자)
|
||||
*
|
||||
* @param {Object} props - 컴포넌트의 프로퍼티
|
||||
* @param {string} props.userId - 사용자 ID
|
||||
* @param {boolean} [props.showStatus=true] - 상태 표시 플래그
|
||||
* @returns {JSX.Element} 렌더링된 컴포넌트
|
||||
*
|
||||
* @generated by Claude 🤖
|
||||
*/
|
||||
const UserProfile = ({ userId, showStatus = true }) => {
|
||||
```
|
||||
|
||||
**Go**:
|
||||
|
||||
```go
|
||||
// CalculateTotal 은 아이템 리스트의 합계 금액을 계산합니다.(30-60 자)
|
||||
//
|
||||
// 각 아이템의 가격과 수량을 곱하여, 세금 포함 합계를 반환합니다.
|
||||
// 빈 슬라이스의 경우 0.0 을 반환합니다.(50-200 자)
|
||||
//
|
||||
// Generated by Claude 🤖
|
||||
func CalculateTotal(items []Item) float64 {
|
||||
```
|
||||
|
||||
**Rust**:
|
||||
|
||||
```rust
|
||||
/// 아이템 리스트의 합계 금액을 계산합니다.(30-60 자)
|
||||
///
|
||||
/// 각 아이템의 가격과 수량을 곱하여, 세금 포함 합계를 반환합니다.
|
||||
/// 빈 벡터의 경우 0.0 을 반환합니다.(50-200 자)
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
pub fn calculate_total(items: &[Item]) -> f64 {
|
||||
```
|
||||
|
||||
**Dart (DartDoc)**:
|
||||
|
||||
```dart
|
||||
/// 사용자 프로필을 표시하는 Widget 입니다.(30-60 자)
|
||||
///
|
||||
/// 아바타 이미지, 사용자명, 상태 정보를 세로로 배치하고,
|
||||
/// 탭 시 프로필 상세 화면으로 전환합니다.(50-200 자)
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
class UserProfileWidget extends StatelessWidget {
|
||||
```
|
||||
|
||||
#### 3. 기존 콘텐츠 보존 규칙
|
||||
|
||||
1. **기존 코멘트가 기준을 만족하는 경우**: 그대로 보존(신규 추가하지 않음)
|
||||
- 기준: 30 자 이상이고 필수 요소(개요·상세·마커)를 포함
|
||||
2. **기존 코멘트가 기준을 만족하지 않는 경우**: 완전히 교체(중복시키지 않음)
|
||||
3. **기존 코멘트가 없는 경우**: 새로운 코멘트를 추가
|
||||
|
||||
**보존해야 할 중요 정보**:
|
||||
|
||||
- URL 이나 링크: `See also:`, `@see`, `참조:` 등
|
||||
- TODO 코멘트: `TODO:`, `FIXME:`, `XXX:` 형식
|
||||
- 주의사항: `Note:`, `Warning:`, `주의:` 등
|
||||
- 사용 예: `Example:`, `예:`, `# Examples` 등
|
||||
- 기존의 파라미터·반환값 설명
|
||||
|
||||
### 언어별 설정
|
||||
|
||||
```yaml
|
||||
# 언어별 기본 설정
|
||||
languages:
|
||||
python:
|
||||
style: "google" # google, numpy, sphinx
|
||||
indent: 4
|
||||
quotes: '"""'
|
||||
|
||||
javascript:
|
||||
style: "jsdoc"
|
||||
indent: 2
|
||||
prefix: "/**"
|
||||
suffix: "*/"
|
||||
|
||||
typescript:
|
||||
style: "tsdoc"
|
||||
indent: 2
|
||||
prefix: "/**"
|
||||
suffix: "*/"
|
||||
|
||||
go:
|
||||
style: "godoc"
|
||||
indent: 0
|
||||
prefix: "//"
|
||||
|
||||
rust:
|
||||
style: "rustdoc"
|
||||
indent: 0
|
||||
prefix: "///"
|
||||
|
||||
dart:
|
||||
style: "dartdoc"
|
||||
indent: 0
|
||||
prefix: "///"
|
||||
```
|
||||
|
||||
### 품질 체크리스트
|
||||
|
||||
- ✅ **글자 수**: 개요 30-60 자, 상세 50-200 자를 엄수
|
||||
- ✅ **필수 요소**: 개요·상세 설명·Claude 마커의 3 요소를 반드시 포함
|
||||
- ✅ **완전성**: 역할·사용 컨텍스트·주의점을 기재
|
||||
- ✅ **언어 규약**: 각 언어의 공식 스타일 가이드에 준수
|
||||
- ✅ **예외**: 오류·예외의 설명(해당하는 경우)
|
||||
- ✅ **정확성**: 구현을 분석하고 사실기반의 기술만
|
||||
|
||||
### 주의사항
|
||||
|
||||
**🔴 절대 금지사항**:
|
||||
|
||||
- ❌ 문서 코멘트 이외의 코드 변경
|
||||
- ❌ 구현 세부사항에 관한 추측(사실만 기재)
|
||||
- ❌ 언어 규약에 반하는 포맷
|
||||
- ❌ 기존 타입 어노테이션의 삭제·변경
|
||||
- ❌ 기존 코멘트와의 중복
|
||||
- ❌ 테스트 파일에 글자 수 기준 미만의 코멘트
|
||||
|
||||
**실행과 검증**:
|
||||
|
||||
```bash
|
||||
# 실행 결과의 기록
|
||||
ADDED_COMMENTS=0
|
||||
UPDATED_COMMENTS=0
|
||||
ERRORS=0
|
||||
|
||||
# 기존 코멘트에서 언어를 자동 판정
|
||||
# 한국어 문자(한글)를 검출하면 ko, 그 외는 en
|
||||
DOC_LANGUAGE="en" # 기본값
|
||||
if grep -r '[가-힣]' --include="*.py" --include="*.js" --include="*.ts" --include="*.dart" --include="*.go" --include="*.rs" . 2>/dev/null | head -n 1; then
|
||||
DOC_LANGUAGE="ko"
|
||||
fi
|
||||
|
||||
# 프로그래밍 언어의 자동 검출과 정적 분석
|
||||
if [ -f "*.py" ]; then
|
||||
pylint --disable=all --enable=missing-docstring .
|
||||
elif [ -f "*.js" ] || [ -f "*.ts" ]; then
|
||||
eslint . --rule 'jsdoc/require-jsdoc: error'
|
||||
elif [ -f "*.go" ]; then
|
||||
golint ./...
|
||||
elif [ -f "*.rs" ]; then
|
||||
cargo doc --no-deps
|
||||
elif [ -f "*.dart" ]; then
|
||||
melos analyze
|
||||
fi
|
||||
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "🔴 에러: 정적 분석이 실패했습니다"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 실행 요약의 출력
|
||||
echo "📊 실행 결과:"
|
||||
echo "- 문서 언어: $DOC_LANGUAGE"
|
||||
echo "- 추가한 코멘트: $ADDED_COMMENTS 건"
|
||||
echo "- 업데이트한 코멘트: $UPDATED_COMMENTS 건"
|
||||
echo "- 에러 발생 수: $ERRORS 건"
|
||||
```
|
||||
|
||||
### 실행 성공 기준
|
||||
|
||||
1. **완료 판정**: 다음을 모두 만족하는 경우에 성공
|
||||
- 언어 고유의 정적 분석이 PASSED
|
||||
- 에러 발생 수가 0
|
||||
- 추가·업데이트한 코멘트가 모두 기준을 만족
|
||||
|
||||
2. **부분 성공**: 다음의 경우
|
||||
- 에러 발생 수가 5 건 미만
|
||||
- 전체의 90% 이상이 기준을 만족
|
||||
|
||||
3. **실패**: 다음의 경우
|
||||
- 정적 분석이 FAILED
|
||||
- 에러 발생 수가 5 건 이상
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# 프로젝트 전체의 분석(언어 자동 판정)
|
||||
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" \)
|
||||
/update-doc-string
|
||||
「이 프로젝트의 docstring 을 언어별 베스트 프랙티스에 따라 업데이트하세요」
|
||||
# → 기존 코멘트에 한국어가 있으면 ko, 없으면 en 으로 실행
|
||||
|
||||
# 명시적으로 영어 문서로 실행
|
||||
/update-doc-string --lang en
|
||||
"Update docstrings following language-specific best practices"
|
||||
|
||||
# 명시적으로 한국어 문서로 실행
|
||||
/update-doc-string --lang ko
|
||||
「이 프로젝트의 docstring 을 언어별 베스트 프랙티스에 따라 업데이트하세요」
|
||||
|
||||
# 마커 없이 실행(언어 자동 판정)
|
||||
/update-doc-string --marker false
|
||||
"Improve existing docstrings without adding Claude markers"
|
||||
|
||||
# 영어 문서, 마커 없음
|
||||
/update-doc-string --lang en --marker false
|
||||
"Improve existing docstrings without adding Claude markers"
|
||||
```
|
||||
105
commands/update-flutter-deps.md
Normal file
105
commands/update-flutter-deps.md
Normal file
@@ -0,0 +1,105 @@
|
||||
## Flutter Dependencies Update
|
||||
|
||||
Flutter 프로젝트의 의존성을 안전하게 업데이트합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# 의존성의 상태를 확인해서 Claude 에 의뢰
|
||||
flutter pub deps --style=compact
|
||||
「pubspec.yaml 의 의존성을 최신 버전으로 업데이트하세요」
|
||||
```
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 현재 의존성을 확인
|
||||
cat pubspec.yaml
|
||||
「이 Flutter 프로젝트의 의존성을 분석해서 업데이트 가능한 패키지를 알려주세요」
|
||||
|
||||
# 업그레이드 후의 확인
|
||||
flutter pub upgrade --dry-run
|
||||
「이 업그레이드 예정 내용에서 파괴적 변경이 있는지 확인하세요」
|
||||
```
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# 포괄적인 의존성 업데이트
|
||||
cat pubspec.yaml
|
||||
「Flutter 의 의존성을 분석하고, 다음을 실행하세요:
|
||||
1. 각 패키지의 최신 버전을 조사
|
||||
2. 파괴적 변경의 유무를 확인
|
||||
3. 위험도를 평가(안전·주의·위험)
|
||||
4. 필요한 코드 변경을 제안
|
||||
5. 업데이트판 pubspec.yaml 을 생성」
|
||||
|
||||
# 안전한 단계적 업데이트
|
||||
flutter pub outdated
|
||||
「메이저 버전 업을 피하고, 안전하게 업데이트 가능한 패키지만 업데이트하세요」
|
||||
|
||||
# 특정 패키지의 업데이트 영향 분석
|
||||
「provider 를 최신 버전으로 업데이트한 경우의 영향과 필요한 변경을 알려주세요」
|
||||
```
|
||||
|
||||
### 상세 예제
|
||||
|
||||
```bash
|
||||
# Release Notes 를 포함한 상세 분석
|
||||
cat pubspec.yaml && flutter pub outdated
|
||||
「의존성을 분석하고, 각 패키지에 대해:
|
||||
1. 현재 → 최신 버전
|
||||
2. 위험도 평가(안전·주의·위험)
|
||||
3. 주요 변경점(CHANGELOG 에서)
|
||||
4. 필요한 코드 수정
|
||||
을 테이블 형식으로 제시하세요」
|
||||
|
||||
# Null Safety 이전의 분석
|
||||
cat pubspec.yaml
|
||||
「Null Safety 에 대응하지 않는 패키지를 특정하고, 이전 계획을 세워주세요」
|
||||
```
|
||||
|
||||
### 위험도의 기준
|
||||
|
||||
```text
|
||||
안전(🟢)：
|
||||
- 패치 버전 업(1.2.3 → 1.2.4)
|
||||
- 버그 수정만
|
||||
- 후방 호환성 보장
|
||||
|
||||
주의(🟡)：
|
||||
- 마이너 버전 업(1.2.3 → 1.3.0)
|
||||
- 새로운 기능 추가
|
||||
- 비권장 경고 있음
|
||||
|
||||
위험(🔴)：
|
||||
- 메이저 버전 업(1.2.3 → 2.0.0)
|
||||
- 파괴적 변경
|
||||
- API 의 삭제·변경
|
||||
```
|
||||
|
||||
### 업데이트의 실행
|
||||
|
||||
```bash
|
||||
# 백업 생성
|
||||
cp pubspec.yaml pubspec.yaml.backup
|
||||
cp pubspec.lock pubspec.lock.backup
|
||||
|
||||
# 업데이트 실행
|
||||
flutter pub upgrade
|
||||
|
||||
# 업데이트 후의 확인
|
||||
flutter analyze
|
||||
flutter test
|
||||
flutter pub deps --style=compact
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
업데이트 후에는 반드시 동작 확인을 실시하세요. 문제가 발생한 경우는 다음으로 복원：
|
||||
|
||||
```bash
|
||||
cp pubspec.yaml.backup pubspec.yaml
|
||||
cp pubspec.lock.backup pubspec.lock
|
||||
flutter pub get
|
||||
```
|
||||
105
commands/update-node-deps.md
Normal file
105
commands/update-node-deps.md
Normal file
@@ -0,0 +1,105 @@
|
||||
## Node Dependencies Update
|
||||
|
||||
Node.js 프로젝트의 의존성을 안전하게 업데이트합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# 의존성의 상태를 확인해서 Claude 에 의뢰
|
||||
npm outdated
|
||||
「package.json 의 의존성을 최신 버전으로 업데이트하세요」
|
||||
```
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 현재 의존성을 확인
|
||||
cat package.json
|
||||
「이 Node.js 프로젝트의 의존성을 분석해서 업데이트 가능한 패키지를 알려주세요」
|
||||
|
||||
# 업데이트 가능한 일람을 확인
|
||||
npm outdated
|
||||
「이 패키지들의 업데이트에서의 위험도를 분석하세요」
|
||||
```
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# 포괄적인 의존성 업데이트
|
||||
cat package.json
|
||||
「Node.js 의 의존성을 분석하고, 다음을 실행하세요:
|
||||
1. 각 패키지의 최신 버전을 조사
|
||||
2. 파괴적 변경의 유무를 확인
|
||||
3. 위험도를 평가(안전·주의·위험)
|
||||
4. 필요한 코드 변경을 제안
|
||||
5. 업데이트판 package.json 을 생성」
|
||||
|
||||
# 안전한 단계적 업데이트
|
||||
npm outdated
|
||||
「메이저 버전 업을 피하고, 안전하게 업데이트 가능한 패키지만 업데이트하세요」
|
||||
|
||||
# 특정 패키지의 업데이트 영향 분석
|
||||
「express 를 최신 버전으로 업데이트한 경우의 영향과 필요한 변경을 알려주세요」
|
||||
```
|
||||
|
||||
### 상세 예제
|
||||
|
||||
```bash
|
||||
# Release Notes 를 포함한 상세 분석
|
||||
cat package.json && npm outdated
|
||||
「의존성을 분석하고, 각 패키지에 대해:
|
||||
1. 현재 → 최신 버전
|
||||
2. 위험도 평가(안전·주의·위험)
|
||||
3. 주요 변경점(CHANGELOG 에서)
|
||||
4. 필요한 코드 수정
|
||||
을 테이블 형식으로 제시하세요」
|
||||
|
||||
# TypeScript 프로젝트의 타입 정의 고려
|
||||
cat package.json tsconfig.json
|
||||
「TypeScript 의 타입 정의도 포함해서 의존성을 업데이트하고, 타입 오류가 발생하지 않도록 업데이트 계획을 세워주세요」
|
||||
```
|
||||
|
||||
### 위험도의 기준
|
||||
|
||||
```text
|
||||
안전(🟢)：
|
||||
- 패치 버전 업(1.2.3 → 1.2.4)
|
||||
- 버그 수정만
|
||||
- 후방 호환성 보장
|
||||
|
||||
주의(🟡)：
|
||||
- 마이너 버전 업(1.2.3 → 1.3.0)
|
||||
- 새로운 기능 추가
|
||||
- 비권장 경고 있음
|
||||
|
||||
위험(🔴)：
|
||||
- 메이저 버전 업(1.2.3 → 2.0.0)
|
||||
- 파괴적 변경
|
||||
- API 의 삭제·변경
|
||||
```
|
||||
|
||||
### 업데이트의 실행
|
||||
|
||||
```bash
|
||||
# 백업 생성
|
||||
cp package.json package.json.backup
|
||||
cp package-lock.json package-lock.json.backup
|
||||
|
||||
# 업데이트 실행
|
||||
npm update
|
||||
|
||||
# 업데이트 후의 확인
|
||||
npm test
|
||||
npm run build
|
||||
npm audit
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
업데이트 후에는 반드시 동작 확인을 실시하세요. 문제가 발생한 경우는 다음으로 복원：
|
||||
|
||||
```bash
|
||||
cp package.json.backup package.json
|
||||
cp package-lock.json.backup package-lock.json
|
||||
npm install
|
||||
```
|
||||
107
commands/update-rust-deps.md
Normal file
107
commands/update-rust-deps.md
Normal file
@@ -0,0 +1,107 @@
|
||||
## Rust Dependencies Update
|
||||
|
||||
Rust 프로젝트의 의존성을 안전하게 업데이트합니다.
|
||||
|
||||
### 사용법
|
||||
|
||||
```bash
|
||||
# 의존성의 상태를 확인해서 Claude 에 의뢰
|
||||
cargo tree
|
||||
「Cargo.toml 의 의존성을 최신 버전으로 업데이트하세요」
|
||||
```
|
||||
|
||||
### 기본 예제
|
||||
|
||||
```bash
|
||||
# 현재 의존성을 확인
|
||||
cat Cargo.toml
|
||||
「이 Rust 프로젝트의 의존성을 분석해서 업데이트 가능한 크레이트를 알려주세요」
|
||||
|
||||
# 업데이트 가능한 일람을 확인
|
||||
cargo update --dry-run
|
||||
「이 크레이트들의 업데이트에서의 위험도를 분석하세요」
|
||||
```
|
||||
|
||||
### Claude 와의 연계
|
||||
|
||||
```bash
|
||||
# 포괄적인 의존성 업데이트
|
||||
cat Cargo.toml
|
||||
「Rust 의 의존성을 분석하고, 다음을 실행하세요:
|
||||
1. 각 크레이트의 최신 버전을 조사
|
||||
2. 파괴적 변경의 유무를 확인
|
||||
3. 위험도를 평가(안전·주의·위험)
|
||||
4. 필요한 코드 변경을 제안
|
||||
5. 업데이트판 Cargo.toml 을 생성」
|
||||
|
||||
# 안전한 단계적 업데이트
|
||||
cargo tree
|
||||
「메이저 버전 업을 피하고, 안전하게 업데이트 가능한 크레이트만 업데이트하세요」
|
||||
|
||||
# 특정 크레이트의 업데이트 영향 분석
|
||||
「tokio 를 최신 버전으로 업데이트한 경우의 영향과 필요한 변경을 알려주세요」
|
||||
```
|
||||
|
||||
### 상세 예제
|
||||
|
||||
```bash
|
||||
# Release Notes 를 포함한 상세 분석
|
||||
cat Cargo.toml && cargo tree
|
||||
「의존성을 분석하고, 각 크레이트에 대해:
|
||||
1. 현재 → 최신 버전
|
||||
2. 위험도 평가(안전·주의·위험)
|
||||
3. 주요 변경점(CHANGELOG 에서)
|
||||
4. 트레이트 경계의 변경
|
||||
5. 필요한 코드 수정
|
||||
을 테이블 형식으로 제시하세요」
|
||||
|
||||
# 비동기 런타임의 이전 분석
|
||||
cat Cargo.toml src/main.rs
|
||||
「async-std 에서 tokio 로의 이전, 또는 tokio 의 메이저 버전 업에 필요한 변경을 모두 제시하세요」
|
||||
```
|
||||
|
||||
### 위험도의 기준
|
||||
|
||||
```text
|
||||
안전(🟢)：
|
||||
- 패치 버전 업(0.1.2 → 0.1.3)
|
||||
- 버그 수정만
|
||||
- 후방 호환성 보장
|
||||
|
||||
주의(🟡)：
|
||||
- 마이너 버전 업(0.1.0 → 0.2.0)
|
||||
- 새로운 기능 추가
|
||||
- 비권장 경고 있음
|
||||
|
||||
위험(🔴)：
|
||||
- 메이저 버전 업(0.x.y → 1.0.0、1.x.y → 2.0.0)
|
||||
- 파괴적 변경
|
||||
- API 의 삭제·변경
|
||||
- 트레이트 경계의 변경
|
||||
```
|
||||
|
||||
### 업데이트의 실행
|
||||
|
||||
```bash
|
||||
# 백업 생성
|
||||
cp Cargo.toml Cargo.toml.backup
|
||||
cp Cargo.lock Cargo.lock.backup
|
||||
|
||||
# 업데이트 실행
|
||||
cargo update
|
||||
|
||||
# 업데이트 후의 확인
|
||||
cargo check
|
||||
cargo test
|
||||
cargo clippy
|
||||
```
|
||||
|
||||
### 주의사항
|
||||
|
||||
업데이트 후에는 반드시 동작 확인을 실시하세요. 문제가 발생한 경우는 다음으로 복원：
|
||||
|
||||
```bash
|
||||
cp Cargo.toml.backup Cargo.toml
|
||||
cp Cargo.lock.backup Cargo.lock
|
||||
cargo build
|
||||
```
|
||||
Reference in New Issue
Block a user