레거시 스타일 계승 (Inherit Legacy Style)
4가지 메타 아키텍처 차원에 걸쳐 코드베이스를 스캔하여 암묵적인 규칙을 찾고, 사용자와 한 번에 하나씩 충돌을 해결한 후 합의된 내용을 .ai-style-rules.md로 결정화하여 AI 코드 스타일 이탈을 방지합니다. 완전히 언어 및 프레임워크에 구애받지 않습니다.
활성화 조건
- 사용자가
/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가지 차원 스캔
- 파일 구조 (File Anatomy) — 파일 내 선언 순서 (imports → types → main logic → helpers → export)
- 상태 및 제어 흐름 (State & Control Flow) — 비동기 상태, 페이지네이션, 플래그 명명 규칙
- 인프라 (Infrastructure) — 공통 유틸리티 위치 (인터셉터, 포맷터, 미들웨어)
- 오류 처리 (Error Handling) — try/catch vs 글로벌 인터셉터 vs Result 반환; null 검사 습관
3. 신호-임계값 노이즈 감소 적용
사용자에게 중단하기 전에 신호 강도를 평가하세요:
- 약한 신호 → 자동 억제: 소수 비율 <5% AND 개수 <10 → 다수결 승리, 소수는 금지 사항(DONTs)으로 이동
- 강한 신호 → 그릴링: 거의 동률이거나 핵심 차원에서 의미론적 분기 발생
- 소규모 프로젝트 예외: 소스 파일 ≲50개, "3 대 2"는 다수결이 아님 → 그릴링
4. 한 번에 하나씩 충돌 해결 (그릴링 프로토콜)
각 강한 신호 충돌에 대해 정확히 하나의 질문을 4가지 옵션과 함께 제시하세요:
증거:
pathA는 스타일 X를 사용,pathB는 스타일 Y를 사용 경고: 위험: 혼합 사용은 프로젝트 스타일을 분열시킵니다 선택:1X를 따름2Y를 따름3이것은 진화이므로 규칙 업데이트4새로운 규칙이 있음
사용자가 답변할 때까지 대기한 후 다음 충돌로 진행하세요. 절대 질문을 쌓아두지 마세요.
5. .ai-style-rules.md 생성 — 다음 세 가지 필수 섹션 포함:
- [골든 파일 (Golden Files)] — 실제 예시 파일 경로와 각 파일이 보여주는 내용에 대한 주석
- [명명 및 상태-제어 규칙 (Naming & State-Control Rules)] — 구체적이고 확인 가능한 규칙
- [금지 사항 (DONTs)] — 전파되어서는 안 되는 안티패턴
6. 영구 훅 설치
사용자에게 강제 수준을 질문하세요 (AskUserQuestion 사용):
| 옵션 | 메커니즘 |
|---|---|
| 1 소프트 훅 (권장) | 프로젝트 CLAUDE.md에 @.ai-style-rules.md 참조 작성 |
| 2 하드 훅 | 소프트 훅 + settings.json에 `PreToolUse[Write |
| 3 훅 없음 | 규칙 파일만 유지; 사용자가 수동으로 참조 |
B 분기 — 증분 스니프
- 기존
.ai-style-rules.md읽기; 커밋 핑거프린트가 있으면git diff <last_hash> HEAD --stat로 델타 확인 - 최근 Git 변경사항 읽기 (
git log -3 --stat→ 의심 파일 요청 시 검사) - 대규모 diff(수백 개 파일 초과)의 경우:
--stat요약만 제공 + 가장 큰 변경사항 샘플링 - 새 코드를 기록된 규칙과 비교 → 충돌 발생 시 그릴링 프로토콜 진행
.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— 재사용 및 단순화 기회를 위한 코드 검토
예시
-
최초 온보딩
- 사용자: "이 오래된 코드베이스에 AI를 온보딩하는데 스타일을 변경하지 않도록 도와주세요."
- 동작: A 분기 전체 스캔 실행 → 규모 측정 → 4가지 차원 스캔 → 충돌 그릴링 →
.ai-style-rules.md생성 → 훅 강도(소프트/하드/없음) 제공.
-
팀 변경 후 증분 업데이트
- 사용자: "새 모듈을 추가했는데 기존 스타일 규칙을 그대로 유지하려고 합니다."
- 동작: B 분기 증분 스니프 실행 → Git 델타를 기록된 규칙과 비교 → 새로운 충돌 그릴링 → 덮어쓰지 않고 진화 로그 추가.
-
CLAUDE.md를 통한 금지 사항 강제
- 사용자: "모든 새 코드가 프로젝트 규칙과 일관성을 유지하도록 하세요."
- 동작: 소프트 훅 설치 →
.ai-style-rules.md가 매 세션마다 자동 로드 → 모든 코드 작성 작업이 준수 선언으로 시작, 예시 파일 패턴 재사용 및 금지 사항 회피.