URL: https://github.com/alinaqi/claude-bootstrap

Title: GitHub - alinaqi/claude-bootstrap: Opinionated project initialization for Claude Code. Security-first, spec-driven, AI-native.

Claude Bootstrap

병목은 코드 생성에서 코드 이해로 옮겨갔습니다. AI는 무한히 코드를 생성할 수 있지만, 인간은 여전히 이를 검토하고 이해하며 유지보수해야 합니다. Claude Bootstrap은 AI가 생성한 코드를 단순하고 안전하며 검증 가능하게 유지하도록 가드레일을 제공합니다.

핵심 철학

┌────────────────────────────────────────────────────────────────┐
│  기본값은 반복 루프                                            │
│  ─────────────────────────────────────────────────────────────│
│  모든 작업은 테스트가 통과할 때까지 자기참조 루프로 실행됩니다. │
│  Claude가 자율적으로 반복합니다. 당신은 어떻게가 아니라 무엇을 │
│  설명합니다.                                                   │
│  Ralph Wiggum이 구동 - 완벽보다 반복.                           │
├────────────────────────────────────────────────────────────────┤
│  항상 테스트 우선                                              │
│  ─────────────────────────────────────────────────────────────│
│  기능: 테스트 작성 → 실패 확인 → 구현 → 통과                   │
│  버그: 테스트 공백 찾기 → 실패하는 테스트 작성 → 수정 → 통과     │
│  먼저 실패한 테스트 없이 코드는 배포되지 않습니다.              │
├────────────────────────────────────────────────────────────────┤
│  단순함은 협상의 여지가 없습니다                                │
│  ─────────────────────────────────────────────────────────────│
│  함수당 20줄 │ 파일당 200줄 │ 매개변수 최대 3개                │
│  한 세션에서 전체 시스템을 이해할 수 없다면,                    │
│  너무 복잡한 것입니다.                                         │
├────────────────────────────────────────────────────────────────┤
│  기본값은 보안                                                  │
│  ─────────────────────────────────────────────────────────────│
│  코드에 시크릿 금지 │ 클라이언트 env vars에 시크릿 금지          │
│  의존성 스캔 │ 프리커밋 훅 │ CI 강제                            │
├────────────────────────────────────────────────────────────────┤
│  코드 리뷰는 필수                                               │
│  ─────────────────────────────────────────────────────────────│
│  모든 커밋은 푸시 전에 /code-review가 필요합니다.               │
│  🔴 치명적 + 🟠 높음 = 차단 │ 🟡 중간 + 🟢 낮음 = 배포 가능        │
│  AI는 인간이 놓치는 것을 잡고, 인간은 AI가 놓치는 것을 잡습니다. │
└────────────────────────────────────────────────────────────────┘

이것이 존재하는 이유

Node, React, Python, React Native 전반에서 수백 건의 AI 보조 프로젝트를 진행하며 패턴이 드러났습니다:

엔지니어가 Claude Code로 고생하는 이유는 도구 때문이 아니라 지시 방식 때문 - 차이는 가드레일에 있습니다.
복잡성에는 상한이 있음 - AI가 시스템을 일관되게 이해하지 못하는 지점이 존재합니다. 이는 실패가 아니라 신호입니다.
재시작은 실패가 아니라 기능 - 무언가를 고치려다 복잡성이 증가한다면, 학습한 내용을 바탕으로 다시 시작하세요. 반복할수록 더 빨라집니다.

이 툴킷은 그 학습을 재사용 가능한 스킬로 인코딩합니다.

빠른 시작

클론 및 설치

git clone https://github.com/alinaqi/claude-bootstrap.git ~/.claude-bootstrap cd ~/.claude-bootstrap && ./install.sh

어떤 프로젝트 디렉터리에서든

claude

Claude는 다음을 수행합니다:

도구 검증 - gh, vercel, supabase CLI 확인
질문 - 언어, 프레임워크, AI-first 여부?, 데이터베이스
리포지토리 설정 - GitHub repo 생성 또는 연결
구조 생성 - 스킬, 보안, CI/CD, 스펙, TODO
스펙 프롬프트 - 첫 기능 정의로 전환

자동 반복 루프 (Ralph Wiggum)

자연스럽게 말하면 됩니다. Claude가 자동으로 반복 TDD 루프를 실행합니다.

┌─────────────────────────────────────────────────────────────┐
│  당신: "가입에 이메일 유효성 검사를 추가해줘"                 │
├─────────────────────────────────────────────────────────────┤
│  Claude 자동 수행:                                             │
│  1. 요청에서 요구사항 추출                                     │
│  2. 완료 기준을 포함한 TDD 루프로 구조화                       │
│  3. 테스트를 종료 조건으로 /ralph-loop 실행                    │
│  4. 모든 테스트 통과 + 린트 클린까지 반복                      │
└─────────────────────────────────────────────────────────────┘

/ralph-loop를 수동으로 호출할 필요가 없습니다. 원하는 것을 설명만 하세요:

당신이 말함	Claude가 수행함
"사용자 인증 추가"	인증 테스트가 통과할 때까지 루프
"로그인 버그 수정"	테스트 공백 찾기 → 테스트 작성 → 고칠 때까지 루프
"할 일(todo) REST API 만들기"	모든 엔드포인트 테스트가 통과할 때까지 루프
"인증 모듈 리팩터링"	테스트를 안전망으로 두고 루프

옵트아웃 문구(루프를 원치 않을 때):

"그냥 설명..." → 설명만
"빠른 수정..." → 한 줄 수정, 루프 없음
"루프 돌리지 마..." → 명시적 옵트아웃

Ralph Wiggum 플러그인 설정

공식 마켓플레이스에서 설치 (Claude Code에서)

/plugin install ralph-loop@claude-plugins-official

문제 해결: "Source path does not exist: .../ralph-wiggum"

마켓플레이스에서 플러그인 이름이 ralph-wiggum에서 ralph-loop로 변경되었습니다. 이 에러가 보이면 캐시가 이전 이름을 참조하지만 플러그인 폴더는 새 이름을 사용하고 있다는 뜻입니다. 심볼릭 링크로 해결하세요:

ln -s ~/.claude/plugins/marketplaces/claude-plugins-official/plugins/ralph-loop
~/.claude/plugins/marketplaces/claude-plugins-official/plugins/ralph-wiggum

그 다음 /plugin install ralph-loop@claude-plugins-official를 다시 시도하세요.

커밋 위생(자동 PR 크기 관리)

Claude가 변경 사항을 모니터링하고 PR이 너무 커지기 전에 커밋을 권장합니다.

┌─────────────────────────────────────────────────────────────┐
│  커밋 크기 임계값                                             │
├─────────────────────────────────────────────────────────────┤
│  🟢 OK:     파일 ≤ 5개,  라인 ≤ 200                          │
│  🟡 WARN:   파일 6-10개, 라인 201-400 → "곧 커밋하세요"      │
│  🔴 STOP:   파일 > 10개, 라인 > 400   → "지금 커밋하세요"    │
└─────────────────────────────────────────────────────────────┘

Claude가 자동으로 체크하고 조언합니다:

상태	Claude의 말
파일 3개, 라인 95	✅ 테스트 통과. 커밋하기 좋은 타이밍입니다!
파일 7개, 라인 225	💡 임계값에 근접했습니다. 커밋을 고려하세요.
파일 12개, 라인 400	⚠️ 변경이 너무 큽니다! 지금 커밋하세요.

이것이 중요한 이유:

PR < 200라인: 결함률 15%
PR 200-400라인: 결함률 23%
PR > 400라인: 결함률 40%+ (제대로 리뷰되지 않고 도장 찍히기 쉬움)

원자적(Atomic) 커밋 원칙: 커밋 설명에 "그리고"가 필요하다면 분리하세요.

에이전틱 광고 최적화(Reddit Ads)

AI 기반 최적화로 Reddit 광고 캠페인을 자동 실행합니다.

┌─────────────────────────────────────────────────────────────┐
│  백그라운드 서비스(4-6시간마다 실행)                          │
├─────────────────────────────────────────────────────────────┤
│  1. 성과 데이터 가져오기(CTR, CPA, ROAS)                      │
│  2. Claude가 분석하고 액션을 추천                             │
│  3. 자동 실행: 일시중지, 확장, 입찰 조정, 광고 교체            │
└─────────────────────────────────────────────────────────────┘

AI 주도 액션:

액션	트리거	결과
`PAUSE`	CTR < 0.3%, 전환 없음	예산 낭비 중단
`SCALE`	CTR > 1%, CPA < 목표	예산 1.5배로 증액
`ADJUST_BID`	중간 성과	입찰가 ±10-20% 조정
`ROTATE_CREATIVE`	3일 이상 CTR 하락	새 크리에이티브 필요로 플래그

Docker 서비스로 배포:

docker-compose up -d reddit-ads-optimizer

멀티-레포 워크스페이스 인지

Claude Code가 이제 워크스페이스 전체를 이해합니다 - 모노레포든 멀티레포든.

┌─────────────────────────────────────────────────────────────┐
│  /analyze-workspace                                          │
├─────────────────────────────────────────────────────────────┤
│  발견: 모듈, 의존성, 계약(contracts)                          │
│  생성: TOPOLOGY.md, CONTRACTS.md, KEY_FILES.md               │
│  추적: API 계약, 공유 타입, 레포 간 변경                      │
└─────────────────────────────────────────────────────────────┘

생성되는 컨텍스트 아티팩트:

아티팩트	목적
`TOPOLOGY.md`	어떤 모듈이 있고, 역할/기술 스택은 무엇인지
`CONTRACTS.md`	API 엔드포인트, 공유 타입, 검증 상태
`DEPENDENCY_GRAPH.md`	누가 누구를 호출하는지, 변경 순서
`KEY_FILES.md`	각 컨텍스트에 로드해야 할 파일
`CROSS_REPO_INDEX.md`	재구현 전에 검색 가능하도록

계약 최신성(자동):

트리거	액션	시간
세션 시작	오래됨(staleness) 체크	~5초
커밋 후	계약이 바뀌면 자동 동기화	~15초
푸시 전	검증 게이트	~10초

레포 간 변경 감지:

⚠️  레포 간 변경 감지됨
이 변경은 다음에 영향을 줍니다: apps/api
권장 순서: shared-types → backend → frontend

코드 리뷰(필수 가드레일)

모든 푸시는 코드 리뷰가 필요합니다. 예외 없음.

┌─────────────────────────────────────────────────────────────┐
│  워크플로: 코드 → 테스트 → 커밋 → 푸시 → 리뷰가 차단          │
├─────────────────────────────────────────────────────────────┤
│  수동 실행: /code-review                                      │
│  강제: 치명적/높음 발견 시 프리-푸시 훅이 차단                 │
└─────────────────────────────────────────────────────────────┘

어떤 프로젝트에서든 프리-푸시 훅 활성화:

~/.claude/install-hooks.sh

심각도 레벨:

레벨	조치	푸시 가능?
🔴 치명적(Critical)	지금 반드시 수정	❌ 차단
🟠 높음(High)	지금 반드시 수정	❌ 차단
🟡 중간(Medium)	곧 수정	✅ 권고
🟢 낮음(Low)	있으면 좋음	✅ 권고

잡아내는 것:

보안 취약점(SQL 인젝션, XSS, 시크릿)
성능 문제(N+1 쿼리, 메모리 릭)
아키텍처 문제(결합도, SOLID 위반)
코드 품질(복잡도, 중복, 타입 누락)

통합: 프리-푸시 훅, GitHub Actions, CI/CD 파이프라인이 자동으로 코드 리뷰를 실행합니다.

팀 조율(여러 명이 함께하는 프로젝트)

여러 개발자가 같은 레포에서 Claude Code를 사용할 때는 조율이 필수입니다.

┌─────────────────────────────────────────────────────────────┐
│  /check-contributors                                        │
├─────────────────────────────────────────────────────────────┤
│  감지: 솔로 프로젝트인가 팀 프로젝트인가?                     │
│  표시: 지금 누가 무엇을 하고 있는가                           │
│  전환: 솔로 → 팀(전체 상태 관리 포함)                         │
└─────────────────────────────────────────────────────────────┘

생성되는 팀 구조:

_project_specs/team/
├── state.md           # 활성 사용자, 할당된 todo, 충돌
├── contributors.md    # 팀원, 소유권, 집중 영역
└── handoffs/          # 작업 인수인계 노트

작동 방식:

기능	목적
Todo 선점(claiming)	시작 전에 선점 - 중복 작업 방지
활성 세션	지금 누가 어떤 파일을 작업 중인지 확인
충돌 감시	여러 사람이 같은 영역을 만지면 경고
인수인계 노트	작업 넘길 때 컨텍스트 전달
결정 동기화	공유 decisions.md - 결정 전에 확인

워크플로:

세션 시작 → Pull → state.md 확인 → todo 선점 → 작업 → state 업데이트 → Push

빠른 명령:

/check-contributors # 상태 확인, 전환 제안 /check-contributors --status # 상태만 빠르게 /check-contributors --team # 팀 프로젝트로 전환

코드 중복 제거(의미적 비대화 방지)

AI는 복사/붙여넣기를 하지 않습니다 - 재구현합니다. 문제는 중복 코드가 아니라 중복된 ‘목적’입니다.

┌─────────────────────────────────────────────────────────────┐
│  쓰기 전에 확인                                               │
├─────────────────────────────────────────────────────────────┤
│  새 함수를 만들기 전에 반드시:                                │
│  1. CODE_INDEX.md에서 기존 기능 확인                          │
│  2. 코드베이스에서 유사 기능 검색                             │
│  3. 가능하면 기존 것을 확장                                   │
│  4. 적절한 것이 없을 때만 새로 생성                           │
└─────────────────────────────────────────────────────────────┘

의미적 기능 인덱스(무엇을 ‘하는지’로 정리):

Validation(검증)

함수	위치	하는 일
`isEmail()`	utils/validate.ts	이메일 형식 검증
`isPhone()`	utils/validate.ts	전화번호 검증

Date/Time(날짜/시간)

함수	위치	하는 일
`formatRelative()`	utils/dates.ts	"2일 전" 형식

validateEmail()을 작성하기 전에 Claude가 검색 → isEmail()이 있음을 발견 → 이를 사용합니다.

명령:

/update-code-index # 코드베이스에서 인덱스 재생성 /audit-duplicates # 병합할 의미적 중복 찾기

대규모 코드베이스(100+ 파일): 의미 검색을 위한 벡터 DB(ChromaDB/LanceDB) 통합 옵션.

생성되는 것

your-project/
├── .claude/skills/           # 코딩 가드레일
│   ├── base.md               # 범용 패턴
│   ├── security.md           # 보안 요구사항
│   ├── [language].md         # 언어별
│   └── [framework].md        # 프레임워크별
├── .github/workflows/
│   ├── quality.yml           # 린트, 타입체크, 테스트(커버리지 80%)
│   └── security.yml          # 시크릿 스캔, 의존성 감사
├── _project_specs/
│   ├── overview.md           # 프로젝트 비전
│   ├── features/             # 기능 스펙
│   └── todos/                # 테스트 케이스를 포함한 원자적 todo
├── docs/                     # 기술 문서
├── scripts/
│   ├── verify-tooling.sh     # CLI 검증
│   └── security-check.sh     # 프리커밋 보안
└── CLAUDE.md                 # Claude 지침

철학

TDD-우선 개발(필수)

모든 기능과 버그 수정은 같은 패턴을 따릅니다:

단계	기능 개발	버그 수정
1. RED	승인 기준 기반으로 테스트 작성	테스트 공백 식별, 버그를 재현하는 테스트 작성
2. RUN	테스트 실행 → 전부 실패해야 함	테스트 실행 → 실패해야 함(버그를 잡는지 증명)
3. GREEN	통과에 필요한 최소 코드 작성	버그 수정
4. RUN	테스트 실행 → 전부 통과해야 함	테스트 실행 → 통과해야 함
5. VALIDATE	린트 + 타입체크 + 커버리지 ≥80%	전체 테스트 + 린트 + 타입체크

왜 테스트는 먼저 실패해야 하는가:

테스트가 요구사항을 실제로 검증함을 증명
버그의 경우: 테스트가 그 버그를 잡았을 것임을 증명
항상 통과하는 테스트로 인한 허위 확신 방지

우리가 방지하는 안티패턴:

❌ 테스트 추가 없이 버그 수정
❌ 구현 후 테스트 작성
❌ 실패하는 테스트가 있는데도 todo 완료 처리
❌ 완료 전에 린트/타입체크 생략

복잡성은 적

모든 코드 한 줄은 책임(liability)입니다. 목표는 어떤 엔지니어(또는 AI)든 한 세션에서 전체 시스템을 이해할 수 있을 만큼 단순한 소프트웨어입니다.

모호한 가이드가 아니라 측정 가능한 제약:

