caliber-ai-org/ai-setup

직접 작성한 CLAUDE.md 파일은 리팩터링(refactor)을 하는 순간 쓸모없게 됩니다. 당신의 AI 에이전트는 더 이상 존재하지 않는 경로를 환각(hallucinate)하고, 새로운 의존성(dependencies)을 놓치며, 어제의 아키텍처를 기반으로 조언을 제공합니다. Caliber는 당신의 AI 컨텍스트 파일들(CLAUDE.md, .cursor/rules/, AGENTS.md, copilot-instructions.md)을 생성하고 유지 관리하여 코드가 진화함에 따라 정확성을 유지하도록 돕습니다. 또한 팀 내의 모든 에이전트가 Claude Code, Cursor, Codex, OpenCode 또는 GitHub Copilot을 사용하더라도 모두 동기화된 상태를 유지하게 합니다. 대부분의 저장소(repos)는 직접 작성한 CLAUDE.md 하나만 있고 그 외에는 아무것도 없는 상태로 시작합니다. Caliber가 찾아내고 수정하는 내용은 다음과 같습니다:

Before After /setup-caliber
────────────────────────────── ──────────────────────────────
Agent Config Score 35 / 100 Agent Config Score 94 / 100
...

점수 산정(Scoring)은 결정론적(deterministic)입니다. 즉, LLM이나 API 호출을 사용하지 않습니다. Caliber는 실제 프로젝트 파일 시스템과 설정 파일들을 교차 참조합니다: 참조된 경로가 존재하는가? 코드 블록이 존재하는가? 마지막 커밋 이후 설정 드리프트(config drift)가 발생했는가?

caliber score --compare main # 브랜치 변경이 점수에 미친 영향을 확인합니다

Node.js >= 20이 필요합니다.

npx @rely-ai/caliber bootstrap

그 다음, 터미널(IDE 채팅창이 아님)에서 Claude Code 또는 Cursor CLI 세션을 시작하고 다음을 입력하세요:

/setup-caliber

당신의 에이전트는 스택(stack)을 감지하고, 팀이 사용하는 모든 플랫폼에 맞춤화된 설정을 생성하며, 프리 커밋 훅(pre-commit hooks)을 설정하고, 지속적인 동기화(continuous sync)를 활성화합니다. 이 모든 과정은 당신의 일반적인 워크플로우 내부에서 이루어집니다.

Claude Code나 Cursor를 사용하지 않나요?
대신 caliber init을 실행하세요. CLI 마법사와 동일한 설정 방식입니다. 모든 LLM 제공업체와 호환됩니다: 본인의 Anthropic, OpenAI 또는 Vertex AI 키를 가져와 사용하세요.

당신의 코드는 머신에 그대로 유지됩니다. 부트스트랩(Bootstrap)은 100% 로컬에서 수행됩니다. LLM 호출이나 코드 전송은 전혀 없습니다. 생성 과정에는 당신의 AI 구독 또는 API 키가 사용됩니다. Caliber는 당신의 코드를 절대 볼 수 없습니다.

Windows 사용자

Caliber는 Windows에서 몇 가지 주의 사항과 함께 작동합니다:

터미널(PowerShell, CMD 또는 Git Bash)에서 실행하세요 — IDE 채팅창 내부가 아닙니다. 터미널을 열고 cd를 입력하여...

프로젝트 폴더로 이동한 다음, npx @rely-ai/caliber bootstrap을 실행하세요.

Git Bash 사용을 권장합니다. Caliber의 프리 커밋 훅 (pre-commit hooks) 및 자동 동기화 스크립트는 셸 (shell) 구문을 사용합니다. Git for Windows에는 이를 자동으로 처리하는 Git Bash가 포함되어 있습니다. PowerShell만 사용할 경우, 훅 (hooks)이 조용히 건너뛰어질 수 있습니다.

