nyxCore-Systems/ckb

코드를 이해하세요. 안전하게 변경하세요. 확신을 가지고 배포하세요.

CKB는 여러분의 코드베이스를 질의 가능한 지식 베이스 (Knowledge Base)로 변환합니다. CLI, API 또는 AI 어시스턴트 (AI Assistants)를 통해 질문하고, 영향을 파악하며, 소유자를 찾고, 데드 코드 (Dead Code)를 탐지하세요.

모든 코드 라인, 모든 결정, 모든 소유자를 알고 있으며, 여러분의 질문에 답하기 위해 24시간 대기 중인 시니어 엔지니어라고 생각하십시오.

질문	CKB 없이	CKB 사용 시
"이것을 변경하면 무엇이 망가질까요?"	Grep으로 검색하고 기도하기	위험 점수 (Risk Score)와 함께 정확한 영향 범위 (Blast Radius) 파악
...
🔍 이해 (Understand) — 시맨틱 검색 (Semantic Search), 호출 그래프 (Call Graphs), 사용 추적 (Usage Tracing), 아키텍처 맵 (Architecture Maps)

⚡ 분석 (Analyze) — 영향 분석 (Impact Analysis), 위험 점수 산정 (Risk Scoring), 핫스팟 탐지 (Hotspot Detection), 결합도 분석 (Coupling Analysis)

🛡️ 보호 (Protect) — 영향받는 테스트 탐지 (Affected Test Detection), 파괴적 변경 경고 (Breaking Change Warnings), PR 위험 평가 (PR Risk Assessment)

🔐 보안 (Secure) — 비밀 정보 탐지 (Secret Detection), 자격 증명 스캔 (Credential Scanning), 보안 민감 코드 식별 (Security-sensitive Code Identification)

👥 협업 (Collaborate) — 소유권 조회 (Ownership Lookup), 리뷰어 추천 (Reviewer Suggestions), 아키텍처 결정 기록 (ADRs)

📊 개선 (Improve) — 데드 코드 탐지 (Dead Code Detection), 기술 부채 추적 (Tech Debt Tracking), 문서화 커버리지 (Documentation Coverage)

🚀 복합 작업 (Compound Operations) — 단일 호출 도구 (explore, understand, prepareChange)를 통해 AI 도구 호출을 60-70% 감소시킵니다.

🔗 통합 (Integrate) — CLI, HTTP API, AI 도구를 위한 MCP, CI/CD 파이프라인, 커스텀 스크립트

# 코드베이스에서 무엇이 위험한지 확인
ckb hotspots --format=human
# 무엇이 변경되었고 무엇이 망가질 수 있는지 확인
...

AI 어시스턴트 (AI Assistants)	CI/CD	사용자의 도구
Claude Code, Cursor, Windsurf, VS Code, Grok	GitHub Actions, GitLab CI	CLI, HTTP API, 스크립트

스마트 프리셋 (Smart Presets)을 통해 83%의 토큰 감소 (Token Reduction) 효과를 누리세요 — 필요한 도구만 로드합니다.

# Claude Code에 연결하는 한 번의 명령
ckb setup

자신만의 도구를 구축 중이신가요? CLI, HTTP API 또는 MCP를 통해 CKB를 백엔드 (Backend)로 사용하세요. Node.js, Python, Go 및 쉘 스크립트 (Shell Scripts) 예제는 통합 가이드 (Integration Guide)를 참조하십시오.

리소스 (Resource)	설명 (Description)
📖 기능 가이드 (Features Guide)	예시가 포함된 전체 기능 목록
💬 프롬프트 쿡북 (Prompt Cookbook)	실제 문제를 해결하기 위한 실제 프롬프트
🔌 통합 가이드 (Integration Guide)	자신의 도구 및 스크립트에서 CKB 사용하기
⚡ 영향 분석 (Impact Analysis)	폭발 반경 (Blast radius), 영향을 받는 테스트, PR 리스크
🔧 CI/CD 통합 (CI/CD Integration)	GitHub Actions, GitLab CI 템플릿

