Alcove은 AI 코딩 에이전트가 비공개 프로젝트 문서에 온디맨드로 액세스할 수 있게 해주는 MCP 서버입니다. 모든 내용을 컨텍스트 창에 덤프하거나, 문서를 공개 저장소에 유출하거나, 사용하는 모든 에이전트마다 프로젝트별 설정을 할 필요가 없습니다.

데모

Alcove 에이전트 데모

Claude, Gemini, Codex — 검색 · 프로젝트 전환 · 전체 검색 · 검증 및 생성. 단일 설정으로 가능합니다.

Alcove CLI 데모

alcove search · 프로젝트 전환 · --scope global · alcove validate

문제점

두 가지 나쁜 선택지밖에 없습니다.

옵션 A: CLAUDE.md / AGENTS.md에 문서 넣기 모든 파일이 실행될 때마다 컨텍스트 창에 주입됩니다. 짧은 규칙에는 효과적이지만, 실제 프로젝트 문서에는 적합하지 않습니다. 아키텍처 파일 10개 = 컨텍스트 비대화 = 응답 속도 저하, 비용 증가, 정확도 감소.

옵션 B: 문서 넣지 않기 에이전트가 이미 문서화한 요구사항을 새로 만들어냅니다. 이미 내린 결정의 제약 사항을 무시합니다. 매 세션마다 같은 내용을 설명하라고 요구합니다.

어느 쪽도 확장성이 없습니다. 이제 이를 5개의 프로젝트와 3개의 에이전트에 곱해보세요. 각각 다르게 설정되어 있습니다. 전환할 때마다 컨텍스트를 잃게 됩니다.

Alcove의 해결책

Alcove은 문서를 주입하지 않습니다. 에이전트가 필요할 때 필요한 것을 검색합니다.

~/projects/my-app $ claude "how is auth implemented?"

  → Alcove detects project: my-app
  → BM25 search: "auth" → ARCHITECTURE.md (score: 0.94), DECISIONS.md (score: 0.71)
  → Agent gets the 2 most relevant docs, not all 12

~/projects/my-api $ codex "review the API design"

  → Alcove detects project: my-api
  → Same doc structure, same access pattern
  → Different project, zero reconfiguration

언제든지 에이전트를 전환하세요. 언제든지 프로젝트를 전환하세요. 문서 계층은 표준화된 상태로 유지됩니다.

올바른 분리

**CLAUDE.md / AGENTS.md**는 에이전트 동작을 위한 것입니다: 피해야 할 반복적인 실수, 코딩 규칙, 세션별 지침. 200줄 미만으로 유지하세요.

Alcove는 프로젝트 지식을 위한 것입니다: 아키텍처, 결정 사항, 런북, API 문서 등 에이전트가 이해해야 하지만 매번 실행할 필요는 없는 모든 것.

패턴:

CLAUDE.md | AGENTS.md                             ← agent rules, coding conventions, recurring corrections
~/.config/alcove/docs/my-app/
  ARCHITECTURE.md                      ← tech stack, data model, system design
  DECISIONS.md                         ← why X was chosen over Y
  DEBT.md                              ← known issues, workarounds
  ...                                  ← agent searches here when it needs context

에이전트가 search_project_docs("auth flow")를 호출하면 12개 전체가 아닌 가장 관련성 높은 2개의 문서만 가져옵니다. 실제로 필요하지 않으면 컨텍스트 창에 아무것도 들어가지 않습니다.

왜 Alcove인가

왜 그냥 CLAUDE.md를 쓰지 않나요? 짧은 규칙과 에이전트 동작은 거기에 두는 것이 맞습니다. 프로젝트 문서(아키텍처, 결정 사항, 런북, PRD)는 컨텍스트 파일에서 확장되지 않습니다. Alcove은 대체품이 아니라, CLAUDE.md가 결코 의도하지 않았던 계층입니다.