Cursor Agent CLI: 설치를 요청받는 경우, macOS/Linux에 표시된 curl | bash 명령 대신 cursor.com/downloads에서 다운로드하세요. 그 다음 터미널에서 agent login을 실행하여 인증을 완료하세요.

한 번에 하나의 터미널만 사용하세요. Caliber를 여러 터미널에서 동시에 실행하지 마세요. 이는 상태 충돌 및 예기치 않은 프로바이더 (provider) 감지를 유발할 수 있습니다.

Caliber는 묻지 않고 기존 설정을 덮어쓰지 않습니다. 워크플로 (workflow)는 코드 리뷰를 반영합니다:

Score (점수 산정) — 현재 설정에 대한 읽기 전용 감사 (audit)
Propose (제안) — 설정을 생성하거나 개선하며, 디프 (diff) 형태로 표시
Review (검토) — 각 변경 사항을 수락, 채팅을 통해 개선 또는 거부
Backup (백업) — 모든 쓰기 작업 전에 원본을 .caliber/backups/에 저장
Undo (되돌리기) — caliber undo를 통해 모든 것을 이전 상태로 복구

기존 설정 점수가 95점 이상인 경우, Caliber는 전체 재생성을 건너뛰고 실패하는 특정 체크 (checks) 항목에 대해서만 타겟팅된 수정을 적용합니다.

부트스트랩 (Bootstrap)을 수행하면 에이전트 (agent)에게 /setup-caliber 기술 (skill)이 부여됩니다. 에이전트는 프로젝트의 언어, 프레임워크 (frameworks), 의존성 (dependencies), 아키텍처 (architecture)를 분석하여 설정을 생성하고 훅 (hooks)을 설치합니다. 그 이후에는 다음과 같은 루프 (loop)가 반복됩니다:

npx @rely-ai/caliber bootstrap ← 1회성, 2초 소요
│
▼
...

프리 커밋 훅 (pre-commit hooks)이 새로고침 루프를 자동으로 실행합니다. 새로운 팀원은 첫 세션에서 부트스트랩을 수행하도록 안내를 받습니다.

Claude Code

CLAUDE.md — 프로젝트 컨텍스트 (context), 빌드/테스트 명령, 아키텍처, 컨벤션 (conventions)
CALIBER_LEARNINGS.md — AI 코딩 세션에서 학습된 패턴 (patterns)
.claude/skills/*/SKILL.md — 재사용 가능한 기술 (reusable skills, OpenSkills 형식)
.mcp.json — 자동 검색된 MCP 서버 설정
.claude/settings.json — 권한 (permissions) 및 훅 (hooks)

Cursor

.cursor/rules/*.mdc

— 프론트매터 (frontmatter)를 포함한 현대적인 규칙 (description, globs, alwaysApply) .cursor/skills/*/SKILL.md

— Cursor를 위한 스킬 (Skills)
.cursor/mcp.json

— MCP 서버 설정 (configurations)

OpenAI Codex

AGENTS.md

— Codex를 위한 프로젝트 컨텍스트 (Project context)
.agents/skills/*/SKILL.md

— Codex를 위한 스킬 (Skills)

OpenCode

AGENTS.md

— 프로젝트 컨텍스트 (Codex와 모두 타겟팅될 경우 공유됨)
.opencode/skills/*/SKILL.md

— OpenCode를 위한 스킬 (Skills)

GitHub Copilot

.github/copilot-instructions.md

— Copilot을 위한 프로젝트 컨텍스트 (Project context)

모든 코드베이스 (Any Codebase)

TypeScript, Python, Go, Rust, Java, Ruby, Terraform 및 기타 언어 지원. 언어 및 프레임워크 감지는 완전히 LLM (Large Language Model) 기반으로 이루어지며, 하드코딩된 매핑 (hardcoded mappings)을 사용하지 않습니다. Caliber는 어떤 프로젝트에서도 작동합니다.

모든 AI 도구 (Any AI Tool)

caliber bootstrap

