@handsupmin/gc-tree 0.1.3 → 0.2.0

package/README.ko.md

@@ -1,166 +1,250 @@
 # gc-tree
 
-AI 코딩 도구를 위한 브랜치 기반 글로벌 컨텍스트 레이어.
+<div align="center">
+
+<img src="./logo.png" alt="gc-tree 로고" width="260" />
+
+### 프로젝트 밖까지 이어지는 글로벌 컨텍스트.
+
+기존 AI 도구 위에 오래 가는, 재사용 가능한 컨텍스트 레이어를 얹어보세요.
+Git 브랜치 다루듯 여러 컨텍스트를 나눠 관리할 수 있습니다.
+
+[![npm version](https://img.shields.io/npm/v/%40handsupmin%2Fgc-tree)](https://www.npmjs.com/package/@handsupmin/gc-tree)
+[![npm downloads](https://img.shields.io/npm/dm/%40handsupmin%2Fgc-tree)](https://www.npmjs.com/package/@handsupmin/gc-tree)
+[![GitHub stars](https://img.shields.io/github/stars/handsupmin/gc-tree)](https://github.com/handsupmin/gc-tree/stargazers)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](https://github.com/handsupmin/gc-tree/blob/main/LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
 
 [English](https://github.com/handsupmin/gc-tree/blob/main/README.md) | [한국어](https://github.com/handsupmin/gc-tree/blob/main/README.ko.md) | [简体中文](https://github.com/handsupmin/gc-tree/blob/main/README.zh.md) | [日本語](https://github.com/handsupmin/gc-tree/blob/main/README.ja.md) | [Español](https://github.com/handsupmin/gc-tree/blob/main/README.es.md)
 
-## 소개
+</div>
 
-`gctree`는 AI 코딩 도구를 위한 가벼운 **Global Context Tree**입니다.
-장기적으로 유지해야 하는 컨텍스트를 파일 기반으로 명시적으로 관리할 수 있게 해주며, 브랜치 단위로 분리해서 기존 워크플로에 자연스럽게 붙일 수 있습니다.
+---
 
-하나의 `AGENTS.md`, `CLAUDE.md`, 혹은 짧은 프롬프트 파일만으로는 부족해질 때 `gctree`는 다음을 도와줍니다.
+## 문제
 
-- 제품, 고객사, 업무 트랙별로 컨텍스트를 분리하기
-- 숨겨진 메모리 대신 markdown 기반의 source-of-truth 문서로 관리하기
-- 작은 인덱스와 summary-first 문서 구조로 필요한 컨텍스트를 빠르게 찾기
-- 선호하는 LLM CLI를 통해 온보딩과 장기 업데이트를 진행하기
-- 특정 gc-branch가 실제로 관련 있는 레포에만 적용되게 하기
+Claude Code나 Codex를 매일 씁니다. 그런데 실제 업무는 여러 레포, 제품, 고객사에 걸쳐 있고 — AI 도구는 현재 파일밖에 모릅니다.
 
-## 간단 특징
+그래서 매번 이렇게 됩니다:
 
-- **Provider 기반 온보딩**
-  `gctree init`은 `claude-code`, `codex`, `both` 중 어떤 provider 모드를 쓸지 묻고, 이어서 응답 언어를 고르게 한 뒤, 그 선택을 저장하고 필요한 명령 표면을 스캐폴딩한 다음 기본 `main` gc-branch 온보딩을 시작합니다.
-- **레포 범위 인식 gc-branch**
-  `~/.gctree/branch-repo-map.json`을 통해 하나의 gc-branch를 특정 레포 집합에만 연결할 수 있습니다. 예를 들어 A는 B/C/D에만 적용하고 F에서는 무시하게 만들 수 있습니다.
-- **인터랙티브 범위 가드**
-  `gctree resolve`가 현재 레포가 아직 이 gc-branch에 매핑되지 않았다고 판단하면, 이번만 진행할지 / 항상 사용할지 / 여기서는 무시할지를 물어볼 수 있습니다.
-- **Summary-first 문서 구조**
-  도구가 먼저 짧은 요약을 읽고, 필요할 때만 본문을 확장해서 읽을 수 있습니다.
-- **가이드형 장기 업데이트**
-  JSON 파일을 직접 만들지 않아도 같은 provider 흐름으로 글로벌 컨텍스트를 갱신할 수 있습니다.
+- 어떤 레포들이 한 묶음인지 다시 설명
+- 같은 아키텍처 문서를 또 프롬프트에 붙여넣기
+- 지난주에 "이미 알던" 컨벤션을 다시 알려주기
+- 현재 레포와 무관한 컨텍스트를 손으로 걷어내기
 
-## 설치 및 빠른 시작
+이건 AI 문제가 아닙니다. **컨텍스트 관리 문제**입니다.
 
-### npm으로 설치
+---
 
-```bash
-npm install -g @handsupmin/gc-tree
-```
+## gc-tree가 하는 일
 
-글로벌 설치 없이 한 번만 실행하려면:
+`gc-tree`는 **레포 위 레벨**에 위치합니다. 컨텍스트를 구조화된 마크다운 파일에 저장하고, AI 도구가 매 세션마다 관련된 것만 자동으로 가져오게 합니다.
 
 ```bash
-npx @handsupmin/gc-tree init
+gctree resolve --query "auth token rotation policy"
 ```
 
-- **패키지 이름:** `@handsupmin/gc-tree`
-- **CLI 명령어:** `gctree`
-- **요구 사항:** Node.js 20+
-소스 기반 개발은 [docs/local-development.md](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.md)를 참고하세요.
+```json
+{
+  "gc_branch": "main",
+  "matches": [
+    {
+      "title": "인증 & 세션 컨벤션",
+      "score": 4,
+      "summary": "모든 요청에서 JWT rotation, refresh token은 httpOnly 쿠키에 저장, access token TTL 15분",
+      "excerpt": "## 인증 플로우\nAccess token: 15분 TTL, 매 인증 요청마다 rotation..."
+    }
+  ]
+}
+```
 
-### 빠른 시작
+AI 도구가 올바른 컨텍스트를 가져옵니다. 지식 베이스 전체가 아니라 — 관련된 조각만.
 
-#### 1) gc-tree 초기화
+**실제로: 쿼리당 전체 컨텍스트의 ~4%만 주입됩니다.** 나머지 96%는 실제로 필요할 때까지 디스크에 남아 토큰 윈도우 밖에 있습니다.
 
-```bash
-gctree init
-```
+---
+
+## 이 도구가 맞는 사람
+
+다음에 해당하면 gc-tree를 제일 잘 쓸 수 있습니다:
+
+- **여러 레포**에 걸쳐 일하는 경우 (모노레포 팀, 플랫폼 + 클라이언트 레포, 백엔드 + 프론트엔드 스택)
+- 같은 주에 **여러 제품이나 고객사** 사이를 오가는 경우
+- AI 세션 시작마다 **같은 컨텍스트를 반복 설명**하는 경우
+- AI 도구가 현재 파일뿐 아니라 **컨벤션, 아키텍처, 도메인 지식**도 알길 원하는 경우
+
+레포 하나, 제품 하나에서만 일한다면 굳이 이 도구가 필요 없습니다. `CLAUDE.md`나 `.cursorrules`로 충분합니다.
+
+---
+
+## CLAUDE.md나 cursor rules와 뭐가 다른가요?
+
+`CLAUDE.md`는 훌륭합니다 — 레포 하나에서는요.
+
+여러 레포, 고객사, 워크스트림이 생기는 순간:
+
+| | `CLAUDE.md` / cursor rules | `gc-tree` |
+|---|---|---|
+| 범위 | 레포 하나 | 여러 레포, 컨텍스트 하나 |
+| 지속성 | 레포 내 파일 | 레포 밖 저장, 세션 간 재사용 |
+| 컨텍스트 전환 | 파일 직접 수정 | `gctree checkout client-b` |
+| 관련성 필터링 | 전부 아니면 없음 | 매칭 문서만 주입 (~4%) |
+| 온보딩 | 손으로 작성 | AI 도구가 가이드 |
+| Codex 지원 | ✅ | ✅ |
+| Claude Code 지원 | ✅ | ✅ |
+
+---
+
+## 검증된 성능
+
+실제 내부 문서 기준 테스트 (Notion 내보내기 4종, 한국어 + 영어 혼합 쿼리):
 
-이 명령은 다음을 수행합니다.
+| 지표 | 결과 |
+|---|---|
+| Recall — 관련 쿼리가 올바른 문서를 찾는 비율 | **100%** (16/16) |
+| Precision — 무관 쿼리가 빈 결과를 반환하는 비율 | **80%** (4/5) |
+| F1 점수 | **88.9%** |
+| 쿼리당 주입 토큰 비율 (전체 컨텍스트 대비) | **~4%** |
+| 한국어 + 영어 혼합 쿼리 지원 | ✅ |
 
-- `~/.gctree` 생성
-- 기본 `main` gc-branch 생성
-- 사용할 provider 모드(`claude-code`, `codex`, `both`) 선택
-- `both`를 고르면 이번 온보딩을 어느 provider로 시작할지 한 번 더 선택
-- 사용할 언어(`English`, `Korean`, 또는 직접 입력한 언어) 선택
-- provider 모드, 실제 온보딩 provider, 언어를 `~/.gctree/settings.json`에 저장
-- 현재 환경에 맞는 명령 표면 스캐폴딩
-- `main`이 비어 있으면 활성 gc-branch에 대한 가이드형 온보딩 시작
+---
 
-#### 2) 현재 컨텍스트 조회
+## Claude Code와 Codex 양쪽 모두 검증 완료
 
 ```bash
-gctree resolve --query "auth token rotation"
+gctree scaffold --host claude-code   # CLAUDE.md 스니펫 + /gc-onboard, /gc-update-global-context 설치
+gctree scaffold --host codex         # AGENTS.md 스니펫 + $gc-onboard, $gc-update-global-context 설치
+gctree scaffold --host both          # 둘 다 한번에
 ```
 
-만약 현재 레포가 이 gc-branch의 매핑 범위 밖이라면, `gctree`는 다음 중 하나를 고르게 할 수 있습니다.
+두 프로바이더 모두 동일한 컨텍스트 저장소를 씁니다. 한 번 온보딩하면 어느 도구에서든 사용 가능.
 
-1. 이번만 진행
-2. 이 레포에서 항상 이 gc-branch 사용
-3. 이 레포에서는 이 gc-branch 무시
+**Claude Code** — `/gc-resolve-context`, `/gc-onboard`, `/gc-update-global-context` 슬래시 커맨드 사용.
 
-2번 또는 3번을 고르면 `~/.gctree/branch-repo-map.json`이 갱신됩니다.
+**Codex** — `$gc-resolve-context`, `$gc-onboard`, `$gc-update-global-context` 스킬 사용. `codex exec`으로 직접 검증됨:
 
-#### 3) 별도 컨텍스트가 필요하면 새 gc-branch 생성
+```
+gctree status → gc_branch: main, doc_count: 2
+gctree resolve --query 'NestJS DTO plainToInstance'
+→ "백엔드 코딩 컨벤션" 매칭 (score: 3)
+→ DTO: class-transformer plainToInstance, class-validator 필수
+→ 에러 처리: HttpException 기반 커스텀 예외, raw Error throw 금지
+```
+
+---
+
+## 설치 & 빠른 시작
 
 ```bash
-gctree checkout -b client-b
+npm install -g @handsupmin/gc-tree
+gctree init
 ```
 
-`checkout -b`는 **새로운 빈 gc-branch**를 만듭니다. 기존 브랜치 문서를 복사하지 않습니다.
+`gctree init`이 안내합니다:
+1. 프로바이더 선택: `claude-code`, `codex`, 또는 `both`
+2. 현재 레포에 통합 파일 스캐폴딩
+3. `main` gc-branch 가이드형 온보딩 실행
+
+이후 AI 도구가 계획·구현 전에 `gctree resolve`를 호출하는 법을 자동으로 알게 됩니다.
+
+- **CLI:** `gctree`
+- **요구 사항:** Node.js 20+
+
+---
+
+## 자주 쓰는 흐름
 
-#### 4) 비어 있는 gc-branch를 온보딩
+### 워크스트림마다 별도 컨텍스트
 
 ```bash
+gctree checkout -b client-b
 gctree onboard
 ```
 
-#### 5) 나중에 장기 컨텍스트 업데이트
+각 gc-branch는 완전히 독립된 컨텍스트 레인입니다. Git 브랜치처럼 오갈 수 있습니다.
+
+### 필요할 때 관련 컨텍스트 가져오기
 
 ```bash
-gctree update-global-context
+gctree resolve --query "billing retry policy"
 ```
 
-짧은 별칭:
+매칭된 문서만 반환합니다 — 제목, 요약, 발췌문. 요약만으로 부족할 때만 전체 문서를 읽습니다.
+
+### 컨텍스트 최신 상태 유지
 
 ```bash
-gctree update-gc
-gctree ugc
+gctree update-global-context   # 또는: gctree update-gc / gctree ugc
 ```
 
-만약 실제 작업을 하다 보니 어떤 레포가 현재 gc-branch에 포함되어야 할 것 같다면, 자연스러운 흐름은 이렇습니다.
+가이드형 업데이트 플로우 — AI 도구가 무엇이 바뀌었는지 물어보고 새 컨텍스트를 gc-branch에 씁니다.
 
-1. 먼저 그 레포를 branch repo map에 포함시키고
-2. 그 다음 `gctree update-global-context`로 이 레포가 어떤 역할을 하는지, 왜 중요한지 같은 장기 컨텍스트를 추가
-
-#### 6) 다시 온보딩하려면 먼저 gc-branch 리셋
+### 특정 레포에 컨텍스트 범위 지정
 
 ```bash
-gctree reset-gc-branch --branch client-b --yes
+gctree set-repo-scope --branch client-b --include   # 현재 레포 포함
+gctree set-repo-scope --branch client-b --exclude   # 현재 레포 제외
 ```
 
-### 런타임에서 보이는 provider 명령
+관계없는 레포에는 컨텍스트가 주입되지 않습니다.
+
+---
+
+## 컨텍스트 저장 구조
 
-스캐폴딩 이후 런타임에서 보이는 명령은 다음과 같습니다.
+```
+~/.gctree/
+  branches/
+    main/
+      index.md          ← 압축 인덱스, ≤2000자, 먼저 로드됨
+      docs/
+        auth.md         ← 전체 문서, 필요할 때만 읽음
+        architecture.md
+    client-b/
+      index.md
+      docs/
+        ...
+  branch-repo-map.json  ← 어떤 레포가 어떤 gc-branch에 속하는지
+  settings.json         ← 선호 프로바이더, 언어
+```
 
-- **Codex:** `$gc-onboard`, `$gc-update-global-context`
-- **Claude Code:** `/gc-onboard`, `/gc-update-global-context`
+컨텍스트는 레포 밖에 저장됩니다 — `.gitignore` 규칙 불필요, 실수로 커밋될 일 없음, 같은 gc-branch를 쓰는 모든 프로젝트에서 재사용 가능.
 
-이 명령들은 항상 현재 활성 gc-branch가 무엇인지 먼저 밝히고, 사용자가 명시적으로 바꾸라고 하지 않는 한 저장된 언어를 끝까지 유지하면서 컨텍스트를 수집하거나 업데이트해야 합니다.
+---
 
-### 핵심 명령 한눈에 보기
+## 핵심 명령
 
 | 목적 | 명령 |
-| --- | --- |
-| gc-tree 초기화 및 provider 선택 | `gctree init` |
-| 현재 gc-branch 확인 | `gctree status` |
-| 현재 컨텍스트 검색 | `gctree resolve --query "..."` |
+|---|---|
+| gc-tree 초기화 및 프로바이더 선택 | `gctree init` |
+| 활성 gc-branch 확인 | `gctree status` |
+| 활성 컨텍스트 검색 | `gctree resolve --query "..."` |
+| gc-branch 생성 또는 전환 | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
+| 모든 gc-branch 목록 | `gctree branches` |
+| 빈 gc-branch 가이드형 온보딩 | `gctree onboard` |
+| 활성 gc-branch 가이드형 업데이트 | `gctree update-global-context` / `gctree ugc` |
 | 레포 범위 규칙 확인 | `gctree repo-map` |
-| gc-branch에 레포 포함/제외 설정 | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
-| gc-branch 생성/전환 | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
-| 비어 있는 gc-branch 온보딩 | `gctree onboard` |
-| 활성 gc-branch 장기 업데이트 | `gctree update-global-context` / `gctree update-gc` / `gctree ugc` |
-| 다시 온보딩하기 전 gc-branch 초기화 | `gctree reset-gc-branch --branch <name> --yes` |
-| 다른 환경에 수동 스캐폴딩 | `gctree scaffold --host codex --target /path/to/repo` |
+| 현재 레포 포함/제외 설정 | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
+| 재온보딩 전 gc-branch 초기화 | `gctree reset-gc-branch --branch <name> --yes` |
+| 새 환경 스캐폴딩 | `gctree scaffold --host codex --target /path/to/repo` |
 
-## 문서
+---
 
-자세한 문서는 [`docs/`](https://github.com/handsupmin/gc-tree/tree/main/docs) 아래에 정리되어 있습니다.
+## 문서
 
 - **컨셉** — [`docs/concept.ko.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/concept.ko.md)
-  `gctree`가 무엇인지, 어떤 문제를 해결하는지, 글로벌 컨텍스트 레이어의 범위를 설명합니다.
 - **원리** — [`docs/principles.ko.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/principles.ko.md)
-  gc-branch, 레포 범위, slim index, summary-first 문서, 가이드형 업데이트 원칙을 정리합니다.
 - **사용방법** — [`docs/usage.ko.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/usage.ko.md)
-  표준 CLI 흐름, provider 명령, 레포 범위 동작, 통합 패턴을 안내합니다.
-- **로컬 실행방법** — [`docs/local-development.ko.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.ko.md)
-  의존성 설치, 로컬 CLI 실행, 변경 검증 방법을 설명합니다.
+- **로컬 개발** — [`docs/local-development.ko.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.ko.md)
+
+---
 
 ## 기여하기
 
-기여는 언제든 환영합니다. 개발 흐름과 PR 체크리스트는 영어 문서인 [CONTRIBUTING.md](https://github.com/handsupmin/gc-tree/blob/main/CONTRIBUTING.md)를 참고해주세요.
+기여는 언제든 환영합니다. 개발 흐름과 PR 체크리스트는 [CONTRIBUTING.md](https://github.com/handsupmin/gc-tree/blob/main/CONTRIBUTING.md)를 참고하세요.
+
+---
 
 ## 라이선스
 
-MIT. 자세한 내용은 [`LICENSE`](https://github.com/handsupmin/gc-tree/blob/main/LICENSE)를 참고하세요.
+MIT. [`LICENSE`](https://github.com/handsupmin/gc-tree/blob/main/LICENSE) 참고.