프로젝트 코드 인텔리전스

코딩 에이전트를 위한 저장소 인텔리전스 및 변경 안전성 증거.

프로젝트 코드 인텔리전스(PCI)는 Git 저장소를 인덱싱하고 코딩 에이전트에게 연구, 리팩토링, 유지보수, 보안 작업을 위한 구조화된 증거를 제공합니다. 에이전트는 개념이나 식별자로 검색하고, 후보 관계를 검사하고, 변경의 폭발 반경(blast radius)을 추정하고, 반복되는 구현 형태를 찾고, 코드를 편집하기 전에 정적 분석 결과를 조회할 수 있습니다.

PCI는 자율 검토자가 아니며, 그 그래프는 컴파일러 수준의 호출 그래프가 아닙니다. PCI는 발견 범위를 좁히고 증거를 제공합니다. 에이전트는 여전히 중요한 결론을 소스에서 검증해야 합니다.

도움이 되는 분야

연구 및 방향 파악

• 정확한 식별자, 파일 이름, 구성 키, 알려진 문자열을 검색합니다.

• 관련 이름을 모를 때 동작으로 검색합니다.

• 저장소 언어, 파일 역할, 스냅샷, 파서 적용 범위, 인덱스 최신 상태를 검사합니다.

• 경로, 줄 범위, 메타데이터, 소스 스니펫이 포함된 제한된 레코드를 가져옵니다.

• 명명된 컬렉션과 저장소 필터를 통해 여러 저장소를 작업합니다.

더 안전한 변경

• 후보 호출자, 피호출자, 참조, 테스트, 모듈 수준 연결을 찾습니다.

• 심볼을 제거, 이름 변경 또는 변경하기 전에 폭발 반경 증거를 확인합니다.

• 진입점, 고아, 테스트 커버리지 신호를 표면화합니다.

• 정의가 추가되거나 제거될 때 지원되는 코딩 에이전트에 인접 증거를 주입합니다.

유지보수 및 중복

• 호출 형태 모티프를 반복하는 함수 그룹을 찾습니다.

• 유사성, 추정 추상화 비용, 예상 순 가치로 중복 후보를 순위화합니다.

• 오래된 인덱스, 중복 이름, 중복 후보, 정적 분석 결과에 대한 저장소 감사를 실행합니다.

보안 및 정적 분석

• 소스 레코드와 함께 SARIF 보고서를 수집합니다.

• 도구, 규칙, 수준, 기준선 상태 또는 경로로 정규화된 결과를 검색합니다.

• 에이전트가 원시 SARIF 아티팩트를 파싱하지 않고 진단, 코드 흐름, 실행 메타데이터를 가져옵니다.

Related MCP server: Graft

작동 방식

pci index는 저장소 파일을 제한된 레코드로 파싱하고, 메타데이터와 후보 관계를 추출하며, 스냅샷을 Postgres/pgvector에 저장합니다. 의미론적 임베딩은 선택 사항입니다. --no-embed를 사용해도 어휘 검색과 대부분의 구조적 증거를 사용할 수 있습니다.

pci mcp는 로컬 stdio MCP 서버를 통해 인덱스를 노출합니다. 코딩 에이전트는 필터 중심 도구를 사용하여 관련성이 높은 코드를 발견한 다음, 조치를 취하기 전에 실제 소스를 읽고 검증합니다.

기본 로컬 아키텍처는 다음과 같습니다:

• Postgres/pgvector: Docker 또는 Podman Compose.

• Linux 임베딩 서비스: 사용자 systemd로 관리되는 Podman Quadlet 유닛.

• Apple Silicon 임베딩: 네이티브 MLX 서비스.

• 에이전트 통합: stdio MCP 서버, 선택적 편집 증거 훅 포함.

의도적인 트레이드오프가 있는 경우 원격 Postgres 및 OpenAI 호환 임베딩 엔드포인트가 지원됩니다.

빠른 시작