설치된 에이전트 (agents)를 자동으로 감지합니다. 수동 제어를 위한 방법은 다음과 같습니다:

caliber init --agent claude # Claude Code 전용
caliber init --agent cursor # Cursor 전용
caliber init --agent codex # Codex 전용
...

채팅 기반 정교화 (Chat-Based Refinement)

생성된 결과가 만족스럽지 않으신가요? 검토 과정에서 자연어 (natural language)를 통해 정교화할 수 있습니다. 변경하고 싶은 내용을 설명하면 Caliber가 만족할 때까지 반복하여 수정합니다.

MCP 서버 검색 (MCP Server Discovery)

Caliber는 프로젝트에서 사용하는 도구 (데이터베이스, API, 서비스)를 감지하고, Claude Code 및 Cursor에 맞는 MCP 서버를 자동으로 구성합니다.

결정론적 점수 산정 (Deterministic Scoring)

caliber score

LLM 호출 없이 설정 품질을 평가합니다. 실제 프로젝트 파일 시스템 (filesystem)과 설정 파일들을 상호 참조하여 순수하게 수행됩니다.

카테고리	점수	확인 항목
파일 및 설정 (Files & Setup)	25	설정 파일 존재 여부, 스킬 (skills) 존재 여부, MCP 서버, 크로스 플랫폼 동등성 (cross-platform parity)
품질 (Quality)	25	코드 블록, 간결한 토큰 예산 (token budget), 구체적인 지침, 구조화된 헤딩
그라운딩 (Grounding)	20	설정이 실제 프로젝트 디렉토리 및 파일을 참조하는지 여부
정확성 (Accuracy)	15	참조된 경로가 디스크에 존재하는지, Git 히스토리 대비 설정의 최신성
최신성 및 안전성 (Freshness & Safety)	10	최근 업데이트 여부, 비밀 정보 (secrets) 유출 없음, 권한 설정 완료
보너스 (Bonus)	5	자동 새로고침 훅 (auto-refresh hooks), AGENTS.md, OpenSkills 형식

실패한 모든 체크 항목에는 구조화된 수정 데이터가 포함됩니다. caliber init이 실행될 때, LLM은 무엇이 잘못되었고 어떻게 수정해야 하는지를 정확하게 전달받습니다.

세션 학습 (Session Learning)

Caliber는 사용자의 AI 코딩 세션을 관찰하고 그로부터 학습합니다. 훅 (Hooks)은 도구 사용, 실패 사례, 사용자의 수정을 캡처하며, 이후 LLM이 운영 패턴을 추출하여 CALIBER_LEARNINGS.md에 정리합니다.

caliber learn install # Claude Code 및 Cursor를 위한 훅 설치
caliber learn status # 훅 상태, 이벤트 횟수 및 ROI 요약 보기
caliber learn finalize # 분석 수동 트리거 (세션 종료 시 자동 실행)
...

학습된 항목은 [correction] (수정), [gotcha] (주의 사항), [fix] (해결), [pattern] (패턴), [env] (환경), [convention] (관례) 유형별로 분류되며 자동으로 중복이 제거됩니다.

자동 새로고침 (Auto-Refresh)

설정 파일을 코드베이스와 자동으로 동기화 상태로 유지하세요:

훅 (Hook)	트리거 (Trigger)	기능
Git pre-commit	각 커밋 전	문서 새로고침 및 업데이트된 파일 스테이징 (stage)
Claude Code 세션 종료	각 세션 종료 시	caliber refresh 실행 및 문서 업데이트
학습 훅 (Learning hooks)	각 세션 중	세션 학습을 위한 이벤트 캡처

caliber hooks --install # 새로고침 훅 활성화
caliber hooks --remove # 새로고침 훅 비활성화

refresh 명령은 Git diff (커밋된 변경 사항, 스테이징된 변경 사항, 스테이징되지 않은 변경 사항)를 분석하여 변경된 내용을 반영하도록 설정 파일을 업데이트합니다.