Alcove 없이	Alcove와 함께
`CLAUDE.md`에 문서를 넣으면 매번 컨텍스트 비대화
Notion, Google Docs, 로컬 파일에 흩어진 내부 문서	하나의 문서 저장소, 프로젝트별 구조화
각 AI 에이전트마다 문서 액세스 설정 필요	단일 설정, 모든 에이전트가 동일한 액세스 공유
프로젝트 전환 시 컨텍스트 재설명 필요	CWD 자동 감지, 즉각적인 프로젝트 전환
에이전트 검색 시 무작위 일치 라인 반환	순위가 매겨진 결과 — 가장 일치하는 항목 우선, 파일당 하나
"OAuth에 대한 내 모든 메모 검색" — 불가능	한 번의 쿼리로 모든 프로젝트 전체 검색
프로젝트 저장소에 방치된 민감한 문서	로컬 머신에 비공개 문서 보관, 공개 저장소에 절대 노출 안 됨
프로젝트 및 팀원마다 다른 문서 구조	`policy.toml`로 모든 프로젝트의 표준 강제
문서 완성 여부 확인 불가	`validate`로 누락된 파일, 빈 템플릿, 누락된 섹션 포착
9개 이상의 에이전트와 호환	Claude Code, Cursor, Claude Desktop, Cline, OpenCode, Codex, Copilot, Antigravity, Gemini CLI

빠른 시작

# macOS
brew install epicsagas/alcove/alcove

# Linux / Windows — pre-built binary (fast, no compilation)
cargo install cargo-binstall
cargo binstall alcove

# Any platform — build from source
cargo install alcove

# Clone and build
git clone https://github.com/epicsagas/alcove.git
cd alcove
make install

alcove setup

참고: Linux (x86_64), macOS (Apple Silicon & Intel), Windows용 사전 빌드 바이너리가 제공됩니다.

setup은 대화형으로 모든 과정을 안내합니다:

문서 위치
추적할 문서 카테고리
선호하는 다이어그램 형식
구성할 AI 에이전트 (MCP + 스킬 파일)

설정을 변경하려면 언제든지 alcove setup을 다시 실행하세요. 이전 선택 사항을 기억합니다.

작동 방식

flowchart LR
    subgraph Projects["Your projects"]
        A1["my-app/\n  src/ ..."]
        A2["my-api/\n  src/ ..."]
    end

    subgraph Docs["Your private docs (one repo)"]
        D1["my-app/\n  PRD.md\n  ARCH.md"]
        D2["my-api/\n  PRD.md\n  ..."]
        P1["policy.toml"]
    end

    subgraph Agents["Any MCP agent"]
        AG["Claude Code · Cursor\nGemini CLI · Codex · Copilot\n+4 more"]
    end

    subgraph MCP["Alcove MCP server"]
        T["search · get_file\noverview · audit\ninit · validate"]
    end

    A1 -- "CWD detected" --> D1
    A2 -- "CWD detected" --> D2
    Agents -- "stdio MCP" --> MCP
    MCP -- "scoped access" --> Docs

문서는 별도의 디렉토리(DOCS_ROOT)에 프로젝트당 하나의 폴더로 구성됩니다. Alcove은 그곳의 문서를 관리하고 stdio를 통해 모든 MCP 호환 AI 에이전트에 제공합니다. 에이전트는 search_project_docs("auth flow")와 같은 도구를 호출하여 어떤 에이전트를 사용하든 프로젝트별 순위가 매겨진 결과를 얻습니다.

기능

온디맨드 문서 검색 — 에이전트가 검색하고 가져옵니다. 컨텍스트에 미리 로드되지 않습니다.
BM25 순위 검색 — tantivy 기반의 빠른 전체 텍스트 검색. 가장 관련성 높은 문서 우선, 자동 인덱싱, grep으로 폴백.
하나의 문서 저장소, 다중 프로젝트 — 프로젝트별로 구성된 비공개 문서, 한 곳에서 관리.
단일 설정, 모든 에이전트 — 한 번 설정하면 모든 MCP 호환 에이전트가 동일한 액세스 권한을 가짐.
CWD에서 프로젝트 자동 감지 — 프로젝트별 설정 불필요.
범위 지정 액세스 — 각 프로젝트는 자신의 문서만 볼 수 있음.
프로젝트 간 검색 — scope: "global"로 모든 프로젝트를 한 번에 검색.
비공개 문서는 비공개로 유지 — 문서는 공개 저장소에 절대 닿지 않으며, stdio를 통해 로컬 머신에서 완전히 실행됨.
표준화된 문서 구조 — policy.toml로 모든 프로젝트와 팀에 걸쳐 일관된 문서 강제.
교차 저장소 감사 — 프로젝트 저장소에 잘못 배치된 내부 문서를 찾아 수정 제안.
문서 검증 — 누락된 파일, 채워지지 않은 템플릿, 필수 섹션 확인.
9개 이상의 에이전트와 호환 — Claude Code, Cursor, Claude Desktop, Cline, OpenCode, Codex, Copilot, Antigravity, Gemini CLI.

