Claude Code는 현재 폴더의 파일들을 읽고 컨텍스트로 활용합니다. 폴더 안에 CLAUDE.md가 있으면 매 작업마다 자동으로 읽어서 고정 지침으로 사용합니다. 이것이 이 가이드의 핵심 개념입니다.
2
Step 2
아이디어를 질문으로 바꾸기
Claude Code를 쓰기 전에, 먼저 claude.ai 대화창에서 아이디어를 구체화합니다.
"이런 거 만들 수 있어?"라고 물어보는 것이 시작입니다.
💡
막연한 아이디어도 괜찮습니다
완벽하게 정리된 기획서가 없어도 됩니다. "이런 게 필요한데 가능할까?"라는 형태로 던져도 됩니다.
📋
번호 붙여서 나열하세요
하고 싶은 것들을 번호로 나열하면 Claude가 각각의 가능 여부와 구현 방법을 정확히 짚어줍니다.
🔍
가능 여부부터 확인하세요
바로 "만들어줘"보다 "이게 구현 가능한지, 어떻게 하면 되는지 설명해줘"가 훨씬 효과적입니다.
실제 대화 예시
나
궁금한 게 있는데,
1. 지금 DB가 전부 흩어진 걸 모으는 스노우플레이크 같은 솔루션 구현 가능 여부
2. 그 DB들을 통합한 환경에서 베이스 환경만 만들어주고
3. 프롬프트를 이용해서 원하는 화면으로 구현이 가능하게끔
4. update/insert 이런 건 안 되지만
5. 화면에 배치된 위젯들을 자기 마음대로 배치할 수 있는 환경
6. 개별 계정마다의 환경으로 구성하는 것
7. 그 구성을 저장해서 공유하는 거
8. 이런 프로젝트가 구현 가능한지, 가능하다면 구현 계획을 상세히 설명해줘
Claude
구현 가능합니다 — 상세 계획 설명
이 프로젝트는 AI-powered Self-Service BI Platform으로, 기술적으로 충분히 구현 가능합니다. 이미 유사한 제품들(Metabase, Superset, Retool)이 각 파트를 따로 구현해놨고, 여기서 하려는 건 그것들을 AI 프롬프트 레이어와 계정별 위젯 시스템으로 통합하는 것입니다.
Phase 1 (MVP, 6~8주): 단일 DB 연결 + 프롬프트로 차트 생성 + 기본 드래그앤드롭 저장 Phase 2 (8~12주): 다중 DB federation + 계정별 레이아웃 + 공유 링크 Phase 3 이후: 위젯 마켓플레이스 + 권한 세분화 + 감사 로그...
핵심 패턴
하고 싶은 것을 번호로 나열하면 Claude가 각 항목의 가능 여부, 기술적 접근법, 난이도를 항목별로 짚어줍니다. 이게 가장 효율적인 첫 대화 방식입니다.
3
Step 3
명세서(Spec) 만들기
아이디어 검토가 끝났으면, 그 대화를 Claude Code가 읽을 수 있는 MD 문서로 변환합니다.
이 문서가 Claude Code의 구현 설계도가 됩니다.
나
이 내용들을 Claude Code가 구현할 수 있게 MD 문서로 작성해볼래?
Claude
문서 생성했습니다. 주요 구성은 다음과 같습니다.
• 전체 아키텍처 다이어그램
• Prisma 스키마 (User, DataSource, Dashboard, Widget, QueryLog)
• AI 서비스 전체 코드 (PromptBuilder, SqlValidator, AiService)
• DB 커넥터 인터페이스 + 구현체
• 프론트엔드 핵심 컴포넌트
• 보안 체크리스트 및 차단 목록
Claude Code에서 이 파일을 프로젝트 루트에 넣고 "이 명세서대로 Phase 1부터 구현해줘"라고 하면 바로 시작합니다.
왜 MD 문서가 필요한가
Claude Code는 대화를 기억하지 않습니다. 매 세션마다 새로 시작합니다. MD 문서가 있으면 "이 파일 읽고 구현해"라고 하면 되고, 팀원이 바뀌거나 나중에 다시 시작해도 동일한 기준으로 이어갈 수 있습니다.
좋은 Spec MD의 구성
아키텍처 개요
전체 시스템 구조와 각 레이어의 역할
기술 스택
프레임워크, DB, 외부 API 명시
데이터 모델
핵심 테이블/스키마 정의
Phase 로드맵
Phase 1/2/3으로 나눈 구현 순서
보안 원칙
절대 하면 안 되는 것들 명시
환경 변수 목록
.env.example 형태로 필요한 키 목록
4
Step 4
CLAUDE.md — 고정 원칙 파일
CLAUDE.md는 Claude Code가 매 작업마다 자동으로 읽는 고정 지침 파일입니다.
"이 프로젝트에서 절대 하지 말아야 할 것"과 "지금 어느 Phase인지"를 여기에 씁니다.
CLAUDE.md가 없으면
Claude Code는 매번 처음 만나는 프로젝트처럼 행동합니다. Phase 1을 짜야 하는데 Phase 4 코드를 먼저 짜거나, 이미 정한 원칙을 잊고 다른 방식으로 구현할 수 있습니다.
CLAUDE.md에 넣어야 할 것들
✓
작업 전 자가 체크 질문 "지금 어느 Phase인가? 이 작업은 현재 범위 안인가?"
✓
절대 원칙 (보안) 읽기 전용 강제, 자격증명 평문 저장 금지, SQL injection 방지
✓
현재 Phase 범위 지금 짜야 할 것 / 나중에 짤 것 명확히 구분
✓
참조할 다른 MD 파일 언제 어떤 파일을 읽어야 하는지 지시
✓
작업 완료 체크리스트 커밋 전 필수 확인 항목들
CLAUDE.md 만드는 법
이 MD를 가지고 구현한다고 했을 때 프롬프트를 작성해줄래? 뭔가 고려사항이나 이런 걸 체크하면서 할 수 있는 고정되는 프롬프트
CLAUDE.md로 만들었습니다. 이 파일명이 중요한데, Claude Code는 프로젝트 루트에 CLAUDE.md가 있으면 매 작업마다 자동으로 읽어서 고정 컨텍스트로 유지합니다.
CLAUDE.md 기본 구조 예시
# CLAUDE.md — 이 파일은 매 작업 시 자동으로 읽힙니다## 작업 전 자가 체크 (매번 확인)1. 현재 작업은 어느 Phase인가?2. 이 작업은 현재 Phase 범위 안인가?3. 생성하는 SQL에 SELECT 외 구문이 없는가?4. 자격증명이 코드에 하드코딩되어 있지 않은가?## 절대 원칙- SELECT만 허용. INSERT/UPDATE/DELETE/DROP 절대 금지- .env 파일은 .gitignore에 반드시 포함- Phase 범위 밖 기능은 주석(TODO)으로만 남길 것## 현재 Phase: Phase 1 MVP포함: 단일 DB 연결, 프롬프트 → 차트, 기본 드래그앤드롭제외: 멀티 DB, 공유 링크, 권한 관리 (Phase 2에서 구현)## 참조 파일- 항상: ai-bi-platform-spec.md (Phase 1~3 구현 명세)- Phase 4 시작 시: ROADMAP.md- 추천 기능 구현 시: org-context-spec.md
5
Step 5
요구사항 점진적으로 추가하기
처음부터 완벽한 기획서를 쓸 필요 없습니다. 대화하면서 생각이 깊어지면,
그 내용을 새로운 MD 파일로 추가하는 방식으로 확장해나갑니다.
나
AI 추천에 대한 거를 사용자들이 팀이나 조직을 설정할 거잖아? 운영자가? 그럼 그거에 맞는 키워드들을 DB에서 추출해서 그 키워드를 가지고 AI가 추천을 해주는 방식으로까지 가면 좋을 것 같아 어때?
Claude
아주 좋은 방향입니다. 이건 단순한 "많이 쓴 것 추천"이 아니라 조직의 언어로 말하는 AI가 되는 거거든요.
키워드를 3가지 소스에서 추출합니다:
1. 스키마 컬럼명 (TB_SALES.sale_amount → 영업 도메인)
2. 쿼리 이력 (팀원들이 자주 쓰는 단어)
3. mapper/서비스 코드 (selectSalesByRegion 같은 메서드명)
이 내용도 spec.md에 추가할까요? 아니면 따로 보는 게 낫나요?
나
고도화 항목들도 구현할 때 한번에 고려해서 구현될 수 있도록 같이 녹여줄 수 있어? 아니면 따로 보는 게 낫나?
Claude
따로 두는 게 낫습니다. spec.md가 지금도 1400줄인데 고도화까지 다 넣으면 2500줄이 넘어요. Claude Code가 Phase 1을 짜고 있는데 Phase 4 코드를 먼저 짜는 혼선이 생깁니다.
대신 CLAUDE.md에 "Phase 4 고도화는 ROADMAP.md 참조, 현재 작업과 연관될 때만 읽어라"고 지시하면 필요할 때만 꺼내보는 구조가 됩니다.
파일 분리 전략
project-root/
├── CLAUDE.md← 항상 읽음 (원칙 + 체크리스트)
├── ai-bi-platform-spec.md← 항상 읽음 (Phase 1~3 구현)
├── ROADMAP.md← Phase 4 시작 시 읽음
└── org-context-spec.md← 추천 기능 구현 시 읽음
핵심 원칙
Claude Code의 집중력을 지키세요. 지금 Phase 1 로그인 기능 짜면서 추천 알고리즘까지 머릿속에 넣으면 혼선이 생깁니다. CLAUDE.md에 "이 파일은 그때 가서 읽어라"고 명시하면, 현재 Phase 작업 중엔 미래 코드를 먼저 짜는 실수가 없어집니다.
6
Step 6
Claude Code 시작 프롬프트
파일이 준비됐으면 어떻게 말을 거느냐가 결과의 질을 결정합니다.
상황별 프롬프트 패턴을 소개합니다.
처음 시작할 때
Phase 1 시작
CLAUDE.md와 ai-bi-platform-spec.md를 읽고,
Phase 1 MVP부터 순서대로 구현해줘.
프로젝트 초기 세팅(패키지 설치,
디렉토리 구조, DB 마이그레이션)부터
시작해.
가장 기본적인 시작 프롬프트. Phase를 명시하는 것이 핵심입니다.
특정 기능 작업할 때
기능 단위 구현
CLAUDE.md와 spec.md를 읽고,
Phase 1의 AI 위젯 생성 기능을 구현해줘.
SqlValidator → AiService → 위젯 API
순서로 진행해.
기능명과 구현 순서까지 명시하면 더 정확하게 작동합니다.
맥락이 끊겼을 때
이어서 계속하기
CLAUDE.md 다시 읽고,
지금까지 구현된 파일들 확인한 다음
이어서 [다음 작업] 진행해줘.
기본 Claude Code 위에 /plugin으로 얹어 쓰는 확장입니다. 사내에는 아래 세 가지를 설치해 두었습니다 —
디버깅·TDD 방법론, 기획–개발–테스트 멀티에이전트 협업, 설계-검증 기반 PDCA.
셋을 함께 켜면 방법론 · 협업 실행 · 설계검증이 상호 보완됩니다.
① 디버깅 · TDD 방법론
superpowers
코딩 에이전트를 규율 있는 엔지니어링 워크플로우(설계→계획→TDD→검증→리뷰)로 이끄는 스킬 모음. 한 방 프롬프트 대신 각 단계를 스킬로 강제해 품질을 올립니다.
· 브레인스토밍(코드 전 설계) · 체계적 디버깅(4단계 근본원인) · TDD(RED-GREEN-REFACTOR 강제) · 계획 수립 · 완료 전 검증 · 코드리뷰
# Claude Code · 공식 마켓플레이스 /plugin install superpowers@claude-plugins-official
② 멀티에이전트 협업 (기획·개발·테스트)
oh-my-claudecode (OMC)
~19개 전문 에이전트에 작업을 자동 위임하는 오케스트레이션 계층. 모델 자동 라우팅(쉬운 건 저렴하게·어려운 건 강하게), 지속 실행 루프, 비용 최적화를 명령 암기 없이.
· 팀 파이프라인(기획→PRD→실행→검증→수정) · Autopilot/Ralph(자율·반복 루프) · UltraQA(테스트 통과까지 QA) · Deep Interview(요구사항 명료화) · 외부 CLI 워커(Codex/Gemini 등)
# 플러그인 (권장) /plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode /plugin install oh-my-claudecode # 또는 npm 전역 설치 npm i -g oh-my-claude-sisyphus@latest
③ 설계-검증 PDCA · 스프린트
bkit (Vibecoding Kit)
Claude Code를 PDCA(Plan-Do-Check-Act) 컨텍스트 엔지니어링 시스템으로. "AI가 만든 코드를 그 코드의 설계 명세와 대조 검증"이 핵심 — 44 스킬·34 전문 에이전트·11 품질 게이트, 설계 어긋나면 자동 재수정.
· PDCA 기능 사이클(설계↔구현 갭 검증) · 스프린트 관리(컨텍스트 예산·세션 복원) · 전문 에이전트(pm/cto/qa/gap-detector) · Trust 레벨 자율성 다이얼(/control)
# Claude Code (README 기준) claude plugin install bkit # 팀 병렬 실행 활성화(선택) export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
각 확장이 실제로 해주는 것
🧠 superpowers — "코딩 전에 올바른 순서를 밟게 한다"
Claude가 곧장 코드를 뱉는 대신, 상황에 맞는 작업 방식(스킬)을 자동으로 꺼내 쓰게 만듭니다. 요청 한 줄에 바로 구현하던 걸, 시니어 엔지니어의 절차로 바꿉니다.
· 새 기능 요청 → 바로 구현하지 않고 브레인스토밍(요구·설계를 먼저 질문)
· 버그·이상동작 → 추측 금지, 체계적 디버깅(근본원인 4단계 후에만 수정)
· 구현 → TDD: 실패하는 테스트 먼저 → 통과 코드 → 리팩터(RED-GREEN-REFACTOR)
· 큰 작업 → 계획서로 잘게 쪼개고, 서브에이전트 병렬 실행 + git worktree로 작업 격리
· "다 됐다" 선언 전 → 실제 실행으로 검증(증거 없이 완료 주장 금지) + 코드리뷰
→ "그럴듯하지만 틀린" 결과를 줄이고, 규율 있는 개발 흐름을 강제합니다.
🤝 oh-my-claudecode — "혼자가 아니라 팀처럼 굴린다"
하나의 요청을 여러 전문 에이전트에 나눠 기획→PRD→구현→검증→수정 파이프라인으로 자동 진행합니다. 명령을 외울 필요 없이 큰 작업을 오케스트레이션합니다.
· 모델 자동 라우팅 — 단순 단계는 저렴·빠른 모델, 어려운 단계는 강한 모델로(비용·속도 최적)
· Autopilot(끝까지 자율 실행) / Ralph(될 때까지 검증-수정 반복 루프)
· UltraQA(테스트 통과할 때까지 QA 사이클) / Ultrawork(대량 병렬 처리)
· Deep Interview — 모호한 요구사항을 먼저 소크라테스식으로 명료화
· 외부 CLI(Codex·Gemini 등)도 워커로 붙여 협업
→ "무엇을·어떻게" 신경 안 써도 자동으로 팀 단위 실행이 굴러갑니다.
📐 bkit — "만든 코드가 설계대로인지 스스로 검증한다"
기능마다 PDCA(Plan-Do-Check-Act) 사이클을 돌려, AI가 만든 코드를 그 코드의 설계 명세와 대조 검증하고 어긋나면 자동으로 다시 고칩니다.
· PDCA 사이클 — Plan(기획)→Design(설계)→Do(구현)→Check(설계↔구현 갭 검사)→Act(자동 재수정, 최대 5회·90% 일치까지)
· 스프린트 관리 — 컨텍스트 예산(≤75K 토큰) 단위로 쪼개 세션이 끊겨도 이어감, 다기능 릴리스는 위상정렬
· 34개 전문 에이전트(pm·cto·gap-detector·qa 등) + 11개 품질 게이트(설계 일치율·중대이슈·데이터흐름 무결성)
· Trust 레벨(/control, L0~L4)로 자동화 강도 조절
→ "AI가 대충 만들고 넘어가는" 걸 게이트로 막고, 설계 준수를 수치로 측정합니다.
Claude에게 설치를 요청하는 문구
슬래시 명령을 외우지 않아도, Claude Code에게 아래처럼 말하면 설치 명령을 대신 실행하거나 정확한 절차를 안내해 줍니다. 그대로 붙여넣어 쓰세요.
# superpowers 설치 요청 superpowers 플러그인 설치해줘. 공식 마켓플레이스(claude-plugins-official)에 있어.
# bkit 설치 요청 bkit 플러그인 설치해줘 (claude plugin install bkit). Claude Code 버전이 2.1.143 미만이면 먼저 업그레이드하고 진행해줘.
# 설치 후 확인 지금 설치된 플러그인 목록 보여줘.
직접 실행할 때는 위 카드의 /plugin 명령을 그대로 입력하면 됩니다.
설치 후 확인
/plugin으로 목록·관리하고, 각 도구의 대표 명령으로 동작을 확인합니다 —
superpowers는 브레인스토밍/TDD 스킬이 자동 발동, OMC는 /omc-setup, bkit은 /bkit.
bkit은 Claude Code v2.1.143+가 필요합니다(npm i -g @anthropic-ai/claude-code@latest로 업그레이드).
전체 흐름 요약
아이디어 → 제품까지의 여정
💬
claude.ai에서
아이디어 구체화 가능 여부 검토
→
📄
Spec MD 생성
구현 명세서 Phase 로드맵
→
📌
CLAUDE.md 작성
원칙 · 체크리스트 Phase 범위
→
⚡
Claude Code 실행
Phase 1부터 순서대로 구현
→
🔄
대화하며 확장
요구사항 추가 파일 분리 확장
가장 중요한 것
처음부터 완벽한 기획서를 쓰려 하지 마세요. claude.ai에서 대화로 구체화 → MD로 정리 → Claude Code로 구현하는 사이클을 반복하면서 점점 쌓아나가는 것이 핵심입니다. 이 가이드에서 소개한 AI BI 플랫폼도 "이런 거 가능해?" 한 마디에서 시작했습니다.