Custom Skill — Deep Project Analysis for Claude Code

9단계로 소스를 읽어
코딩 습관까지 Claude에게 가르치는
/init-project

문제는 Claude Code 의 기본 명령 /init 이 프로젝트를 겉만 보고 설정을 만든다는 점이었습니다. 패키지 설정 파일과 안내 문서만 읽고, 어디에나 맞는 뻔한 견본(제네릭 템플릿)을 채워 넣습니다. 그래서 프로젝트의 소스 코드 전체(코드베이스)를 9단계로 깊이 읽어, 그 프로젝트만의 코딩 습관을 Claude에게 학습시키는 도구를 따로 만들었습니다. Claude Code 에서는 이런 도구를 스킬(특정 작업의 절차를 가르치는 지시문 묶음)이라고 부릅니다. 결과물은 실제로 이 프로젝트에서 쓰는 코딩 방식을 뽑아 담은 설정 파일들입니다.

Comparison
/init vs /init-project
built-in command

/init

"프로젝트가 뭔지" 수준

  • 기본 템플릿을 채워 넣은 안내 파일 하나를 만듭니다. Claude 가 프로젝트를 읽을 때 기준으로 삼는 설정 파일이고, 이름은 CLAUDE.md
  • 정보는 패키지 설정 파일과 프로젝트 안내 문서, 이 둘에서만 뽑습니다. 두 파일의 이름은 package.json · README
  • 빌드(소스를 실행 가능한 형태로 묶는 일) 명령과 실행 명령만 알아냅니다.
  • 어느 프로젝트에나 똑같이 붙는 범용 체크리스트를 끼워 넣습니다.
  • 코딩 패턴(이 프로젝트가 코드를 짜는 버릇)은 분석하지 않습니다.
  • 이미 있던 .claude/ 폴더(Claude Code 설정을 모아 두는 곳)의 설정을 덮어쓸 위험이 있습니다.
  • 산출물은 파일 1개뿐입니다. 위에서 말한 안내 파일 CLAUDE.md
custom skill

/init-project

"어떻게 코딩하는지" 수준

  • 실제 소스 코드를 깊이 읽어 분석합니다.
  • 네이밍(이름 짓는 규칙), 레이어(코드를 역할별로 나눈 층), 패턴을 자동으로 뽑아냅니다.
  • 빌드 명령과 테스트 명령을 실제로 실행해 맞는지 검증합니다.
  • 이 프로젝트에만 맞는 맥락(context, Claude 가 작업 전에 알아야 할 배경 정보)을 만듭니다.
  • backend/frontend/qa 패턴 분리. 백엔드(서버 쪽)·프론트엔드(화면 쪽)·QA(품질 검사) 코딩 패턴을 파일 셋으로 나눠 적습니다.
  • 이미 있던 .claude/ 설정은 보존합니다. 덮어쓰지 않고 뒤에 덧붙입니다.
  • 산출물은 6개 파일입니다. 아래 산출물 트리에 그린 .claude/ 폴더 전체입니다.