MCP 도구

도구	기능
`get_project_docs_overview`	분류 및 크기를 포함한 모든 문서 나열
`search_project_docs`	스마트 검색 — BM25 순위 또는 grep 자동 선택, 프로젝트 간 검색을 위한 `scope: "global"` 지원
`get_doc_file`	경로별 특정 문서 읽기 (대용량 파일의 경우 `offset`/`limit` 지원)
`list_projects`	문서 저장소의 모든 프로젝트 표시
`audit_project`	교차 저장소 감사 — 문서 저장소 및 로컬 프로젝트 저장소 스캔, 작업 제안
`init_project`	새 프로젝트를 위한 문서 스캐폴딩 (내부 + 외부 문서, 선택적 파일 생성)
`validate_docs`	팀 정책(`policy.toml`)에 따라 문서 검증
`rebuild_index`	전체 텍스트 검색 인덱스 재구축 (보통 자동)
`check_doc_changes`	마지막 인덱스 빌드 이후 추가, 수정, 삭제된 문서 감지

CLI

alcove              Start MCP server (agents call this)
alcove setup        Interactive setup — re-run anytime to reconfigure
alcove doctor       Check the health of your alcove installation
alcove validate     Validate docs against policy (--format json, --exit-code)
alcove index        Build or rebuild the full-text search index for ranked search
alcove search       Search docs from the terminal
alcove uninstall    Remove skills, config, and legacy files

검색

Alcove은 자동으로 최상의 검색 전략을 선택합니다. 검색 인덱스가 존재하면 tantivy 기반의 BM25 순위 검색을 사용하여 관련성 점수가 매겨진 결과를 제공합니다. 인덱스가 없으면 grep으로 폴백합니다. 신경 쓸 필요가 없습니다.

# Search the current project (auto-detected from CWD)
alcove search "authentication flow"

# Force grep mode if you want exact substring matching
alcove search "FR-023" --mode grep

인덱스는 MCP 서버가 시작될 때 백그라운드에서 자동으로 빌드되며, 파일 변경이 감지되면 재빌드됩니다. 크론 작업이나 수동 단계가 없습니다.

에이전트 작동 방식: 에이전트는 쿼리와 함께 search_project_docs를 호출하기만 하면 됩니다. Alcove은 순위 지정, 중복 제거(파일당 하나의 결과), 프로젝트 간 검색, 폴백을 처리합니다. 에이전트는 검색 모드를 선택할 필요가 없습니다.

전체 검색

모든 아키텍처 결정, 모든 런북, 모든 프로젝트 메모를 모든 프로젝트에서 한 번에 검색할 수 있습니다.

# Search across ALL projects
alcove search "rate limiting patterns" --scope global
alcove search "OAuth token refresh" --scope global

에이전트도 search_project_docs에서 scope: "global"을 사용하여 동일하게 수행할 수 있습니다. 하나의 쿼리로 모든 프로젝트를 검색합니다.

프로젝트 감지

기본적으로 Alcove은 터미널의 작업 디렉토리(CWD)에서 현재 프로젝트를 감지합니다. MCP_PROJECT_NAME 환경 변수로 이를 재정의할 수 있습니다:

MCP_PROJECT_NAME=my-api alcove

이는 CWD가 문서 저장소의 프로젝트 이름과 일치하지 않을 때 유용합니다.

문서 정책

문서 저장소의 policy.toml로 팀 전체의 문서 표준을 정의하세요:

[policy]
enforce = "strict"    # strict | warn

[[policy.required]]
name = "PRD.md"
aliases = ["prd.md", "product-requirements.md"]

