handoff-verify

# /handoff-verify - 핸드오프 + 자동 검증 통합 (v6)

v5의 `/handoff` + `/clear` + `/verify`를 **하나의 커맨드**로 통합.
핵심 변경: `/clear` 불필요 — Task 도구로 생성한 **서브에이전트가 fresh context**를 자동으로 제공한다.

## v5 대비 변경사항

| v5 | v6 |
|----|-----|
| /handoff → /clear → /verify (3단계, 수동) | /handoff-verify (1단계, 자동) |
| /clear로 컨텍스트 초기화 필요 | 서브에이전트가 fresh context 제공 |
| 부모 컨텍스트 손실 | 부모 컨텍스트 보존 |
| /context-status로 사용량 확인 | 빌트인 /cost 사용 |

## 0단계: 인자 파싱

$ARGUMENTS에서 플래그를 파싱한다.

| 플래그 | 기본값 | 설명 |
|--------|--------|------|
| `--once` | false | 단발 검증 (루프 없음) |
| `--loop N` | 5 | 최대 재시도 횟수 |
| `--security` | false | 보안 리뷰 포함 |
| `--coverage` | false | 테스트 커버리지 분석 모드 |
| `--extract` | false | 에러 추출 모드 |
| `--skip-handoff` | false | handoff.md 생성 건너뛰기 (이미 있을 때) |
| `--effort` | high | 검증 깊이: low / medium / high / max |
| `--only` | all | 특정 단계만: build / test / lint / type |

플래그를 제외한 나머지 텍스트 = 의도 설명(intent).

### effort별 동작 차이

| effort | 코드 리뷰 범위 | thinking 수준 | 자동 수정 범위 | 보안 검토 |
|--------|---------------|--------------|---------------|-----------|
| low | 변경 파일만 빠른 스캔 | 기본 | import/lint만 | 건너뜀 |
| medium | 변경 파일 + 직접 의존성 | think hard | Fixable 전체 | 패턴 매칭만 |
| high | 변경 파일 + 의존성 그래프 | think harder | Fixable 전체 + 리팩토링 제안 | 주요 패턴 검사 |
| max | 전체 프로젝트 영향 분석 | ultrathink | Fixable 전체 + 아키텍처 검토 | security-reviewer 에이전트 |

## 1단계: 환경 수집

다음을 병렬로 수집한다:

1. `git status --short` — 변경 파일 목록
2. `git diff --name-only` — 스테이징 전 변경사항
3. `git log --oneline -10` — 최근 커밋
4. `.claude/handoff.md` 읽기 (존재 시)
5. 프로젝트 문서 읽기 (존재 시): `CLAUDE.md`, `spec.md`, `prompt_plan.md`
6. 프로젝트 타입 감지:
   - `package.json` → Node.js (npm/pnpm/yarn 자동 감지)
   - `go.mod` → Go
   - `Cargo.toml` → Rust
   - `pyproject.toml` / `requirements.txt` → Python
   - `Makefile` → Make 기반

**패키지 매니저 감지 순서:**
1. `pnpm-lock.yaml` 존재 → pnpm
2. `yarn.lock` 존재 → yarn
3. `bun.lockb` 존재 → bun
4. 기본값 → npm

git 레포가 아니면 → "git init 필요" 안내 후 중단.
변경사항 없으면 → "변경사항 없음" 안내 후 중단.

## 2단계: Handoff 문서 자동 생성

> `--skip-handoff` 플래그가 있으면 이 단계를 건너뛴다.
> `.claude/handoff.md`가 이미 있으면 → 기존 내용에 누적 추가 (append).

`.claude/` 디렉토리 없으면 `mkdir -p .claude` 실행.
`.claude/handoff.md`에 다음 템플릿으로 작성한다:

```markdown
# Handoff Document
생성일시: [YYYY-MM-DD HH:MM KST]
effort: [현재 세션에서 사용된 effort level, 없으면 "default"]

## 1. 완료한 작업
- [작업 1: 구현/수정한 기능과 의도]
- [작업 2: 구현/수정한 기능과 의도]

## 2. 변경 파일 요약
| 파일 | 변경 유형 | 설명 |
|------|----------|------|
| src/xxx.ts | 수정 | [변경 내용] |
| src/yyy.ts | 신규 | [파일 목적] |

## 3. 테스트 필요 사항
- [ ] [테스트 항목 1: 시나리오 및 기대 결과]
- [ ] [테스트 항목 2: 엣지 케이스]

## 4. 알려진 이슈 / TODO
- [ ] [이슈 1: 미완성 부분]

## 5. 주의사항
- [다음 세션에서 주의할 점]

## 6. 검증 권장 설정
- effort: [다음 검증에 권장하는 effort level]
- security: [true/false]
- coverage: [true/false]
- only: [특정 검증만 필요하면 명시, 없으면 all]
- loop: [권장 재시도 횟수]
```

### security 판단 기준
- `auth`, `login`, `session`, `token`, `password`, `secret`, `key`, `credential`, `middleware` 포함 파일 변경 시 → true
- `.env`, `.env.*` 관련 변경 시 → true
- 그 외 → false

