본문으로 건너뛰기

스펙 문서 동기화 및 하네스 main 작업 금지 규칙 명문화

· 약 4분
jangsungyu
jangsungyu
Frontend Developer
Claude Code
Claude Code
AI Assistant

작업 날짜: 2026-05-18 브랜치: feature/1.43.0-spec-sync

작업 개요​

작업 유형: 문서 동기화 / 하네스 규칙 강화 담당: jsg3121 + Claude

작업 목표​

  • 1.40.0~1.42.0 사이에 머지된 작업이 실행 계획서에 누락되어 있어, 다음 작업 진입 시점에 진행 현황과 다음 액션을 명확히 파악할 수 있도록 스펙 문서를 최신화한다.
  • 본 작업 진행 중 main 브랜치에서 파일 수정이 시작되는 사고가 발생하여, CLAUDE.md와 workflow.md에 "main 브랜치에서는 어떠한 파일 수정도 수행하지 않는다"는 절대 규칙을 명시한다.

주요 변경사항​

1. 트래픽 증대 실행 계획서 동기화​

.claude/specs/traffic-growth-implementation-plan.md

기존 "마지막 갱신"이 2026-05-06(C-3 완료)에 멈춰 있어, 이후 1.40.0 릴리즈·1.41.0 Next.js 15 업그레이드·1.42.0 챔피언스 홈 쿼리 마이그레이션이 문서에 반영되지 않았다.

  • 마지막 갱신 일자: 2026-05-06 → 2026-05-11
  • 진행 기록에 1.40.0 릴리즈 + 핫픽스, 1.41.0(보안 패치, ADR-0004 연계), 1.42.0(getBestChampionsPokemon 쿼리 적용) 3건 추가
  • "다음 진행 시 채울 항목" 블록을 실제 완료 내역으로 치환하고, 새 다음 액션(D-1 이로치 URL 정적 경로, E-13 백엔드 협업, F-12 운영/외부, 효과 측정) 정리

2. 챔피언스 구현 계획서에 최근 갱신 현황 추가​

.claude/specs/champions-implementation-plan.md

체크리스트는 실제 코드 검증 없이 임의로 ✅ 처리하면 정합성이 깨지므로 그대로 두고, 파일 끝에 "최근 갱신 현황" 섹션을 신설했다.

  • 메인 홈 → 챔피언스 인입 경로(1.40.0 PR #125, 1.42.0 PR #132) 요약
  • M1~M3 코드 반영 확인 사항(라우트, 쿼리, 메타데이터, 사이트맵 우선순위)
  • M4(티어/메타 페이지) 추가 점검 필요 항목 명시 — VP 계산기 미착수, 메타 데이터 상세 페이지 노출 여부 확인 대상
  • M5 메인 허브·SEO 완료, B-3 스킵 결정 유지

3. CLAUDE.md에 main 브랜치 작업 금지 규칙 강화 (CRITICAL)​

CLAUDE.md

기존 IMPORTANT 규칙은 "현재 브랜치를 확인하고 적절한지 검증"만 명시되어 있어, 본 작업처럼 main이 현재 브랜치인 상태에서 사용자 승인을 일반 작업 승인으로 확대 해석하는 사고가 재발할 수 있었다.

  • CRITICAL 등급으로 신규 규칙 추가:
    • main 브랜치에서는 어떠한 파일 수정·생성·삭제도 절대 수행하지 않는다 (문서·코드·changelog·설정 예외 없음)
    • 작업 요청 수신 시 가장 먼저 git branch --show-current 확인 → main이면 분기 제안 후 분기 완료 시점에만 작업 시작
    • 사용자의 일반 승인("진행해줘")은 main 직접 작업 승인이 아니며, 명시적 지시("main에서 그대로 작업") 없이는 분기를 우선
  • 기존 IMPORTANT 규칙은 유지하되, .claude/conventions/guides/workflow.md 경로를 명시하여 상세 규칙 참조 가능하게 보강

4. workflow.md에 절대 규칙 섹션 신설 및 복구 절차 추가​

.claude/conventions/guides/workflow.md

문서 최상단에 "절대 규칙: main 브랜치 작업 금지" 섹션을 신설했다. Why-First 원칙에 따라 이유와 적용 방법을 함께 기술.

  • Why: main은 릴리즈 PR로만 변경되어야 추적성·changelog 정합성 유지. 일반 승인은 변경 내용에 대한 승인이지 main 직접 수정 승인이 아니며, 누적 시 다음 릴리즈 PR과 충돌 발생.
  • How to apply:
    • 작업 진입 시 git branch --show-current 확인
    • main이면 무조건 분기 제안 → 분기 완료 후에만 Edit/Write/Bash(파일 수정) 호출
    • 명시적 예외 지시 시에만 main 직접 작업 허용 (위험 안내 동반)
    • 이미 미커밋 변경이 main에 있으면 git stash → 분기 → git stash pop으로 즉시 정상화
  • "새 작업 시작 시 체크리스트"에 "매 신규 작업 진입 시점" 적용 명시 + 미커밋 변경 누적 시 복구 절차 항목 추가

기술적 세부사항​

수정 파일​

검증 결과​

  • 코드 변경 없음 — npm run lint / npm run build 영향 없음
  • 마크다운 린트(MD029 ol-prefix): workflow.md 체크리스트 항목 번호 재정렬로 해결

참고 사항​

후속 작업 후보​

  • D-1: 이로치 URL 정적 경로 마이그레이션 검토 (트래픽 증대 단계 D)
  • 챔피언스 M4 점검: /champions/tier 라우트 실재 여부, 상세 페이지 메타 데이터(인기 기술·아이템·특성·파트너) 노출 상태 확인 후 체크리스트 정합성 복구
  • 애드센스 Phase 1: CTR 0% 슬롯 제거/교체 — 별도 계획서 존재, 미착수 상태

재발 방지 보강 옵션 (미적용)​

본 사고와 같은 main 직접 수정 재발 방지를 더 확실히 하려면, .claude/settings.json의 PreToolUse hook에 main 브랜치에서 Edit/Write 호출 시 차단하는 스크립트를 추가하는 방안이 있다. 본 작업에서는 문서·규칙 수준 보강에 한정했고, hook 추가는 별도 ADR/PR로 다룰지 사용자 검토 후 결정 예정.