# 전역 설치 (Install globally)
npm install -g @tastehub/ckb
# 또는 npx로 직접 실행 (설치 불필요)
...

brew tap SimplyLiz/ckb
brew install ckb

git clone https://github.com/SimplyLiz/CodeMCP.git
cd CodeMCP
go build -o ckb ./cmd/ckb

# 1. 프로젝트에서 초기화 (Initialize in your project)
cd /path/to/your/project
ckb init # 또는: npx @tastehub/ckb init
...

시작 시 표시되는 토큰 효율성 (Token efficiency):

CKB MCP Server v9.0.0
활성 도구 (Active tools): 14 / 76 (18%)
예상 컨텍스트 (Estimated context): ~1k tokens
...

이제 Claude는 다음과 같은 질문에 답할 수 있습니다:

"HandleRequest 함수를 호출하는 것은 무엇인가요?"
"API에서 ProcessPayment에 어떻게 도달하나요?"
"UserService를 변경하면 폭발 반경 (blast radius)이 어떻게 되나요?"
"internal/api 모듈의 소유자는 누구인가요?"
"이 레거시 코드가 여전히 사용되고 있나요?"

CKB 미사용 시	CKB 사용 시
AI가 패턴을 검색 (greps) 함	AI가 의미론적으로 탐색 (navigates semantically) 함
...

인터페이스 (Interface)	최적 용도 (Best For)
MCP	AI 보조 개발 — Claude, Cursor, Windsurf, VS Code, OpenCode, Grok
CLI	터미널에서의 빠른 조회, 스크립팅
HTTP API	IDE 플러그인, CI 통합, 커스텀 도구 제작

CKB는 코드를 이해하기 위해 **SCIP 인덱스 (SCIP indexes)**를 사용합니다. 이는 모든 함수가 어디에 정의되어 있는지, 누가 호출하는지, 그리고 모든 것이 어떻게 연결되어 있는지를 알고 있는 데이터베이스와 같다고 생각하면 됩니다.

# 1. 인덱스 생성 (언어 자동 감지)
ckb index
# 2. 인덱스가 최신인지 확인
...

인덱스가 없어도 CKB는 tree-sitter 파싱 (기본 모드)을 사용하여 작동하지만, 인덱스가 있으면 다음과 같은 이점을 얻을 수 있습니다:

• 파일 간 참조 ("이 함수를 호출하는 곳은 어디인가?")
• 정밀한 영향 분석 (Impact analysis)
• 호출 그래프 (Call graph) 탐색

모든 언어가 동일한 것은 아닙니다. CKB는 인덱서 (indexer)의 성숙도에 따라 언어를 **품질 티어 (quality tiers)**로 분류합니다:

티어 (Tier)	품질 (Quality)	언어 (Languages)
Tier 1	완전한 지원, 모든 기능 제공	Go
Tier 2	완전한 지원, 사소한 예외 케이스 존재	TypeScript, JavaScript, Python
Tier 3	기본 지원, 호출 그래프 (call graph)가 불완전할 수 있음	Rust, Java, Kotlin, C++, Ruby, Dart
Tier 4	실험적 단계 (Experimental)	C#, PHP

주요 제한 사항 (Key limitations):

**증분 인덱싱 (Incremental indexing)**은 Go 언어에서만 지원됩니다. 다른 언어는 전체 재인덱싱 (full reindex)이 필요합니다.
**TypeScript 모노레포 (monorepos)**는 --infer-tsconfig 플래그가 필요할 수 있습니다.
**C/C++**는 compile_commands.json이 필요합니다.
Python은 활성화된 가상 환경 (virtual environment)에서 가장 잘 작동합니다.

ckb doctor --tier standard를 실행하여 언어 도구들이 제대로 설치되었는지 확인하세요.