체크아웃에서 CLI를 설치합니다:

uv tool install /path/to/project-code-intelligence
export PATH="$HOME/.local/bin:$PATH"

번들된 데이터베이스와 사용 가능한 최상의 로컬 임베딩 백엔드를 시작합니다:

pci doctor --start
pci doctor

Git 저장소를 인덱싱합니다:

cd /path/to/repo
pci index .

코딩 에이전트용 MCP 구성을 설치합니다:

pci mcp install --target codex

지원 대상에는 claude, codex, opencode, pi, vscode, copilot, cline, zed가 포함됩니다. 클라이언트별 설정, 프로젝트 범위 지정, 자격 증명 처리는 docs/MCP_SETUP.md를 참조하세요.

임베딩 없이 어휘 검색을 하려면:

pci doctor --start-db
pci index --no-embed .

핵심 에이전트 도구

전체 트리 증거 보고서를 보려면 pci audit를 실행하세요.

증거이지 판결이 아닙니다

PCI는 의도적으로 더 강력한 인덱스 사실과 근사적·휴리스틱 증거를 구분합니다.

• 후보 관계 엣지는 타입 검사된 호출 그래프 사실이 아닙니다.

• 폭발 반경은 변경이 안전하다는 것을 증명할 수 없습니다.

• 중복 점수는 두 함수가 추상화를 공유해야 하는지 결정할 수 없습니다.

• 정적 분석 결과는 원래 분석기의 한계를 그대로 유지합니다.

• 커밋되지 않거나 새로 커밋된 변경 후 인덱스가 오래될 수 있습니다.

• 의미론적 검색은 관련 코드를 놓치거나 그럴듯한 이웃을 반환할 수 있습니다.

중요한 호출자와 결과를 실제 소스에서 검증하세요. 알려진 경로와 작은 제한된 질문에는 직접 파일 읽기를 사용하세요. PCI는 위치, 이름 또는 영향이 아직 알려지지 않았을 때 가장 유용합니다.

설치

Python CLI

uv로 현재 사용자용으로 설치합니다:

uv tool install /path/to/project-code-intelligence

편집 가능한 개발 설치의 경우:

cd /path/to/project-code-intelligence
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .

Nix

flakes가 활성화된 NixOS 또는 다른 Linux 호스트에서:

nix build
nix run . -- doctor --skip-db --embedding skip
nix develop

사용자 프로필에 영구적으로 설치합니다:

nix profile install .#project-code-intelligence

Nix 클로저에는 CLI, MCP 서버, Python 종속성, 번들된 Compose 및 Quadlet 자산이 포함됩니다. 무거운 Linux 임베딩 런타임은 호스트 네이티브 Nix 종속성이 되는 대신 Podman 컨테이너에 유지됩니다.

로컬 데이터베이스

번들된 Postgres/pgvector 데이터베이스만 시작합니다:

pci doctor --start-db

설치된 Compose 파일은 사용자 캐시에 구체화됩니다. 대신 사용자 지정 복사본을 사용하려면:

export PCI_COMPOSE_FILE=/path/to/docker-compose.yml
pci doctor --start-db

로컬 임베딩 서비스

CLI에는 서비스 템플릿이 포함되어 있습니다. 별도의 PCI 임베딩 패키지는 없습니다. Linux에서 Podman을 설치하고 systemctl --user가 작동하는지 확인한 후 다음을 실행하세요:

pci doctor
pci doctor --start-embedding

PCI는 사용 가능한 하드웨어를 감지하고, 선택한 백엔드만 ~/.config/containers/systemd/ 아래에 구체화하고, 사용자 systemd를 다시 로드한 후 시작합니다. 다른 임베딩 백엔드에 대한 오래된 PCI 유닛은 중지되고 제거됩니다. 이미지와 기본 모델은 첫 사용 시 다운로드됩니다.

원하는 경우 백엔드를 명시적으로 선택합니다:

# AMD GPU
pci doctor --start-embedding --embedding-backend rocm

# NVIDIA GPU
pci doctor --start-embedding --embedding-backend cuda

# Portable CPU fallback
pci doctor --start-embedding --embedding-backend fastembed

# AMD Ryzen AI NPU (experimental)
pci doctor --start-embedding --embedding-backend lemonade

사용 가능한 선택자는 auto, fastembed, lemonade, rocm, cuda, apple입니다. PCI는 필요한 하드웨어나 런타임을 사용할 수 없을 때 요청된 백엔드를 거부합니다. apple은 Quadlet이 아닌 네이티브로 실행됩니다.

데이터베이스와 명시적 백엔드를 함께 시작하려면:

pci doctor --start --embedding-backend rocm

컨테이너화된 백엔드는 기본적으로 http://127.0.0.1:18081/v1/embeddings에서 OpenAI 호환 엔드포인트를 게시합니다. 이 엔드포인트를 공유하므로 한 번에 하나의 로컬 백엔드만 실행하세요.

데이터베이스를 건드리지 않고 임베딩 서비스를 중지합니다:

pci doctor --stop-embedding

생성된 로컬 서비스, 캐시, 번들된 데이터베이스 볼륨을 제거합니다:

pci doctor --clean

--clean은 파괴적이며 데이터를 제거하기 전에 확인을 요청합니다.

원격 임베딩

데이터베이스만 시작한 다음 신뢰할 수 있는 OpenAI 호환 공급자를 구성합니다:

pci doctor --start-db
export PCI_ALLOW_REMOTE_EMBEDDING=1
export PCI_EMBEDDING_ENDPOINT=https://api.openai.com/v1/embeddings
export PCI_EMBEDDING_ENDPOINT_MODEL=text-embedding-3-small
export OPENAI_API_KEY=...
pci doctor

원격 엔드포인트는 소스에서 파생된 텍스트를 수신합니다. 인덱싱 중인 저장소에 허용되는 경우에만 활성화하세요.

저장소 인덱싱

하나의 저장소를 인덱싱합니다:

pci index /path/to/repo

여러 저장소를 워크스페이스로 인덱싱합니다:

cd /path/to/workspace
pci index service-api web-ui shared-lib

PCI는 경로에서 컬렉션과 저장소 이름을 유추합니다. MCP 클라이언트는 절대 파일 시스템 경로가 아닌 이러한 논리적 이름으로 필터링합니다. 인덱싱은 증분식입니다. 호환 가능한 스냅샷이 있으면 변경되지 않은 파일이 재사용됩니다.

인덱싱된 저장소 경로에서 발견된 SARIF 보고서는 자동으로 수집됩니다. 하나의 저장소를 재설정하고 다시 빌드하려면:

pci index --reset /path/to/repo

pci status를 사용하여 인덱싱 실행을 검사하고, pci index --help를 사용하여 파서, 임베딩, 컬렉션, 데이터베이스 옵션을 확인하세요.

MCP 및 에이전트 훅

프로젝트 범위의 읽기 전용 데이터베이스 자격 증명을 만들고 MCP 구성을 출력합니다:

pci index --init-db --mcp-config codex .

재인덱싱 없이 MCP 구성을 설치하거나 제거합니다:

pci mcp install --target codex
pci mcp install --target codex --uninstall

생성된 클라이언트 구성에는 데이터베이스 비밀번호가 포함되지 않습니다. 자격 증명은 사용자의 PCI 구성 디렉터리에 모드 0600으로 저장됩니다. Pi는 프로젝트 로컬 .pi/extensions/ MCP 브리지를 사용합니다. Cline은 설정 파일이 사용자 범위이므로 --config-path가 필요합니다.

선택적 훅은 에이전트에게 인덱스 사용을 상기시키고 정의를 추가하거나 제거하는 편집 근처에 증거를 주입할 수 있습니다:

pci hook install --target codex

