레거시 스타일 상속

레거시 스타일 상속은(는) 무엇을 하나요?

AI 코드 스타일 표류(drift)를 방지하여 레거시 프로젝트의 암묵적 관례를 분석하고, 4가지 메타 아키텍처 차원에 걸쳐 충돌을 하나씩 해결한 후 합의된 규칙을 .ai-style-rules.md로 결정화합니다. 언어와 프레임워크에 완전히 독립적입니다.

활성화 시점

• 사용자가 /inherit-legacy-style 입력
• 사용자가 수동으로 작성된 레거시 프로젝트에 AI 온보딩을 언급
• 사용자가 AI 생성 코드가 기존 프로젝트 관례에서 "표류"하는 것을 우려
• 사용자가 프로젝트의 암묵적 코딩 규칙을 추출하고 정리하고자 함

사용 시기

레거시 프로젝트 스타일을 유지하고 AI 생성 스타일 표류를 방지해야 할 때 이 스킬을 사용하세요. 위 활성화 시점 조건을 참고하십시오.

전제 조건

• Git (권장; Git이 없는 프로젝트는 증분 모드에서 파일 타임스탬프 사용)
• 프로젝트 루트에 대한 읽기/쓰기 권한 (.ai-style-rules.md 및 선택적으로 CLAUDE.md 생성)

워크플로우

단계 0 — 자동 감지 모드

프로젝트 루트에서 .ai-style-rules.md의 존재 여부를 조용히 확인합니다:

파일 존재 여부	모드
아니오	분기 A — 첫 번째 전체 스캔
예	분기 B — 증분 감지

모드를 한 줄로 알리고 진행하세요. 사용자에게 선택을 요청하지 마십시오.

분기 A — 첫 번째 전체 스캔

1. 규모 측정, 스캔 계층 선택

git ls-files | grep -cE '\.(js|ts|jsx|tsx|vue|py|go|rs|java|kt|rb|php|cs|swift|c|cpp|h)$'

계층	소스 파일 수	전략
소규모	≲ 50	모든 소스 전체 상세 읽기
중간	50–500	인프라 계층 = 전체 읽기; 비즈니스 계층 = 차원당 2–3개 샘플
대규모	≳ 500	엄격한 샘플링 + 예산 제한; 먼저 --stat 요약, 그 다음 대상 읽기

2. 4가지 차원 스캔

1. 파일 구조 — 파일 내 선언 순서 (import → 타입 → 메인 로직 → 헬퍼 → export)
2. 상태 및 제어 흐름 — 비동기 상태, 페이지네이션, 플래그의 명명 규칙
3. 인프라 — 교차 관심 유틸리티 위치 (인터셉터, 포매터, 미들웨어)
4. 오류 처리 — try/catch vs 전역 인터셉터 vs Result 반환; null 검사 습관

3. 신호 임계값 노이즈 감소 적용

사용자에게 방해하기 전에 신호 강도 평가:

• 약한 신호 → 자동 억제: 소수 <5% AND 개수 <10 → 다수 승리, 소수는 DONTs로 이동
• 강한 신호 → 집중 질문: 거의 균등 분할, 또는 핵심 차원의 의미적 분기
• 소규모 프로젝트 예외: 소스 ≲50, "3 대 2"는 다수가 아님 → 집중 질문

4. 충돌을 하나씩 해결 (집중 질문 프로토콜)

각 강한 신호 충돌에 대해 정확히 하나의 질문을 4가지 옵션과 함께 제시:

증거: pathA는 스타일 X 사용, pathB는 스타일 Y 사용 경고: 위험: 둘을 혼합하면 프로젝트 스타일이 분열됩니다 선택: 1 X 따름 2 Y 따름 3 이는 진화, 규칙 업데이트 4 새로운 규칙 있음

사용자가 답변할 때까지 일시 중지하고, 그런 다음 다음 충돌로 진행합니다. 질문을 절대 쌓아두지 마십시오.

5. .ai-style-rules.md 생성 — 세 가지 필수 섹션 포함:

• [황금 파일] — 실제 예시 파일 경로와 해당 파일이 보여주는 내용 설명
• [명명 및 상태-제어 규칙] — 구체적이고 확인 가능한 관례
• [금지 사항] — 전파되어서는 안 되는 안티패턴

6. 영구 훅 설치

사용자에게 적용 강도를 묻습니다 (AskUserQuestion 사용):

