organize-claude-md

Files (5)

• SKILL.md
• adr-template.md · references/
• frameworks.md · references/
• monorepo.md · references/
• reference-docs.md · references/

SKILL.md (first lines)

# Organize CLAUDE.md

CLAUDE.md 를 **Lazy Loading 참조 구조** + **프레임워크 특화 템플릿** + **Mermaid 아키텍처** 로 재구성합니다.

## 인자 (사용자가 함께 전달)

| 인자 | 동작 |
|------|------|
| `(빈 값)` | **git diff 기반 증분**: 마지막 organize (Last Updated 기준) 이후 변경된 파일만 감지하여 영향받는 reference 만 선택적 갱신. CLAUDE.md 부재 또는 Last Updated 없으면 `full` 동일 |
| `full` | 전체 재구성 (CLAUDE.md + 모든 reference — git diff 무시) |
| `main` | CLAUDE.md 만 재구성 |
| `references` | reference 만 생성/갱신 |
| `module:<name>` | 특정 모듈의 reference 만 (monorepo 는 `module:<sub>/<name>`) |
| `scan` | 현황 분석만 (변경 없이 리포트) |
| `diff` | 기존 vs 제안 차이점만 표시 |
| `gap` | 기존 reference GAP 분석 (품질 점수 + 누락/구식 리포트) |
| `<경로>` | 지정 경로만 스캔 + 해당 영역 reference 만 갱신 |

## 왜 이 구조가 필요한가

CLAUDE.md 는 매 세션 시작 시 전체가 컨텍스트에 로드된다. 다음을 알면 결정이 쉬워진다:

- **120줄 이상**이면 에이전트가 핵심을 놓치고 지시 compliance 가 떨어진다 (monorepo root 는 150줄)
- **금지형 규칙 ("NEVER do X")**이 권장형 ("Always prefer Y") 보다 compliance 가 높다
- 상세 정보는 `.claude/docs/reference/` 에 분리 → 작업 맥락에 따라 lazy loading
- 스캔 (Phase 1) 결과가 생성 (Phase 5) 으로 **명시적으로 매핑**되어야 빈약한 문서 생성을 방지
- **Monorepo 는 본질이 다르다** — 단일 CLAUDE.md 가 모든 sub 의 NEVER 를 담으면 sub 단독 작업 시 노이즈. root + sub 분리가 표준 — `references/monorepo.md` 참조

## 실행 흐름

```
Phase 0: 전제 조건 + 신규 생성 여부
Phase 1: 프로젝트 분석 (현황 + 프레임워크 감지 + 딥 스캔 + 매핑)
Phase 2: 콘텐츠 분류 (메인 vs 분리, 규모 분류)
Phase 3: Mermaid 아키텍처 생성
Phase 4: 메인 CLAUDE.md 작성
Phase 5: reference 생성/갱신 + 병합
Phase 6: 사용자 확인 (실행 전 변경 계획 제시)
Phase 7: 검증 + 최종 리포트
Phase 8: 구조 결정 ADR 작성 (해당 시)
```

---

## Phase 0: 전제 조건 확인

### 0-1. 기존 AI 설정 파일 감지

다음 파일이 존재하면 읽어서 Key Rules 이관 후보로 활용:
- `.cursorrules` / `.cursor/rules/*.mdc` → Cursor AI
- `.windsurfrules` → Windsurf AI
- `.aider.conf.yml` → Aider
- `copilot-instructions.md` → GitHub Copilot

감지 시:
1. 규칙 추출 + 프레임워크 감지 단서로 활용
2. 충돌 규칙은 사용자에게 알림
3. 원본 삭제 여부는 사용자 확인

### 0-2. CLAUDE.md 부재 시 신규 생성

CLAUDE.md 가 없으면:
1. `README.md` 가 있으면 → 프로젝트 설명, 명령어, 환경 정보 추출
2. `package.json` / `build.gradle` 등 → Phase 1-2 와 동일한 프레임워크 감지
3. 최소 골격: Project Overview + Architecture (Mermaid) + Commands + Key Rules (3개) + Reference Docs
4. 사용자에게 "신규 생성 모드입니다. 기존 팀 규칙이 있으면 알려주세요" 안내

### 0-3. CLAUDE.local.md 분리 판단

개인별 차이 있는 설정 (Swagger URL, 로컬 포트, 테스트 계정 등) 이 있으면:
1. `CLAUDE.local.md` 로 분리 제안
2. `.gitignore` 추가 확인

---

## Phase 1: 프로젝트 분석

### 1-1. 기존 상태 확인

1. 기존 CLAUDE.md 전체 읽기 (없으면 Phase 0-2 신규 생성)
2. 기존 `.claude/docs/reference/` 파일 목록 + 각 파일 줄 수
3. `.gitignore` 에서 `.claude/docs/reference/` 차단 여부
4. 기존 `.claude/rules/` 파일
5. **작업 산출물 감지** — 다음 경로에 최근 MD 가 있으면 읽어서 Phase 5 병합 활용:
   - `.claude/workflow/dev-guide-*.md`
   - `.claude/workflow/sprint-contract-*.md`
   - `.claude/docs/dev-guide/`
6. **git diff 기반 변경 감지** (`(빈 값)` 인자의 핵심):
   - CLAUDE.md 에 `Last Updated` 가 있으면:
     ```bash
     git log --since="<Last Updated 날짜>" --name-only --pretty=format:""
     ```
     → 변경 파일 목록 → `references/frameworks.md § git diff 역매핑` 으로 영향받는 reference 결정
   - Last Updated 없거나 CLAUDE.md 부재 → `full` 모드
   - `<경로>` 인자 시 → 해당 경로 하위만 스캔 대상

### 1-2. 프레임워크 + 언어 감지

`references/frameworks.md § 프레임워크 + 언어 감지 우선순위` 참조.

핵심:
- 언어 단독 분류 X — 항상 프레임워크와 함께 (`Spring Boot 3.3.8 (Java 21)`)
- **JVM 은 Java vs Kotlin 필수 구분** (Lombok ↔ data class 충돌)
- **복수 스택 감지 → Monorepo** → `references/monorepo.md` 적용

### 1-3. 프레임워크별 딥 스캔

`references/frameworks.md` 의 해당 프레임워크 섹션을 읽고 스캔. 추측 금지, 실제 코드 분석.

### 1-4. 스캔 결과 → reference 매핑

`references/frameworks.md` 의 각 프레임워크별 매핑 테이블 적용. 매핑되지 않은 항목은 `architecture.md` 에 요약 포함.

---

## Phase 2: 콘텐츠 분류

### 프로젝트 규모 분류

From bigbulgogiburger/claude_jira_harness, MIT.

More from bigbulgogiburger/claude_jira_harness