제약	한도
함수당 라인 수	최대 20
함수 매개변수 수	최대 3
중첩 깊이	최대 2단계
파일당 라인 수	최대 200
테스트 커버리지	최소 80%

보안은 협상의 여지가 없음

코드에 시크릿 금지 - 절대
VITE_* 또는 NEXT_PUBLIC_* 환경 변수에 시크릿 금지(클라이언트에 노출!)
.env 파일은 항상 gitignore
모든 PR에서 의존성 스캔
프리커밋 보안 체크

중앙화된 자격 증명

모든 API 키를 하나의 파일에 저장하세요(예: ~/Documents/Access.txt):

OpenAI API: sk-proj-xxx
Claude API: sk-ant-xxx
Stripe: sk_test_xxx
Supabase url: https://xxx.supabase.co
Anon key: eyJxxx

프로젝트 시작 시 Claude가 액세스 파일 위치를 묻고, 패턴으로 키를 자동 탐지해 검증한 뒤 .env를 생성합니다.

AI-우선 아키텍처

LLM이 핵심 로직을 담당하는 애플리케이션의 경우:

로직은 LLM, 배관은 코드 - 분류/추출/의사결정은 LLM, 검증/라우팅/인증은 코드
LLM 호출을 제대로 테스트 - 유닛 테스트는 목(mock), 파싱은 픽스처(fixture), 정확도는 eval
비용 추적 - 토큰 사용량과 지연시간 모니터링

스펙 주도 개발

만들기 전에 정의하세요:

_project_specs/features/의 기능 스펙
검증 기준과 테스트 케이스가 있는 원자적 todo
삭제하지 말고 이동 - 완료된 todo는 참고를 위해 completed.md로 이동

포함된 스킬(53개)

핵심 스킬

스킬	목적
`base.md`	범용 패턴, 제약, TDD 워크플로, 원자적 todo
`iterative-development.md`	Ralph Wiggum 루프 - 테스트 통과까지 자기참조 TDD 반복
`code-review.md`	`/code-review`로 필수 코드 리뷰 - Claude, Codex, Gemini 또는 멀티 엔진 선택
`codex-review.md`	OpenAI Codex CLI 코드 리뷰(GPT-5.2-Codex), CI/CD 통합
`gemini-review.md`	Google Gemini CLI 코드 리뷰(Gemini 2.5 Pro, 100만 토큰 컨텍스트)
`workspace.md`	멀티레포 워크스페이스 인지, 계약 추적, 레포 간 컨텍스트
`commit-hygiene.md`	원자적 커밋, PR 크기 제한, 커밋 임계값, 스택드 PR
`code-deduplication.md`	기능 인덱스로 의미적 중복 방지, 작성 전 확인
`team-coordination.md`	다인 프로젝트 - 공유 상태, todo 선점, 인수인계, 충돌 방지
`security.md`	OWASP 패턴, 시크릿 관리, 보안 테스트
`credentials.md`	Access.txt에서 중앙 API 키 관리
`session-management.md`	컨텍스트 보존, 계층 요약, 재개 가능성
`project-tooling.md`	gh, vercel, supabase, render CLI + 배포 플랫폼 설정
`existing-repo.md`	기존 레포 분석, 구조 유지, 가드레일 설정(Husky, pre-commit, commitlint)

언어 & 프레임워크 스킬

스킬	목적
`python.md`	Python + ruff + mypy + pytest
`typescript.md`	TypeScript strict + eslint + jest
`nodejs-backend.md`	Express/Fastify 패턴, 리포지토리
`react-web.md`	React + hooks + React Query + Zustand
`react-native.md`	모바일 패턴, 플랫폼별 코드
`android-java.md`	Android Java(MVVM, ViewBinding, Espresso 테스트)
`android-kotlin.md`	Android Kotlin(Coroutines, Jetpack Compose, Hilt, MockK/Turbine)
`flutter.md`	Flutter(Riverpod, Freezed, go_router, mocktail 테스트)

UI 스킬

스킬	목적
`ui-web.md`	웹 UI - 글래스모피즘, Tailwind, 다크 모드, 접근성
`ui-mobile.md`	모바일 UI - React Native, iOS/Android 패턴, 터치 타깃
`ui-testing.md`	비주얼 테스트 - 보이지 않는 버튼, 깨진 레이아웃, 대비 문제 탐지
`playwright-testing.md`	E2E 테스트 - Playwright, Page Objects, 크로스 브라우저, CI/CD
`user-journeys.md`	사용자 경험 흐름 - 저니 매핑, UX 검증, 오류 복구
`pwa-development.md`	PWA - 서비스 워커, 캐싱 전략, 오프라인, Workbox

AI & 에이전틱 스킬

스킬	목적
`agentic-development.md`	AI 에이전트 구축 - Pydantic AI(Python), Claude SDK(Node.js)
`llm-patterns.md`	AI-first 앱, LLM 테스트, 프롬프트 관리
`ai-models.md`	최신 모델 레퍼런스 - Claude, OpenAI, Gemini, Eleven Labs, Replicate

데이터베이스 & 백엔드 스킬

스킬	목적
`database-schema.md`	스키마 인지 - 코딩 전 읽기, 타입 생성, 컬럼 오류 방지
`supabase.md`	Supabase CLI 핵심, 마이그레이션, RLS, Edge Functions
`supabase-nextjs.md`	Next.js + Supabase + Drizzle ORM
`supabase-python.md`	FastAPI + Supabase + SQLAlchemy/SQLModel
`supabase-node.md`	Express/Hono + Supabase + Drizzle ORM
`firebase.md`	Firebase Firestore, Auth, Storage, 실시간 리스너, 보안 규칙
`cloudflare-d1.md`	Cloudflare D1 SQLite(Workers, Drizzle ORM, 마이그레이션)
`aws-dynamodb.md`	AWS DynamoDB 싱글 테이블 설계, GSI 패턴, SDK v3
`aws-aurora.md`	AWS Aurora Serverless v2, RDS Proxy, Data API, 커넥션 풀링
`azure-cosmosdb.md`	Azure Cosmos DB 파티션 키, 일관성 레벨, change feed

콘텐츠 & SEO 스킬

스킬	목적
`aeo-optimization.md`	AEO(AI Engine Optimization) - 시맨틱 트리플, 페이지 템플릿, AI 인용을 위한 콘텐츠 클러스터
`web-content.md`	SEO + AI 발견(GEO) - 스키마, 콘텐츠 구조, ChatGPT/Perplexity 최적화
`site-architecture.md`	테크니컬 SEO - robots.txt, sitemap, meta 태그, AI 크롤러 처리, Core Web Vitals

통합 스킬

스킬	목적
`web-payments.md`	Stripe Checkout, 구독, 웹훅, 고객 포털
`reddit-api.md`	Reddit API(PRAW(Python), Snoowrap(Node.js))
`reddit-ads.md`	Reddit Ads API - 캠페인, 타기팅, 전환 + 에이전틱 최적화 서비스
`ms-teams-apps.md`	Microsoft Teams 봇/AI 에이전트 - Claude/OpenAI 통합, Adaptive Cards, Graph API
`posthog-analytics.md`	PostHog 분석, 이벤트 트래킹, 기능 플래그, 프로젝트 대시보드
`shopify-apps.md`	Shopify 앱 개발 - Remix, Admin API, 체크아웃 확장, GDPR 준수
`woocommerce.md`	WooCommerce REST API - 상품, 주문, 고객, 웹훅
`medusa.md`	Medusa 헤드리스 커머스 - 모듈, 워크플로, API 라우트, 어드민 UI
`klaviyo.md`	Klaviyo 이메일/SMS 마케팅 - 프로필, 이벤트, 플로우, 세그먼트

사용 패턴

새 프로젝트

mkdir my-new-app && cd my-new-app claude

질문에 답하면 전체 세팅 완료

기존 프로젝트

cd my-existing-app claude

스킬 업데이트, 기존 설정은 보존

기존 코드베이스(자동 분석!)

cd unfamiliar-codebase claude

기존 코드 자동 감지 → 먼저 분석 실행

표시: 구조, 기술 스택, 가드레일 상태, 컨벤션

질문: "무엇을 해드릴까요?"

1. Claude 스킬만 추가

2. 스킬 + 누락된 가드레일 추가

3. 전체 세팅

4. 분석만 보여주기

단독 분석

cd any-repo claude

변경 없이 언제든 분석 실행

전역 스킬 업데이트

cd ~/.claude-bootstrap git pull ./install.sh

그런 다음 어떤 프로젝트에서든:

claude

GitHub CLI

brew install gh gh auth login

Vercel CLI