팀 온보딩 (Team Onboarding)

레포지토리(repo)에 Caliber가 설정되면, 새로운 팀원들이 자신의 로컬 환경에 이를 구성하도록 자동으로 안내합니다. 가벼운 세션 훅(session hook)이 pre-commit 훅(pre-commit hook)이 설치되어 있는지 확인하고, 설치되어 있지 않으면 설정을 유도하므로 별도의 수동 조정이 필요하지 않습니다.

완전한 가역성 (Fully Reversible)

자동 백업 (Automatic backups) — 모든 쓰기 작업 전에 원본을 .caliber/backups/에 저장합니다.
점수 하락 방지 (Score regression guard) — 재생성 결과가 더 낮은 점수를 생성할 경우, 변경 사항이 자동으로 되돌려집니다.
전체 실행 취소 (Full undo) — caliber undo 명령어를 통해 모든 것을 이전 상태로 복구합니다.
깔끔한 삭제 (Clean uninstall) — caliber uninstall을 통해 사용자의 콘텐츠는 보존하면서 Caliber가 추가한 모든 것(훅, 생성된 섹션, 기술, 학습 내용)을 제거합니다.
드라이 런 (Dry run) — 변경 사항을 적용하기 전에 --dry-run으로 미리 확인합니다.

명령어	설명
caliber bootstrap	에이전트 기술(agent skills) 설치 — 가장 빠르게 시작하는 방법
caliber init	전체 설정 마법사 — 분석, 생성, 검토, 훅 설치
caliber score	설정 품질 점수 측정 (결정론적 방식, LLM 미사용)
caliber score --compare <ref>	현재 점수를 git ref와 비교
caliber regenerate	설정 재분석 및 재생성 (별칭: regen, re)
caliber refresh	최근 코드 변경 사항을 기반으로 문서 업데이트
caliber skills	커뮤니티 기술 탐색 및 설치
caliber learn	세션 학습 — 훅 설치, 상태 확인, 분석 완료
caliber hooks	자동 새로고침 훅 관리
caliber config	LLM 제공자, API 키 및 모델 설정
caliber status	현재 설정 상태 표시
caliber uninstall	프로젝트에서 모든 Caliber 리소스 제거
caliber undo	Caliber에 의해 수행된 모든 변경 사항 되돌리기

기존 설정을 덮어쓰나요?

아니요. Caliber는 제안된 모든 변경 사항에 대해 diff(차이점)를 보여줍니다. 사용자는 각 변경 사항을 수락, 수정 또는 거부할 수 있습니다. 원본은 자동으로 백업됩니다.

API 키가 필요한가요?

Bootstrap 및 점수 측정 (Scoring): 아니요. 두 기능 모두 LLM 없이 100% 로컬에서 실행됩니다.

생성 (Generation) (/setup-caliber 또는 caliber init을 통해 실행)

): 기존의 Claude Code 또는 Cursor 구독을 사용하며 (API 키가 필요 없음), 또는 Anthropic, OpenAI, Vertex AI를 위한 본인의 키를 직접 가져올 수 있습니다.

bootstrap과 init의 차이점은 무엇인가요?

caliber bootstrap은 2초 만에 에이전트 기술 (agent skills)을 설치하며, 그 후 에이전트가 세션 내부에서 나머지 과정을 처리하기 위해 /setup-caliber를 실행합니다. caliber init은 CLI 기반 설정을 선호하는 사용자를 위한 전체 대화형 마법사 (interactive wizard)입니다. 두 방식 모두 결과적으로는 동일한 상태에 도달합니다.

생성된 결과가 마음에 들지 않으면 어떻게 하나요?

검토 과정 중 채팅을 통해 수정하거나, 변경 사항을 완전히 거부할 수 있습니다. 이미 수락했다면, caliber undo를 통해 모든 것을 복구할 수 있습니다. 또한 --dry-run을 사용하여 미리 볼 수도 있습니다.

모노레포 (monorepos)에서도 작동하나요?