[[policy.required]]
name = "ARCHITECTURE.md"

  [[policy.required.sections]]
  heading = "## Overview"
  required = true

  [[policy.required.sections]]
  heading = "## Components"
  required = true
  min_items = 2

정책 파일은 우선순위에 따라 해결됩니다: 프로젝트 (<project>/.alcove/policy.toml) > 팀 (DOCS_ROOT/.alcove/policy.toml) > 기본값 (핵심 config.toml 파일에서). 이를 통해 모든 프로젝트에서 일관된 문서 품질을 보장하면서 프로젝트별 재정의를 허용합니다.

문서 분류

Alcove은 문서를 계층별로 분류합니다:

분류	위치	예시
doc-repo-required	Alcove (비공개)	PRD, 아키텍처, 결정 사항, 규칙
doc-repo-supplementary	Alcove (비공개)	배포, 온보딩, 테스트, 런북
reference	Alcove `reports/` 폴더	감사 보고서, 벤치마크, 분석
project-repo	GitHub 저장소 (공개)	README, CHANGELOG, CONTRIBUTING

audit 도구는 문서 저장소와 로컬 프로젝트 디렉토리를 모두 스캔한 다음, 비공개 PRD에서 공개 README를 생성하거나 잘못 배치된 보고서를 Alcove으로 다시 가져오는 등의 작업을 제안합니다.

구성

설정은 ~/.config/alcove/config.toml에 있습니다:

docs_root = "/Users/you/documents"

[core]
files = ["PRD.md", "ARCHITECTURE.md", "PROGRESS.md", "DECISIONS.md", "CONVENTIONS.md", "SECRETS_MAP.md", "DEBT.md"]

[team]
files = ["ENV_SETUP.md", "ONBOARDING.md", "DEPLOYMENT.md", "TESTING.md", ...]

[public]
files = ["README.md", "CHANGELOG.md", "CONTRIBUTING.md", "SECURITY.md", ...]

[diagram]
format = "mermaid"

이 모든 것은 alcove setup을 통해 대화형으로 설정됩니다. 파일을 직접 편집할 수도 있습니다.

파일 목록은 완전히 사용자 정의할 수 있습니다. 팀의 워크플로우에 맞게 카테고리에 파일 이름을 추가하거나 카테고리 간에 파일을 이동하세요:

[core]
files = ["PRD.md", "ARCHITECTURE.md", "DECISIONS.md", "MY_SPEC.md"]  # added custom doc

[public]
files = ["README.md", "CHANGELOG.md", "PRD.md"]  # PRD exposed as public for this project

지원되는 에이전트

에이전트	MCP	스킬
Claude Code	`~/.claude.json`	`~/.claude/skills/alcove/`
Cursor	`~/.cursor/mcp.json`	`~/.cursor/skills/alcove/`
Claude Desktop	플랫폼 설정	—
Cline (VS Code)	VS Code globalStorage	`~/.cline/skills/alcove/`
OpenCode	`~/.config/opencode/opencode.json`	`~/.opencode/skills/alcove/`
Codex CLI	`~/.codex/config.toml`	`~/.codex/skills/alcove/`
Copilot CLI	`~/.copilot/mcp-config.json`	`~/.copilot/skills/alcove/`
Antigravity	`~/.gemini/antigravity/mcp_config.json`	—
Gemini CLI	`~/.gemini/settings.json`	`~/.gemini/skills/alcove/`

스킬을 지원하는 에이전트는 프로젝트 아키텍처, 규칙, 결정 사항 또는 상태에 대해 질문할 때 Alcove을 자동으로 활성화합니다. 명시적으로 호출할 수도 있습니다:

/alcove                          Summarize current project docs and status
/alcove search auth flow         Search docs for a specific topic
/alcove what conventions apply?  Ask a doc question directly

지원되는 언어

CLI는 시스템 로캘을 자동으로 감지합니다. ALCOVE_LANG 환경 변수로 재정의할 수도 있습니다.

언어	코드
English	`en`
한국어	`ko`
简体中文	`zh-CN`
日本語	`ja`
Español	`es`
हिन्दी	`hi`
Português (Brasil)	`pt-BR`
Deutsch	`de`
Français	`fr`
Русский	`ru`

# Override language
ALCOVE_LANG=ko alcove setup

Alcove

데모

문제점