인덱서 설치, 알려진 문제 및 전체 기능 매트릭스 (feature matrix)에 대해서는 언어 지원 (Language Support) 섹션을 참조하세요.

커밋을 하면 인덱스가 오래된 상태 (stale)가 됩니다. CKB는 최신 상태를 유지하기 위한 몇 가지 방법을 제공합니다:

방법 (Method)	명령어 (Command)	사용 시점 (When to Use)
수동 (Manual)	ckb index	일회성 업데이트, 스크립트
워치 모드 (Watch mode)	ckb index --watch	개발 중 자동 새로고침
MCP watch	ckb mcp --watch	AI 세션 중 자동 새로고침
CI 웹훅 (CI webhook)	POST /api/v1/refresh	CI/CD에서 트리거

AI 세션을 위한 빠른 시작 (Quick start for AI sessions):

ckb mcp --watch # 인덱스가 오래되면 30초마다 자동 재인덱싱

최신 상태 여부 확인 (Check staleness):

ckb status
# 출력 예시: "5 commits behind HEAD" 또는 "Up to date"

Go 프로젝트의 경우, CKB는 **증분 인덱싱 (incremental indexing)**을 사용하여 변경된 파일만 처리하므로 업데이트가 빠릅니다.

전체 문서는 **인덱스 관리 가이드 (Index Management Guide)**를 참조하세요.

기능	설명
복합 작업 (Compound Operations)	explore, understand, prepareChange — AI 오버헤드를 60-70% 줄여주는 단일 호출 도구
코드 탐색 (Code Navigation)	시맨틱 검색 (Semantic search), 호출 그래프 (Call graphs), 사용 추적 (Trace usage), 엔트리포인트 (Entrypoints) 찾기
영향 분석 (Impact Analysis)	영향 범위 (Blast radius), 리스크 점수 (Risk scoring), 영향을 받는 테스트, 파괴적 변경 사항 (Breaking changes) (compareAPI)
아키텍처 (Architecture)	모듈 개요, ADR (Architecture Decision Records), 의존성 그래프 (Dependency graphs), 기원 설명
소유권 (Ownership)	CODEOWNERS + git blame, 리뷰어 제안, 드리프트 탐지 (Drift detection)
코드 품질 (Code Quality)	데드 코드 탐지 (findDeadCode), 결합도 분석 (Coupling analysis), 복잡도 (Complexity)
보안 (Security)	비밀 정보 탐지 (Secret detection), 자격 증명 스캐닝 (Credential scanning), 허용 목록 (Allowlists)
문서화 (Documentation)	문서-심볼 연결 (Doc-symbol linking), 노후화 탐지 (Staleness detection), 커버리지 지표 (Coverage metrics)
멀티 리포 (Multi-Repo)	연합 (Federation), API 계약 (API contracts), 원격 인덱스 서빙 (Remote index serving)
런타임 (Runtime)	OpenTelemetry 통합, 관찰된 사용량 (Observed usage), 프로덕션 데드 코드
스트리밍 (Streaming)	findReferences를 위한 SSE 스트리밍, 실시간 진행 상황을 포함한 searchSymbols
자동화 (Automation)	데몬 모드 (Daemon mode), 워치 모드 (Watch mode), 웹훅 (Webhooks), 증분 인덱싱 (Incremental indexing)

📖 전체 기능 가이드 (Full Features Guide) — 예시가 포함된 상세 문서

📋 변경 이력 (Changelog) — 버전 히스토리

CKB 리뷰는 5초 안에 20가지 품질 검사를 실행합니다 — 비밀 정보, 파괴적 변경 사항, 데드 코드, 복잡도, 테스트 공백, 버그 패턴 등을 검사합니다. 토큰 소모 제로, API 호출 제로입니다.

