Quickstart (60 seconds)

지원 환경: CLI(Command Line Interface), Claude Desktop, VS Code(Visual Studio Code), Cursor

CLI Claude Desktop VS Code Cursor

1. Install

pip install clouvel
2. Activate (Pro만)

clouvel activate LICENSE_KEY

# Free users skip this step
3. Setup (auto config)

clouvel setup

# 이 명령 하나로:

- ~/.claude/CLAUDE.md에 can_code 자동 호출 규칙 추가

- claude mcp add clouvel 자동 실행

Verify config: Claude Code에서 /mcp 실행 후 도구 목록에 clouvel이 보이면 연결 완료
4. Verify (품질 게이트)
- • No PRD → BLOCK (코딩 차단)
- • PRD exists but missing recommended docs → WARN (진행 가능, 권장 안내)
- • All docs ready → PASS (Start coding 가능)

Note (License): Pro/Team은 License activation 후에도 some premium features(예: install_shovel)이 7일간 잠금될 수 있습니다.

Architecture

Clouvel은 MCP (Model Context Protocol) 서버로 동작하며, Claude Code와 통합되어 docs-first development을 강제합니다.

// System Architecture

Claude Code

CLI / IDE

→

Clouvel MCP

stdio server

→

Local Files

docs/, PRD.md

Pro/Team:

License Server

api.clouvel.dev

동작 원리

1

MCP Server Start

Claude Code가 시작될 때 `.claude.json`에 설정된 Clouvel MCP 서버가 stdio로 실행됩니다.

2

도구 호출

Claude가 코딩 작업을 시작하기 전 `can_code` 도구를 호출합니다.

3

Document check

로컬 파일 시스템에서 PRD.md, Architecture.md 등 required docs 존재 여부를 확인합니다.

4

결과 반환

문서가 없으면 block message, 있으면 allow message를 반환합니다.

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

FREE clouvel

# pip

pip install clouvel

# pipx (isolated)

pipx install clouvel

PRO clouvel

# pip

pip install clouvel

# License activation (Claude Code에서)

> activate_license 도구 사용

Integration

Clouvel은 works in various environments. Setup guide for each environment을 확인하세요.

1 Claude Code

Where to configure: 터미널에서 claude mcp add 명령어 실행
무엇을 추가함: ~/.claude.json에 mcpServers 설정 자동 추가
어떻게 검증함: /mcp 실행 후 clouvel 도구 목록 확인

# 등록

claude mcp add clouvel

# ~/.claude.json에 추가되는 내용

