빠른 시작 (60초)

Claude Code Claude Desktop VS Code Cursor

  1. 1. 설치

    pip install clouvel

  2. 2. Claude Code에 추가

    clouvel setup

    # 이 명령 하나로:

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

    - claude mcp add clouvel 자동 실행

  3. 3. 코딩 시작

    # Claude Code가 코드 작성 전 자동으로 can_code 호출

    PRD 없음 → BLOCK (코딩 차단)

    PRD 있음 → PASS (코딩 시작)

Pro 사용자: 구매 후 Claude Code에서 activate_license 실행하면 Pro 도구 10개가 추가 해제됩니다.

아키텍처

Clouvel은 MCP (Model Context Protocol) 서버입니다. Claude Code에 에러 메모리, 스펙 게이트, 맹점 탐지 도구를 제공합니다.

// System Architecture

Claude Code
CLI / IDE
→
Clouvel MCP
stdio server
→
Local Files
.claude/, docs/
Pro만:
License Server
Polar.sh 검증

동작 원리

1

MCP 서버 시작

Claude Code 시작 시 Clouvel MCP 서버가 stdio로 실행됩니다.

2

도구 호출

코딩 전 Claude가 can_code를 호출하여 스펙을 확인합니다.

3

문서 검사

로컬 파일 시스템에서 PRD.md와 필수 문서 존재 여부를 확인합니다.

4

결과 반환

BLOCK (문서 없음), WARN (일부 부족), PASS (코딩 가능)을 반환합니다.

시스템 요구사항

Runtime

  • ✓ Python 3.10+
  • ✓ Claude Code CLI (latest)
  • ✓ pip / pipx

OS 지원

  • ✓ Windows 10/11
  • ✓ macOS 12+
  • ✓ Linux (Ubuntu 20.04+)

의존성

# clouvel

mcp>=1.0.0

pydantic>=2.0.0

설치

모든 사용자 하나의 패키지

# pip

pip install clouvel

# pipx (격리 설치)

pipx install clouvel

Free 사용자는 즉시 도구 10개 사용 가능. Pro 사용자는 activate_license로 10개 추가 해제.

연동

1 Claude Code

# 등록

claude mcp add clouvel

# 확인

/mcp

# ~/.claude.json 결과

{

"mcpServers": {

"clouvel": {

"type": "stdio",

"command": "clouvel",

"args": []

}

}

}

2 Claude Desktop

// claude_desktop_config.json

{

"mcpServers": {

"clouvel": {

"command": "clouvel",

"args": [],

"env": {

"PROJECT_PATH": "/path/to/project"

}

}

}

}

3 VS Code / Cursor

// .vscode/mcp.json 또는 Cursor 설정

{

"servers": {

"clouvel": {

"command": "clouvel",

"type": "stdio"

}

}

}

환경 설정

환경 변수

변수 기본값 설명
CLOUVEL_DEV_MODE false 개발 모드 (라이선스 검증 스킵)
CLOUVEL_LICENSE_PATH ~/.clouvel-license 라이선스 파일 경로

API 레퍼런스: Free 도구 (10개)

항상 사용 가능. 라이선스 불필요.

can_code 스펙 게이트 (BLOCK / WARN / PASS)

코딩 전 필수 문서 존재 여부 확인. 코드 작성 전 반드시 호출.

# 파라미터

path: str - docs 폴더 경로

# 반환

BLOCK - PRD 없음, 코딩 차단

WARN - PRD 있지만 권장 문서 부족

PASS - 모든 문서 준비됨, 코딩 시작

출력 예시

Status: BLOCK

docs/ 에서 PRD를 찾을 수 없음

확인: docs/PRD.md, docs/prd.md, docs/requirements.md

조치: PRD를 먼저 작성하세요.

실행: start(path="/your/project", init=true)

start 프로젝트 온보딩 + PRD 생성

프로젝트 타입 자동 감지, PRD 템플릿 생성. --template, --guide, --init 옵션 포함.

# 파라미터

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

template: str (선택) - web-app, api, cli, generic

