Hestia

Hestia (헤스티아) — 화로의 여신, 코드 위생 관리자

헤스티아(Hestia): 올림포스 12신 중 하나, 화로와 가정의 여신. 화로를 깨끗이 유지하듯, 코드베이스에서 쓸모없는 것을 찾아 치운다. 조용하지만 빠지면 집이 무너진다.

argos가 "빠진 걸 찾고", hestia는 "남은 걸 치운다."

Quick Start

/hestia                         # 전체 스캔 (기본 = 보고만, 삭제 안 함)
/hestia scan                    # 스캔만 (보고만, 삭제 안 함)
/hestia clean                   # 스캔 + 자동 삭제
/hestia src/                    # 특정 디렉토리만
/hestia --dry-run               # 삭제 대상 미리보기 (실행 안 함)

공식 호출명: /hestia (별칭: 헤스티아, 코드 정리, dead code)

파이프라인 위치

/agent-team → /argos → /minos → /hestia → /clio
  구현          감리      QA      정리       기록
                                  ↑
                          "argos/minos 통과 후, clio 기록 전"

또는 독립 실행 — 언제든 /hestia로 현재 코드베이스 점검 가능.

Phase 1: 측정 (Before)

변경 전 현재 상태를 측정합니다. 측정 없는 정리는 감이지 사실이 아닙니다.

# 총 LOC (프로덕션 코드만, 테스트 제외)
find src/ app/ lib/ -name "*.ts" -o -name "*.tsx" -o -name "*.py" -o -name "*.java" -o -name "*.cs" \
  | grep -v "__test__\|\.test\.\|\.spec\.\|_test\." \
  | xargs wc -l 2>/dev/null | tail -1

# 파일 수
find src/ app/ lib/ -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.py" \) | wc -l

# 책임 분리 검토용 대형 파일
find src/ -type f \( -name "*.ts" -o -name "*.py" \) \
  -exec awk 'END{print NR,FILENAME}' {} \; | sort -nr | head -20

📏 현재 상태:
  LOC: {N}줄
  파일: {M}개
  책임 분리 검토 대상 파일: {K}개

Phase 2: 스캔 (Dead Code 탐지)

2-1. 미사용 Export

# TypeScript/JavaScript — knip 권장 (미사용 export·파일·의존성을 한 번에, --fix로 자동 제거)
# ts-prune/depcheck/unimported는 2025년 archive/maintenance → knip이 통합 후속
npx knip 2>/dev/null | head -40

# 레거시 단일 목적 대안 (export만): npx ts-prune | grep -v "used in module"
# 결과 예시:
# src/utils/format.ts:15 - formatCurrency (unused)

2-2. 미사용 의존성

# JS/TS는 knip(2-1)이 의존성도 함께 탐지. depcheck는 레거시 대안 (2025 archive)
npx depcheck 2>/dev/null | head -20

# Python
pip-extra-reqs --ignore-requirement=dev src/ 2>/dev/null

# 결과 예시:
# Unused dependencies: lodash, moment, classnames
# Missing dependencies: (none)

2-3. 미사용 파일

# JS/TS는 knip(2-1)이 미사용 파일도 함께 탐지. unimported는 레거시 대안 (knip으로 대체)
npx unimported 2>/dev/null | head -20

# 결과 예시:
# src/components/OldButton.tsx - not imported anywhere
# src/utils/deprecated.ts - not imported anywhere

2-4. Dead Code 마커

# 삭제 예고된 코드
grep -rn "@deprecated\|TODO.*remove\|TODO.*delete\|HACK\|FIXME\|XXX" \
  --include="*.{ts,tsx,py,java,cs}" src/ app/ lib/ 2>/dev/null | head -20

# 호환성 코드
grep -rn "backwards.*compat\|legacy.*shim\|// old\|// deprecated" \
  --include="*.{ts,tsx,py,java,cs}" src/ 2>/dev/null | head -20

2-5. 빈 파일/폴더

find src/ app/ lib/ -empty -type f 2>/dev/null
find src/ app/ lib/ -empty -type d 2>/dev/null

2-6. 사전 미등재 도메인 식별자 (도메인사전 있을 때만)

docs/domain-dictionary.md가 있으면 코드의 클래스/함수/타입명 중 사전에 없는 도메인 식별자를 보고합니다. 삭제 대상 ❌ — 사전 갱신 트리거일 뿐.

# 대문자로 시작하는 식별자 추출 (도메인 명사 후보)
grep -rE "^(export\s+)?(class|interface|type|enum)\s+[A-Z]\w+" --include="*.ts" --include="*.tsx" src/ \
  | grep -oE "(class|interface|type|enum)\s+[A-Z]\w+" | sort -u

각 식별자에 대해:

• 사전 영문 식별자 목록과 대조
• 사전에 없으면 → 보고 (도메인 신규 용어인지 / 기술 인프라 용어인지 사용자 판단)

출력 분류:

• 도메인 신규 용어 (예: class Voucher) → 사전 갱신 권장
• 기술 인프라 용어 (예: class CacheManager) → 사전 외 정상