### effort 권장 기준
- 단순 수정 (1~3 파일, 린트/포맷) → low
- 기능 수정 (4~10 파일) → medium
- 기능 추가/리팩토링 (10+ 파일) → high
- 아키텍처 변경, 보안 관련, DB 스키마 변경 → max

### coverage 판단 기준
- 테스트 파일 (`*.test.*`, `*.spec.*`) 변경 시 → true
- 비즈니스 로직 파일 변경이 있으나 대응 테스트 변경 없을 시 → true
- 그 외 → false

## 3단계: 의도 병합

handoff.md의 검증 권장 설정과 CLI 플래그를 병합한다.
**CLI 플래그가 우선.** handoff.md는 CLI에서 명시하지 않은 항목만 적용.

의도 우선순위:
1. `$ARGUMENTS`에서 파싱한 의도 설명
2. `.claude/handoff.md`의 검증 권장 설정
3. 둘 다 없으면 → 일반 검증 진행

## 4단계: 서브에이전트 검증 실행 (핵심)

> 이것이 v6의 핵심 혁신이다.
> Task 도구로 `verify-agent` 서브에이전트를 생성하여 **fresh context에서 검증**한다.
> 부모 컨텍스트는 보존되면서 /clear 효과를 얻는다.

### 모드 분기

플래그에 따라 서브에이전트에 전달할 모드를 결정한다:

- `--extract` → 에러 추출 모드 (루프 없음)
- `--coverage` → 커버리지 모드 (루프 없음)
- `--security` → security-reviewer 에이전트 호출 포함
- `--once` → 단발 검증 (1회)
- 기본 → 검증 루프 (최대 N회)

### 서브에이전트 호출

Task 도구로 `verify-agent`를 호출한다:

```
Task (subagent_type: general-purpose, model: sonnet)

지시:
1. .claude/handoff.md를 읽어 변경 의도를 파악하라
2. 프로젝트 타입: [감지된 타입]
3. 패키지 매니저: [감지된 PM]
4. 검증 모드: [mode]
5. effort: [level]
6. 최대 재시도: [N]
7. --only: [all 또는 특정 단계]
8. --security: [true/false]

검증 파이프라인을 실행하고 결과를 반환하라.
실패 시 Fixable 에러는 자동 수정을 시도하고 재검증하라.
Non-fixable 에러는 보고만 하라.
```

서브에이전트가 실행하는 검증 파이프라인:

**A. 코드 리뷰 (effort 기반 adaptive thinking)**

effort에 따라 thinking 깊이를 조절한다:
- low: 변경 파일의 명백한 오류만 체크
- medium: think hard — 변경 파일과 직접 참조 파일 분석
- high: think harder — 의존성 그래프 따라 영향 범위 분석
- max: ultrathink — 전체 아키텍처 영향, 엣지 케이스, 성능 영향 분석

리뷰 체크리스트:
- [ ] 변경된 코드가 의도와 일치하는가
- [ ] 뮤테이션 없이 불변성 패턴 사용
- [ ] 에러 핸들링 존재
- [ ] 하드코딩된 비밀값 없음
- [ ] console.log 없음 (디버깅용 제외)
- [ ] 함수 50줄 이하
- [ ] 파일 800줄 이하
- [ ] 입력값 검증 (사용자 입력 경로)

**B. 자동 검증 실행**

프로젝트 타입별 검증 커맨드 (`[pm]` = 감지된 패키지 매니저):

**Node.js:**
```bash
# 1. 타입 체크 (tsconfig.json 존재 시)
[pm] run typecheck || npx tsc --noEmit

# 2. 린트
[pm] run lint || npx eslint .

# 3. 빌드
[pm] run build

# 4. 테스트
[pm] run test || npx vitest run || npx jest
```

**Go:**
```bash
go build ./...
go vet ./...
go test ./...
golangci-lint run  # 설치 시
```

**Rust:**
```bash
cargo check
cargo clippy -- -D warnings
cargo test
```

**Python:**
```bash
python -m py_compile [changed files]
ruff check . || flake8 .
pytest
```

`--only` 플래그가 있으면 해당 단계만 실행:
- `--only build` → 빌드만
- `--only test` → 테스트만
- `--only lint` → 린트만
- `--only type` → 타입 체크만

**C. 결과 표시**

각 검증 단계별 상태:
```
  [attempt 1/5]
  ──────── ────────── ────────
  TypeCheck    PASS
  Lint         FAIL    2 errors (fixable)
  Build        PASS
  Test         PASS    42 passed
  ──────── ────────── ────────
```

상태 분류:
- PASS: 통과
- FAIL: 실패
- SKIP: 해당 없음 (설정 파일 없음 등)
- WARN: 경고 (non-blocking)

**D. 실패 시 자동 수정 (루프 모드)**

Fixable 에러 목록:

| 에러 유형 | 자동 수정 방법 | effort 최소 |
|-----------|--------------|-------------|
| import missing | 올바른 import 문 추가 | low |
| lint format | `eslint --fix` / `prettier --write` | low |
| unused imports | import 문 자동 제거 | low |
| missing semicolons | 자동 추가 | low |
| trailing whitespace | 자동 제거 | low |
| unused variables | 삭제 또는 `_` prefix | medium |
| type simple errors | 타입 추론으로 수정 | medium |
| missing return types | 반환 타입 자동 추가 | medium |
| simple null checks | optional