{

"mcpServers": {

"clouvel": {

"type": "stdio",

"command": "clouvel",

"args": []

}

2 CLI

Where to configure: 프로젝트 루트에서 실행
무엇을 추가함: (필요 시) 환경변수/설정 파일에 project_path 지정
어떻게 검증함: can_code 실행 결과가 BLOCK/PASS로 나뉘는지 확인

3 Claude Desktop

Where to configure: 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

Where to configure: 에디터 내 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 모델 모두 available합니다.

설정 파일 위치: ~/.gemini/antigravity/mcp_config.json
UI로 열기: Agent → "..." → MCP Servers → Manage → View raw config

// ~/.gemini/antigravity/mcp_config.json

{

"mcpServers": {

"clouvel": {

"command": "clouvel"

}

Windows users: may need full Python path 수 있습니다. C:\\Users\\username\\AppData\\Local\\Programs\\Python\\Python310\\Scripts\\clouvel.exe

If existing config exists: mcpServers 안에 "clouvel" 블록만 추가하세요. Do not overwrite existing server config.

Configuration

Environment Variables

변수	기본값	Description
CLOUVEL_DEV_MODE	false	dev mode (license validation 스킵)
CLOUVEL_LICENSE_PATH	~/.clouvel-license	license file path
CLOUVEL_API_URL	https://api.clouvel.dev	API 서버 URL

DEV_MODE 설정

개발/tests 시 license validation을 스킵하려면:

// ~/.claude.json

{

"mcpServers": {

"clouvel": {

"type": "stdio",

"command": "clouvel",

"env": {

"CLOUVEL_DEV_MODE": "1"

}

API Reference: Free Tools

Start with these 4 tools: 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: Start coding 가능

can_code 3단계 품질 게이트 (BLOCK/WARN/PASS)

Parameters

path: str - docs 폴더 경로 (예: "docs" 또는 "/path/to/project/docs")

Returns (3단계)

# BLOCK - 코딩 금지

⛔ BLOCK: 코딩 금지

No PRD 또는 acceptance 섹션 누락

# WARN - 진행 가능, 권장 안내

✅ PASS | ⚠️ WARN 2개 | Required: PRD ✓ | 권장 없음: 아키텍처, tests

# PASS - Start coding 가능

✅ PASS | Required: PRD ✓ | tests 3개 | Start coding 가능

검사 항목

필수 (BLOCK): PRD 파일, acceptance(완료 기준) 섹션
권장 (WARN): 아키텍처, API 스펙, DB 스키마, 검증 계획, tests 파일

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 태스크

- 현재: "Implement auth feature"

- 다음: "API 엔드포인트 추가"

get_goal 프로젝트 목표 리마인드

Parameters

project_path: str (optional) - 프로젝트 경로

Returns

## 프로젝트 목표

PRD.md에서 추출한 핵심 목표:

- 바이브코딩 프로세스 강제

- docs-first development 자동화

plan NEW v1.3 상세 실행 계획 생성

Parameters

path: str - 프로젝트 루트 경로

task: str - 수행할 작업

goals: list[str] - 달성 목표

Returns

## 상세 실행 계획

### Phase: 준비 → 설계 → 구현 → 검증

| # | 액션 | 담당 | 완료조건 |

매니저 피드백 기반 자동 구성

API Reference: Pro Tools

clouvel Pro features (15+ tools) - Augmentation, not Automation

quick_perspectives NEW v1.4

코딩 전 3초 관점 체크. 3-4명 매니저가 핵심 질문을 던집니다.

# Parameters

context: str - 무엇을 만들려는지

max_managers: int - 최대 매니저 수 (기본 4)

# Output

## 💡 Quick Perspectives

**👔 PM**: Is this MVP scope?

**🔒 CSO**: How do you verify the user?

💡 Related past decision: auth...

manager v1.4 Augmentation

8명의 AI 매니저가 답을 주는 대신 질문을 던집니다. 당신이 놓친 관점을 발견하게 도와줍니다.

# Philosophy: Augmentation, not Automation

❌ "Use OAuth for auth"

✅ "What's your user base? Social login or email?"

# 8 Managers ask tough questions

PM: Scope, priorities, user value

CTO: Architecture, tradeoffs, tech debt

QA: Edge cases, failure modes, testing

CSO: Auth, permissions, vulnerabilities

CDO: UX, accessibility, design patterns

CMO: Positioning, competition, GTM

CFO: Costs, monetization, ROI

Error: Past mistakes, prevention rules

# Output Format

## 🤔 Decisions for YOU

| Auth | OAuth / Email / Magic Link | _____ |

record_decision / search_knowledge NEW v1.4

Knowledge Base: 모든 결정을 기억합니다. 같은 실수 두 번 하지 않기.

# 6 Knowledge Base Tools

record_decision - 결정 저장

record_location - 중요 코드 위치 저장

search_knowledge - FTS5 전문 검색

get_context - 세션 복구 컨텍스트

init_knowledge - DB 초기화

rebuild_index - 검색 인덱스 재구축

# Storage

~/.clouvel/knowledge.db (SQLite)

50MB limit, auto-archive 30+ day data

ship NEW v1.2

원클릭으로 tests → 검증 → 증거 생성을 실행합니다.

# Parameters

path: str - 프로젝트 루트 경로

feature: str (optional) - feature to verify

steps: ["lint", "typecheck", "test", "build"]

# Returns

PASS | Start coding 가능

[====] 4/4 PASS

lint (120ms), test (450ms)...

# 증거 파일 생성

.claude/evidence/feature_20260121.md

activate_license

Activate license key purchased from Polar.sh.

# Parameters

license_key: str - "CLOUVEL-XXXX-XXXX-XXXX"

# Returns

✓ License activation됨 (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 - tests 실행

/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. 기본은 로컬 실행 - 모든 Document check/게이트 검증은 로컬에서 수행
2. 라이선스/팀 기능만 서버 통신 - 코드/문서는 서버로 전송되지 않음
3. 전송 데이터는 아래 표 참고 - 최소한의 메타데이터만 전송

Data Privacy

✓ 로컬 실행: 모든 Document check는 로컬에서 수행됩니다. 코드/문서가 서버로 전송되지 않습니다.
✓ license validation만: 서버와 통신하는 것은 라이선스 키 검증뿐입니다.
✓ Team 컨텍스트: sync_project_context 사용 시에만 PRD 요약, 파일 구조가 서버에 저장됩니다.

네트워크 통신

엔드포인트	목적	전송 데이터
/api/validate	license validation	license_key, machine_id
/api/team/*	팀 관리	license_key, email
/api/context/*	팀 컨텍스트	PRD 요약, 파일 목록

Licensing

`activate_license` License activation

Activate license key purchased from Polar.sh.

# 입력값

license_key: "CLOUVEL-XXXX-XXXX-XXXX"

# 반환

✓ License activation됨 (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 등)

언제 풀림? License activation 후 7일 경과 시 자동 해제. check_license로 남은 기간 확인 가능.

available: watch_logs, check_logs는 즉시 사용 가능합니다.

Deprecation Notice (v1.9)

WARNING Tool Consolidation in v1.9

v1.9 consolidates 52 tools into 12 standard tools with options. Deprecated tools still work but show warnings. They will be removed in v2.0.

Migration Guide

Deprecated Tool	New Usage
get_prd_template	start --template=web-app
get_prd_guide	start --guide
init_docs	start --init
list_templates	start --template (shows available)
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

v1.9.0 2026-01-26 Latest

- Tool Consolidation: 52 tools → 12 standard tools with options
- Deprecation Warnings: Old tools show warnings, work until v2.0
- Developer Mode Fix: Dynamic meeting works in dev mode

v1.8.0 2026-01-25

- Manager Worker API: Manager uses Worker API instead of local module
- Architecture Documentation: Added manager architecture docs

v1.3.4 2026-01-22

- 8 Templates: web-app, api, cli, chrome-ext, discord-bot, landing-page, saas, generic
- start improvements: Auto-detect project type + interactive PRD guide
- save_prd: PRD save tool added
- Version check: PyPI latest version notification (24h cache)

v0.6.1 2026-01-18

- clouvel setup: 원커맨드 설정 (글로벌 규칙 + MCP 자동 등록)
- 3단계 품질 게이트: BLOCK / WARN / PASS
- can_code 자동 호출 메커니즘 (B0)
- 출력 간소화 (한 줄 요약)

v0.5.0 2026-01-17

- 초기 릴리즈
- can_code, get_progress, get_goal 도구
- PRD 기반 코딩 게이트

PRO clouvel

v1.9.0 2026-01-26 Latest

- Tool Consolidation: 52 tools → 12 standard tools with options
- Deprecation Warnings: Old tools show warnings, work until v2.0
- Developer Mode Fix: Dynamic meeting works in dev mode

v1.8.0 2026-01-25

- Manager Worker API: Manager uses Worker API instead of local module
- Architecture Documentation: Added manager architecture docs

v1.3.4 2026-01-22

- 8 Templates: web-app, api, cli, chrome-ext, discord-bot, landing-page, saas, generic
- start improvements: Auto-detect project type + interactive PRD guide
- save_prd: PRD save tool added
- Version check: PyPI latest version notification (24h cache)

v1.2.0 2026-01-21

- start: 프로젝트 온보딩 + PRD 자동 생성 (Free)
- manager: 8명 C-Level 매니저 협업 피드백 (Pro)
- ship: 원클릭 tests→검증→증거 생성 (Pro)
- 컨텍스트 기반 매니저 자동 그룹핑
- PM/CTO/QA/CDO/CMO/CFO/CSO/Error 8명 매니저

v1.1.0 2026-01-19

- clouvel install: MCP 설치 간소화
- 보안 hook 추가 (민감 파일 커밋 차단)
- pre-commit hook 자동 설치

v1.4.2 2026-01-18

- DEV_MODE 경로 수정
- 모든 20개 MCP 도구 tests 완료
- 랜딩 페이지 인터랙티브 모달 추가

v1.4.0 2026-01-17

- Team API 구현 (F7-F10)
- DEV_MODE 로컬 Shovel 직접 복사
- C-Level 역할 토글 기능

v1.3.0 2026-01-15

- 에러 관리 도구 추가
- 로그 감시 기능

Roadmap

DONE v1.4 - Knowledge Base + Error Learning

Decision recording, context recovery, error pattern learning

DONE v1.6 - Locked Decisions + File Tracking

Decision lock/unlock, file creation tracking

DONE v1.7 - Architecture Guard

Architecture validation, import rules enforcement

DONE v1.8 - Manager Worker API

Manager uses Worker API instead of local module

DONE v1.9 - Tool Consolidation

52 tools → 12 standard tools with options, deprecation warnings

NEXT v2.0 - Major Release

Remove deprecated tools, analytics dashboard, team features

PLANNED v2.1 - Enterprise

SSO integration, audit logs, on-premise deployment

Quickstart (60 seconds)

Architecture

동작 원리

System Requirements

Runtime

OS Support

Dependencies

Installation

Integration

1 Claude Code

2 CLI

3 Claude Desktop

4 VS Code / Cursor

5 Antigravity (Google)

Configuration

Environment Variables

DEV_MODE 설정

API Reference: Free Tools

API Reference: Pro Tools

API Reference: Team Tools

API Reference: Shovel Commands

Security Model

Data Privacy

네트워크 통신

Licensing

activate_license License activation

check_license 라이선스 상태 확인

검증 흐름

7일 프리미엄 잠금 정책

Deprecation Notice (v1.9)

Migration Guide

Changelog

FREE clouvel

PRO clouvel

Roadmap

`activate_license` License activation

`check_license` 라이선스 상태 확인