Init 가이드

신규 프로젝트에 RAGit을 적용하는 절차부터 보려면 먼저 Getting Started를 읽으십시오. 저장소 init 명령은 이제 discover-first bootstrap 흐름입니다. 저장소 루트 정규화, .ragit/** 준비, AGENTS.md, guide 자산, 빈 zvec store bootstrap은 유지하지만, 그 전에 먼저 저장소를 스캔해서 무엇을 이미 알고 있는지 판정합니다.

흐름

Git 문맥 확인 및 필요 시 git init
저장소 코드/문서/빌드 파일 스캔
empty, existing, docs-heavy, monorepo 모드 판정
문서 census, coverage 평가, maturity 평가 수행
기존 저장소 소스로 knowledge-slot map 구성
누락된 기초 문서를 계획하고 기존 문서를 먼저 재사용
1단계 draft 문서 작성 및 .ragit/** bootstrap
RAGit runtime data에 대한 .gitignore 정책 선택
zvec store bootstrap
최종 리포트와 next actions 출력

1단계 생성 문서

init은 1단계에서 아래 draft 문서만 생성할 수 있습니다.

RAGIT.md
docs/workspace-map.md
docs/ragit/ingestion-policy.md
docs/known-gaps.md
docs/adr/README.md

생성 문서는 모두 inferred draft로 표시되므로, 사람이 검증한 저장소 문서와 쉽게 구분할 수 있습니다.

`init`이 준비하는 것

Git 인지 저장소 루트 정규화
기존 문서 탐지와 coverage 평가
부족한 영역만 메우는 draft foundational docs
.ragit/config.toml
.ragit/guide/templates/*
.ragit/guide/guide-index.json
선택된 runtime-data 정책에 따른 .gitignore entries
.ragit/store/meta.json
documents, chunks 빈 zvec 컬렉션

`init`이 준비하지 않는 것

searchable corpus 생성 없음
zvec document/chunk 레코드 생성 없음
snapshot manifest 생성 없음
query-ready knowledge state 생성 없음

즉, init은 저장소 문서를 읽고 분류할 수는 있지만, searchable knowledge는 여전히 ingest부터 시작합니다.

Git 추적 선택

init은 durable project knowledge와 local runtime state를 분리합니다. --yes와 --non-interactive의 기본값은 safe policy이며, 생성된 runtime state를 Git 밖에 둡니다. 대화형 터미널 실행에서 manifest와 harness 질문에 다른 답을 해야 하는 경우는 해당 파일들이 저장소 계약의 일부일 때입니다.

저장소 형태	권장 policy	이유
제품 또는 애플리케이션 저장소	`safe`	log, report, security ledger, session state, manifest, harness artifact, store, cache를 로컬에만 둡니다.
snapshot history를 팀이 공유하는 저장소	`snapshot-history`	`.ragit/manifest/**`는 추적 가능하게 두고 runtime state는 로컬에 둡니다.
RAGit dogfooding 또는 testbed 저장소	`dogfood`	manifest와 reviewed harness artifact를 리뷰/재현 대상으로 추적할 수 있게 둡니다.

init 이후 git status에는 보통 .ragit/config.toml, .ragit/guide/**, .ragit/docs/index.json, AGENTS.md, RAGIT.md, 생성된 docs/** draft 같은 project-facing file이 보여야 합니다. .ragit/store/**, .ragit/cache/**, .ragit/log/**, .ragit/reports/**, .ragit/security/**, .ragit/memory/sessions/**, .ragit/memory/working/**, .ragit/artifacts/session/**는 보이지 않아야 합니다.

대표 시나리오

비어 있는 저장소

pnpm ragit init --yes --git-init
선택 모드: empty
기대 결과: foundational draft + control-plane/bootstrap 자산 생성

기존 코드베이스

pnpm ragit init
선택 모드: existing
기대 결과: 기존 문서 재사용, 누락된 draft만 추가, 핵심 문서 덮어쓰기 없음

문서가 풍부한 저장소

pnpm ragit init
선택 모드: docs-heavy
기대 결과: 재사용 비율 높음, 생성 문서 수 낮음

모노레포

pnpm ragit init
선택 모드: monorepo
기대 결과: apps/packages 구조가 workspace map과 knowledge map에 반영됨

Dry-run

pnpm ragit init --dry-run --output json

기대 결과:

전체 scan/coverage/maturity report 반환
create/reuse/skip 계획 반환
bootstrap.gitignore 아래에 planned .gitignore policy와 entries 반환
파일 시스템 변경 없음

비대화형 예시

pnpm ragit init --yes
pnpm ragit init --yes --git-init
pnpm ragit init --mode auto --strategy balanced --merge-existing --output json
pnpm ragit init --dry-run --output json

생성 구조

RAGIT.md
docs/
  adr/README.md
  known-gaps.md
  ragit/ingestion-policy.md
  workspace-map.md
.ragit/
  config.toml
  guide/
    guide-index.json
    templates/
  store/
    meta.json
    documents/
    chunks/

Init 가이드

On this page