ai-rules 적용 이슈 로그

- **재발 방지**: 한 프로젝트에서 겪은 함정을 다른 프로젝트 sync 시 다시 겪지 않도록 한다. - **ai-rules 개선 근거**: 인덱스의 이슈들이 쌓이면 sync 로직, adapter, hook 템플릿의 어느 부분이 취약한지 드러난다.

issues docs/issues/00_INDEX.md

프로젝트에 ai-rules를 sync/적용하면서 발견된 결함, 설치 누락, 설계 충돌을 시간순으로 수집한다. 이 문서는 "ai-rules가 어떤 현실 프로젝트에서 어떻게 깨졌는가"의 원본 기록이며, 여기서 확인된 패턴은 docs/changes/ 또는 core/ 규칙으로 승격된다.

이 문서의 목적

재발 방지: 한 프로젝트에서 겪은 함정을 다른 프로젝트 sync 시 다시 겪지 않도록 한다.
ai-rules 개선 근거: 인덱스의 이슈들이 쌓이면 sync 로직, adapter, hook 템플릿의 어느 부분이 취약한지 드러난다.
문서 ↔ 현실 gap 탐지: 규칙 문서상으로는 옳아 보이지만 실제 프로젝트에서는 동작하지 않는 경우를 수집한다.

기록 대상

다음에 해당하는 사건만 이 로그에 기록한다:

ai-rules sync가 배포한 파일이 설치/초기화 누락으로 동작하지 않음
ai-rules sync가 배포한 hook/설정이 다른 프로젝트 도구와 충돌
ai-rules 규칙 문서 간 내부 모순 (A 규칙은 X를 말하고 B 규칙은 그 반대)
ai-rules 규칙이 특정 환경(Windows/macOS/WSL/Docker)에서만 깨짐
ai-rules 규칙이 현실 프로젝트의 에이전트 모드/워크플로와 충돌하여 에이전트가 작업 불가능

기록하지 않는 것:

프로젝트 고유의 버그 (ai-rules와 무관)
규칙을 단순히 "마음에 들지 않음" 수준의 의견
이미 core 규칙으로 해결된 이슈 (→ docs/changes/로 이동)

이슈 인덱스

#	날짜	제목	발생 프로젝트	심각도	상태
ISS-001	2026-04-07	husky v9 hook 반쪽짜리 설치	AX-Studio-plan	🔴 Blocker	Workaround

심각도 기준

심각도	의미
🔴 Blocker	프로젝트 작업 자체가 불가능 (커밋, 배포 등 핵심 경로 차단)
🟠 High	우회 가능하지만 매번 수작업 필요
🟡 Medium	일부 환경/일부 작업에서만 문제
⚪ Low	경고/경고 수준, 작업은 계속 가능

상태 정의

Open: 이슈 확인, 미해결
Investigating: 원인 조사 중
Workaround: 해당 프로젝트에서 임시 우회책으로 처리됨, ai-rules 본체는 미수정
Fixed-in-project: 해당 프로젝트에서 자체 해결, ai-rules 본체는 미수정
Fixed-in-ai-rules: ai-rules 본체가 수정되어 다른 프로젝트도 재발 방지
Won't Fix: 의도된 동작 또는 수정 가치 없음으로 판정

문서 템플릿

새 이슈는 ISS-{NNN}-{slug}.md 형식으로 생성하고 아래 템플릿을 사용한다.

# ISS-NNN: {한 줄 제목}

## 메타

- **ID**: ISS-NNN
- **발생 프로젝트**: {프로젝트명}
- **발생 날짜**: YYYY-MM-DD
- **보고 날짜**: YYYY-MM-DD
- **심각도**: 🔴/🟠/🟡/⚪
- **상태**: Open
- **관련 ai-rules 구성요소**: {예: `adapters/claude-code.mjs`, `tooling.commitlint`, `core/01-git.md`}
- **환경**: {OS, 패키지 매니저, Node 버전, 관련 툴 버전}

## 요약

이슈를 3줄 이내로 설명.

## 재현 절차

이 버그를 처음 겪는 사람이 똑같이 재현할 수 있도록 단계를 적는다.

## 증상

관찰된 에러 메시지, 로그, 스크린샷 증거.

## 원인 분석

근본 원인 체인. "왜 이 현상이 나타났는가"를 하위 레이어까지 추적.

## 영향 범위

- 어떤 프로젝트 구성에서 재현되는가
- 어떤 환경에서는 재현되지 않는가
- 다른 이슈와 연관이 있는가

## 대응 방법

- **즉시 우회**: 이 프로젝트를 당장 진행하기 위한 최소 조치
- **근본 해결**: ai-rules 본체 또는 프로젝트 설정의 올바른 고정 방법
- **장기 개선**: ai-rules sync 로직에 제안할 변경

## 관련 문서

- ai-rules 내부 문서 링크
- 외부 레퍼런스 (GitHub issue, 공식 문서 등)

## 타임라인

- YYYY-MM-DD HH:MM — 최초 관측
- YYYY-MM-DD HH:MM — 원인 파악
- YYYY-MM-DD HH:MM — 임시 우회 적용
- YYYY-MM-DD HH:MM — 근본 해결 또는 상태 전환