tidy

name	tidy
description	Performs small structural code cleanups (tidyings). Use when preparing code changes, removing dead code, reducing nesting, or cleaning up before feature work.

Tidy

Kent Beck의 "Tidy First?" 방법론으로 작은 구조적 정리를 수행합니다.

핵심 철학

• Tidying ≠ Refactoring: 몇 분 내 완료되는 작은 정리 — "Tidying is geek self-care"
• 구조 변경(S) vs 행동 변경(B) 분리: 하나의 변경에 구조와 행동을 섞지 않는다
• 1 tidying = 1 commit: 각 tidying은 반드시 별도 커밋
• 연속 실행 가능: 여러 tidying 수행 시 여러 커밋 생성
• 가역성 원칙: 대부분의 SW 설계 결정은 쉽게 되돌릴 수 있다 — 가역적 결정은 빠르게 내린다

WHY: 1 tidying = 1 commit

• 되돌리기 쉬운 단위
• 각 변경을 개별 추적 가능
• 문제 발생 시 특정 tidying만 revert

DECISION: 별도 커밋

• 이유: revert 용이, 리뷰 명확
• 대안: 기능과 함께 커밋 (거부: 문제 원인 추적 어려움)

자동 트리거

조건	예시
"tidy" + 작업 동사	"코드 정리해줘", "tidy 해줘"
기능 변경 전 정리 요청	"이거 수정 전에 좀 정리하고 싶어"
특정 패턴 언급	"guard clause로 바꿔줘", "dead code 제거"

Instructions

워크플로우 1: 작업 영역 파악

1. 기준 커밋 확인 (tidy 커밋 제외)

   # tidy: 커밋을 제외한 최근 커밋
   git log --format='%H %s' --grep='^tidy:' --invert-grep -n 1
   

   이 커밋이 테스트 통과의 기준점이 됩니다.

2. 컨텍스트 확인

   git status
   git diff --stat
   

3. 대상 파일 특정 (우선순위 순)

   1. 사용자가 명시한 파일
   2. git diff에 있는 수정 파일 → 전체 대상으로 자동 진행
   3. git diff가 비어있고 명시 파일도 없는 경우에만 → AskUserQuestion

4. 파일 분석 (code-analysis.md 준수)

   • < 200줄: 전체 Read 허용
   • 200-500줄: ast-grep 또는 부분 Read
   • 500줄+: Explore subagent 필수

워크플로우 2: 전체 Survey

대상 파일 전체를 스캔하여 적용 가능한 tidying 후보를 한번에 수집한다.

탐색 우선순위:

우선순위	패턴	감지 신호	선택 이유
1	Guard Clause	깊은 중첩, if-else 체인	중첩 감소로 버그 추적 용이
2	Dead Code	미사용 함수/변수, 주석 코드	혼란 제거, 오판 방지
3	Explaining Variable	복잡한 조건문	의도 명확화
4	Explaining Constant	매직 넘버/문자열	의미 부여
5	Normalize Symmetries	비일관적 패턴	일관성 확보 (⚠️ 우연한 유사성 주의)
6	Chunk Statements	빈 줄 없는 긴 문장 나열	논리 단위 시각화
7	Explicit Parameters	전역/컨텍스트 암묵 의존	의존성 명시화
8	Extract Helper	3회+ 반복 코드	중복 제거
9	Reading Order	함수 순서 불일치	흐름 개선
10	Cohesion Order	관련 코드 분산	응집도 향상

Dead Code 탐지 (작업 파일 범위 내):

• 주석 처리된 코드 블록
• 파일 내 미호출 private 함수
• 미사용 로컬 변수
• 전체 프로젝트 스캔은 범위 초과 → 별도 작업으로

상세 패턴: resources/01-tidying-patterns.md 참조

⚠️ 우연한 유사성 vs 진짜 중복

구분	진짜 중복	우연한 유사성
정의	동일 비즈니스 로직	구현 유사, 도메인 상이
특징	변경 시 함께 바뀜	독립 진화 가능
행동	통합	유지

통합 금지 신호: 다른 엔티티/도메인, 제네릭 필요, 조건문 증가

Survey 결과 형식 — 발견된 후보를 번호 매긴 테이블로 출력:

## Tidying Survey

| # | 패턴 | 위치 | 변경 요약 | 영향도 |
|---|------|------|-----------|--------|
| 1 | Guard Clause | auth.ts:42 | 3단 중첩 → early return | 가독성 ↑ |
| 2 | Dead Code | auth.ts:78-85 | 주석 코드 블록 제거 | 혼란 ↓ |
| 3 | Explaining Variable | order.ts:15 | 복합 조건 → 변수 추출 | 의도 명확 |
| ... | ... | ... | ... | ... |

총 {N}개 발견. 어떻게 진행할까요?

대상 파일이 많은 경우: Explore subagent를 활용하여 병렬 스캔한다.

판단 가이드: 언제 정리할 것인가 (Part II)

Survey 후 적용 전, 타이밍을 판단한다:

타이밍	조건	행동
First	다음 변경이 정리하면 쉬워질 때	지금 정리 후 변경
After	변경 완료 후 구조 개선 기회 발견	변경 커밋 후 별도 정리
Later	관련 없지만 발견한 문제	목록에 기록, 나중에 처리
Never	비용 > 가치, 또는 코드가 안정적	정리하지 않음

리듬: 1시간 이상 정리에 빠지면 → 더 작은 최소 변경을 놓쳤을 가능성. 멈추고 재평가. 배치 크기: 당장 필요한 범위만 정리. 파레토 분포 — 소수의 정리가 대부분의 가치를 제공.

상세: resources/02-managing-tidyings.md

워크플로우 3: 선택 및 적용

1. 사용자 선택 대기

   Survey 테이블 출력 후 AskUserQuestion으로 진행 방식 확인:

   • 전체 적용 — 모든 후보를 순서대로 적용
   • 번호 선택 — 특정 번호만 선택 (예: "1, 3, 5")
   • 패턴 선택 — 특정 패턴만 (예: "Guard Clause만")
   • 취소

2. 순차 적용

   선택된 후보를 순서대로 적용. 각 tidying마다:

   • 변경 적용
   • 테스트 확인 (중요 원칙 참조)
   • 커밋: git add {파일} && git commit -m "tidy: {패턴명} in {파일명}"
   • 실패 시: git restore {파일} + 해당 항목 skip 보고 후 다음으로

   질문 없이 연속 적용: 사용자가 선택한 항목은 개별 확인 없이 연속 진행한다.

3. 완료 보고

   ## Tidy 완료
   
   | # | 패턴 | 위치 | 상태 |
   |---|------|------|------|
   | 1 | Guard Clause | auth.ts:42 | ✓ 커밋됨 |
   | 2 | Dead Code | auth.ts:78 | ✓ 커밋됨 |
   | 3 | Explaining Variable | order.ts:15 | ✗ 테스트 실패 (skip) |
   
   {N}개 중 {M}개 적용, {K}개 커밋 생성됨
   

워크플로우 4: 특정 패턴 적용

사용자가 특정 패턴을 요청한 경우:

User: "guard clause로 바꿔줘"
→ Guard Clause 패턴만 집중 탐색
→ 해당 패턴 적용

중요 원칙

1. cost(SW) ≈ coupling (Constantine's Equivalence): 소프트웨어 비용의 대부분은 결합도에서 온다. 정리의 궁극적 목표는 불필요한 결합 감소. 상세: resources/03-theory.md
2. 동작 변경 금지: tidying은 구조만 변경, 동작은 그대로
3. 테스트 통과 유지: 기준 커밋(tidy 제외 최근 커밋)과 동일한 테스트 결과 유지
   • 워크플로우 1에서 확인한 기준 커밋의 테스트 상태를 기준으로 함
   • export/public 함수 수정 시: 전체 테스트 (Task subagent)
   • 내부 로직만 변경 시: 해당 파일 테스트만
   • 테스트 없는 경우: WARNING 후 계속
   • 실패 시: 자동 git restore {파일} + 보고
4. 1 tidying = 1 commit: 여러 tidying 실행 시 각각 별도 커밋
5. 되돌리기 쉽게: 독립적인 커밋으로 개별 revert 가능

Examples

기본 사용

User: "이 함수 정리해줘"
→ 워크플로우 1: 대상 파일 분석
→ 워크플로우 2: 전체 Survey → 5개 후보 테이블 출력
→ User: "전체 적용"
→ 워크플로우 3: 5개 연속 적용 → 5개 커밋
→ 완료 보고 테이블

선택 적용

User: "/tidy"
→ 워크플로우 1 → 2: 8개 후보 Survey
→ User: "1, 3, 5번만"
→ 워크플로우 3: 3개 연속 적용 → 3개 커밋
→ 완료 보고

특정 패턴 요청

User: "guard clause로 바꿔줘"
→ 워크플로우 4: Guard Clause 패턴만 Survey
→ 2개 발견 → 테이블 출력
→ User: "전체 적용"
→ 2개 연속 적용 → 2개 커밋

테스트 실패 시

User: "전체 적용"
→ #1 Guard Clause → ✓ 커밋
→ #2 Dead Code → ✗ 테스트 실패 → restore → skip
→ #3 Rename → ✓ 커밋
→ 완료 보고: 3개 중 2개 적용, 1개 skip

Technical Details

커밋 메시지 형식

tidy: {패턴명} in {파일명}

- {구체적 변경 내용}

예시:

tidy: guard clause in auth.ts

- Convert nested if-else to early returns
- Reduce nesting depth from 4 to 1

tidy-commit agent와의 관계

tidy skill	tidy-commit agent
코드 구조 정리	커밋 단위 정리
기능 변경 전	작업 완료 후
사용자 직접 호출	proactive 호출

조합 사용:

/tidy → 코드 정리 → 기능 구현 → tidy-commit → 커밋 정리

리소스

• resources/01-tidying-patterns.md: 15가지 tidying 패턴 상세
• resources/02-managing-tidyings.md: Part II — 정리 시점과 관리
• resources/03-theory.md: Part III — 구조, 결합, 경제학