npm i -g vercel vercel login

Supabase CLI

brew install supabase/tap/supabase supabase login

품질 게이트

모든 프로젝트에는 자동 강제가 포함됩니다:

프리-커밋(로컬)

자동 수정 포함 린트
타입 체크
보안 체크(시크릿 금지, .env 금지)
변경된 파일에 대한 유닛 테스트

CI(GitHub Actions)

전체 린트 + 타입 체크
커버리지 80%로 모든 테스트
시크릿 스캔(trufflehog)
의존성 감사(npm audit / safety)

원자적 Todo

모든 작업은 검증, 테스트 케이스, TDD 실행 로그와 함께 추적됩니다:

[TODO-042] 가입 폼에 이메일 유효성 검사 추가

상태: 진행 중 우선순위: 높음 추정: S

승인 기준

이메일 필드가 잘못된 형식에 오류를 표시한다
잘못된 이메일이면 폼 제출이 불가능하다

테스트 케이스

입력	기대
user@example.com	유효
notanemail	오류

TDD 실행 로그

단계	명령	결과
RED	`npm test -- --grep "email validation"`	테스트 2개 실패 ✓
GREEN	`npm test -- --grep "email validation"`	테스트 2개 통과 ✓
VALIDATE	`npm run lint && npm run typecheck && npm test -- --coverage`	통과, 84% ✓

버그 리포트에는 테스트 공백 분석이 포함됩니다:

[BUG-007] 이메일 검증이 "user@"를 허용함

테스트 공백 분석

기존 테스트: signup.test.ts - 유효한 이메일만 테스트
공백: 도메인이 없는 이메일에 대한 테스트 누락
새 테스트: 부분 이메일 케이스 추가

TDD 실행 로그

단계	명령	결과
DIAGNOSE	`npm test`	모두 통과(테스트 공백!)
RED	`npm test -- --grep "partial email"`	테스트 1개 실패 ✓
GREEN	`npm test -- --grep "partial email"`	테스트 1개 통과 ✓
VALIDATE	`npm run lint && npm test -- --coverage`	통과 ✓

루프에서의 오류 처리

모든 실패가 동일한 것은 아닙니다. Claude는 반복 전에 오류를 분류합니다:

오류 유형	예시	Claude가 수정?	액션
코드 오류	로직 버그, 잘못된 assertion	✅ 예	루프 계속
접근 오류	API 키 없음, DB 거부	❌ 아니오	중단 + 보고
환경 오류	패키지 누락, 버전 불일치	❌ 아니오	중단 + 보고

Claude가 접근/환경 오류를 만났을 때:

🛑 루프 차단됨 - 사람의 조치 필요

Error: ECONNREFUSED 127.0.0.1:5432

필요한 조치:
1. PostgreSQL 시작: brew services start postgresql
2. 연결 확인: psql -U postgres -c "SELECT 1"
3. .env의 DATABASE_URL 확인

고친 뒤 /ralph-loop를 다시 실행하세요.

자주 발생하는 차단 요인과 해결:

오류	원인	해결
`ECONNREFUSED :5432`	PostgreSQL이 실행 중이 아님	`brew services start postgresql`
`ECONNREFUSED :6379`	Redis가 실행 중이 아님	`brew services start redis`
`401 Unauthorized`	API 키가 잘못됨	`.env` 파일 확인
`MODULE_NOT_FOUND`	패키지 누락	`npm install`

FAQ

이것은 그냥 Claude Code를 쓰는 것과 무엇이 다른가요?

Claude Code는 강력하지만 가드레일이 없으면 예측 불가능합니다. Claude Bootstrap은 다음을 추가합니다:

TDD 강제 - 구현 전에 테스트가 반드시 실패해야 함
자동 반복 - 원샷이 아니라 테스트 통과까지 루프
오류 분류 - 멈추고 도움을 요청해야 할 때를 앎
복잡성 제한 - 유지보수 불가능한 코드를 막는 하드 캡

매번 `/ralph-loop`를 수동으로 실행해야 하나요?

아니요. Claude Bootstrap 스킬을 로드하면 Claude가 요청을 자동으로 반복 TDD 루프로 변환합니다. "이메일 유효성 검사 추가"라고 말하면 테스트가 통과할 때까지 루프합니다.

어떤 작업에 루프를 원하지 않으면?

옵트아웃 문구를 사용하세요:

"그냥 설명..." → 설명만
"빠른 수정..." → 한 줄 수정
"루프 돌리지 마..." → 명시적 옵트아웃

루프가 끝없이 돌면 어떻게 하나요?

세 가지 안전 장치가 있습니다:

--max-iterations - 하드 제한(기본 20-30)
오류 분류 - 접근/환경 오류에서 중단
차단 요인 감지 - 막히면 보고하고 사람의 도움이 필요함을 알림

기존 프로젝트에서도 동작하나요?

네. 어떤 디렉터리에서든 /initialize-project를 실행하세요. 기존 설정을 깨지 않으면서 스킬을 추가합니다.

테스트 커버리지는요?

최소 80% 커버리지가 강제됩니다. 임계값 아래이면 CI가 PR을 차단합니다.

스킬은 어떻게 업데이트하나요?

cd ~/.claude-bootstrap git pull ./install.sh

그 다음 프로젝트에서 /initialize-project를 실행해 최신 스킬을 받으세요.

스킬을 커스터마이즈할 수 있나요?

네. 스킬은 .claude/skills/의 마크다운 파일입니다. 편집하거나 직접 추가할 수 있습니다.

어떤 언어/프레임워크를 지원하나요?

카테고리	지원
언어	TypeScript, Python, Kotlin, Dart, Java
프론트엔드	React, Next.js, React Native, Flutter, PWA
모바일	React Native, Flutter, Android(Java/Kotlin)
백엔드	Node.js, Express, FastAPI
데이터베이스	Supabase, Firebase, Cloudflare D1, AWS DynamoDB, Aurora, Azure Cosmos DB
웹 기술	PWA(서비스 워커, Workbox, 오프라인 우선)
이커머스	Shopify, WooCommerce, Medusa
광고	Reddit Ads API(캠페인, 타기팅, 전환)
협업	Microsoft Teams(봇, AI 에이전트, Adaptive Cards)
마케팅	Klaviyo, PostHog

비교

기능	다른 도구	Claude Bootstrap
테스트	선택, 종종 생략	TDD 필수 - 테스트가 먼저 실패
반복	원샷	테스트 통과까지 루프
버그 수정	바로 수정으로 점프	테스트 공백 분석 → 실패 테스트 → 수정
오류 처리	영원히 루프	오류 분류, 차단 요인에서 중단
보안	거의 다루지 않음	CI 강제로 1급 시민
복잡성	모호한 가이드	하드 제한(함수 20줄, 파일 200줄)

기여

가이드라인은 CONTRIBUTING.md를 참고하세요.

핵심 원칙:

모호한 가이드보다 측정 가능한 제약
동작하는 코드 예시
멱등성(idempotency) 유지
제출 전 로컬 테스트

변경 로그

버전 히스토리와 업데이트는 CHANGELOG.md를 참고하세요.

최신: v2.4.0 - 멀티레포 워크스페이스 인지, 계약 추적, 레포 간 컨텍스트를 포함한 53개 스킬

라이선스

MIT - LICENSE 참고

크레딧

고객 경험 관리, 에이전틱 AI 플랫폼, 모바일 앱, 풀스택 웹 애플리케이션 등 100+ 프로젝트에서 얻은 학습을 기반으로 만들었습니다.

조직에서 AI 확장을 도와드릴까요? Claude Code & MCP 전문가

URL: https://github.com/alinaqi/claude-bootstrap

Title: GitHub - alinaqi/claude-bootstrap: Opinionated project initialization for Claude Code. Security-first, spec-driven, AI-native.

Claude Bootstrap

핵심 철학