layout: str (선택) - lite, standard, detailed

guide: bool (선택) - PRD 작성 가이드 표시

init: bool (선택) - docs 폴더 초기화

save_prd PRD 저장

Claude와의 대화를 통해 작성된 PRD를 저장합니다.

# 파라미터

path: str - 프로젝트 경로

content: str - PRD 내용 (마크다운)

error_check 선제적 에러 경고

코드 수정 전 과거 에러 패턴을 확인합니다. 비슷한 실수가 있었다면 경고.

# 파라미터

path: str - 프로젝트 루트

context: str - 현재 작업 컨텍스트

file_path: str (선택) - 수정할 파일

error_record 5 Whys 에러 기록

에러를 구조화된 근본 원인 분석과 함께 기록합니다. 예방 규칙 자동 생성.

# 파라미터

path: str - 프로젝트 루트

error_text: str - 에러 메시지

root_cause: str (선택) - 근본 원인

five_whys: list (선택) - 5 Whys 분석

context_save 컨텍스트 체크포인트

컨텍스트 압축 전 작업 상태를 저장합니다. 한 번 호출로 복구에 필요한 모든 것을 캡처.

# 파라미터

path: str - 프로젝트 루트

reason: str (선택) - 저장 이유

active_files: list (선택) - 작업 중인 파일

context_load 컨텍스트 복원

압축 후 또는 새 세션에서 체크포인트를 로드합니다.

# 파라미터

path: str - 프로젝트 루트

checkpoint: str (선택) - "latest" 또는 특정 파일명

quick_perspectives 빠른 맹점 체크

3~4명 매니저가 10초 안에 핵심 질문. 코딩 전 맹점을 발견합니다.

# 파라미터

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

max_managers: int (선택) - 최대 4

gate lint → test → build 자동화

순차 품질 게이트. 첫 실패에서 중단.

# 파라미터

path: str - 프로젝트 루트

steps: list (선택) - ["lint", "test", "build"]

fix: bool (선택) - 린트 에러 자동 수정

license_status 라이선스 관리

라이선스 상태 확인, 활성화, 무료 체험 시작.

# 파라미터

license_key: str (선택) - 활성화용

action: str (선택) - "trial"로 7일 무료 체험

API 레퍼런스: Pro 도구 (10개)

Pro 라이선스 필요 ($7.99/월 또는 $49/년). 7일 무료 체험 가능.

Pro가 제공하는 것

✓ 같은 버그 반복 방지 — 회귀 메모리가 세션 간 패턴을 감지하여 같은 실수가 두 번 배포되지 않음
✓ 증거와 함께 배포 — 원클릭 lint → test → build 파이프라인이 매 릴리스마다 증거 파일 생성
✓ 코딩 전 맹점 발견 — 8명의 AI 매니저(CTO, QA, CSO…)가 계획을 리뷰하고 놓친 리스크 발견
✓ 사라지지 않는 컨텍스트 — 결정, 코드 위치, 에러 패턴이 모든 세션과 프로젝트에 걸쳐 영구 유지
error_learn 에러 패턴 학습

에러 히스토리 분석, NEVER/ALWAYS 규칙 생성, CLAUDE.md 자동 업데이트.

# 파라미터

path: str - 프로젝트 루트

auto_update_claude_md: bool (선택)

출력 예시

# 에러 학습 분석

패턴 분석:

  import_error   3회   학습 필요

  null_check     2회   관찰 중

CLAUDE.md 업데이트:

  + NEVER: 삭제된 모듈에서 import

  + ALWAYS: 쿼리 결과 사용 전 검증

학습: 규칙 2개 · 분석: 에러 5개

memory_status 회귀 메모리 통계

활성 메모리, 히트 수, 절약률, 상위 에러 패턴을 표시합니다.

memory_search 회귀 메모리 검색

근본 원인, 예방 규칙, 작업 설명에 대한 전문 검색.

# 파라미터

path: str - 프로젝트 루트

query: str - 검색 키워드

memory_global_search 크로스 프로젝트 메모리