네. 어느 디렉토리에서든 caliber init을 실행하면 됩니다. 부모 디렉토리에서 실행할 경우 caliber refresh를 통해 여러 레포지토리(repos)에 걸쳐 설정을 업데이트할 수 있습니다.

제 코드를 어디론가 전송하나요?

점수 산정 (Scoring)은 완전히 로컬에서 이루어집니다. 생성 (Generation) 시에는 프로젝트 요약 정보(언어, 구조, 의존성 — 소스 코드는 제외)를 사용자가 설정한 LLM 제공업체로 전송하며, 이는 사용자의 AI 에디터가 이미 사용 중인 것과 동일한 제공업체입니다. 익명 사용 분석 데이터(명령어 이름, 실행 시간 — 코드 및 파일 내용은 제외)는 PostHog를 통해 수집됩니다. 수집을 거부하려면:

실행 시마다 적용: caliber --no-traces <command>

지속적인 환경 변수 설정: export CALIBER_TELEMETRY_DISABLED=1

API 키가 없어도 문제없습니다. Caliber는 기존의 AI 도구 구독과 함께 작동합니다:

제공업체 (Provider)	설정 (Setup)	기본 모델 (Default Model)
Claude Code (사용자 계정)	caliber config → Claude Code	Claude Code로부터 상속
Cursor (사용자 계정)	caliber config → Cursor	Cursor로부터 상속
Anthropic	export ANTHROPIC_API_KEY=sk-ant-...	claude-sonnet-4-6
OpenAI	export OPENAI_API_KEY=sk-...	gpt-5.4-mini
Vertex AI	export VERTEX_PROJECT_ID=my-project	claude-sonnet-4-6
커스텀 엔드포인트 (Custom endpoint)	OPENAI_API_KEY + OPENAI_BASE_URL	gpt-5.4-mini

모든 제공업체에 대해 모델을 재정의하려면 export CALIBER_MODEL=<model-name>을 사용하거나 caliber config를 사용하세요.

Caliber는 **2단계 모델 시스템 (two-tier model system)**을 사용합니다. 가벼운 작업(분류 (classification), 점수 매기기 (scoring))에는 더 빠른 모델이 자동으로 사용되는 반면, 무거운 작업(생성 (generation), 정교화 (refinement))에는 기본 모델이 사용됩니다. 이를 통해 비용은 낮게 유지하고 속도는 높게 유지합니다.

설정은 제한된 권한(0600)과 함께 ~/.caliber/config.json에 저장됩니다. API 키는 프로젝트 파일에 절대 기록되지 않습니다.

Vertex AI 고급 설정

# 커스텀 리전 (Custom region)
export VERTEX_PROJECT_ID=my-gcp-project
export VERTEX_REGION=europe-west1
...

환경 변수 (Environment variables) 참조

변수	용도
ANTHROPIC_API_KEY	Anthropic API 키
OPENAI_API_KEY	OpenAI API 키
OPENAI_BASE_URL	커스텀 OpenAI 호환 엔드포인트 (endpoint)
VERTEX_PROJECT_ID	Vertex AI를 위한 GCP 프로젝트 ID
VERTEX_REGION	Vertex AI 리전 (기본값: us-east5)
VERTEX_SA_CREDENTIALS	서비스 계정 (Service account) JSON (인라인)
GOOGLE_APPLICATION_CREDENTIALS	서비스 계정 (Service account) JSON 파일 경로
CALIBER_USE_CLAUDE_CLI	Claude Code CLI 사용 (1로 설정 시 활성화)
CALIBER_USE_CURSOR_SEAT	Cursor 구독 사용 (1로 설정 시 활성화)
CALIBER_MODEL	모든 제공자(provider)에 대해 모델 재정의
CALIBER_FAST_MODEL	모든 제공자(provider)에 대해 빠른 모델 재정의

자세한 가이드라인은 CONTRIBUTING.md를 참조하세요.