┌────────────────────────────────────────────────────────────────┐
│  기본값은 반복 루프                                            │
│  ─────────────────────────────────────────────────────────────│
│  모든 작업은 테스트가 통과할 때까지 자기참조 루프로 실행됩니다. │
│  Claude가 자율적으로 반복합니다. 당신은 어떻게가 아니라 무엇을 │
│  설명합니다.                                                   │
│  Ralph Wiggum이 구동 - 완벽보다 반복.                           │
├────────────────────────────────────────────────────────────────┤
│  항상 테스트 우선                                              │
│  ─────────────────────────────────────────────────────────────│
│  기능: 테스트 작성 → 실패 확인 → 구현 → 통과                   │
│  버그: 테스트 공백 찾기 → 실패하는 테스트 작성 → 수정 → 통과     │
│  먼저 실패한 테스트 없이 코드는 배포되지 않습니다.              │
├────────────────────────────────────────────────────────────────┤
│  단순함은 협상의 여지가 없습니다                                │
│  ─────────────────────────────────────────────────────────────│
│  함수당 20줄 │ 파일당 200줄 │ 매개변수 최대 3개                │
│  한 세션에서 전체 시스템을 이해할 수 없다면,                    │
│  너무 복잡한 것입니다.                                         │
├────────────────────────────────────────────────────────────────┤
│  기본값은 보안                                                  │
│  ─────────────────────────────────────────────────────────────│
│  코드에 시크릿 금지 │ 클라이언트 env vars에 시크릿 금지          │
│  의존성 스캔 │ 프리커밋 훅 │ CI 강제                            │
├────────────────────────────────────────────────────────────────┤
│  코드 리뷰는 필수                                               │
│  ─────────────────────────────────────────────────────────────│
│  모든 커밋은 푸시 전에 /code-review가 필요합니다.               │
│  🔴 치명적 + 🟠 높음 = 차단 │ 🟡 중간 + 🟢 낮음 = 배포 가능        │
│  AI는 인간이 놓치는 것을 잡고, 인간은 AI가 놓치는 것을 잡습니다. │
└────────────────────────────────────────────────────────────────┘

이것이 존재하는 이유

Node, React, Python, React Native 전반에서 수백 건의 AI 보조 프로젝트를 진행하며 패턴이 드러났습니다:

엔지니어가 Claude Code로 고생하는 이유는 도구 때문이 아니라 지시 방식 때문 - 차이는 가드레일에 있습니다.
복잡성에는 상한이 있음 - AI가 시스템을 일관되게 이해하지 못하는 지점이 존재합니다. 이는 실패가 아니라 신호입니다.
재시작은 실패가 아니라 기능 - 무언가를 고치려다 복잡성이 증가한다면, 학습한 내용을 바탕으로 다시 시작하세요. 반복할수록 더 빨라집니다.

이 툴킷은 그 학습을 재사용 가능한 스킬로 인코딩합니다.

빠른 시작

클론 및 설치

git clone https://github.com/alinaqi/claude-bootstrap.git ~/.claude-bootstrap cd ~/.claude-bootstrap && ./install.sh

어떤 프로젝트 디렉터리에서든

claude

Claude는 다음을 수행합니다:

도구 검증 - gh, vercel, supabase CLI 확인
질문 - 언어, 프레임워크, AI-first 여부?, 데이터베이스
리포지토리 설정 - GitHub repo 생성 또는 연결
구조 생성 - 스킬, 보안, CI/CD, 스펙, TODO
스펙 프롬프트 - 첫 기능 정의로 전환

자동 반복 루프 (Ralph Wiggum)

자연스럽게 말하면 됩니다. Claude가 자동으로 반복 TDD 루프를 실행합니다.

┌─────────────────────────────────────────────────────────────┐
│  당신: "가입에 이메일 유효성 검사를 추가해줘"                 │
├─────────────────────────────────────────────────────────────┤
│  Claude 자동 수행:                                             │
│  1. 요청에서 요구사항 추출                                     │
│  2. 완료 기준을 포함한 TDD 루프로 구조화                       │
│  3. 테스트를 종료 조건으로 /ralph-loop 실행                    │
│  4. 모든 테스트 통과 + 린트 클린까지 반복                      │
└─────────────────────────────────────────────────────────────┘

/ralph-loop를 수동으로 호출할 필요가 없습니다. 원하는 것을 설명만 하세요:

당신이 말함	Claude가 수행함
"사용자 인증 추가"	인증 테스트가 통과할 때까지 루프
"로그인 버그 수정"	테스트 공백 찾기 → 테스트 작성 → 고칠 때까지 루프
"할 일(todo) REST API 만들기"	모든 엔드포인트 테스트가 통과할 때까지 루프
"인증 모듈 리팩터링"	테스트를 안전망으로 두고 루프

옵트아웃 문구(루프를 원치 않을 때):

"그냥 설명..." → 설명만
"빠른 수정..." → 한 줄 수정, 루프 없음
"루프 돌리지 마..." → 명시적 옵트아웃

Ralph Wiggum 플러그인 설정

공식 마켓플레이스에서 설치 (Claude Code에서)

/plugin install ralph-loop@claude-plugins-official

문제 해결: "Source path does not exist: .../ralph-wiggum"

ln -s ~/.claude/plugins/marketplaces/claude-plugins-official/plugins/ralph-loop
~/.claude/plugins/marketplaces/claude-plugins-official/plugins/ralph-wiggum

그 다음 /plugin install ralph-loop@claude-plugins-official를 다시 시도하세요.

커밋 위생(자동 PR 크기 관리)

Claude가 변경 사항을 모니터링하고 PR이 너무 커지기 전에 커밋을 권장합니다.

┌─────────────────────────────────────────────────────────────┐
│  커밋 크기 임계값                                             │
├─────────────────────────────────────────────────────────────┤
│  🟢 OK:     파일 ≤ 5개,  라인 ≤ 200                          │
│  🟡 WARN:   파일 6-10개, 라인 201-400 → "곧 커밋하세요"      │
│  🔴 STOP:   파일 > 10개, 라인 > 400   → "지금 커밋하세요"    │
└─────────────────────────────────────────────────────────────┘

Claude가 자동으로 체크하고 조언합니다:

상태	Claude의 말
파일 3개, 라인 95	✅ 테스트 통과. 커밋하기 좋은 타이밍입니다!
파일 7개, 라인 225	💡 임계값에 근접했습니다. 커밋을 고려하세요.
파일 12개, 라인 400	⚠️ 변경이 너무 큽니다! 지금 커밋하세요.

이것이 중요한 이유:

PR < 200라인: 결함률 15%
PR 200-400라인: 결함률 23%
PR > 400라인: 결함률 40%+ (제대로 리뷰되지 않고 도장 찍히기 쉬움)

원자적(Atomic) 커밋 원칙: 커밋 설명에 "그리고"가 필요하다면 분리하세요.

에이전틱 광고 최적화(Reddit Ads)

AI 기반 최적화로 Reddit 광고 캠페인을 자동 실행합니다.

┌─────────────────────────────────────────────────────────────┐
│  백그라운드 서비스(4-6시간마다 실행)                          │
├─────────────────────────────────────────────────────────────┤
│  1. 성과 데이터 가져오기(CTR, CPA, ROAS)                      │
│  2. Claude가 분석하고 액션을 추천                             │
│  3. 자동 실행: 일시중지, 확장, 입찰 조정, 광고 교체            │
└─────────────────────────────────────────────────────────────┘

AI 주도 액션:

액션	트리거	결과
`PAUSE`	CTR < 0.3%, 전환 없음	예산 낭비 중단
`SCALE`	CTR > 1%, CPA < 목표	예산 1.5배로 증액
`ADJUST_BID`	중간 성과	입찰가 ±10-20% 조정
`ROTATE_CREATIVE`	3일 이상 CTR 하락	새 크리에이티브 필요로 플래그

Docker 서비스로 배포:

docker-compose up -d reddit-ads-optimizer

멀티-레포 워크스페이스 인지

Claude Code가 이제 워크스페이스 전체를 이해합니다 - 모노레포든 멀티레포든.

┌─────────────────────────────────────────────────────────────┐
│  /analyze-workspace                                          │
├─────────────────────────────────────────────────────────────┤
│  발견: 모듈, 의존성, 계약(contracts)                          │
│  생성: TOPOLOGY.md, CONTRACTS.md, KEY_FILES.md               │
│  추적: API 계약, 공유 타입, 레포 간 변경                      │
└─────────────────────────────────────────────────────────────┘

생성되는 컨텍스트 아티팩트:

아티팩트	목적
`TOPOLOGY.md`	어떤 모듈이 있고, 역할/기술 스택은 무엇인지
`CONTRACTS.md`	API 엔드포인트, 공유 타입, 검증 상태
`DEPENDENCY_GRAPH.md`	누가 누구를 호출하는지, 변경 순서
`KEY_FILES.md`	각 컨텍스트에 로드해야 할 파일
`CROSS_REPO_INDEX.md`	재구현 전에 검색 가능하도록

계약 최신성(자동):

트리거	액션	시간
세션 시작	오래됨(staleness) 체크	~5초
커밋 후	계약이 바뀌면 자동 동기화	~15초
푸시 전	검증 게이트	~10초

레포 간 변경 감지:

⚠️  레포 간 변경 감지됨
이 변경은 다음에 영향을 줍니다: apps/api
권장 순서: shared-types → backend → frontend

코드 리뷰(필수 가드레일)

모든 푸시는 코드 리뷰가 필요합니다. 예외 없음.

┌─────────────────────────────────────────────────────────────┐
│  워크플로: 코드 → 테스트 → 커밋 → 푸시 → 리뷰가 차단          │
├─────────────────────────────────────────────────────────────┤
│  수동 실행: /code-review                                      │
│  강제: 치명적/높음 발견 시 프리-푸시 훅이 차단                 │
└─────────────────────────────────────────────────────────────┘

어떤 프로젝트에서든 프리-푸시 훅 활성화:

~/.claude/install-hooks.sh

심각도 레벨:

레벨	조치	푸시 가능?
🔴 치명적(Critical)	지금 반드시 수정	❌ 차단
🟠 높음(High)	지금 반드시 수정	❌ 차단
🟡 중간(Medium)	곧 수정	✅ 권고
🟢 낮음(Low)	있으면 좋음	✅ 권고

잡아내는 것:

보안 취약점(SQL 인젝션, XSS, 시크릿)
성능 문제(N+1 쿼리, 메모리 릭)
아키텍처 문제(결합도, SOLID 위반)
코드 품질(복잡도, 중복, 타입 누락)

통합: 프리-푸시 훅, GitHub Actions, CI/CD 파이프라인이 자동으로 코드 리뷰를 실행합니다.

팀 조율(여러 명이 함께하는 프로젝트)

여러 개발자가 같은 레포에서 Claude Code를 사용할 때는 조율이 필수입니다.

┌─────────────────────────────────────────────────────────────┐
│  /check-contributors                                        │
├─────────────────────────────────────────────────────────────┤
│  감지: 솔로 프로젝트인가 팀 프로젝트인가?                     │
│  표시: 지금 누가 무엇을 하고 있는가                           │
│  전환: 솔로 → 팀(전체 상태 관리 포함)                         │
└─────────────────────────────────────────────────────────────┘

생성되는 팀 구조:

_project_specs/team/
├── state.md           # 활성 사용자, 할당된 todo, 충돌
├── contributors.md    # 팀원, 소유권, 집중 영역
└── handoffs/          # 작업 인수인계 노트

작동 방식:

기능	목적
Todo 선점(claiming)	시작 전에 선점 - 중복 작업 방지
활성 세션	지금 누가 어떤 파일을 작업 중인지 확인
충돌 감시	여러 사람이 같은 영역을 만지면 경고
인수인계 노트	작업 넘길 때 컨텍스트 전달
결정 동기화	공유 decisions.md - 결정 전에 확인

워크플로:

세션 시작 → Pull → state.md 확인 → todo 선점 → 작업 → state 업데이트 → Push

빠른 명령:

/check-contributors # 상태 확인, 전환 제안 /check-contributors --status # 상태만 빠르게 /check-contributors --team # 팀 프로젝트로 전환

코드 중복 제거(의미적 비대화 방지)

AI는 복사/붙여넣기를 하지 않습니다 - 재구현합니다. 문제는 중복 코드가 아니라 중복된 ‘목적’입니다.

┌─────────────────────────────────────────────────────────────┐
│  쓰기 전에 확인                                               │
├─────────────────────────────────────────────────────────────┤
│  새 함수를 만들기 전에 반드시:                                │
│  1. CODE_INDEX.md에서 기존 기능 확인                          │
│  2. 코드베이스에서 유사 기능 검색                             │
│  3. 가능하면 기존 것을 확장                                   │
│  4. 적절한 것이 없을 때만 새로 생성                           │
└─────────────────────────────────────────────────────────────┘

의미적 기능 인덱스(무엇을 ‘하는지’로 정리):

Validation(검증)

함수	위치	하는 일
`isEmail()`	utils/validate.ts	이메일 형식 검증
`isPhone()`	utils/validate.ts	전화번호 검증

Date/Time(날짜/시간)

함수	위치	하는 일
`formatRelative()`	utils/dates.ts	"2일 전" 형식

validateEmail()을 작성하기 전에 Claude가 검색 → isEmail()이 있음을 발견 → 이를 사용합니다.

명령:

/update-code-index # 코드베이스에서 인덱스 재생성 /audit-duplicates # 병합할 의미적 중복 찾기

대규모 코드베이스(100+ 파일): 의미 검색을 위한 벡터 DB(ChromaDB/LanceDB) 통합 옵션.

생성되는 것

your-project/
├── .claude/skills/           # 코딩 가드레일
│   ├── base.md               # 범용 패턴
│   ├── security.md           # 보안 요구사항
│   ├── [language].md         # 언어별
│   └── [framework].md        # 프레임워크별
├── .github/workflows/
│   ├── quality.yml           # 린트, 타입체크, 테스트(커버리지 80%)
│   └── security.yml          # 시크릿 스캔, 의존성 감사
├── _project_specs/
│   ├── overview.md           # 프로젝트 비전
│   ├── features/             # 기능 스펙
│   └── todos/                # 테스트 케이스를 포함한 원자적 todo
├── docs/                     # 기술 문서
├── scripts/
│   ├── verify-tooling.sh     # CLI 검증
│   └── security-check.sh     # 프리커밋 보안
└── CLAUDE.md                 # Claude 지침

철학

TDD-우선 개발(필수)

모든 기능과 버그 수정은 같은 패턴을 따릅니다:

단계	기능 개발	버그 수정
1. RED	승인 기준 기반으로 테스트 작성	테스트 공백 식별, 버그를 재현하는 테스트 작성
2. RUN	테스트 실행 → 전부 실패해야 함	테스트 실행 → 실패해야 함(버그를 잡는지 증명)
3. GREEN	통과에 필요한 최소 코드 작성	버그 수정
4. RUN	테스트 실행 → 전부 통과해야 함	테스트 실행 → 통과해야 함
5. VALIDATE	린트 + 타입체크 + 커버리지 ≥80%	전체 테스트 + 린트 + 타입체크

왜 테스트는 먼저 실패해야 하는가:

테스트가 요구사항을 실제로 검증함을 증명
버그의 경우: 테스트가 그 버그를 잡았을 것임을 증명
항상 통과하는 테스트로 인한 허위 확신 방지

우리가 방지하는 안티패턴:

❌ 테스트 추가 없이 버그 수정
❌ 구현 후 테스트 작성
❌ 실패하는 테스트가 있는데도 todo 완료 처리
❌ 완료 전에 린트/타입체크 생략

복잡성은 적

모든 코드 한 줄은 책임(liability)입니다. 목표는 어떤 엔지니어(또는 AI)든 한 세션에서 전체 시스템을 이해할 수 있을 만큼 단순한 소프트웨어입니다.

모호한 가이드가 아니라 측정 가능한 제약:

제약	한도
함수당 라인 수	최대 20
함수 매개변수 수	최대 3
중첩 깊이	최대 2단계
파일당 라인 수	최대 200
테스트 커버리지	최소 80%

보안은 협상의 여지가 없음

코드에 시크릿 금지 - 절대
VITE_* 또는 NEXT_PUBLIC_* 환경 변수에 시크릿 금지(클라이언트에 노출!)
.env 파일은 항상 gitignore
모든 PR에서 의존성 스캔
프리커밋 보안 체크

중앙화된 자격 증명

모든 API 키를 하나의 파일에 저장하세요(예: ~/Documents/Access.txt):

OpenAI API: sk-proj-xxx
Claude API: sk-ant-xxx
Stripe: sk_test_xxx
Supabase url: https://xxx.supabase.co
Anon key: eyJxxx

프로젝트 시작 시 Claude가 액세스 파일 위치를 묻고, 패턴으로 키를 자동 탐지해 검증한 뒤 .env를 생성합니다.

AI-우선 아키텍처

LLM이 핵심 로직을 담당하는 애플리케이션의 경우:

로직은 LLM, 배관은 코드 - 분류/추출/의사결정은 LLM, 검증/라우팅/인증은 코드
LLM 호출을 제대로 테스트 - 유닛 테스트는 목(mock), 파싱은 픽스처(fixture), 정확도는 eval
비용 추적 - 토큰 사용량과 지연시간 모니터링

스펙 주도 개발

만들기 전에 정의하세요:

_project_specs/features/의 기능 스펙
검증 기준과 테스트 케이스가 있는 원자적 todo
삭제하지 말고 이동 - 완료된 todo는 참고를 위해 completed.md로 이동

포함된 스킬(53개)

