name	claude-md-guide
description	프로젝트별 claude.md를 리뷰하고 정리합니다. 가이드라인에 따라 분석하고, Skills로 분리할 내용을 찾아 개선안을 제시합니다.

Claude.md Guide

프로젝트별 claude.md 파일을 리뷰하고 정리하는 skill입니다.

핵심 목표:

프로젝트 고유 정보만 유지 (50-100줄)
범용 패턴은 Skills로 분리
필수 항목 누락 방지

Instructions

워크플로우: 기존 claude.md 리뷰

1. 파일 확인

# 현재 디렉토리 확인
pwd

# claude.md 찾기
ls claude.md 2>/dev/null || ls CLAUDE.md 2>/dev/null

있으면: 리뷰 시작 없으면: 생성 제안 (templates/ 참조)

2. Read 및 분석

Read claude.md (또는 CLAUDE.md)

분석 항목:

길이 체크
- 50-100줄: ✅ 적절
- 100-200줄: ⚠️ 약간 김
- 200줄 이상: ❌ Skills 분리 필요
Skills로 분리할 내용 감지

키워드 패턴으로 감지:
- "TypeScript", "타입", "컨벤션", "린팅" → patterns-typescript
- "React", "컴포넌트", "hooks", "상태 관리" → patterns-react
- "API 설계", "엔드포인트", "RESTful" → patterns-api
- "테스트", "유닛", "E2E", "mocking" → test-guidelines
- "에러 핸들링", "try-catch", "로깅" → patterns-error-handling
판단 기준:
- 해당 섹션이 20줄 이상
- 프로젝트 독립적인 범용 내용
- 다른 프로젝트에도 적용 가능
필수 항목 체크
- 프로젝트 개요 (1-2줄 설명)
- 퀵 커맨드 (build, test, dev, deploy 등)
- 서비스 엔드포인트/포트
- 환경변수 필수 항목
- 프로젝트 특이사항/주의사항

3. 리포트 생성

사용자에게 분석 결과 요약:

## 📊 claude.md 리뷰 결과

### 전체 현황
- 총 라인: XXX줄 (권장: 50-100줄)
- 상태: ✅ 적절 / ⚠️ 약간 김 / ❌ 분리 필요

### Skills로 분리 권장 (총 YYY줄)
1. TypeScript 컨벤션 (50줄) → patterns-typescript
2. React 패턴 (80줄) → patterns-react
3. 테스트 가이드 (40줄) → test-guidelines

### 필수 항목 누락
- [ ] 퀵 커맨드
- [ ] 서비스 엔드포인트

### 적절한 내용
- [x] 프로젝트별 quirks
- [x] 특정 서비스 설정

4. 사용자 확인

개선 방향 선택지 제시:

[1] Skills 분리 + 정리

범용 내용을 skills로 분리
프로젝트 고유 정보만 남김
누락된 필수 항목 추가

[2] 정리만 (분리 없이)

현재 구조 유지
포맷만 정리

[3] 새로 작성

기존 내용 참고하여 템플릿 기반 재작성

5. 개선 실행

[1] Skills 분리 선택 시:

각 분리 대상마다 확인:

"TypeScript 컨벤션(50줄)을 patterns-typescript skill로 분리하시겠습니까?"
→ Yes: 새 skill 생성
→ No: claude.md에 유지

새 skill 생성:

mkdir -p skills/patterns-{name}/
Write skills/patterns-{name}/SKILL.md

claude.md에서 해당 섹션 제거

claude.md에 skill 참조 추가:

## 코딩 가이드
- TypeScript: `patterns-typescript` skill 참조
- React: `patterns-react` skill 참조

[2] 정리만 선택 시:

포맷 정리
섹션 재배치
필수 항목 추가

[3] 새로 작성 선택 시:

프로젝트 유형 확인:
- Web App (Next.js, React 등)
- API Server (Express, Fastify 등)
- Monorepo (Turborepo, Nx 등)
- Minimal (기본)
적절한 템플릿 선택 (templates/{유형}.md)
사용자와 대화하며 커스터마이징:
- "프로젝트명은?"
- "빌드 명령어는?"
- "개발 서버 포트는?"
- "특별한 주의사항은?"
claude.md 생성

6. 검증

정리 후 재확인:

길이: 50-100줄 이내?
필수 항목 모두 포함?
Skills 참조 명확?

포함/제외 기준

✅ claude.md에 포함할 것

프로젝트 고유 정보:

프로젝트 개요 및 목적
빌드/테스트/배포 명령어
서비스 엔드포인트 및 포트
환경변수 필수 항목
인증/테스팅 워크플로우 (프로젝트 특화)
프로젝트별 quirks 및 주의사항
특정 서비스 설정 (Redis, DB 등)
프로젝트 특화 트러블슈팅

예시:

# MyApp

웹 기반 사용자 관리 시스템

## 퀵 커맨드
- Build: `npm run build`
- Dev: `npm run dev` (http://localhost:3000)
- Test: `npm test`
- Deploy: `./scripts/deploy.sh`

## 서비스
- API: http://localhost:3000/api
- Admin: http://localhost:3001
- Redis: localhost:6379

## 환경변수 필수
- DATABASE_URL
- REDIS_URL
- JWT_SECRET

## 주의사항
- DB 마이그레이션은 항상 백업 후 실행
- Redis는 개발 시 docker compose로 자동 실행

❌ Skills로 분리할 것

범용 패턴 및 가이드:

언어별 컨벤션 (TypeScript, Python 등)
프레임워크 패턴 (React, Vue, Express 등)
API 설계 원칙 (RESTful, GraphQL)
테스트 작성 가이드
에러 핸들링 패턴
데이터베이스 설계 원칙
성능 최적화 기법

분리 대상 skill 매핑:

TypeScript 컨벤션 → patterns-typescript
React 패턴 → patterns-react
Backend 아키텍처 → patterns-backend
API 설계 → patterns-api
테스트 가이드 → test-guidelines
에러 핸들링 → patterns-error-handling
보안 → review-security

체크리스트

필수 항목

프로젝트 개요 (1-2줄)
퀵 커맨드 (build, test, dev)
서비스 엔드포인트/포트
환경변수 필수 항목

품질

50-100줄 이내
Skills 참조 명확
프로젝트 고유 정보만
섹션 구조 명확

Skills 분리

코딩 컨벤션 (> 20줄) 분리
프레임워크 패턴 분리
범용 가이드 분리

예시

예시 1: 리뷰 후 Skills 분리

User: "claude.md 리뷰해줘" Assistant:

Read claude.md (250줄)
분석:
- TypeScript 컨벤션 (60줄) → patterns-typescript
- React 패턴 (70줄) → patterns-react
- 퀵 커맨드 누락
리포트 제시
사용자 승인
실행:
- skills/patterns-typescript/ 생성
- skills/patterns-react/ 생성
- claude.md에서 해당 섹션 제거
- 퀵 커맨드 추가
결과: 80줄의 깔끔한 claude.md

예시 2: 새로 작성

User: "claude.md 만들어줘" Assistant:

프로젝트 유형 확인
templates/web-app.md 선택
커스터마이징
claude.md 생성

Technical Details

템플릿은 templates/ 디렉토리 참조:

minimal.md: 최소 구성
web-app.md: 웹앱 프로젝트
api-server.md: API 서버
monorepo.md: 모노레포

Install Skill

SKILL.md