모든 프로젝트에서 학습한 패턴을 검색합니다. 프로젝트 A의 실수가 프로젝트 B에서 반복되지 않게.

drift_check 컨텍스트 드리프트 감지

현재 작업이 원래 목표에서 벗어나는지 감지합니다. 최근 액션과 계획을 비교.

record_decision 의사결정 기록

세션을 넘어 의사결정을 보존합니다. 잠금(lock)으로 변경 방지 가능.

# 파라미터

category: str - architecture, pricing, security 등

decision: str - 결정 내용

reasoning: str (선택) - 이유

locked: bool (선택) - 변경 방지

search_knowledge 지식 베이스 검색

과거 의사결정, 코드 위치, 컨텍스트를 검색합니다. FTS5 전문 검색.

plan 실행 계획 생성

단계별 액션 아이템, 의존성, 검증 포인트가 포함된 상세 실행 계획을 생성합니다.

# 파라미터

path: str - 프로젝트 루트

task: str - 수행할 작업

goals: list (선택) - 달성 목표

meeting C-Level 회의 시뮬레이션

8명 AI 매니저 (PM, CTO, QA, CSO, CDO, CMO, CFO, Error)가 어려운 질문을 던집니다. 답을 주지 않고 맹점을 드러냅니다.

# 파라미터

context: str - 회의 주제/상황

topic: str (선택) - auth, api, payment, ui 등

managers: list (선택) - 특정 매니저 지정

출력 예시

# C-Level 회의: 인증 시스템

토픽: auth · 매니저: PM, CTO, CSO, QA

PM: "토큰이 세션 중에 만료되면?"

CTO: "비밀번호 해싱 bcrypt? argon2?"

CSO: "로그인 레이트 리밋? 무차별 대입 1순위."

QA: "엣지 케이스: 두 기기 동시 로그인?"

매니저 4명 · 맹점 8개 발견

ship 원클릭 검증 + 증거

lint → typecheck → test → build 순차 실행. 성공 시 증거 파일 생성.

# 파라미터

path: str - 프로젝트 루트

feature: str (선택) - 검증할 기능

steps: list (선택) - ["lint", "typecheck", "test", "build"]

auto_fix: bool (선택) - 린트 에러 수정

예시: 생성된 증거 파일

# .claude/evidence/auth-refactor_20260215_143012.md

## Ship 증거

프로젝트: my-app   기능: auth-refactor   날짜: 2026-02-15 14:30:12

Lint✓ PASS0 errors, 0 warnings
Typecheck✓ PASSmypy clean
Test✓ PASS42 passed, 0 failed
Build✓ PASSdist/ 생성 완료

결론: 배포 가능.

보안 모델

  • 1. 로컬 실행 - 모든 문서 검사와 게이트가 로컬에서 실행
  • 2. 라이선스만 - 라이선스 검증만 서버 통신
  • 3. 코드 업로드 없음 - 코드와 문서가 절대 외부로 전송되지 않음

데이터 프라이버시

  • ✓ 로컬 실행: 모든 검사가 사용자 머신에서 실행됩니다. 코드나 문서가 서버로 전송되지 않습니다.
  • ✓ 라이선스만: 서버 통신은 라이선스 키 검증에 한정됩니다.
  • ✓ 활성화 후 오프라인: Pro 라이선스 활성화에 인터넷이 한 번만 필요합니다. 이후 완전 오프라인 동작.

네트워크 통신

엔드포인트 목적 전송 데이터
/api/validate 라이선스 검증 license_key, machine_id

machine_id란?

  • • 하드웨어 핑거프린트(CPU, 호스트명, OS)의 SHA-256 해시. 역추적 불가능.
  • • 라이선스를 하나의 기기에 바인딩하는 용도로만 사용.
  • • 개인정보 없음 — IP, 사용자명, 파일 경로 미포함.
  • • 기기 변경? 24~48시간 내 자동 리셋. 즉시 리셋은 GitHub Issues로 문의.

라이선스

Free vs Pro