핵심 스킬

스킬	목적
`base.md`	범용 패턴, 제약, TDD 워크플로, 원자적 todo
`iterative-development.md`	Ralph Wiggum 루프 - 테스트 통과까지 자기참조 TDD 반복
`code-review.md`	`/code-review`로 필수 코드 리뷰 - Claude, Codex, Gemini 또는 멀티 엔진 선택
`codex-review.md`	OpenAI Codex CLI 코드 리뷰(GPT-5.2-Codex), CI/CD 통합
`gemini-review.md`	Google Gemini CLI 코드 리뷰(Gemini 2.5 Pro, 100만 토큰 컨텍스트)
`workspace.md`	멀티레포 워크스페이스 인지, 계약 추적, 레포 간 컨텍스트
`commit-hygiene.md`	원자적 커밋, PR 크기 제한, 커밋 임계값, 스택드 PR
`code-deduplication.md`	기능 인덱스로 의미적 중복 방지, 작성 전 확인
`team-coordination.md`	다인 프로젝트 - 공유 상태, todo 선점, 인수인계, 충돌 방지
`security.md`	OWASP 패턴, 시크릿 관리, 보안 테스트
`credentials.md`	Access.txt에서 중앙 API 키 관리
`session-management.md`	컨텍스트 보존, 계층 요약, 재개 가능성
`project-tooling.md`	gh, vercel, supabase, render CLI + 배포 플랫폼 설정
`existing-repo.md`	기존 레포 분석, 구조 유지, 가드레일 설정(Husky, pre-commit, commitlint)

언어 & 프레임워크 스킬

스킬	목적
`python.md`	Python + ruff + mypy + pytest
`typescript.md`	TypeScript strict + eslint + jest
`nodejs-backend.md`	Express/Fastify 패턴, 리포지토리
`react-web.md`	React + hooks + React Query + Zustand
`react-native.md`	모바일 패턴, 플랫폼별 코드
`android-java.md`	Android Java(MVVM, ViewBinding, Espresso 테스트)
`android-kotlin.md`	Android Kotlin(Coroutines, Jetpack Compose, Hilt, MockK/Turbine)
`flutter.md`	Flutter(Riverpod, Freezed, go_router, mocktail 테스트)

UI 스킬

스킬	목적
`ui-web.md`	웹 UI - 글래스모피즘, Tailwind, 다크 모드, 접근성
`ui-mobile.md`	모바일 UI - React Native, iOS/Android 패턴, 터치 타깃
`ui-testing.md`	비주얼 테스트 - 보이지 않는 버튼, 깨진 레이아웃, 대비 문제 탐지
`playwright-testing.md`	E2E 테스트 - Playwright, Page Objects, 크로스 브라우저, CI/CD
`user-journeys.md`	사용자 경험 흐름 - 저니 매핑, UX 검증, 오류 복구
`pwa-development.md`	PWA - 서비스 워커, 캐싱 전략, 오프라인, Workbox

AI & 에이전틱 스킬

스킬	목적
`agentic-development.md`	AI 에이전트 구축 - Pydantic AI(Python), Claude SDK(Node.js)
`llm-patterns.md`	AI-first 앱, LLM 테스트, 프롬프트 관리
`ai-models.md`	최신 모델 레퍼런스 - Claude, OpenAI, Gemini, Eleven Labs, Replicate

데이터베이스 & 백엔드 스킬

스킬	목적
`database-schema.md`	스키마 인지 - 코딩 전 읽기, 타입 생성, 컬럼 오류 방지
`supabase.md`	Supabase CLI 핵심, 마이그레이션, RLS, Edge Functions
`supabase-nextjs.md`	Next.js + Supabase + Drizzle ORM
`supabase-python.md`	FastAPI + Supabase + SQLAlchemy/SQLModel
`supabase-node.md`	Express/Hono + Supabase + Drizzle ORM
`firebase.md`	Firebase Firestore, Auth, Storage, 실시간 리스너, 보안 규칙
`cloudflare-d1.md`	Cloudflare D1 SQLite(Workers, Drizzle ORM, 마이그레이션)
`aws-dynamodb.md`	AWS DynamoDB 싱글 테이블 설계, GSI 패턴, SDK v3
`aws-aurora.md`	AWS Aurora Serverless v2, RDS Proxy, Data API, 커넥션 풀링
`azure-cosmosdb.md`	Azure Cosmos DB 파티션 키, 일관성 레벨, change feed

콘텐츠 & SEO 스킬

스킬	목적
`aeo-optimization.md`	AEO(AI Engine Optimization) - 시맨틱 트리플, 페이지 템플릿, AI 인용을 위한 콘텐츠 클러스터
`web-content.md`	SEO + AI 발견(GEO) - 스키마, 콘텐츠 구조, ChatGPT/Perplexity 최적화
`site-architecture.md`	테크니컬 SEO - robots.txt, sitemap, meta 태그, AI 크롤러 처리, Core Web Vitals

통합 스킬

스킬	목적
`web-payments.md`	Stripe Checkout, 구독, 웹훅, 고객 포털
`reddit-api.md`	Reddit API(PRAW(Python), Snoowrap(Node.js))
`reddit-ads.md`	Reddit Ads API - 캠페인, 타기팅, 전환 + 에이전틱 최적화 서비스
`ms-teams-apps.md`	Microsoft Teams 봇/AI 에이전트 - Claude/OpenAI 통합, Adaptive Cards, Graph API
`posthog-analytics.md`	PostHog 분석, 이벤트 트래킹, 기능 플래그, 프로젝트 대시보드
`shopify-apps.md`	Shopify 앱 개발 - Remix, Admin API, 체크아웃 확장, GDPR 준수
`woocommerce.md`	WooCommerce REST API - 상품, 주문, 고객, 웹훅
`medusa.md`	Medusa 헤드리스 커머스 - 모듈, 워크플로, API 라우트, 어드민 UI
`klaviyo.md`	Klaviyo 이메일/SMS 마케팅 - 프로필, 이벤트, 플로우, 세그먼트

사용 패턴

새 프로젝트

mkdir my-new-app && cd my-new-app claude

질문에 답하면 전체 세팅 완료

기존 프로젝트

cd my-existing-app claude

스킬 업데이트, 기존 설정은 보존

기존 코드베이스(자동 분석!)

cd unfamiliar-codebase claude

기존 코드 자동 감지 → 먼저 분석 실행

표시: 구조, 기술 스택, 가드레일 상태, 컨벤션

질문: "무엇을 해드릴까요?"

1. Claude 스킬만 추가

2. 스킬 + 누락된 가드레일 추가

3. 전체 세팅

4. 분석만 보여주기

단독 분석

cd any-repo claude

변경 없이 언제든 분석 실행

전역 스킬 업데이트

cd ~/.claude-bootstrap git pull ./install.sh

그런 다음 어떤 프로젝트에서든:

claude

GitHub CLI

brew install gh gh auth login

Vercel CLI

npm i -g vercel vercel login

Supabase CLI

brew install supabase/tap/supabase supabase login

품질 게이트

모든 프로젝트에는 자동 강제가 포함됩니다:

프리-커밋(로컬)

자동 수정 포함 린트
타입 체크
보안 체크(시크릿 금지, .env 금지)
변경된 파일에 대한 유닛 테스트

CI(GitHub Actions)

전체 린트 + 타입 체크
커버리지 80%로 모든 테스트
시크릿 스캔(trufflehog)
의존성 감사(npm audit / safety)

원자적 Todo

모든 작업은 검증, 테스트 케이스, TDD 실행 로그와 함께 추적됩니다:

[TODO-042] 가입 폼에 이메일 유효성 검사 추가

상태: 진행 중 우선순위: 높음 추정: S

승인 기준

이메일 필드가 잘못된 형식에 오류를 표시한다
잘못된 이메일이면 폼 제출이 불가능하다

테스트 케이스

입력	기대
user@example.com	유효
notanemail	오류

TDD 실행 로그

단계	명령	결과
RED	`npm test -- --grep "email validation"`	테스트 2개 실패 ✓
GREEN	`npm test -- --grep "email validation"`	테스트 2개 통과 ✓
VALIDATE	`npm run lint && npm run typecheck && npm test -- --coverage`	통과, 84% ✓

버그 리포트에는 테스트 공백 분석이 포함됩니다:

[BUG-007] 이메일 검증이 "user@"를 허용함

테스트 공백 분석

기존 테스트: signup.test.ts - 유효한 이메일만 테스트
공백: 도메인이 없는 이메일에 대한 테스트 누락
새 테스트: 부분 이메일 케이스 추가

TDD 실행 로그

단계	명령	결과
DIAGNOSE	`npm test`	모두 통과(테스트 공백!)
RED	`npm test -- --grep "partial email"`	테스트 1개 실패 ✓
GREEN	`npm test -- --grep "partial email"`	테스트 1개 통과 ✓
VALIDATE	`npm run lint && npm test -- --coverage`	통과 ✓

루프에서의 오류 처리

모든 실패가 동일한 것은 아닙니다. Claude는 반복 전에 오류를 분류합니다:

오류 유형	예시	Claude가 수정?	액션
코드 오류	로직 버그, 잘못된 assertion	✅ 예	루프 계속
접근 오류	API 키 없음, DB 거부	❌ 아니오	중단 + 보고
환경 오류	패키지 누락, 버전 불일치	❌ 아니오	중단 + 보고

Claude가 접근/환경 오류를 만났을 때:

🛑 루프 차단됨 - 사람의 조치 필요

Error: ECONNREFUSED 127.0.0.1:5432

필요한 조치:
1. PostgreSQL 시작: brew services start postgresql
2. 연결 확인: psql -U postgres -c "SELECT 1"
3. .env의 DATABASE_URL 확인

고친 뒤 /ralph-loop를 다시 실행하세요.

자주 발생하는 차단 요인과 해결:

오류	원인	해결
`ECONNREFUSED :5432`	PostgreSQL이 실행 중이 아님	`brew services start postgresql`
`ECONNREFUSED :6379`	Redis가 실행 중이 아님	`brew services start redis`
`401 Unauthorized`	API 키가 잘못됨	`.env` 파일 확인
`MODULE_NOT_FOUND`	패키지 누락	`npm install`

FAQ

이것은 그냥 Claude Code를 쓰는 것과 무엇이 다른가요?

Claude Code는 강력하지만 가드레일이 없으면 예측 불가능합니다. Claude Bootstrap은 다음을 추가합니다:

TDD 강제 - 구현 전에 테스트가 반드시 실패해야 함
자동 반복 - 원샷이 아니라 테스트 통과까지 루프
오류 분류 - 멈추고 도움을 요청해야 할 때를 앎
복잡성 제한 - 유지보수 불가능한 코드를 막는 하드 캡

매번 `/ralph-loop`를 수동으로 실행해야 하나요?

어떤 작업에 루프를 원하지 않으면?

옵트아웃 문구를 사용하세요:

"그냥 설명..." → 설명만
"빠른 수정..." → 한 줄 수정
"루프 돌리지 마..." → 명시적 옵트아웃

루프가 끝없이 돌면 어떻게 하나요?

세 가지 안전 장치가 있습니다:

--max-iterations - 하드 제한(기본 20-30)
오류 분류 - 접근/환경 오류에서 중단
차단 요인 감지 - 막히면 보고하고 사람의 도움이 필요함을 알림

기존 프로젝트에서도 동작하나요?

네. 어떤 디렉터리에서든 /initialize-project를 실행하세요. 기존 설정을 깨지 않으면서 스킬을 추가합니다.

테스트 커버리지는요?

최소 80% 커버리지가 강제됩니다. 임계값 아래이면 CI가 PR을 차단합니다.

스킬은 어떻게 업데이트하나요?

cd ~/.claude-bootstrap git pull ./install.sh

그 다음 프로젝트에서 /initialize-project를 실행해 최신 스킬을 받으세요.

스킬을 커스터마이즈할 수 있나요?

네. 스킬은 .claude/skills/의 마크다운 파일입니다. 편집하거나 직접 추가할 수 있습니다.

어떤 언어/프레임워크를 지원하나요?

카테고리	지원
언어	TypeScript, Python, Kotlin, Dart, Java
프론트엔드	React, Next.js, React Native, Flutter, PWA
모바일	React Native, Flutter, Android(Java/Kotlin)
백엔드	Node.js, Express, FastAPI
데이터베이스	Supabase, Firebase, Cloudflare D1, AWS DynamoDB, Aurora, Azure Cosmos DB
웹 기술	PWA(서비스 워커, Workbox, 오프라인 우선)
이커머스	Shopify, WooCommerce, Medusa
광고	Reddit Ads API(캠페인, 타기팅, 전환)
협업	Microsoft Teams(봇, AI 에이전트, Adaptive Cards)
마케팅	Klaviyo, PostHog

비교

기능	다른 도구	Claude Bootstrap
테스트	선택, 종종 생략	TDD 필수 - 테스트가 먼저 실패
반복	원샷	테스트 통과까지 루프
버그 수정	바로 수정으로 점프	테스트 공백 분석 → 실패 테스트 → 수정
오류 처리	영원히 루프	오류 분류, 차단 요인에서 중단
보안	거의 다루지 않음	CI 강제로 1급 시민
복잡성	모호한 가이드	하드 제한(함수 20줄, 파일 200줄)

기여

가이드라인은 CONTRIBUTING.md를 참고하세요.

핵심 원칙:

모호한 가이드보다 측정 가능한 제약
동작하는 코드 예시
멱등성(idempotency) 유지
제출 전 로컬 테스트

변경 로그

버전 히스토리와 업데이트는 CHANGELOG.md를 참고하세요.

최신: v2.4.0 - 멀티레포 워크스페이스 인지, 계약 추적, 레포 간 컨텍스트를 포함한 53개 스킬

라이선스

MIT - LICENSE 참고

크레딧

고객 경험 관리, 에이전틱 AI 플랫폼, 모바일 앱, 풀스택 웹 애플리케이션 등 100+ 프로젝트에서 얻은 학습을 기반으로 만들었습니다.

조직에서 AI 확장을 도와드릴까요? Claude Code & MCP 전문가

Claude Bootstrap

Claude Bootstrap

핵심 철학

이것이 존재하는 이유

빠른 시작

클론 및 설치

어떤 프로젝트 디렉터리에서든

자동 반복 루프 (Ralph Wiggum)

Ralph Wiggum 플러그인 설정

공식 마켓플레이스에서 설치 (Claude Code에서)

커밋 위생(자동 PR 크기 관리)

에이전틱 광고 최적화(Reddit Ads)

멀티-레포 워크스페이스 인지

코드 리뷰(필수 가드레일)

팀 조율(여러 명이 함께하는 프로젝트)

코드 중복 제거(의미적 비대화 방지)

Validation(검증)

Date/Time(날짜/시간)

생성되는 것

철학

TDD-우선 개발(필수)

복잡성은 적

보안은 협상의 여지가 없음

중앙화된 자격 증명

AI-우선 아키텍처

스펙 주도 개발

포함된 스킬(53개)

핵심 스킬

언어 & 프레임워크 스킬

UI 스킬

AI & 에이전틱 스킬

데이터베이스 & 백엔드 스킬

콘텐츠 & SEO 스킬

통합 스킬

사용 패턴

새 프로젝트

질문에 답하면 전체 세팅 완료

기존 프로젝트

스킬 업데이트, 기존 설정은 보존

기존 코드베이스(자동 분석!)

기존 코드 자동 감지 → 먼저 분석 실행

표시: 구조, 기술 스택, 가드레일 상태, 컨벤션

질문: "무엇을 해드릴까요?"

1. Claude 스킬만 추가

2. 스킬 + 누락된 가드레일 추가

3. 전체 세팅

4. 분석만 보여주기

단독 분석

변경 없이 언제든 분석 실행

전역 스킬 업데이트

그런 다음 어떤 프로젝트에서든:

최신 스킬을 받음

사전 요구사항

GitHub CLI

Vercel CLI

Supabase CLI

품질 게이트

프리-커밋(로컬)

CI(GitHub Actions)

원자적 Todo

[TODO-042] 가입 폼에 이메일 유효성 검사 추가

승인 기준

테스트 케이스

TDD 실행 로그

[BUG-007] 이메일 검증이 "user@"를 허용함

테스트 공백 분석

TDD 실행 로그

루프에서의 오류 처리

FAQ

이것은 그냥 Claude Code를 쓰는 것과 무엇이 다른가요?

매번 /ralph-loop를 수동으로 실행해야 하나요?

어떤 작업에 루프를 원하지 않으면?

루프가 끝없이 돌면 어떻게 하나요?

기존 프로젝트에서도 동작하나요?

테스트 커버리지는요?

스킬은 어떻게 업데이트하나요?

스킬을 커스터마이즈할 수 있나요?

어떤 언어/프레임워크를 지원하나요?

비교

기여

매번 `/ralph-loop`를 수동으로 실행해야 하나요?