Quickstart (60 seconds)
지원 환경: CLI(Command Line Interface), Claude Desktop, VS Code(Visual Studio Code), Cursor
-
1. Install
pip install clouvel
-
2. Activate (Pro만)
clouvel activate 라이선스키
# Free 사용자는 이 단계 스킵
-
3. Setup (자동 설정)
clouvel setup
# 이 명령 하나로:
- ~/.claude/CLAUDE.md에 can_code 자동 호출 규칙 추가
- claude mcp add clouvel 자동 실행
설정 확인: Claude Code에서
/mcp실행 후 도구 목록에 clouvel이 보이면 연결 완료 -
4. Verify (품질 게이트)
- • PRD 없음 → BLOCK (코딩 차단)
- • PRD 있지만 권장 문서 부족 → WARN (진행 가능, 권장 안내)
- • 모든 문서 완비 → PASS (코딩 시작 가능)
주의(라이선스/잠금): Pro/Team은 라이선스 활성화 후에도 일부 프리미엄 기능(예: install_shovel)이 7일간 잠금될 수 있습니다.
Architecture
Clouvel은 MCP (Model Context Protocol) 서버로 동작하며, Claude Code와 통합되어 문서 기반 개발을 강제합니다.
// System Architecture
동작 원리
MCP 서버 시작
Claude Code가 시작될 때 `.claude.json`에 설정된 Clouvel MCP 서버가 stdio로 실행됩니다.
도구 호출
Claude가 코딩 작업을 시작하기 전 `can_code` 도구를 호출합니다.
문서 검사
로컬 파일 시스템에서 PRD.md, Architecture.md 등 필수 문서 존재 여부를 확인합니다.
결과 반환
문서가 없으면 차단 메시지, 있으면 허용 메시지를 반환합니다.
System Requirements
Runtime
- ✓ Python 3.10+
- ✓ Claude Code CLI (latest)
- ✓ pip / pipx
OS Support
- ✓ Windows 10/11
- ✓ macOS 12+
- ✓ Linux (Ubuntu 20.04+)
Dependencies
# clouvel (free)
mcp>=1.0.0
pydantic>=2.0.0
# clouvel (paid)
mcp>=1.0.0
pydantic>=2.0.0
httpx>=0.25.0
aiofiles>=23.0.0
Installation
# pip
pip install clouvel
# pipx (isolated)
pipx install clouvel
# pip
pip install clouvel
# 라이선스 활성화 (Claude Code에서)
> activate_license 도구 사용
Integration
Clouvel은 다양한 환경에서 사용할 수 있습니다. 각 환경별 설정 방법을 확인하세요.
1 Claude Code
-
어디에 설정함:
터미널에서
claude mcp add명령어 실행 -
무엇을 추가함:
~/.claude.json에 mcpServers 설정 자동 추가 -
어떻게 검증함:
/mcp실행 후 clouvel 도구 목록 확인
# 등록
claude mcp add clouvel
# ~/.claude.json에 추가되는 내용
{
"mcpServers": {
"clouvel": {
"type": "stdio",
"command": "clouvel",
"args": []
}
}
}
2 CLI
- 어디에 설정함: 프로젝트 루트에서 실행
-
무엇을 추가함:
(필요 시) 환경변수/설정 파일에
project_path지정 -
어떻게 검증함:
can_code실행 결과가 BLOCK/PASS로 나뉘는지 확인
3 Claude Desktop
- 어디에 설정함: Claude Desktop 설정의 MCP 서버 등록 영역
- 무엇을 추가함: clouvel stdio MCP 서버 (command/env) 등록
-
어떻게 검증함:
도구 목록에 표시되고
can_code가 호출되는지 확인
// claude_desktop_config.json
{
"mcpServers": {
"clouvel": {
"command": "clouvel",
"args": [],
"env": {
"PROJECT_PATH": "/path/to/project"
}
}
}
}
4 VS Code / Cursor
- 어디에 설정함: 에디터 내 MCP/툴 연결 설정 (확장/설정 파일)
- 무엇을 추가함: clouvel MCP 서버 (command/env) 등록
-
어떻게 검증함:
에디터에서
can_code실행 또는 연결 확인
// .vscode/mcp.json 또는 Cursor 설정
{
"servers": {
"clouvel": {
"command": "clouvel",
"type": "stdio"
}
}
}
5 Antigravity (Google)
Google Antigravity IDE는 VS Code 기반으로 MCP를 네이티브 지원합니다. Gemini와 Claude 모델 모두 사용 가능합니다.
-
설정 파일 위치:
~/.gemini/antigravity/mcp_config.json - UI로 열기: Agent → "..." → MCP Servers → Manage → View raw config
// ~/.gemini/antigravity/mcp_config.json
{
"mcpServers": {
"clouvel": {
"command": "clouvel"
}
}
}
Windows 사용자: Python 전체 경로를 사용해야 할
수 있습니다.
C:\\Users\\사용자명\\AppData\\Local\\Programs\\Python\\Python310\\Scripts\\clouvel.exe
기존 설정이 있는 경우: mcpServers 안에 "clouvel" 블록만 추가하세요. 기존 서버 설정을 덮어쓰지 마세요.
Configuration
Environment Variables
| 변수 | 기본값 | 설명 |
|---|---|---|
| CLOUVEL_DEV_MODE | false | 개발 모드 (라이선스 검증 스킵) |
| CLOUVEL_LICENSE_PATH | ~/.clouvel-license | 라이선스 파일 경로 |
| CLOUVEL_API_URL | https://api.clouvel.dev | API 서버 URL |
DEV_MODE 설정
개발/테스트 시 라이선스 검증을 스킵하려면:
// ~/.claude.json
{
"mcpServers": {
"clouvel": {
"type": "stdio",
"command": "clouvel",
"env": {
"CLOUVEL_DEV_MODE": "1"
}
}
}
}
API Reference: Free Tools
처음 시작할 때 이 4개만 쓰면 됩니다:
start
(온보딩 + PRD 생성),
can_code
(게이트),
get_goal
(목표 리마인드),
get_progress
(진행 확인)
clouvel 패키지에 포함된 무료 도구 (6개)
start
UPDATED v1.9
프로젝트 온보딩 + PRD 자동 생성 (통합 도구)
Parameters
path: str - 프로젝트 루트 경로
project_name: str (optional) - 프로젝트 이름
template: str (optional) - PRD 템플릿 타입 (web-app, api, cli, generic)
layout: str (optional) - 템플릿 레이아웃 (lite, standard, detailed)
guide: bool (optional) - PRD 작성 가이드 표시
init: bool (optional) - docs 폴더 초기화
v1.9 통합된 기능
• get_prd_template → start --template=web-app
• get_prd_guide → start --guide
• init_docs → start --init
Returns
# PRD 없으면 자동 생성
CREATED: PRD 템플릿 생성됨
docs/PRD.md 생성 완료
# PRD 있으면 검증
READY: 코딩 시작 가능
can_code
3단계 품질 게이트 (BLOCK/WARN/PASS)
Parameters
path: str - docs 폴더 경로 (예: "docs" 또는 "/path/to/project/docs")
Returns (3단계)
# BLOCK - 코딩 금지
⛔ BLOCK: 코딩 금지
PRD 없음 또는 acceptance 섹션 누락
# WARN - 진행 가능, 권장 안내
✅ PASS | ⚠️ WARN 2개 | 필수: PRD ✓ | 권장 없음: 아키텍처, 테스트
# PASS - 코딩 시작 가능
✅ PASS | 필수: PRD ✓ | 테스트 3개 | 코딩 시작 가능
검사 항목
- 필수 (BLOCK): PRD 파일, acceptance(완료 기준) 섹션
- 권장 (WARN): 아키텍처, API 스펙, DB 스키마, 검증 계획, 테스트 파일
save_prd
NEW v1.3
PRD 저장
Parameters
path: str - 프로젝트 경로
content: str - PRD 내용
project_name: str (optional) - 프로젝트 이름
project_type: str (optional) - 프로젝트 타입
Returns
# PRD 저장 완료
✅ docs/PRD.md 저장됨
이제 can_code가 PASS됩니다
get_progress
진행 상황 확인
Parameters
project_path: str (optional) - 프로젝트 경로
Returns
## 진행 상황
- 완료: 3/10 태스크
- 현재: "인증 기능 구현"
- 다음: "API 엔드포인트 추가"
get_goal
프로젝트 목표 리마인드
Parameters
project_path: str (optional) - 프로젝트 경로
Returns
## 프로젝트 목표
PRD.md에서 추출한 핵심 목표:
- 바이브코딩 프로세스 강제
- 문서 기반 개발 자동화
plan
NEW v1.3
상세 실행 계획 생성
Parameters
path: str - 프로젝트 루트 경로
task: str - 수행할 작업
goals: list[str] - 달성 목표
Returns
## 상세 실행 계획
### Phase: 준비 → 설계 → 구현 → 검증
| # | 액션 | 담당 | 완료조건 |
매니저 피드백 기반 자동 구성
API Reference: Pro Tools
clouvel Pro 기능 (15개+) - 자동화가 아닌 증강
quick_perspectives
NEW v1.4
코딩 전 3초 관점 체크. 3-4명 매니저가 핵심 질문을 던집니다.
# Parameters
context: str - 무엇을 만들려는지
max_managers: int - 최대 매니저 수 (기본 4)
# Output
## 💡 Quick Perspectives
**👔 PM**: 이게 MVP 스코프인가요?
**🔒 CSO**: 사용자 인증은 어떻게?
💡 관련 과거 결정: auth...
manager
v1.4 Augmentation
8명의 AI 매니저가 답을 주는 대신 질문을 던집니다. 당신이 놓친 관점을 발견하게 도와줍니다.
# 철학: 자동화가 아닌 증강
❌ "인증은 OAuth 쓰세요"
✅ "유저층이 어떻게 되나요? 소셜 로그인? 이메일?"
# 8명의 매니저가 어려운 질문을 던집니다
PM: 스코프, 우선순위, 사용자 가치
CTO: 아키텍처, 트레이드오프, 기술 부채
QA: 엣지 케이스, 실패 모드, 테스팅
CSO: 인증, 권한, 취약점
CDO: UX, 접근성, 디자인 패턴
CMO: 포지셔닝, 경쟁사, GTM
CFO: 비용, 수익화, ROI
Error: 과거 실수, 예방 규칙
# Output Format
## 🤔 당신이 결정할 것들
| 인증 | OAuth / Email / Magic Link | _____ |
record_decision / search_knowledge
NEW v1.4
Knowledge Base: 모든 결정을 기억합니다. 같은 실수 두 번 하지 않기.
# 6개 Knowledge Base 도구
record_decision - 결정 저장
record_location - 중요 코드 위치 저장
search_knowledge - FTS5 전문 검색
get_context - 세션 복구 컨텍스트
init_knowledge - DB 초기화
rebuild_index - 검색 인덱스 재구축
# 저장소
~/.clouvel/knowledge.db (SQLite)
50MB 제한, 30일 이상 데이터 자동 아카이브
ship
NEW v1.2
원클릭으로 테스트 → 검증 → 증거 생성을 실행합니다.
# Parameters
path: str - 프로젝트 루트 경로
feature: str (optional) - 검증할 기능명
steps: ["lint", "typecheck", "test", "build"]
# Returns
PASS | 코딩 시작 가능
[====] 4/4 PASS
lint (120ms), test (450ms)...
# 증거 파일 생성
.claude/evidence/feature_20260121.md
activate_license
Polar.sh에서 구매한 라이선스 키를 활성화합니다.
# Parameters
license_key: str - "CLOUVEL-XXXX-XXXX-XXXX"
# Returns
✓ 라이선스 활성화됨 (Personal, 영구)
check_license
현재 라이선스 상태를 확인합니다.
# Parameters
None
# Returns
티어: Team | 인원: 10명 | 프리미엄 잠금: 7일 남음
install_shovel
Shovel 워크플로우 (24개 슬래시 커맨드)를 설치합니다.
# Parameters
project_path: str (optional) - 설치 경로
force: bool (optional) - 덮어쓰기 여부
# Creates
.claude/commands/ - 24개 슬래시 커맨드
CLAUDE.md - 프로젝트 규칙
scripts/ - Gate 스크립트
sync_commands
최신 Shovel 커맨드로 동기화합니다.
# Parameters
project_path: str (optional)
mode: "merge" | "overwrite" - 동기화 모드
log_error
에러를 ERROR_LOG.md에 기록합니다.
# Parameters
error_type: str - "TypeError", "RuntimeError" 등
message: str - 에러 메시지
context: str (optional) - 발생 컨텍스트
solution: str (optional) - 해결 방법
analyze_error
ERROR_LOG.md를 분석하여 패턴을 찾습니다.
# Returns
가장 빈번한 에러: TypeError (5회)
최근 트렌드: import 관련 에러 증가
get_error_summary
에러 통계 요약을 반환합니다.
총 에러: 12개 | TypeError: 5 | ImportError: 3 | ...
add_prevention_rule
CLAUDE.md에 NEVER/ALWAYS 규칙을 추가합니다.
# Parameters
rule_type: "never" | "always"
rule: str - 규칙 내용
watch_logs
check_logs
로그 감시 설정 및 상태 확인.
# watch_logs
patterns: list[str] - 감시할 패턴
# check_logs
감시 중: ["error", "warning"] | 마지막 확인: 5분 전
setup_auto_recovery
NEW
자동 컨텍스트 복구 기능 설정. 컴팩션 후에도 프로젝트 맥락이 유지됩니다.
# Parameters
project_path: str (optional) - 프로젝트 경로
# Creates
.claude/hooks/PreCompact.ps1 - 상태 저장 훅
.claude/hooks/SessionStart.ps1 - 상태 복구 훅
# How it works
1. PreCompact: 현재 상태를 session-state.json에 저장
2. SessionStart: 저장된 상태를 additionalContext로 주입
API Reference: Team Tools
Team 티어 전용 도구 (10개)
team_invite
이메일로 팀원을 초대합니다.
email: str - 초대할 이메일
role: "member" | "admin" (optional)
team_members
팀원 목록을 조회합니다. (최대 10명)
team_remove
팀원을 제거합니다. (오너 전용)
email: str - 제거할 멤버 이메일
team_settings
C-Level 역할 설정을 조회합니다.
CTO: ON | CDO: ON | CPO: ON | CFO: ON | CMO: ON
team_toggle_role
C-Level 역할을 ON/OFF 합니다.
role: "CTO" | "CDO" | "CPO" | "CFO" | "CMO"
sync_team_errors
로컬 에러 패턴을 팀에 공유합니다.
get_team_rules
apply_team_rules
팀 공유 NEVER/ALWAYS 규칙 조회 및 로컬 적용.
sync_project_context
get_project_context
프로젝트 컨텍스트 (PRD, 파일 구조)를 팀에 업로드/조회.
# sync_project_context
project_path: str (optional)
# get_project_context
project_id: str - 조회할 프로젝트 ID
API Reference: Shovel Commands
install_shovel로 설치되는 24개 슬래시 커맨드
# Core Workflow
/start - 프로젝트 온보딩
/plan - 계획 수립
/implement - 구현 실행
/gate - Gate 검증
/verify - 검증 (Shovel + Boris)
/commit - 커밋 (Gate PASS 필수)
# Quality Checks
/lint - ESLint 검사
/typecheck - TypeScript 검사
/test - 테스트 실행
/build - 프로덕션 빌드
/review - 코드 리뷰
/ssot-check - SSOT 검사
# Error Management
/error-log - 에러 학습
/learn-error - 에러 학습 자동화
/deep-debug - 근본 원인 분석
# Advanced
/sync - 프로젝트 동기화
/interview - 스펙 인터뷰
/design - UI 탈피 가이드
/pm - PM 모드 활성화
/verify-server - 서버 정밀 검증
# Completion
/step-done - Step 완료 시
/handoff - 의도 기록
/check-complete - 미연결 검사
Security Model
- 1. 기본은 로컬 실행 - 모든 문서 검사/게이트 검증은 로컬에서 수행
- 2. 라이선스/팀 기능만 서버 통신 - 코드/문서는 서버로 전송되지 않음
- 3. 전송 데이터는 아래 표 참고 - 최소한의 메타데이터만 전송
Data Privacy
- ✓ 로컬 실행: 모든 문서 검사는 로컬에서 수행됩니다. 코드/문서가 서버로 전송되지 않습니다.
- ✓ 라이선스 검증만: 서버와 통신하는 것은 라이선스 키 검증뿐입니다.
- ✓ Team 컨텍스트: sync_project_context 사용 시에만 PRD 요약, 파일 구조가 서버에 저장됩니다.
네트워크 통신
| 엔드포인트 | 목적 | 전송 데이터 |
|---|---|---|
| /api/validate | 라이선스 검증 | license_key, machine_id |
| /api/team/* | 팀 관리 | license_key, email |
| /api/context/* | 팀 컨텍스트 | PRD 요약, 파일 목록 |
Licensing
activate_license
라이선스 활성화
Polar.sh에서 구매한 라이선스 키를 활성화합니다.
# 입력값
license_key: "CLOUVEL-XXXX-XXXX-XXXX"
# 반환
✓ 라이선스 활성화됨 (Personal, 영구)
check_license
라이선스 상태 확인
현재 라이선스 상태와 잠금 기간을 확인합니다.
티어: Team | 인원: 10명 | 프리미엄 잠금: 7일 남음
검증 흐름
1. activate_license("CLOUVEL-XXXX-XXXX")
↓
2. POST /api/validate {key, machine_id}
↓
3. Server: Polar.sh API 검증
↓
4. Response: {tier, seats, features}
↓
5. Save to ~/.clouvel-license (로컬 캐시)
7일 프리미엄 잠금 정책
왜? 결제 사기 방지 및 정상 사용자 보호를 위해 최초 7일간 일부 기능이 잠깁니다.
무엇이? install_shovel, sync_commands, 에러 관리 도구 (log_error, analyze_error 등)
언제 풀림? 라이선스 활성화 후 7일 경과 시 자동 해제. check_license로 남은 기간 확인 가능.
사용 가능: watch_logs, check_logs는 즉시 사용 가능합니다.
지원 종료 안내 (v1.9)
v1.9에서 52개 도구가 12개 표준 도구(옵션 포함)로 통합됩니다. 지원 종료된 도구는 경고와 함께 동작하며, v2.0에서 제거됩니다.
마이그레이션 가이드
| 지원 종료 도구 | 새 사용법 |
|---|---|
| get_prd_template | start --template=web-app |
| get_prd_guide | start --guide |
| init_docs | start --init |
| list_templates | start --template (사용 가능 목록 표시) |
| init_rules | setup_cli --rules |
| hook_design | setup_cli --hook=design |
| hook_verify | setup_cli --hook=verify |
| quick_ship | ship --quick |
| full_ship | ship --full |
| init_planning | plan --init |
| refresh_goals | plan --refresh |
| update_progress | plan --update |
Changelog
FREE clouvel
- - 도구 통합: 52개 도구 → 12개 표준 도구(옵션 포함)
- - 지원 종료 경고: 기존 도구 경고 표시, v2.0까지 동작
- - 개발자 모드 수정: 동적 회의 기능 개발자 모드에서 동작
- - Manager Worker API: Manager가 로컬 모듈 대신 Worker API 사용
- - 아키텍처 문서: Manager 아키텍처 문서 추가
- - 템플릿 8종: web-app, api, cli, chrome-ext, discord-bot, landing-page, saas, generic (16개 파일)
- - start 개선: 프로젝트 타입 자동 감지 + 대화형 PRD 가이드
- - save_prd: PRD 저장 도구 추가
- - 버전 체크: PyPI 최신 버전 알림 (24시간 캐싱)
- - clouvel setup: 원커맨드 설정 (글로벌 규칙 + MCP 자동 등록)
- - 3단계 품질 게이트: BLOCK / WARN / PASS
- - can_code 자동 호출 메커니즘 (B0)
- - 출력 간소화 (한 줄 요약)
- - 초기 릴리즈
- - can_code, get_progress, get_goal 도구
- - PRD 기반 코딩 게이트
PRO clouvel
- - 도구 통합: 52개 도구 → 12개 표준 도구(옵션 포함)
- - 지원 종료 경고: 기존 도구 경고 표시, v2.0까지 동작
- - 개발자 모드 수정: 동적 회의 기능 개발자 모드에서 동작
- - Manager Worker API: Manager가 로컬 모듈 대신 Worker API 사용
- - 아키텍처 문서: Manager 아키텍처 문서 추가
- - 템플릿 8종: web-app, api, cli, chrome-ext, discord-bot, landing-page, saas, generic
- - start 개선: 프로젝트 타입 자동 감지 + 대화형 PRD 가이드 (5-6개 질문)
- - save_prd: PRD 저장 도구 추가
- - 버전 체크: PyPI 최신 버전 알림 (24시간 캐싱)
- - start: 프로젝트 온보딩 + PRD 자동 생성 (Free)
- - manager: 8명 C-Level 매니저 협업 피드백 (Pro)
- - ship: 원클릭 테스트→검증→증거 생성 (Pro)
- - 컨텍스트 기반 매니저 자동 그룹핑
- - PM/CTO/QA/CDO/CMO/CFO/CSO/Error 8명 매니저
- - clouvel install: MCP 설치 간소화
- - 보안 hook 추가 (민감 파일 커밋 차단)
- - pre-commit hook 자동 설치
- - DEV_MODE 경로 수정
- - 모든 20개 MCP 도구 테스트 완료
- - 랜딩 페이지 인터랙티브 모달 추가
- - Team API 구현 (F7-F10)
- - DEV_MODE 로컬 Shovel 직접 복사
- - C-Level 역할 토글 기능
- - 에러 관리 도구 추가
- - 로그 감시 기능
Roadmap
의사결정 기록, 컨텍스트 복구, 에러 패턴 학습
결정 잠금/해제, 파일 생성 추적
아키텍처 검증, import 규칙 강제
Manager가 로컬 모듈 대신 Worker API 사용
52개 도구 → 12개 표준 도구(옵션 포함), 지원 종료 경고
지원 종료 도구 제거, 분석 대시보드, 팀 기능
SSO 통합, 감사 로그, 온프레미스 배포 옵션