기술 인프라 용어 휴리스틱: Manager, Handler, Factory, Builder, Cache, Queue, Worker, Pool, Adapter 같은 GoF/구조 패턴 접미사가 붙으면 인프라로 분류.

2-7. 의도적 단순화 마커 (minimal 부채 장부)

Hestia가 소유하는 // minimal: <상한> — <업그레이드 시점> 규약을 사용합니다. 상한은 현재 구현이 의도적으로 감수하는 제약이고, 업그레이드 시점은 교체를 검토할 수치·상태 조건입니다. 마커를 수확해 부채 장부로 보고합니다. 삭제 대상 ❌ — 의도된 지름길의 추적 장부일 뿐, "later means never"로 썩는 것을 막는 게 목적입니다.

# 주석 스타일별 minimal 마커 수확 (// # -- <!--)
grep -rn "// minimal:\|# minimal:\|-- minimal:\|<!-- minimal:" \
  --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" \
  --include="*.py" --include="*.java" --include="*.cs" --include="*.sql" \
  src/ app/ lib/ 2>/dev/null | head -30

장부 형식으로 보고:

📒 단순화 부채 장부 ({N}건)
  1. src/api/orders.ts:42 — 전역 락 | 업그레이드: 처리량 문제 시 계좌별 락
  2. app/report.py:88 — O(n²) 스캔 | 업그레이드: 1만 행 초과 시 인덱스 조인

판단 기준:

• 상한 조건이 이미 도달한 것으로 보이는 마커 (예: "1만 행 초과 시" — 현재 데이터가 초과) → ⚠️ 업그레이드 권장 표시
• 마커에 상한/업그레이드 시점이 없는 것 → 형식 보완 권장 (<상한> — <시점>)
• 업그레이드 실행 여부는 사용자 결정 — hestia는 장부만 만든다

스캔 결과 보고

🔍 Hestia 스캔 결과
━━━━━━━━━━━━━━━━━━━
  미사용 export:     {N}개
  미사용 의존성:     {N}개
  미사용 파일:       {N}개
  @deprecated 마커:  {N}개
  빈 파일/폴더:      {N}개
  사전 미등재 도메인: {N}개  (사전 있을 때만)
  minimal 부채 장부:  {N}건  (보고 전용, 삭제 안 함)
  ──────────────────
  총 정리 대상:      {N}건

scan 모드면 여기서 종료. clean 모드면 Phase 3으로 진행.

Phase 3: 정리 (Clean)

삭제 전 안전 체크

삭제 순서 (안전한 것부터)

1단계: 빈 파일/폴더 삭제           (위험도: 없음)
2단계: 미사용 의존성 제거           (위험도: 낮음, package.json만)
3단계: 미사용 파일 삭제             (위험도: 낮음, import 체인에 없음)
4단계: 미사용 export 삭제           (위험도: 중간, 동적 import 가능성)
5단계: @deprecated 코드 제거        (위험도: 중간, 외부 사용자 확인 필요)

각 삭제 후 검증

# 삭제할 때마다
# 1. 타입 체크
npx tsc --noEmit 2>&1 || echo "타입 에러 발생 — revert"

# 2. 테스트
npm test 2>&1 || echo "테스트 실패 — revert"

# 실패 시 즉시 revert
git checkout -- {삭제한 파일}

원칙: 삭제 → 검증 → 실패 시 되돌리기. 한꺼번에 삭제하지 않고, 단계별로 검증합니다.

Phase 4: 측정 (After) + 보고

# 동일 명령 재실행
find src/ app/ lib/ -name "*.ts" -o -name "*.tsx" -o -name "*.py" -o -name "*.java" -o -name "*.cs" \
  | grep -v "__test__\|\.test\.\|\.spec\.\|_test\." \
  | xargs wc -l 2>/dev/null | tail -1

최종 보고

🏠 Hestia 정리 완료
━━━━━━━━━━━━━━━━━━━━━
  Before: {N} LOC, {M} files
  After:  {N'} LOC, {M'} files
  Delta:  -{차이} LOC (-{퍼센트}%), -{파일} files

  삭제 내역:
    🗑️ 미사용 export {N}개 제거
    🗑️ 미사용 의존성 {N}개 제거
    🗑️ 미사용 파일 {N}개 삭제
    🗑️ @deprecated 코드 {N}건 제거
    ⏭️ 건너뜀 {N}건 (동적 참조 가능성)

  테스트: {PASS / 삭제 전으로 revert된 항목 N건}

다음 단계:
  /commit     → 정리 결과 커밋
  /clio       → 최종 기록

옵션

하지 않는 것

• 리팩토링 안 함 — 로직 변경, 함수 분리, 구조 개선은 범위 밖
• 마이그레이션 안 함 — 라이브러리 교체는 /deprecate
• 기능 추가 안 함 — 누락된 기능 구현은 /argos Healer
• 설계 판단 안 함 — "이 기능이 필요한가?"는 사용자 결정

헤스티아는 오직 "아무도 안 쓰는 것을 치우는 것"만 합니다.

Related Files