사용자의 AI 어시스턴트 (Claude Code, Cursor, Windsurf)가 PR을 리뷰할 때, 먼저 CKB를 호출하여 약 1k 토큰 내외의 구조화된 분석 결과를 얻습니다. 그 후 중요한 파일만 읽기 때문에, 대규모 PR에서 50-80%의 토큰을 절약할 수 있습니다.

ckb review --base=main # 사람이 읽기 쉬운 리뷰
ckb review --base=main --ci # CI 모드 (종료 코드 반환)
ckb review --base=main --post=123 # PR 댓글로 게시

LLM 없이도 CI에서 작동합니다:

- run: npx @tastehub/ckb review --base=main --ci --format=sarif > review.sarif

CKB 미사용 시	CKB 사용 시
100개 파일 PR에 대한 LLM 토큰 사용량	~200k
...

📖 AI 리뷰를 돕는 방법 · 벤치마크 · CI 통합 · 퀵스타트

ckb status # 시스템 상태 (복구 제안 포함)
ckb search Handler # 심볼(symbols) 찾기
ckb diff-summary # 변경 사항 분석
...

v9.0 복합 작업 (Compound Operations) (MCP를 통해):

# 이 도구들은 여러 쿼리를 단일 호출로 결합합니다
explore # 영역 탐색 (exploration): 심볼(symbols), 의존성(dependencies), 핫스팟(hotspots)
understand # 심볼 심층 분석 (deep-dive): 참조(refs), 호출자(callers), 설명(explanation)
...

📖 사용자 가이드 (User Guide) — 모든 CLI 명령어 및 옵션

# HTTP 서버 시작
ckb serve --port 8080
# 호출 예시
...

CKB는 모든 MCP 호환 AI 코딩 도구와 함께 작동합니다.

Claude Code

# 현재 프로젝트를 위해 자동 설정
npx @tastehub/ckb setup
# 또는 모든 프로젝트를 위해 전역(globally)으로 추가
...

또는 .mcp.json에 수동으로 추가:

{
"mcpServers": {
"ckb": {
...

Cursor

~/.cursor/mcp.json (전역) 또는 .cursor/mcp.json (프로젝트)에 추가:

{
"mcpServers": {
"ckb": {
...

Windsurf

~/.codeium/windsurf/mcp_config.json에 추가:

{
"mcpServers": {
"ckb": {
...

VS Code

VS Code의 settings.json에 추가:

{
"mcp": {
"servers": {
...

OpenCode

프로젝트 루트의 opencode.json에 추가:

{
"mcp": {
"ckb": {
...

Grok

# 현재 프로젝트를 위해 자동 설정
npx @tastehub/ckb setup --tool=grok
# 또는 전역으로 추가
...

또는 .grok/settings.json (프로젝트) 또는 ~/.grok/user-settings.json (전역)에 수동으로 추가:

{
"mcpServers": {
"ckb": {
...

Claude Desktop

Claude Desktop은 프로젝트 컨텍스트(context)를 가지고 있지 않으므로, 반드시 리포지토리(repository) 경로를 지정해야 합니다.

자동 설정 (Automatic setup) (권장):

cd /path/to/your/repo
ckb setup --tool=claude-desktop

수동 구성 (Manual configuration) — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows)에 추가:

{
"mcpServers": {
"ckb": {
...

CKB_REPO 환경 변수는 CKB가 어떤 리포지토리를 분석할지 알려줍니다. Claude Desktop은 한 번에 하나의 리포지토리만 작업할 수 있습니다.

Windows

cmd /c를 사용하세요.

위의 어떤 설정(config)에서도 다음과 같이 래퍼(wrapper)를 사용하세요:

{
"mcpServers": {
"ckb": {
...

프리셋 (Presets, 토큰 최적화)

CKB는 80개 이상의 도구(tools)를 제공하지만, 대부분의 세션에서는 그중 일부만 필요합니다. 프리셋을 사용하면 토큰 오버헤드(token overhead)를 최대 83%까지 줄일 수 있습니다:

# 도구 개수 및 토큰 추정치와 함께 사용 가능한 모든 프리셋 목록 표시
ckb mcp --list-presets
# 기본값: 코어 프리셋 (14개의 필수 도구)
...

MCP 설정에서:

{
"mcpServers": {
"ckb": {
...

AI는 expandToolset 도구를 사용하여 세션 도중에 동적으로 도구 세트(toolset)를 확장할 수 있습니다.

CKB는 여러 코드 인텔리전스(code intelligence) 백엔드를 오케스트레이션(orchestrates)합니다:

SCIP— 정밀하고 미리 인덱싱된 심볼(symbol) 데이터 (가장 빠름)
LSP— 실시간 언어 서버(language server) 쿼리
Git— Blame, 히스토리, churn 분석, 소유권(ownership)
LIP— 최근접 이웃 검색(nearest-neighbour search) 및 재순위화(re-ranking)를 위한 시맨틱 임베딩(semantic embedding) 데몬 (선택 사항, 권장)

결과는 지능적으로 병합되며 LLM 컨텍스트 제한(context limits)에 맞춰 압축됩니다.

LIP는 시맨틱 검색(semantic search), PR 참신성 탐지(novelty detection), 테스트 발견, 파일 경계 분석, 아키텍처 결합 신호(architecture coupling signals)를 강화합니다. LIP가 CKB와 함께 실행되면 검색 품질이 크게 향상됩니다. 특히 심볼 이름과 문자 그대로 일치하지 않는 자연어 쿼리(natural-language queries)의 경우 더욱 그렇습니다. 자세한 내용은 Hybrid Retrieval 또는 LIP 문서를 참조하세요.

지속적인 지식(Persistent knowledge)은 세션 간에도 유지됩니다:

모듈 레지스트리 (Module Registry)— 경계, 책임, 태그
소유권 레지스트리 (Ownership Registry)— CODEOWNERS + 시간 경과에 따른 가중치를 적용한 git-blame
핫스팟 트래커 (Hotspot Tracker)— 트렌드 분석이 포함된 히스토리 스냅샷
결정 로그 (Decision Log)— 전체 텍스트 검색이 가능한 ADR(Architecture Decision Records)

AI 어시스턴트를 사용하는 개발자— AI 도구에 초능력을 부여하세요
대규모 코드베이스를 가진 팀— 복잡성을 효율적으로 탐색하세요
리팩터링을 수행하는 모든 이— 변경하기 전에 영향을 이해하세요
코드 리뷰어— 변경 사항의 전체 그림을 확인하세요
테크 리드 (Tech leads)— 시간에 따른 아키텍처 건강 상태를 추적하세요

CKB가 탁월한 분야:

• 정적 코드 탐색 (Static code navigation)—정의(definitions), 참조(references), 호출 그래프(call graphs) 찾기
• 안전한 리팩터링 (refactoring)을 위한 영향 분석 (Impact analysis)
• 소유권 조회 (Ownership lookup) (CODEOWNERS + git blame)
• 아키텍처 및 모듈 이해

CKB가 도움을 줄 수 없는 분야:

• 동적 디스패치 (Dynamic dispatch) / 런타임 동작 (runtime behavior) (디버거 사용 권장)
• 인덱싱되지 않은 생성된 코드 (Generated code)
• 코드 생성 (Code generation), 린팅 (linting), 또는 포맷팅 (formatting)
• 리포지토리 간 호출 (Cross-repo calls) (이를 위해서는 federation 사용 권장)

CKB는 정적 분석 (static analysis) 도구이며 마법이 아닙니다. 중요한 결정은 항상 실제 코드를 읽어 확인하십시오.

📖 실질적 한계 (Practical Limits) — 정확도, 사각지대, 그리고 결과를 신뢰해야 하는 시점에 대한 전체 가이드

다음 사항은 **전체 문서 위키 (Full Documentation Wiki)**를 참조하세요: