@handsupmin/gc-tree 0.1.4 → 0.2.0

package/README.ja.md

@@ -19,214 +19,229 @@ Git のブランチ感覚で、複数のコンテキストを分けて持てま
 
 </div>
 
-日々の仕事が複数のリポジトリ、プロダクト、クライアント、ワークフローにまたがっている開発者のために作りました。
-
-`gc-tree` は、AI コーディングツールに **リポジトリの外側で再利用できるコンテキストレイヤー** を足してくれます。長く使う前提の文脈は残しつつ、関係あるリポジトリにだけ効かせ、無関係な場所では静かに引っ込みます。
-
 ---
 
-## なぜ gc-tree なのか
+## 問題
 
-AI エージェントを本気で実務に入れると、リポジトリローカルのコンテキストだけではすぐ足りなくなります。
+Claude Code や Codex を毎日使っています。でも実際の仕事は複数のリポジトリ、プロダクト、クライアントにまたがっていて——AI ツールは今開いているファイルしか知りません。
 
-作業が複数のリポジトリやワークストリームに広がると、たとえばこんなことが起きがちです。
+だから毎回こうなってしまいます：
 
-- 長期コンテキストがプロンプトの中に押し込まれていく
-- 無関係な文脈が別のリポジトリまで漏れてしまう
-- 新しいセッションを開くたびに同じ説明をやり直すことになる
-- クライアントやプロダクトの知識がチャット履歴の中に埋もれる
-- 作業を切り替えるたびに頭の中で手動で文脈を切り替える必要がある
+- どのリポジトリが一緒に動くか、また最初から説明する
+- 同じアーキテクチャ文書をプロンプトに貼り直す
+- 先週「もう知っていた」規約をもう一度教える
+- 今のリポジトリと無関係なコンテキストを手作業で取り除く
 
-`gc-tree` は、Codex や Claude Code のような AI コーディングツールをすでにしっかり使っていて、コンテキスト管理まで手作業で回したくない人のための道具です。
+これは AI の問題ではありません。**コンテキスト管理の問題**です。
 
 ---
 
-## これでできること
+## gc-tree がやること
 
-- **長期コンテキストを複数持てる**
-  プロダクト、クライアント、ワークストリームごとに別々のコンテキストレーンを維持できます。
+`gc-tree` は**リポジトリより上のレイヤー**に位置します。コンテキストを構造化された Markdown ファイルに保存し、AI ツールがセッションのたびに関連するものだけを自動で引き出せるようにします。
 
-- **リポジトリ単位で関連性を絞れる**
-  どのコンテキストをどのリポジトリにだけ適用するかをはっきり決められます。
+```bash
+gctree resolve --query "auth token rotation policy"
+```
 
-- **スコープを賢くガードできる**
-  まだ紐付いていないリポジトリに入ったとき、今回だけ続けるか、ここでは常に使うか、ここでは無視するかを選べます。
+```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..."
+    }
+  ]
+}
+```
 
-- **ガイド付きでオンボードと更新ができる**
-  Codex、Claude Code、あるいは両方を使いながら、コンテキストを育てていけます。
+AI ツールに渡るのは正しいコンテキスト——ナレッジベース全体ではなく、関係する部分だけです。
 
-- **summary-first の markdown ナレッジとして残せる**
-  隠れたメモリではなくファイルに残し、ツールにはまず短い要約から読ませられます。
+**実測値：1 クエリあたり全コンテキストの約 4% だけ注入されます。** 残り 96% は実際に必要になるまでディスクに留まり、トークンウィンドウに入りません。
 
 ---
 
-## インストール & クイックスタート
-
-```bash
-npm install -g @handsupmin/gc-tree
-gctree init
-```
+## こんな人に向いています
 
-これでスタート準備は完了です。
-あとはいつもどおり開発を進めれば大丈夫。`gc-tree` が普段の流れにグローバルコンテキストのレーンを足してくれます。
+以下に当てはまるなら、gc-tree が一番よく効きます：
 
-- **CLI コマンド:** `gctree`
-- **要件:** Node.js 20+
+- **複数のリポジトリ**にまたがって仕事をしている（モノレポチーム、プラットフォーム + クライアントリポジトリ、バックエンド + フロントエンドスタック）
+- 同じ週に**複数のプロダクトやクライアント**を行き来している
+- AI セッションを開くたびに**同じコンテキストを繰り返し説明**している
+- AI ツールに今のファイルだけでなく**規約・アーキテクチャ・ドメイン知識**まで理解してほしい
 
-ソースから試す場合は [docs/local-development.ja.md](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.ja.md) を参照してください。
+リポジトリ一つ、プロダクト一つで完結するなら、このツールは必要ありません。`CLAUDE.md` や `.cursorrules` で十分です。
 
 ---
 
-## よく使う流れ
+## CLAUDE.md や cursor rules との違いは？
 
-### 作業に専用レーンが欲しくなったら新しいコンテキストを切る
+`CLAUDE.md` は優れています——一つのリポジトリにおいては。
 
-```bash
-gctree checkout -b client-b
-gctree onboard
-```
+複数のリポジトリ・クライアント・ワークストリームが増えた瞬間：
 
-クライアント、プロダクト、移行案件、期間限定の施策など、文脈を分けておきたい仕事は gc-branch を切っておくと楽です。
+| | `CLAUDE.md` / cursor rules | `gc-tree` |
+|---|---|---|
+| スコープ | リポジトリ一つ | 複数リポジトリ、コンテキスト一つ |
+| 永続化 | リポジトリ内のファイル | リポジトリ外に保存、セッション間で再利用 |
+| コンテキスト切り替え | ファイルを手で編集 | `gctree checkout client-b` |
+| 関連性フィルタリング | 全部か何もないか | 一致したドキュメントだけ注入（約 4%） |
+| オンボーディング | 手書き | AI ツールがガイド |
+| Codex 対応 | ✅ | ✅ |
+| Claude Code 対応 | ✅ | ✅ |
 
-### 後から長期コンテキストを育てる
+---
 
-```bash
-gctree update-global-context
-```
+## 検証済みのパフォーマンス
 
-作業が進んだら、アクティブな gc-branch に長く効く文脈を足していきます。
+実際の社内ドキュメントでテスト（Notion エクスポート 4 件、日本語・英語混合クエリ）：
 
-短い別名:
+| 指標 | 結果 |
+|---|---|
+| Recall——関連クエリが正しい文書を見つける割合 | **100%**（16/16） |
+| Precision——無関係なクエリが空を返す割合 | **80%**（4/5） |
+| F1 スコア | **88.9%** |
+| クエリあたりの注入トークン割合（全体比） | **約 4%** |
+| 日英混合クエリ対応 | ✅ |
 
-```bash
-gctree update-gc
-gctree ugc
-```
+---
 
-### 必要になったタイミングでコンテキストを引く
+## 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          # 両方同時に
 ```
 
-必要な瞬間だけ、関係ある文脈を呼び戻せば十分です。
-
----
+どちらのプロバイダーも同じ基盤のコンテキストストアを使います。一度オンボーディングすれば、どちらのツールからでも使えます。
 
-## しっくりくる理由
+**Claude Code** — `/gc-resolve-context`、`/gc-onboard`、`/gc-update-global-context` スラッシュコマンドを使用。
 
-**Git のブランチみたいに複数のコンテキストを持てるのに、Git のブランチみたいに逐一面倒を見る必要はありません。**
+**Codex** — `$gc-resolve-context`、`$gc-onboard`、`$gc-update-global-context` スキルを使用。`codex exec` で実際に検証済み：
 
-たとえば次のようにコンテキストを分けられます。
+```
+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
-gctree checkout main
+npm install -g @handsupmin/gc-tree
+gctree init
 ```
 
-ただし Git と違って、その切り替えを常に人が意識して管理する必要はありません。
+`gctree init` が次のことを案内してくれます：
+1. プロバイダーの選択：`claude-code`、`codex`、または `both`
+2. 現在のリポジトリへの統合ファイルのインストール
+3. `main` gc-branch のガイド付きオンボーディング実行
 
-今いるリポジトリが現在のコンテキストのスコープ外なら、`gc-tree` はその文脈を「今は関係ないもの」として扱えます。だから、無関係なコンテキストが別のセッションに混ざり込みません。
+その後は、AI ツールが計画・実装の前に `gctree resolve` を呼ぶ流れを自然に覚えます。
 
-その結果、長く使うコンテキストを複数抱えたままでも、毎回すべてを全部のセッションに持ち込まずに済みます。
+- **CLI：** `gctree`
+- **動作条件：** Node.js 20+
 
 ---
 
-## 現実的なワークフロー
-
-たとえば、こんな構成で仕事をしているとします。
+## よく使う流れ
 
-- 共通のプラットフォームリポジトリが 1 つ
-- クライアント向けリポジトリが 2 つ
-- 社内ツール用リポジトリが 1 つ
+### ワークストリームごとに別々のコンテキストを持つ
 
-`gc-tree` がないと、新しい AI セッションを開くたびに説明し直すことになります。
+```bash
+gctree checkout -b client-b
+gctree onboard
+```
 
-- 今どのクライアントの話なのか
-- どのリポジトリ同士がひとまとまりなのか
-- ここで重要なワークフローは何か
-- 今はどの文脈がむしろノイズになるのか
+各 gc-branch は完全に独立したコンテキストレーンです。Git ブランチと同じ感覚で行き来できます。
 
-`gc-tree` があれば、レーンごとにコンテキストを持ち分けて、セッションをまたいで再利用し、repo scope のルールで不要な文脈の流入も防げます。
+### 必要なときに関連コンテキストを引き出す
 
-要するに、本当にやりたいのはこういうことです。
+```bash
+gctree resolve --query "billing retry policy"
+```
 
-> プロンプトをもっと溜め込むことではなく、
-> **仕事の単位に合ったコンテキストを、正しいレイヤーで管理すること。**
+一致したドキュメントだけが返ります——タイトル、要約、抜粋。要約で足りなければ、ツールが全文を読みます。
 
----
+### コンテキストを常に最新に保つ
 
-## コア概念
+```bash
+gctree update-global-context   # または：gctree update-gc / gctree ugc
+```
 
-- **gc-branch**
-  1 つのプロダクト、クライアント、ワークストリーム、ドメインのための長期コンテキストレーンです。
+ガイド付き更新フロー——AI ツールが何が変わったかを確認し、新しいコンテキストを gc-branch に書き戻します。
 
-- **repo scope**
-  そのコンテキストをどのリポジトリで効かせるかを決めるルールです。
+### コンテキストを特定のリポジトリに限定する
 
-- **provider-guided flow**
-  JSON を手で書く代わりに、好みの AI コーディングツールでオンボードと更新を進める流れです。
+```bash
+gctree set-repo-scope --branch client-b --include   # 現在のリポジトリを含める
+gctree set-repo-scope --branch client-b --exclude   # 現在のリポジトリを除外する
+```
 
-- **context tree**
-  `gc-tree` は内部的には、ブランチを意識したファイルベースの知識ツリーとしてコンテキストを整理します。
-  ユーザーが得る価値は、プロジェクトの外までつながる再利用可能なコンテキストです。
+`gc-tree` は関係のないリポジトリにコンテキストを注入しません。
 
 ---
 
-## ランタイムで見える provider コマンド
-
-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` |
+|---|---|
+| 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) を参照してください。
 
 ---