Pipeline
9-Phase Analysis Pipeline
P1
프로젝트 스캔
먼저 프로젝트 폴더에 어떤 설정 파일이 있는지 봅니다. 8개 파일 타입을 감지해 기술 스택(프로젝트가 쓰는 언어와 프레임워크의 묶음)을 파악합니다. 파일이 있는지 없는지만으로 프레임워크(뼈대가 되는 라이브러리)와 언어를 확정합니다.
감지 파일식별 스택
package.jsonNode.js / NPM 생태계 (자바스크립트 실행 환경과 그 패키지 관리자)
pom.xml / build.gradleJava / Kotlin (Spring Boot)
pubspec.yamlFlutter / Dart
requirements.txt / pyproject.tomlPython / FastAPI
go.modGo
Cargo.tomlRust
*.csproj.NET / C#
Dockerfile / docker-compose.yml컨테이너 환경 (앱을 격리된 상자에 담아 어디서나 같은 방식으로 실행)
P2
심층 구조 분석
프로젝트 구조를 4단계 순서로 파악합니다. 먼저 디렉토리 트리(폴더 구조)를 훑고, 핵심 소스 파일을 읽고, 테스트 파일을 읽고, 마지막에 설정 파일을 읽습니다.
디렉토리 트리 탐색
→
핵심 소스 파일 읽기
→
테스트 파일 읽기
→
설정 파일 읽기
P3
CLAUDE.md 생성
프로젝트 전체 맥락(컨텍스트, Claude 가 작업 전에 알아야 할 배경 정보)을 담는 메인 설정 파일을 만듭니다. 이미 파일이 있으면 기존 내용을 덮어쓰지 않습니다. 뒤에 덧붙여(append) 기존 설정을 보존합니다.
프로젝트 기술 스택 (버전 포함) 빌드/실행/테스트 명령 (검증됨) 디렉토리 구조 및 주요 모듈 환경변수 목록 배포 방법
P4
backend-patterns.md
백엔드(서버 쪽) 코드에서 추출한 7개 패턴 항목을 담는 파일입니다. 실제 코드를 분석해 구체적인 예시를 함께 적습니다.
API 라우팅 구조 레이어 아키텍처 (요청을 받는 Controller → 규칙을 처리하는 Service → 데이터를 다루는 Repository) 네이밍 컨벤션 (이름 짓는 규칙: camelCase, Entity 접미사 등) 에러 처리 패턴 인증/인가 방식 데이터베이스 접근 패턴 테스트 작성 방식
P5
frontend-patterns.md
프론트엔드(화면 쪽) 코드에서 추출한 6개 분석 항목을 담는 파일입니다. 컴포넌트(화면을 이루는 부품) 구조와 상태 관리 방식을 구체적으로 적습니다.
컴포넌트 구조 (파일명, props 패턴) 상태 관리 방식 (Context, Zustand, Redux 등) API 호출 패턴 (서버 데이터를 받아 오는 라이브러리를 무엇으로 쓰는가: React Query 또는 SWR) 스타일링 방식 (Tailwind, CSS Modules 등) 라우팅 구조 폼 처리 방식
P6
qa-strategy.md
프로젝트의 테스트 전략을 적는 문서입니다. 기존 테스트 파일을 분석해 현재 커버리지(테스트가 실제로 검사하는 코드의 범위)와 부족한 영역을 파악합니다.
테스트 실행 명령 테스트 유형 (unit 단위 / integration 통합 / e2e 끝에서 끝까지) 커버리지 목표 모킹(외부 서비스를 가짜로 대체해 테스트하는 방법) 전략
P7
auto-issue.md
자동 이슈 생성 스킬의 설정 파일입니다. 기술 부채(나중으로 미뤄 둔 정리 작업), 버그, 개선 사항을 자동으로 감지해 GitHub 이슈(할 일 카드)로 만드는 규칙을 정의합니다.
이슈 분류 기준 우선순위 결정 로직 라벨 매핑 자동 assignee(담당자) 설정
P8
qa-scenarios.md
프로젝트 고유의 QA(품질 검사) 시나리오 모음입니다. 핵심 비즈니스 로직(서비스의 핵심 규칙을 구현한 코드)과 사용자 플로우(사용자가 화면을 거치는 순서)를 바탕으로 자동 생성됩니다.
주요 사용자 플로우 엣지 케이스(경계값처럼 드물게 생기는 입력) 목록 성능 테스트 기준 접근성 체크포인트
P9
settings.json
Claude Code 의 동작 설정 파일입니다. 허용할 명령과 금지할 명령, 자동 승인 정책, 에이전트(작업을 나눠 맡는 AI 작업자)의 권한 범위를 프로젝트에 맞춰 구성합니다.
allowedCommands 화이트리스트 (허용할 명령 목록) deniedCommands 블랙리스트 (금지할 명령 목록) auto-approve 정책 (묻지 않고 자동 승인할 범위) 에이전트 권한 스코프 (권한이 미치는 범위)
Artifacts
산출물 트리
.claude/
├── 📄 CLAUDE.md — 프로젝트 전체 맥락(컨텍스트). 기술 스택, 빌드 명령, 구조 설명
├── 📁 skills/ — 분석에서 뽑아낸 이 프로젝트 전용 스킬(작업 지시문) 모음
│ ├── 📋 auto-issue.md — 자동 이슈 생성 규칙 및 분류 기준
│ ├── 🔧 backend-patterns.md — API 레이어, 네이밍, 에러 처리 패턴 (7개 항목)
│ ├── 🎨 frontend-patterns.md — 컴포넌트 구조, 상태 관리, 스타일링 패턴 (6개 항목)
│ ├── 🧪 qa-strategy.md — 테스트 전략, 커버리지 목표, 모킹 방식
│ └── 📝 qa-scenarios.md — 프로젝트 고유 QA(품질 검사) 시나리오와 엣지 케이스
└── ⚙️ settings.json — Claude Code 동작 설정 (명령 허용/금지, 권한 스코프)
Specificity
구체성 비교
/init 결과 generic
# 프로젝트 정보 기술 스택: Spring Boot 빌드: mvn clean package 실행: mvn spring-boot:run 테스트: mvn test # 일반 가이드라인 - RESTful API 설계 원칙 준수 - 단위 테스트 작성 권장 - 코드 리뷰 필수
/init-project 결과 project-specific
# 기술 스택 (버전 확정) Kotlin 1.9.25 + Spring Boot 3.5.5 QueryDSL 7.0 + JPA 레이어 구조: Controller → Service → Repository 네이밍: - camelCase (변수, 메서드) - Entity 접미사 (UserEntity) - Dto 접미사 (CreateUserDto) 테스트: mvn test -pl module-name 배포: ./gradlew bootJar → Docker build
Design
핵심 원칙
원칙 01

제네릭 템플릿 금지

실제 소스 코드를 읽지 않고 만든 패턴은 의미가 없습니다. 모든 항목은 실제 파일에서 뽑아낸 증거에 근거해야 합니다.

원칙 02

빌드/테스트 명령 검증

문서에 적은 빌드 명령은 실제로 실행해 검증합니다. 예를 들어 테스트 명령 mvn test가 실패하면 올바른 명령을 찾아 고친 뒤에 기록합니다.

원칙 03

기존 .claude/ 보존

이미 설정해 둔 스킬과 패턴을 덮어쓰지 않습니다. 새로운 분석 결과는 기존 설정 뒤에 덧붙이거나 섹션별로 합칩니다.

원칙 04

버전까지 콕 집는 구체성

"Spring Boot 사용" 한 줄로 끝내지 않습니다. "Kotlin 1.9.25 + Spring Boot 3.5.5 + QueryDSL 7.0, Controller → Service → Repository 레이어"처럼 버전과 구조까지 적습니다.

Resources
관련 링크

autoresearch-builder

자율 실험 빌더(가설을 세우고 실험을 돌려 결과로 채택 여부를 정하는 루프를 자동으로 만드는 도구)입니다. /init-project 와 연계해 새 프로젝트를 자동으로 분석하고 최적화 루프를 실행합니다.

github
raground@gmail.com 복사됨