옵션	메커니즘
1 소프트 훅 (권장)	@.ai-style-rules.md 참조를 프로젝트 CLAUDE.md에 작성
2 하드 훅	소프트 훅 + settings.json의 `PreToolUse[Write
3 훅 없음	규칙 파일 유지; 사용자가 수동으로 참조

분기 B — 증분 감지

1. 기존 .ai-style-rules.md 읽기; 커밋 지문이 있으면 git diff <last_hash> HEAD --stat로 델타 파악
2. 최근 Git 변경사항 읽기 (git log -3 --stat → 의심 파일 점검)
3. 과도한 diff(수백 개 파일)의 경우: --stat 요약만 + 가장 큰 변경사항 샘플링
4. 새 코드를 기록된 규칙과 비교 → 충돌 시 집중 질문 프로토콜 진행
5. .ai-style-rules.md 끝에 진화 로그 추가 (기존 규칙은 절대 덮어쓰지 않음)

턴당 강제

.ai-style-rules.md가 컨텍스트에 로드된 경우 (CLAUDE.md를 통해), 모든 코드 작성 작업은 추론 체인에 준수 선언을 포함해야 하며, 따르는 예시와 피하는 금지 사항을 명시해야 합니다.

작동 방식

이 스킬은 .ai-style-rules.md의 존재 여부를 통해 첫 실행인지 증분 실행인지 자동 감지합니다:

• 첫 실행 (분기 A) — 프로젝트 규모 측정, 4가지 메타 아키텍처 차원(파일 구조, 상태 및 제어 흐름, 인프라, 오류 처리)으로 코드베이스 스캔, 신호 임계값 노이즈 감소로 약한 충돌 억제, 강한 신호 충돌을 사용자와 하나씩 해결, 황금 파일/명명 규칙/금지 사항이 포함된 .ai-style-rules.md 생성, 선택적 적용 훅 제공.
• 증분 (분기 B) — 기존 규칙 읽기, 최근 Git diff에서 새 패턴 또는 충돌 패턴 확인, 발견된 충돌에 대해 동일한 1:1 집중 질문 프로토콜 실행, 기존 규칙을 덮어쓰지 않고 진화 로그 추가.
• 턴당 강제 — CLAUDE.md를 통해 훅이 설치되면, 모든 코드 작성 작업은 따르는 예시와 피하는 금지 사항을 명시한 준수 선언으로 시작합니다.

출력 사양

• 프로젝트 루트의 .ai-style-rules.md (헤더에 커밋 지문 + 규모 계층 포함)
• 선택적으로 @.ai-style-rules.md 참조가 포함된 CLAUDE.md
• ### [YYYY-MM-DD] 스타일 진화 로그 항목으로 진화 로그 추가

안티패턴

• 실패: 규모 측정 단계를 건너뛰지 마십시오 — 30개 파일 프로젝트를 샘플링하면 "굶기게" 되고; 5,000개 파일 저장소를 전체 스캔하면 폭발합니다
• 실패: 여러 충돌 질문을 한 번에 쌓아두지 마십시오 — 집중 질문은 엄격히 하나씩입니다
• 실패: 증분 모드에서 기존 규칙을 덮어쓰지 마십시오 — 항상 진화 로그를 추가하십시오
• 실패: 묻지 않고 "하드 훅"을 기본값으로 설정하지 마십시오 — 적용 강도는 사용자의 결정입니다
• 실패: 구문이나 기술 스택 품질을 판단하지 마십시오 — 이 스킬은 메타 아키텍처만 정렬합니다
• 실패: 예시 파일에서 버그를 복사하지 마십시오 — 구조를 재사용하고 결함은 표시하십시오

모범 사례

• 스캔 전에 감지된 모드(첫 실행 vs 증분)와 규모 계층을 한 줄로 알리십시오
• 대규모 프로젝트의 경우 먼저 --stat 요약을 읽고, 그 다음 의심 파일에 대해 대상 Read를 수행하십시오
• 신호 임계값이 노이즈를 처리하도록 하십시오 — 843 대 8의 명명 분할은 사용자 방해 없이 자동 해결되어야 합니다
• 신호 강도가 확실하지 않으면 질문 쪽으로 기울이십시오
• CLAUDE.md 소프트 훅(@.ai-style-rules.md)이 일반적으로 충분합니다; 사용자가 기계적 적용을 원할 경우에만 하드 훅을 사용하십시오

관련 스킬

• init — 코드베이스 문서와 함께 새 CLAUDE.md 초기화
• code-review — 정확성과 스타일 문제에 대한 diff 검토
• simplify — 재사용 및 단순화 기회를 위한 코드 검토

예시

1. 첫 번째 온보딩

   • 사용자: "스타일을 변경하지 않고 이 오래된 코드베이스에 AI를 온보딩하도록 도와주세요."
   • 동작: 분기 A 전체 스캔 실행 → 규모 측정 → 4가지 차원 스캔 → 충돌 집중 질문 → .ai-style-rules.md 생성 → 훅 강도 제공 (소프트/하드/없음).

2. 팀 변경 후 증분 업데이트

   • 사용자: "새 모듈을 추가했습니다. 기존 스타일 규칙을 그대로 유지해주세요."
   • 동작: 분기 B 증분 감지 실행 → Git 델타를 기록된 규칙과 비교 → 새 충돌 집중 질문 → 덮어쓰지 않고 진화 로그 추가.

3. CLAUDE.md를 통한 금지 사항 강제

   • 사용자: "모든 새 코드가 프로젝트 규칙과 일관성을 유지하도록 해주세요."
   • 동작: 소프트 훅 설치 → .ai-style-rules.md가 매 세션마다 자동 로드 → 모든 코드 작성 작업이 준수 선언으로 시작, 예시 패턴 재사용 및 금지 사항 회피.