Free Pro
가격 $0 영원히 $7.99/월 또는 $49/년
도구 10개 10 + 10 = 20개
에러 메모리 기록 + 체크 + 학습 + 검색 + 크로스 프로젝트
매니저 리뷰 Quick Perspectives + 전체 회의 (8명 매니저)
체험 - 7일 무료, 카드 불필요

활성화 흐름

1. polar.sh/clouvel에서 구매

↓

2. Claude Code에서: activate_license YOUR_KEY

↓

3. 서버가 Polar.sh API로 검증

↓

4. 라이선스 로컬 캐시 (~/.clouvel-license)

↓

5. Pro 도구 10개 해제. 오프라인 동작.

무료 체험

모든 20개 도구를 7일간 무료 체험. 카드 불필요.

# Claude Code에서

license_status action="trial"

문제 해결

자주 발생하는 문제와 해결 방법입니다.

• clouvel: command not found

pip install 후 clouvel 명령어가 PATH에 없는 경우입니다.

# Windows - Python 모듈 구문 사용

py -m clouvel install

# Mac/Linux - python3 사용

python3 -m clouvel install

# 또는 pipx로 설치 (자동으로 PATH에 추가)

pipx install clouvel

• claude mcp add clouvel 실패

Claude Code가 Clouvel 실행 파일을 찾지 못하는 경우입니다.

# 1. clouvel 설치 위치 확인

pip show clouvel

# 2. 전체 경로로 등록

claude mcp add clouvel -- py -m clouvel

# 3. 등록 확인

claude mcp list

• Python 버전 오류

Clouvel은 Python 3.10 이상이 필요합니다.

# Python 버전 확인

python --version

# 3.10 미만이면 Python 업그레이드 필요

• Pro 라이선스 활성화 실패

라이선스 검증 서버에 연결할 수 없거나 키가 유효하지 않은 경우입니다.

# 1. 인터넷 연결 확인

# 2. 라이선스 키 확인 (Polar.sh 이메일)

# 3. 다시 시도

activate_license YOUR_KEY

# 계속 실패? GitHub Issue에 키와 함께 문의

• Windows 경로 문제

Windows 경로의 백슬래시가 문제를 일으킬 수 있습니다.

# 경로 인자에 슬래시 사용

can_code path="D:/myproject/docs"

# 또는 이스케이프 사용

can_code path="D:\\myproject\\docs"

• can_code가 항상 BLOCK을 반환

예상 위치에 PRD가 없는 경우입니다.

# 1. docs 폴더와 PRD 생성

start path="/your/project" init=true

# 2. 또는 대화에서 PRD 저장

save_prd path="/your/project" content="# My PRD\n..."

# 3. path가 docs/가 아닌 프로젝트 루트를 가리키는지 확인

해결되지 않나요? GitHub Issues 또는 문의 양식을 이용하세요. 보통 24~48시간 내에 응답합니다.

변경 로그

v5.0.0 2026-02 최신
  • - 리부트: Free 10개 + Pro 10개 깔끔한 아키텍처
  • - 가격 단순화: $7.99/월 또는 $49/년 (얼리 어답터 가격)
  • - 티어 게이팅: 방어적 심층 (list_tools + call_tool)
  • - 고스트 데이터: Free 사용자에게 에러 도구 Pro 티저
  • - CTA 통일: 모든 메시지에 단일 체험 CTA
v1.9.0 2026-01-26
  • - 도구 통합: 52개 → 12개 표준 도구
  • - 구 도구 지원 종료 경고
v1.4.0 2026-01-22
  • - Knowledge Base: record_decision, search_knowledge
  • - Error Learning: 회귀 메모리, 패턴 감지
  • - Quick Perspectives: 10초 맹점 체크
v1.2.0 2026-01-21
  • - 8명 C-Level 매니저 회의 시뮬레이션
  • - Ship: 원클릭 검증 + 증거
  • - 프로젝트 온보딩 (start 도구)
v0.5.0 2026-01-17
  • - 최초 릴리즈
  • - can_code 스펙 게이트 (BLOCK / WARN / PASS)
  • - PRD 기반 코딩 게이트