Getting Started

이 문서는 누구를 위한 것인가

이 문서는 신규 프로젝트에 RAGit을 처음 적용하면서 설치부터 첫 번째 검증 가능한 ingest까지 한 번에 끝내고 싶은 사용자를 위한 canonical onboarding입니다.

RAGit 저장소 자체를 개발하고 있다면 이 문서보다 Init Guide를 먼저 읽으십시오.

요구 사항

Git 저장소
Node.js 22.14+
pnpm 10+
Linux: libaio (Debian/Ubuntu에서는 sudo apt-get install libaio-dev)
로컬 초기화를 위한 zvec bootstrap 지원 플랫폼: darwin/arm64, linux/arm64

Node 24는 두 지원 대상 모두에서 검증합니다. 고정된 zvec 0.2.1 런타임은 Linux x64와 Windows x64를 지원하지 않으며, 미지원 대상에서는 native binding을 로드하기 전에 지원 매트릭스와 함께 실패합니다.

이 문서는 RAGit 2.0.0을 기준으로 합니다. 1.1.2에서 업그레이드하면 Node.js 최소 버전이 20.19.0에서 올라가고, 검증된 native matrix는 위의 ARM64 두 대상으로 좁아집니다. 기존 1.1.2 저장소는 release reopen-and-query gate로 검증하며, 2.0.0에서 새 쓰기를 수행한 뒤 downgrade에 의존하려면 먼저 .ragit을 백업하십시오.

설치 경로 선택

Published CLI

일반적인 신규 프로젝트 적용 경로라면 published CLI를 사용하는 편이 좋습니다.

npm install -g ragit
# 또는
pnpm add -g ragit
# 또는
bun add -g ragit

저장소 로컬 개발

이 경로는 RAGit 저장소 자체를 개발할 때만 사용하십시오.

pnpm install
pnpm ragit --help

Happy Path

published CLI 또는 로컬 저장소 스크립트로 RAGit을 설치합니다.
ragit init으로 저장소를 초기화합니다.
프로젝트의 최소 문서 세트를 작성하거나 검토합니다.
의도한 저장소 지식 상태를 커밋합니다.
해당 커밋을 대상으로 full ingest를 실행합니다.
ragit status와 ragit query로 결과를 확인합니다.

ragit init
git add AGENTS.md docs .ragit/config.toml .gitignore
git commit -m "initialize ragit knowledge"
ragit ingest --all
ragit status --format json
ragit query "project goal" --format json

RAGit 저장소를 직접 개발 중이라면 ragit 대신 pnpm ragit을 사용하십시오.

생성된 초안은 staging 전에 검토하십시오. 선택한 init 정책이 .ragit/config.toml을 ignore한다면 해당 정책이 추적 대상으로 유지하는 저장소 파일만 staging하고, ignore된 runtime state를 강제로 추가하지 마십시오.

RAGit은 searchable knowledge를 커밋에 결속합니다. Apply-mode ingest는 관련 문서 후보가 modified, deleted, untracked 상태이면 거부하며, 조회 명령은 worktree 변경을 제외했다는 warning과 함께 커밋된 snapshot을 계속 사용합니다.

Greenfield 최소 문서 세트

다음 에이전트가 프로젝트를 이해하기 위해 필요한 최소 세트부터 시작하십시오.

PRD 1개
SRS 또는 SPEC 1개
안정화된 결정을 남겨야 할 때만 ADR 1개

선택 단계

첫 번째 ingest가 성공한 뒤에는, 저장소 변경과 인덱싱을 더 가깝게 유지하고 싶을 때만 managed hooks를 설치하십시오.

ragit hooks install

완료 판정

다음 조건을 만족하면 신규 프로젝트 적용이 끝난 상태로 봅니다.

status에서 저장소가 초기화되고 인덱싱된 상태로 보입니다.
status.data.snapshot.status가 정확한 현재 HEAD에 대해 indexed입니다.
query가 관련 chunk를 반환하고 snapshotSha와 snapshot.resolvedSha에 같은 SHA를 보고합니다.
팀이 bootstrap 과정을 다시 읽지 않아도 문서만으로 다음 작업을 이어갈 수 있습니다.

첫 검증이 끝난 뒤에는 intent 기준으로 retrieval을 고르십시오. raw indexed hit가 필요하면 query, 다음 에이전트 단계에 넘길 bounded packet이 필요하면 context pack, working state까지 포함해 활성 작업을 재개해야 하면 memory recall을 사용하십시오.

검증이 실패하면 워크플로를 바꾸기 전에 doctor로 먼저 진단하십시오.

이 흐름은 commit-bound snapshot integrity를 확립하지만 완전한 production readiness를 보장하지는 않습니다. Exclusive ingest locking, crash recovery, retrieval evaluation, distribution matrix 검증은 별도 작업으로 남아 있습니다.