@handsupmin/gc-tree 0.1.3 → 0.2.0

package/README.ja.md

@@ -1,165 +1,249 @@
 # gc-tree
 
-AI コーディングツール向けのブランチ対応グローバルコンテキストレイヤー。
+<div align="center">
+
+<img src="./logo.png" alt="gc-tree logo" 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** です。
-長期的なコンテキストに、ファイルベースで再利用しやすく、ブランチ単位で切り替えられる明確な置き場所を与え、既存のワークフローにも自然に組み込めます。
+---
 
-1 つの `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` により、1 つの 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` は**リポジトリより上のレイヤー**に位置します。コンテキストを構造化された Markdown ファイルに保存し、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 Cookie に保存、access token の TTL は 15 分",
+      "excerpt": "## 認証フロー\nAccess token：15 分 TTL、認証リクエストのたびに rotation..."
+    }
+  ]
+}
+```
 
-### クイックスタート
+AI ツールに渡るのは正しいコンテキスト——ナレッジベース全体ではなく、関係する部分だけです。
 
-#### 1) gc-tree を初期化する
+**実測値：1 クエリあたり全コンテキストの約 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` を選んだ場合は、今回のオンボーディングをどちらで始めるかをさらに選ばせる
-- 言語（`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 に属するべきだと分かった場合は、自然な流れはこうです。
-
-1. まずそのリポジトリを branch repo map に追加する
-2. その後 `gctree update-global-context` を実行して、そのリポジトリが何を担うのか、なぜ重要なのかといった長期コンテキストを追加する
+ガイド付き更新フロー——AI ツールが何が変わったかを確認し、新しいコンテキストを gc-branch に書き戻します。
 
-#### 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 コマンド
+`gc-tree` は関係のないリポジトリにコンテキストを注入しません。
 
-scaffold 後に見えるコマンドは次の通りです。
+---
 
-- **Codex:** `$gc-onboard`, `$gc-update-global-context`
-- **Claude Code:** `/gc-onboard`, `/gc-update-global-context`
+## コンテキストの保存構造
+
+```
+~/.gctree/
+  branches/
+    main/
+      index.md          ← 圧縮インデックス、≤2000 文字、最初にロード
+      docs/
+        auth.md         ← 全文、必要なときだけ読む
+        architecture.md
+    client-b/
+      index.md
+      docs/
+        ...
+  branch-repo-map.json  ← どのリポジトリがどの gc-branch に属するか
+  settings.json         ← 優先プロバイダー、言語
+```
 
-これらのコマンドは、長期コンテキストを集めたり更新したりする前に、現在の gc-branch を必ず明示し、ユーザーが明示的に切り替えを求めない限り、保存された言語を最後まで維持するべきです。
+コンテキストはリポジトリの外に保存されます——`.gitignore` 設定不要、誤コミットの心配なし、同じ 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 set-repo-scope --branch <name> --include` / `--exclude` |
 | 再オンボーディング前に gc-branch をリセットする | `gctree reset-gc-branch --branch <name> --yes` |
-| 別環境に手動で scaffold を入れる | `gctree scaffold --host codex --target /path/to/repo` |
+| 別の環境に scaffold をインストールする | `gctree scaffold --host codex --target /path/to/repo` |
 
-## ドキュメント
+---
 
-詳細ドキュメントは [`docs/`](https://github.com/handsupmin/gc-tree/tree/main/docs) にまとまっています。
+## ドキュメント
 
 - **コンセプト** — [`docs/concept.ja.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/concept.ja.md)
-  `gctree` が何であり、どの課題を解決し、どこまでを担当するのかを説明します。
 - **原則** — [`docs/principles.ja.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/principles.ja.md)
-  gc-branch、リポジトリ範囲、summary-first 文書、ガイド付き更新の考え方をまとめています。
 - **使い方** — [`docs/usage.ja.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/usage.ja.md)
-  標準 CLI フロー、provider コマンド、リポジトリ範囲の挙動、統合パターンを案内します。
-- **ローカル実行方法** — [`docs/local-development.ja.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.ja.md)
-  依存関係のインストール、CLI のローカル実行、変更確認手順を説明します。
+- **ローカル開発** — [`docs/local-development.ja.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.ja.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) を参照してください。
+
+---
 
 ## ライセンス