훅 지원 및 설치 세부 사항은 클라이언트에 따라 다릅니다. 훅은 보조 수단이지 강제 또는 정확성 메커니즘이 아닙니다. docs/MCP_SETUP.md 및 docs/SYSTEM_PROMPT.md를 참조하세요.

개인정보 보호 및 보안

로컬 기본값은 소스에서 파생된 레코드와 임베딩을 머신에 유지합니다. 그렇다고 모든 아티팩트를 게시해도 안전한 것은 아닙니다.

데이터베이스 덤프, 복원 아티팩트, SARIF 출력, 임베딩 캐시, 모델 파일, 벡터 인덱스, 비공개 저장소에서 생성된 데이터, 로컬 MCP 자격 증명 파일을 커밋하거나 배포하지 마세요. 여기에는 소스에서 파생된 소스 스니펫, 경로, 심볼, 결과, 메타데이터, 임베딩이 포함될 수 있습니다.

컬렉션은 저장소를 구성하지만 보안 경계는 아닙니다. 저장소에 더 강력한 격리가 필요한 경우 별도의 데이터베이스 또는 데이터베이스 사용자를 사용하세요. 프로젝트 범위의 MCP 자격 증명은 일반 액세스를 제한하지만 호스트 및 데이터베이스 보안을 대체하지는 않습니다.

PCI가 적합한 경우

PCI는 다음과 같은 경우에 도움이 되는 경향이 있습니다:

• 저장소 또는 워크스페이스가 크거나 익숙하지 않은 경우;

• 작업 시작 시 식별자를 모르는 경우;

• 생성된 파일로 인해 광범위한 읽기가 비용이 많이 들거나 노이즈가 많은 경우;

• 리팩토링에 호출자, 테스트, 연결 증거가 필요한 경우;

• 유지보수 작업에 반복 패턴 발견이 필요한 경우;

• 정적 분석 결과를 소스와 연관시켜야 하는 경우;

• 여러 저장소를 하나의 인터페이스로 검색해야 하는 경우.

작고 익숙한 저장소, 알려진 파일 및 줄 범위, 또는 제한된 rg나 파일 읽기 하나로 답할 수 있는 질문에는 가치가 거의 없을 수 있습니다. 목표는 표준 개발자 도구를 대체하는 것이 아니라 그 주변의 불확실한 발견 및 변경 계획 단계를 개선하는 것입니다.

토큰 및 비용 절감은 유용한 부수 효과일 수 있지만 PCI는 이를 보장하지 않습니다. docs/EVALUATING_VALUE.md 및 세션 회고 프롬프트를 사용하여 인덱스가 실제 세션을 개선하는지 측정하세요.

개발

MCP 서버는 stdio를 사용합니다. Docker Compose는 로컬 데이터베이스용이지 MCP 프로세스를 호스팅하기 위한 것이 아닙니다. 전체 개발 게이트를 실행하려면:

nix develop
make check

수집, 데이터베이스 또는 MCP 동작 변경의 경우 다음도 실행하세요:

docker compose up -d pgvector
make integration-smoke

프로젝트 규칙 및 게시 보호 조치는 CONTRIBUTING.md 및 AGENTS.md를 참조하세요.

문서

• docs/MCP_SETUP.md — MCP 클라이언트, 범위, 자격 증명 및 보안 모델

• docs/PUBLIC_API.md — CLI, 환경, MCP 및 Python 호환성 표면

• docs/EVALUATING_VALUE.md — 실제 코딩 세션에서 PCI 평가

• docs/SYSTEM_PROMPT.md — PCI 사용을 위한 에이전트 지침

• docs/SYSTEM_PROMPT_RATIONALE.md — 프롬프트 설계 근거

• docs/SESSION_RETROSPECTIVE_PROMPT.md — 세션 종료 평가 프롬프트

• .env.example — 환경 구성 참조

• CONTRIBUTING.md — 개발 워크플로

라이선스

MIT. LICENSE를 참조하세요.