@handsupmin/gc-tree 0.2.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.es.md +60 -59
- package/README.ja.md +60 -59
- package/README.ko.md +62 -61
- package/README.md +61 -60
- package/README.zh.md +62 -61
- package/docs/concept.es.md +45 -33
- package/docs/concept.ja.md +41 -29
- package/docs/concept.ko.md +48 -36
- package/docs/concept.md +13 -1
- package/docs/concept.zh.md +48 -36
- package/docs/local-development.es.md +44 -22
- package/docs/local-development.ja.md +40 -18
- package/docs/local-development.ko.md +47 -25
- package/docs/local-development.md +27 -5
- package/docs/local-development.zh.md +27 -5
- package/docs/principles.es.md +39 -26
- package/docs/principles.ja.md +26 -13
- package/docs/principles.ko.md +40 -27
- package/docs/principles.md +15 -2
- package/docs/principles.zh.md +42 -29
- package/docs/usage.es.md +98 -50
- package/docs/usage.ja.md +71 -23
- package/docs/usage.ko.md +100 -52
- package/docs/usage.md +51 -3
- package/docs/usage.zh.md +95 -47
- package/package.json +3 -1
package/README.es.md
CHANGED
|
@@ -36,6 +36,39 @@ Esto no es un problema de IA. Es un **problema de gestión del contexto**.
|
|
|
36
36
|
|
|
37
37
|
---
|
|
38
38
|
|
|
39
|
+
## Para quién es esto
|
|
40
|
+
|
|
41
|
+
Sacarás más partido a `gc-tree` si:
|
|
42
|
+
|
|
43
|
+
- Trabajas en **múltiples repositorios** (equipos con monorepo, repos de plataforma + cliente, stacks de backend + frontend)
|
|
44
|
+
- Cambias entre **múltiples productos o clientes** en la misma semana
|
|
45
|
+
- Te encuentras **explicando el mismo contexto** al inicio de cada sesión de IA
|
|
46
|
+
- Quieres que tus herramientas de IA entiendan tus **convenciones, arquitectura y conocimiento de dominio** — no solo el archivo actual
|
|
47
|
+
|
|
48
|
+
Si solo trabajas en un repositorio y un producto, no necesitas esto. `CLAUDE.md` o `.cursorrules` es suficiente.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Instalación y arranque rápido
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
npm install -g @handsupmin/gc-tree
|
|
56
|
+
gctree init
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`gctree init` te guía a través de:
|
|
60
|
+
|
|
61
|
+
1. Elegir provider: `claude-code`, `codex` o `both`
|
|
62
|
+
2. Instalar los archivos de integración en el repositorio actual
|
|
63
|
+
3. Completar el onboarding guiado para el gc-branch `main`
|
|
64
|
+
|
|
65
|
+
Después, tu herramienta de IA aprenderá a llamar a `gctree resolve` antes de planificar o implementar.
|
|
66
|
+
|
|
67
|
+
- **CLI:** `gctree`
|
|
68
|
+
- **Requisito:** Node.js 20+
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
39
72
|
## Qué hace gc-tree
|
|
40
73
|
|
|
41
74
|
`gc-tree` opera **por encima del nivel del repositorio**. Almacena contexto en archivos Markdown estructurados y permite que tus herramientas de IA traigan solo lo relevante antes de cada sesión, de forma automática.
|
|
@@ -64,34 +97,21 @@ Tu herramienta de IA recibe el contexto correcto — no toda la base de conocimi
|
|
|
64
97
|
|
|
65
98
|
---
|
|
66
99
|
|
|
67
|
-
## Para quién es esto
|
|
68
|
-
|
|
69
|
-
Sacarás más partido a `gc-tree` si:
|
|
70
|
-
|
|
71
|
-
- Trabajas en **múltiples repositorios** (equipos con monorepo, repos de plataforma + cliente, stacks de backend + frontend)
|
|
72
|
-
- Cambias entre **múltiples productos o clientes** en la misma semana
|
|
73
|
-
- Te encuentras **explicando el mismo contexto** al inicio de cada sesión de IA
|
|
74
|
-
- Quieres que tus herramientas de IA entiendan tus **convenciones, arquitectura y conocimiento de dominio** — no solo el archivo actual
|
|
75
|
-
|
|
76
|
-
Si solo trabajas en un repositorio y un producto, no necesitas esto. `CLAUDE.md` o `.cursorrules` es suficiente.
|
|
77
|
-
|
|
78
|
-
---
|
|
79
|
-
|
|
80
100
|
## ¿En qué se diferencia de CLAUDE.md o cursor rules?
|
|
81
101
|
|
|
82
102
|
`CLAUDE.md` es genial — para un solo repositorio.
|
|
83
103
|
|
|
84
104
|
En el momento en que tienes múltiples repos, clientes o workstreams:
|
|
85
105
|
|
|
86
|
-
|
|
|
87
|
-
|
|
88
|
-
| Alcance
|
|
89
|
-
| Persistencia
|
|
90
|
-
| Cambio de contexto
|
|
91
|
-
| Filtrado por relevancia
|
|
92
|
-
| Onboarding
|
|
93
|
-
| Compatible con Codex
|
|
94
|
-
| Compatible con Claude Code | ✅
|
|
106
|
+
| | `CLAUDE.md` / cursor rules | `gc-tree` |
|
|
107
|
+
| -------------------------- | -------------------------- | --------------------------------------------- |
|
|
108
|
+
| Alcance | Un repositorio | Múltiples repos, un contexto |
|
|
109
|
+
| Persistencia | Archivo dentro del repo | Almacenado fuera, reutilizable entre sesiones |
|
|
110
|
+
| Cambio de contexto | Edición manual de archivos | `gctree checkout client-b` |
|
|
111
|
+
| Filtrado por relevancia | Todo o nada | Solo inyecta docs coincidentes (~4%) |
|
|
112
|
+
| Onboarding | Escrito a mano | Guiado por tu herramienta de IA |
|
|
113
|
+
| Compatible con Codex | ✅ | ✅ |
|
|
114
|
+
| Compatible con Claude Code | ✅ | ✅ |
|
|
95
115
|
|
|
96
116
|
---
|
|
97
117
|
|
|
@@ -99,13 +119,13 @@ En el momento en que tienes múltiples repos, clientes o workstreams:
|
|
|
99
119
|
|
|
100
120
|
Probado con documentación interna real (4 exportaciones de Notion, consultas mixtas en español e inglés):
|
|
101
121
|
|
|
102
|
-
| Métrica
|
|
103
|
-
|
|
122
|
+
| Métrica | Resultado |
|
|
123
|
+
| ------------------------------------------------------------ | ---------------- |
|
|
104
124
|
| Recall — consultas relevantes que encuentran el doc correcto | **100%** (16/16) |
|
|
105
|
-
| Precision — consultas irrelevantes que devuelven vacío
|
|
106
|
-
| F1 score
|
|
107
|
-
| Tokens inyectados por consulta vs. contexto total
|
|
108
|
-
| Compatible con consultas mixtas en varios idiomas
|
|
125
|
+
| Precision — consultas irrelevantes que devuelven vacío | **80%** (4/5) |
|
|
126
|
+
| F1 score | **88.9%** |
|
|
127
|
+
| Tokens inyectados por consulta vs. contexto total | **~4%** |
|
|
128
|
+
| Compatible con consultas mixtas en varios idiomas | ✅ |
|
|
109
129
|
|
|
110
130
|
---
|
|
111
131
|
|
|
@@ -133,25 +153,6 @@ gctree resolve --query 'NestJS DTO plainToInstance'
|
|
|
133
153
|
|
|
134
154
|
---
|
|
135
155
|
|
|
136
|
-
## Instalación y arranque rápido
|
|
137
|
-
|
|
138
|
-
```bash
|
|
139
|
-
npm install -g @handsupmin/gc-tree
|
|
140
|
-
gctree init
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
`gctree init` te guía a través de:
|
|
144
|
-
1. Elegir provider: `claude-code`, `codex` o `both`
|
|
145
|
-
2. Instalar los archivos de integración en el repositorio actual
|
|
146
|
-
3. Completar el onboarding guiado para el gc-branch `main`
|
|
147
|
-
|
|
148
|
-
Después, tu herramienta de IA aprenderá a llamar a `gctree resolve` antes de planificar o implementar.
|
|
149
|
-
|
|
150
|
-
- **CLI:** `gctree`
|
|
151
|
-
- **Requisito:** Node.js 20+
|
|
152
|
-
|
|
153
|
-
---
|
|
154
|
-
|
|
155
156
|
## Movimientos habituales
|
|
156
157
|
|
|
157
158
|
### Contextos separados para workstreams distintos
|
|
@@ -214,19 +215,19 @@ El contexto vive fuera de tus repositorios — sin reglas de `.gitignore`, sin c
|
|
|
214
215
|
|
|
215
216
|
## Comandos principales
|
|
216
217
|
|
|
217
|
-
| Objetivo
|
|
218
|
-
|
|
219
|
-
| Inicializar gc-tree y elegir provider
|
|
220
|
-
| Confirmar el gc-branch activo
|
|
221
|
-
| Buscar en el contexto activo
|
|
222
|
-
| Crear o cambiar gc-branches
|
|
223
|
-
| Listar todos los gc-branches
|
|
224
|
-
| Onboarding guiado de un gc-branch vacío
|
|
225
|
-
| Actualización guiada del gc-branch activo
|
|
226
|
-
| Ver reglas de alcance por repo
|
|
218
|
+
| Objetivo | Comando |
|
|
219
|
+
| -------------------------------------------------- | --------------------------------------------------------------- |
|
|
220
|
+
| Inicializar gc-tree y elegir provider | `gctree init` |
|
|
221
|
+
| Confirmar el gc-branch activo | `gctree status` |
|
|
222
|
+
| Buscar en el contexto activo | `gctree resolve --query "..."` |
|
|
223
|
+
| Crear o cambiar gc-branches | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
|
|
224
|
+
| Listar todos los gc-branches | `gctree branches` |
|
|
225
|
+
| Onboarding guiado de un gc-branch vacío | `gctree onboard` |
|
|
226
|
+
| Actualización guiada del gc-branch activo | `gctree update-global-context` / `gctree ugc` |
|
|
227
|
+
| Ver reglas de alcance por repo | `gctree repo-map` |
|
|
227
228
|
| Incluir o excluir el repo actual para un gc-branch | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
|
|
228
|
-
| Resetear un gc-branch antes de re-onboard
|
|
229
|
-
| Instalar scaffold en un nuevo entorno
|
|
229
|
+
| Resetear un gc-branch antes de re-onboard | `gctree reset-gc-branch --branch <name> --yes` |
|
|
230
|
+
| Instalar scaffold en un nuevo entorno | `gctree scaffold --host codex --target /path/to/repo` |
|
|
230
231
|
|
|
231
232
|
---
|
|
232
233
|
|
package/README.ja.md
CHANGED
|
@@ -36,6 +36,39 @@ Claude Code や Codex を毎日使っています。でも実際の仕事は複
|
|
|
36
36
|
|
|
37
37
|
---
|
|
38
38
|
|
|
39
|
+
## こんな人に向いています
|
|
40
|
+
|
|
41
|
+
以下に当てはまるなら、gc-tree が一番よく効きます：
|
|
42
|
+
|
|
43
|
+
- **複数のリポジトリ**にまたがって仕事をしている（モノレポチーム、プラットフォーム + クライアントリポジトリ、バックエンド + フロントエンドスタック）
|
|
44
|
+
- 同じ週に**複数のプロダクトやクライアント**を行き来している
|
|
45
|
+
- AI セッションを開くたびに**同じコンテキストを繰り返し説明**している
|
|
46
|
+
- AI ツールに今のファイルだけでなく**規約・アーキテクチャ・ドメイン知識**まで理解してほしい
|
|
47
|
+
|
|
48
|
+
リポジトリ一つ、プロダクト一つで完結するなら、このツールは必要ありません。`CLAUDE.md` や `.cursorrules` で十分です。
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## インストール & クイックスタート
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
npm install -g @handsupmin/gc-tree
|
|
56
|
+
gctree init
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`gctree init` が次のことを案内してくれます：
|
|
60
|
+
|
|
61
|
+
1. プロバイダーの選択：`claude-code`、`codex`、または `both`
|
|
62
|
+
2. 現在のリポジトリへの統合ファイルのインストール
|
|
63
|
+
3. `main` gc-branch のガイド付きオンボーディング実行
|
|
64
|
+
|
|
65
|
+
その後は、AI ツールが計画・実装の前に `gctree resolve` を呼ぶ流れを自然に覚えます。
|
|
66
|
+
|
|
67
|
+
- **CLI：** `gctree`
|
|
68
|
+
- **動作条件：** Node.js 20+
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
39
72
|
## gc-tree がやること
|
|
40
73
|
|
|
41
74
|
`gc-tree` は**リポジトリより上のレイヤー**に位置します。コンテキストを構造化された Markdown ファイルに保存し、AI ツールがセッションのたびに関連するものだけを自動で引き出せるようにします。
|
|
@@ -64,34 +97,21 @@ AI ツールに渡るのは正しいコンテキスト——ナレッジベー
|
|
|
64
97
|
|
|
65
98
|
---
|
|
66
99
|
|
|
67
|
-
## こんな人に向いています
|
|
68
|
-
|
|
69
|
-
以下に当てはまるなら、gc-tree が一番よく効きます：
|
|
70
|
-
|
|
71
|
-
- **複数のリポジトリ**にまたがって仕事をしている（モノレポチーム、プラットフォーム + クライアントリポジトリ、バックエンド + フロントエンドスタック）
|
|
72
|
-
- 同じ週に**複数のプロダクトやクライアント**を行き来している
|
|
73
|
-
- AI セッションを開くたびに**同じコンテキストを繰り返し説明**している
|
|
74
|
-
- AI ツールに今のファイルだけでなく**規約・アーキテクチャ・ドメイン知識**まで理解してほしい
|
|
75
|
-
|
|
76
|
-
リポジトリ一つ、プロダクト一つで完結するなら、このツールは必要ありません。`CLAUDE.md` や `.cursorrules` で十分です。
|
|
77
|
-
|
|
78
|
-
---
|
|
79
|
-
|
|
80
100
|
## CLAUDE.md や cursor rules との違いは？
|
|
81
101
|
|
|
82
102
|
`CLAUDE.md` は優れています——一つのリポジトリにおいては。
|
|
83
103
|
|
|
84
104
|
複数のリポジトリ・クライアント・ワークストリームが増えた瞬間：
|
|
85
105
|
|
|
86
|
-
|
|
|
87
|
-
|
|
88
|
-
| スコープ
|
|
89
|
-
| 永続化
|
|
90
|
-
| コンテキスト切り替え | ファイルを手で編集
|
|
91
|
-
| 関連性フィルタリング | 全部か何もないか
|
|
92
|
-
| オンボーディング
|
|
93
|
-
| Codex 対応
|
|
94
|
-
| Claude Code 対応
|
|
106
|
+
| | `CLAUDE.md` / cursor rules | `gc-tree` |
|
|
107
|
+
| -------------------- | -------------------------- | ---------------------------------------- |
|
|
108
|
+
| スコープ | リポジトリ一つ | 複数リポジトリ、コンテキスト一つ |
|
|
109
|
+
| 永続化 | リポジトリ内のファイル | リポジトリ外に保存、セッション間で再利用 |
|
|
110
|
+
| コンテキスト切り替え | ファイルを手で編集 | `gctree checkout client-b` |
|
|
111
|
+
| 関連性フィルタリング | 全部か何もないか | 一致したドキュメントだけ注入（約 4%） |
|
|
112
|
+
| オンボーディング | 手書き | AI ツールがガイド |
|
|
113
|
+
| Codex 対応 | ✅ | ✅ |
|
|
114
|
+
| Claude Code 対応 | ✅ | ✅ |
|
|
95
115
|
|
|
96
116
|
---
|
|
97
117
|
|
|
@@ -99,13 +119,13 @@ AI ツールに渡るのは正しいコンテキスト——ナレッジベー
|
|
|
99
119
|
|
|
100
120
|
実際の社内ドキュメントでテスト（Notion エクスポート 4 件、日本語・英語混合クエリ）：
|
|
101
121
|
|
|
102
|
-
| 指標
|
|
103
|
-
|
|
122
|
+
| 指標 | 結果 |
|
|
123
|
+
| -------------------------------------------- | ----------------- |
|
|
104
124
|
| Recall——関連クエリが正しい文書を見つける割合 | **100%**（16/16） |
|
|
105
|
-
| Precision——無関係なクエリが空を返す割合
|
|
106
|
-
| F1 スコア
|
|
107
|
-
| クエリあたりの注入トークン割合（全体比）
|
|
108
|
-
| 日英混合クエリ対応
|
|
125
|
+
| Precision——無関係なクエリが空を返す割合 | **80%**（4/5） |
|
|
126
|
+
| F1 スコア | **88.9%** |
|
|
127
|
+
| クエリあたりの注入トークン割合（全体比） | **約 4%** |
|
|
128
|
+
| 日英混合クエリ対応 | ✅ |
|
|
109
129
|
|
|
110
130
|
---
|
|
111
131
|
|
|
@@ -133,25 +153,6 @@ gctree resolve --query 'NestJS DTO plainToInstance'
|
|
|
133
153
|
|
|
134
154
|
---
|
|
135
155
|
|
|
136
|
-
## インストール & クイックスタート
|
|
137
|
-
|
|
138
|
-
```bash
|
|
139
|
-
npm install -g @handsupmin/gc-tree
|
|
140
|
-
gctree init
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
`gctree init` が次のことを案内してくれます：
|
|
144
|
-
1. プロバイダーの選択：`claude-code`、`codex`、または `both`
|
|
145
|
-
2. 現在のリポジトリへの統合ファイルのインストール
|
|
146
|
-
3. `main` gc-branch のガイド付きオンボーディング実行
|
|
147
|
-
|
|
148
|
-
その後は、AI ツールが計画・実装の前に `gctree resolve` を呼ぶ流れを自然に覚えます。
|
|
149
|
-
|
|
150
|
-
- **CLI：** `gctree`
|
|
151
|
-
- **動作条件：** Node.js 20+
|
|
152
|
-
|
|
153
|
-
---
|
|
154
|
-
|
|
155
156
|
## よく使う流れ
|
|
156
157
|
|
|
157
158
|
### ワークストリームごとに別々のコンテキストを持つ
|
|
@@ -214,19 +215,19 @@ gctree set-repo-scope --branch client-b --exclude # 現在のリポジトリ
|
|
|
214
215
|
|
|
215
216
|
## 主要コマンド
|
|
216
217
|
|
|
217
|
-
| 目的
|
|
218
|
-
|
|
219
|
-
| gc-tree を初期化してプロバイダーを選ぶ
|
|
220
|
-
| アクティブな gc-branch を確認する
|
|
221
|
-
| アクティブなコンテキストを検索する
|
|
222
|
-
| gc-branch を作成または切り替える
|
|
223
|
-
| 全 gc-branch を一覧表示する
|
|
224
|
-
| 空の gc-branch をガイド付きオンボーディングする
|
|
225
|
-
| アクティブな gc-branch をガイド付き更新する
|
|
226
|
-
| リポジトリ範囲ルールを確認する
|
|
218
|
+
| 目的 | コマンド |
|
|
219
|
+
| ------------------------------------------------ | --------------------------------------------------------------- |
|
|
220
|
+
| gc-tree を初期化してプロバイダーを選ぶ | `gctree init` |
|
|
221
|
+
| アクティブな gc-branch を確認する | `gctree status` |
|
|
222
|
+
| アクティブなコンテキストを検索する | `gctree resolve --query "..."` |
|
|
223
|
+
| gc-branch を作成または切り替える | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
|
|
224
|
+
| 全 gc-branch を一覧表示する | `gctree branches` |
|
|
225
|
+
| 空の gc-branch をガイド付きオンボーディングする | `gctree onboard` |
|
|
226
|
+
| アクティブな gc-branch をガイド付き更新する | `gctree update-global-context` / `gctree ugc` |
|
|
227
|
+
| リポジトリ範囲ルールを確認する | `gctree repo-map` |
|
|
227
228
|
| 現在のリポジトリを gc-branch に含める / 除外する | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
|
|
228
|
-
| 再オンボーディング前に gc-branch をリセットする
|
|
229
|
-
| 別の環境に scaffold をインストールする
|
|
229
|
+
| 再オンボーディング前に gc-branch をリセットする | `gctree reset-gc-branch --branch <name> --yes` |
|
|
230
|
+
| 別の環境に scaffold をインストールする | `gctree scaffold --host codex --target /path/to/repo` |
|
|
230
231
|
|
|
231
232
|
---
|
|
232
233
|
|
package/README.ko.md
CHANGED
|
@@ -36,6 +36,39 @@ Claude Code나 Codex를 매일 씁니다. 그런데 실제 업무는 여러 레
|
|
|
36
36
|
|
|
37
37
|
---
|
|
38
38
|
|
|
39
|
+
## 이 도구가 맞는 사람
|
|
40
|
+
|
|
41
|
+
다음에 해당하면 gc-tree를 제일 잘 쓸 수 있습니다:
|
|
42
|
+
|
|
43
|
+
- **여러 레포**에 걸쳐 일하는 경우 (모노레포 팀, 플랫폼 + 클라이언트 레포, 백엔드 + 프론트엔드 스택)
|
|
44
|
+
- 같은 주에 **여러 제품이나 고객사** 사이를 오가는 경우
|
|
45
|
+
- AI 세션 시작마다 **같은 컨텍스트를 반복 설명**하는 경우
|
|
46
|
+
- AI 도구가 현재 파일뿐 아니라 **컨벤션, 아키텍처, 도메인 지식**도 알길 원하는 경우
|
|
47
|
+
|
|
48
|
+
레포 하나, 제품 하나에서만 일한다면 굳이 이 도구가 필요 없습니다. `CLAUDE.md`나 `.cursorrules`로 충분합니다.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## 설치 & 빠른 시작
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
npm install -g @handsupmin/gc-tree
|
|
56
|
+
gctree init
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`gctree init`이 안내합니다:
|
|
60
|
+
|
|
61
|
+
1. 프로바이더 선택: `claude-code`, `codex`, 또는 `both`
|
|
62
|
+
2. 현재 레포에 통합 파일 스캐폴딩
|
|
63
|
+
3. `main` gc-branch 가이드형 온보딩 실행
|
|
64
|
+
|
|
65
|
+
이후 AI 도구가 계획·구현 전에 `gctree resolve`를 호출하는 법을 자동으로 알게 됩니다.
|
|
66
|
+
|
|
67
|
+
- **CLI:** `gctree`
|
|
68
|
+
- **요구 사항:** Node.js 20+
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
39
72
|
## gc-tree가 하는 일
|
|
40
73
|
|
|
41
74
|
`gc-tree`는 **레포 위 레벨**에 위치합니다. 컨텍스트를 구조화된 마크다운 파일에 저장하고, AI 도구가 매 세션마다 관련된 것만 자동으로 가져오게 합니다.
|
|
@@ -64,34 +97,21 @@ AI 도구가 올바른 컨텍스트를 가져옵니다. 지식 베이스 전체
|
|
|
64
97
|
|
|
65
98
|
---
|
|
66
99
|
|
|
67
|
-
## 이 도구가 맞는 사람
|
|
68
|
-
|
|
69
|
-
다음에 해당하면 gc-tree를 제일 잘 쓸 수 있습니다:
|
|
70
|
-
|
|
71
|
-
- **여러 레포**에 걸쳐 일하는 경우 (모노레포 팀, 플랫폼 + 클라이언트 레포, 백엔드 + 프론트엔드 스택)
|
|
72
|
-
- 같은 주에 **여러 제품이나 고객사** 사이를 오가는 경우
|
|
73
|
-
- AI 세션 시작마다 **같은 컨텍스트를 반복 설명**하는 경우
|
|
74
|
-
- AI 도구가 현재 파일뿐 아니라 **컨벤션, 아키텍처, 도메인 지식**도 알길 원하는 경우
|
|
75
|
-
|
|
76
|
-
레포 하나, 제품 하나에서만 일한다면 굳이 이 도구가 필요 없습니다. `CLAUDE.md`나 `.cursorrules`로 충분합니다.
|
|
77
|
-
|
|
78
|
-
---
|
|
79
|
-
|
|
80
100
|
## CLAUDE.md나 cursor rules와 뭐가 다른가요?
|
|
81
101
|
|
|
82
102
|
`CLAUDE.md`는 훌륭합니다 — 레포 하나에서는요.
|
|
83
103
|
|
|
84
104
|
여러 레포, 고객사, 워크스트림이 생기는 순간:
|
|
85
105
|
|
|
86
|
-
|
|
|
87
|
-
|
|
88
|
-
| 범위
|
|
89
|
-
| 지속성
|
|
90
|
-
| 컨텍스트 전환
|
|
91
|
-
| 관련성 필터링
|
|
92
|
-
| 온보딩
|
|
93
|
-
| Codex 지원
|
|
94
|
-
| Claude Code 지원 | ✅
|
|
106
|
+
| | `CLAUDE.md` / cursor rules | `gc-tree` |
|
|
107
|
+
| ---------------- | -------------------------- | ---------------------------- |
|
|
108
|
+
| 범위 | 레포 하나 | 여러 레포, 컨텍스트 하나 |
|
|
109
|
+
| 지속성 | 레포 내 파일 | 레포 밖 저장, 세션 간 재사용 |
|
|
110
|
+
| 컨텍스트 전환 | 파일 직접 수정 | `gctree checkout client-b` |
|
|
111
|
+
| 관련성 필터링 | 전부 아니면 없음 | 매칭 문서만 주입 (~4%) |
|
|
112
|
+
| 온보딩 | 손으로 작성 | AI 도구가 가이드 |
|
|
113
|
+
| Codex 지원 | ✅ | ✅ |
|
|
114
|
+
| Claude Code 지원 | ✅ | ✅ |
|
|
95
115
|
|
|
96
116
|
---
|
|
97
117
|
|
|
@@ -99,13 +119,13 @@ AI 도구가 올바른 컨텍스트를 가져옵니다. 지식 베이스 전체
|
|
|
99
119
|
|
|
100
120
|
실제 내부 문서 기준 테스트 (Notion 내보내기 4종, 한국어 + 영어 혼합 쿼리):
|
|
101
121
|
|
|
102
|
-
| 지표
|
|
103
|
-
|
|
104
|
-
| Recall — 관련 쿼리가 올바른 문서를 찾는 비율
|
|
105
|
-
| Precision — 무관 쿼리가 빈 결과를 반환하는 비율 | **80%** (4/5)
|
|
106
|
-
| F1 점수
|
|
107
|
-
| 쿼리당 주입 토큰 비율 (전체 컨텍스트 대비)
|
|
108
|
-
| 한국어 + 영어 혼합 쿼리 지원
|
|
122
|
+
| 지표 | 결과 |
|
|
123
|
+
| ----------------------------------------------- | ---------------- |
|
|
124
|
+
| Recall — 관련 쿼리가 올바른 문서를 찾는 비율 | **100%** (16/16) |
|
|
125
|
+
| Precision — 무관 쿼리가 빈 결과를 반환하는 비율 | **80%** (4/5) |
|
|
126
|
+
| F1 점수 | **88.9%** |
|
|
127
|
+
| 쿼리당 주입 토큰 비율 (전체 컨텍스트 대비) | **~4%** |
|
|
128
|
+
| 한국어 + 영어 혼합 쿼리 지원 | ✅ |
|
|
109
129
|
|
|
110
130
|
---
|
|
111
131
|
|
|
@@ -133,25 +153,6 @@ gctree resolve --query 'NestJS DTO plainToInstance'
|
|
|
133
153
|
|
|
134
154
|
---
|
|
135
155
|
|
|
136
|
-
## 설치 & 빠른 시작
|
|
137
|
-
|
|
138
|
-
```bash
|
|
139
|
-
npm install -g @handsupmin/gc-tree
|
|
140
|
-
gctree init
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
`gctree init`이 안내합니다:
|
|
144
|
-
1. 프로바이더 선택: `claude-code`, `codex`, 또는 `both`
|
|
145
|
-
2. 현재 레포에 통합 파일 스캐폴딩
|
|
146
|
-
3. `main` gc-branch 가이드형 온보딩 실행
|
|
147
|
-
|
|
148
|
-
이후 AI 도구가 계획·구현 전에 `gctree resolve`를 호출하는 법을 자동으로 알게 됩니다.
|
|
149
|
-
|
|
150
|
-
- **CLI:** `gctree`
|
|
151
|
-
- **요구 사항:** Node.js 20+
|
|
152
|
-
|
|
153
|
-
---
|
|
154
|
-
|
|
155
156
|
## 자주 쓰는 흐름
|
|
156
157
|
|
|
157
158
|
### 워크스트림마다 별도 컨텍스트
|
|
@@ -214,19 +215,19 @@ gctree set-repo-scope --branch client-b --exclude # 현재 레포 제외
|
|
|
214
215
|
|
|
215
216
|
## 핵심 명령
|
|
216
217
|
|
|
217
|
-
| 목적
|
|
218
|
-
|
|
219
|
-
| gc-tree 초기화 및 프로바이더 선택 | `gctree init`
|
|
220
|
-
| 활성 gc-branch 확인
|
|
221
|
-
| 활성 컨텍스트 검색
|
|
222
|
-
| gc-branch 생성 또는 전환
|
|
223
|
-
| 모든 gc-branch 목록
|
|
224
|
-
| 빈 gc-branch 가이드형 온보딩
|
|
225
|
-
| 활성 gc-branch 가이드형 업데이트
|
|
226
|
-
| 레포 범위 규칙 확인
|
|
227
|
-
| 현재 레포 포함/제외 설정
|
|
228
|
-
| 재온보딩 전 gc-branch 초기화
|
|
229
|
-
| 새 환경 스캐폴딩
|
|
218
|
+
| 목적 | 명령 |
|
|
219
|
+
| --------------------------------- | --------------------------------------------------------------- |
|
|
220
|
+
| gc-tree 초기화 및 프로바이더 선택 | `gctree init` |
|
|
221
|
+
| 활성 gc-branch 확인 | `gctree status` |
|
|
222
|
+
| 활성 컨텍스트 검색 | `gctree resolve --query "..."` |
|
|
223
|
+
| gc-branch 생성 또는 전환 | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
|
|
224
|
+
| 모든 gc-branch 목록 | `gctree branches` |
|
|
225
|
+
| 빈 gc-branch 가이드형 온보딩 | `gctree onboard` |
|
|
226
|
+
| 활성 gc-branch 가이드형 업데이트 | `gctree update-global-context` / `gctree ugc` |
|
|
227
|
+
| 레포 범위 규칙 확인 | `gctree repo-map` |
|
|
228
|
+
| 현재 레포 포함/제외 설정 | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
|
|
229
|
+
| 재온보딩 전 gc-branch 초기화 | `gctree reset-gc-branch --branch <name> --yes` |
|
|
230
|
+
| 새 환경 스캐폴딩 | `gctree scaffold --host codex --target /path/to/repo` |
|
|
230
231
|
|
|
231
232
|
---
|
|
232
233
|
|
package/README.md
CHANGED
|
@@ -36,6 +36,39 @@ That's not an AI problem. It's a **context management problem**.
|
|
|
36
36
|
|
|
37
37
|
---
|
|
38
38
|
|
|
39
|
+
## Who this is for
|
|
40
|
+
|
|
41
|
+
You'll get the most out of `gc-tree` if you:
|
|
42
|
+
|
|
43
|
+
- Work across **multiple repos** (monorepo teams, platform + client repos, backend + frontend stacks)
|
|
44
|
+
- Switch between **multiple products or clients** in the same week
|
|
45
|
+
- Find yourself **re-explaining the same context** at the start of every AI session
|
|
46
|
+
- Want AI tools to understand your **conventions, architecture, and domain knowledge** — not just the current file
|
|
47
|
+
|
|
48
|
+
If you only ever work in one repo and one product, you probably don't need this. `CLAUDE.md` or `.cursorrules` is enough.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Install & quick start
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
npm install -g @handsupmin/gc-tree
|
|
56
|
+
gctree init
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`gctree init` walks you through:
|
|
60
|
+
|
|
61
|
+
1. Choose provider: `claude-code`, `codex`, or `both`
|
|
62
|
+
2. Scaffold the integration files into your current repo
|
|
63
|
+
3. Run guided onboarding for the `main` gc-branch
|
|
64
|
+
|
|
65
|
+
After that, your AI tool will know to call `gctree resolve` before planning or implementing.
|
|
66
|
+
|
|
67
|
+
- **CLI:** `gctree`
|
|
68
|
+
- **Requires:** Node.js 20+
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
39
72
|
## What gc-tree does
|
|
40
73
|
|
|
41
74
|
`gc-tree` sits **above the repo level**. It stores durable context in structured markdown files and lets your AI tools pull only what's relevant — before each session, automatically.
|
|
@@ -64,34 +97,21 @@ Your AI tool gets the right context. Not the whole knowledge base — just the r
|
|
|
64
97
|
|
|
65
98
|
---
|
|
66
99
|
|
|
67
|
-
## Who this is for
|
|
68
|
-
|
|
69
|
-
You'll get the most out of `gc-tree` if you:
|
|
70
|
-
|
|
71
|
-
- Work across **multiple repos** (monorepo teams, platform + client repos, backend + frontend stacks)
|
|
72
|
-
- Switch between **multiple products or clients** in the same week
|
|
73
|
-
- Find yourself **re-explaining the same context** at the start of every AI session
|
|
74
|
-
- Want AI tools to understand your **conventions, architecture, and domain knowledge** — not just the current file
|
|
75
|
-
|
|
76
|
-
If you only ever work in one repo and one product, you probably don't need this. `CLAUDE.md` or `.cursorrules` is enough.
|
|
77
|
-
|
|
78
|
-
---
|
|
79
|
-
|
|
80
100
|
## Why not just use CLAUDE.md or cursor rules?
|
|
81
101
|
|
|
82
102
|
`CLAUDE.md` is great — for one repo.
|
|
83
103
|
|
|
84
104
|
The moment you have multiple repos, clients, or workstreams:
|
|
85
105
|
|
|
86
|
-
|
|
|
87
|
-
|
|
88
|
-
| Scope
|
|
89
|
-
| Persistence
|
|
90
|
-
| Switching contexts
|
|
91
|
-
| Relevance filtering
|
|
92
|
-
| Onboarding
|
|
93
|
-
| Works with Codex
|
|
94
|
-
| Works with Claude Code | ✅
|
|
106
|
+
| | `CLAUDE.md` / cursor rules | `gc-tree` |
|
|
107
|
+
| ---------------------- | -------------------------- | -------------------------------------------- |
|
|
108
|
+
| Scope | One repo | Multiple repos, one context |
|
|
109
|
+
| Persistence | Per-repo file | Stored outside repos, reused across sessions |
|
|
110
|
+
| Switching contexts | Manual file edits | `gctree checkout client-b` |
|
|
111
|
+
| Relevance filtering | Everything or nothing | Only injects matching docs (~4% of total) |
|
|
112
|
+
| Onboarding | Hand-written | Guided by your AI tool |
|
|
113
|
+
| Works with Codex | ✅ | ✅ |
|
|
114
|
+
| Works with Claude Code | ✅ | ✅ |
|
|
95
115
|
|
|
96
116
|
---
|
|
97
117
|
|
|
@@ -99,13 +119,13 @@ The moment you have multiple repos, clients, or workstreams:
|
|
|
99
119
|
|
|
100
120
|
Tested against real internal documentation (4 Notion exports, Korean + English mixed queries):
|
|
101
121
|
|
|
102
|
-
| Metric
|
|
103
|
-
|
|
122
|
+
| Metric | Result |
|
|
123
|
+
| -------------------------------------------- | ---------------- |
|
|
104
124
|
| Recall — relevant queries find the right doc | **100%** (16/16) |
|
|
105
|
-
| Precision — irrelevant queries return empty
|
|
106
|
-
| F1 score
|
|
107
|
-
| Tokens injected per query vs. total context
|
|
108
|
-
| Works with mixed Korean + English queries
|
|
125
|
+
| Precision — irrelevant queries return empty | **80%** (4/5) |
|
|
126
|
+
| F1 score | **88.9%** |
|
|
127
|
+
| Tokens injected per query vs. total context | **~4%** |
|
|
128
|
+
| Works with mixed Korean + English queries | ✅ |
|
|
109
129
|
|
|
110
130
|
---
|
|
111
131
|
|
|
@@ -133,25 +153,6 @@ gctree resolve --query 'NestJS DTO plainToInstance'
|
|
|
133
153
|
|
|
134
154
|
---
|
|
135
155
|
|
|
136
|
-
## Install & quick start
|
|
137
|
-
|
|
138
|
-
```bash
|
|
139
|
-
npm install -g @handsupmin/gc-tree
|
|
140
|
-
gctree init
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
`gctree init` walks you through:
|
|
144
|
-
1. Choose provider: `claude-code`, `codex`, or `both`
|
|
145
|
-
2. Scaffold the integration files into your current repo
|
|
146
|
-
3. Run guided onboarding for the `main` gc-branch
|
|
147
|
-
|
|
148
|
-
After that, your AI tool will know to call `gctree resolve` before planning or implementing.
|
|
149
|
-
|
|
150
|
-
- **CLI:** `gctree`
|
|
151
|
-
- **Requires:** Node.js 20+
|
|
152
|
-
|
|
153
|
-
---
|
|
154
|
-
|
|
155
156
|
## Common moves
|
|
156
157
|
|
|
157
158
|
### Separate contexts for separate workstreams
|
|
@@ -214,19 +215,19 @@ Context lives outside your repos — no `.gitignore` rules needed, no accidental
|
|
|
214
215
|
|
|
215
216
|
## Core commands
|
|
216
217
|
|
|
217
|
-
| Goal
|
|
218
|
-
|
|
219
|
-
| Initialize gc-tree and choose a provider
|
|
220
|
-
| Confirm the active gc-branch
|
|
221
|
-
| Search the active context
|
|
222
|
-
| Create or switch gc-branches
|
|
223
|
-
| List all gc-branches
|
|
224
|
-
| Guided onboarding for an empty gc-branch
|
|
225
|
-
| Guided durable update for the active gc-branch | `gctree update-global-context` / `gctree ugc`
|
|
226
|
-
| Show repo-scope rules
|
|
227
|
-
| Include/exclude current repo for a gc-branch
|
|
228
|
-
| Reset a gc-branch before re-onboarding
|
|
229
|
-
| Scaffold a new environment
|
|
218
|
+
| Goal | Command |
|
|
219
|
+
| ---------------------------------------------- | --------------------------------------------------------------- |
|
|
220
|
+
| Initialize gc-tree and choose a provider | `gctree init` |
|
|
221
|
+
| Confirm the active gc-branch | `gctree status` |
|
|
222
|
+
| Search the active context | `gctree resolve --query "..."` |
|
|
223
|
+
| Create or switch gc-branches | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
|
|
224
|
+
| List all gc-branches | `gctree branches` |
|
|
225
|
+
| Guided onboarding for an empty gc-branch | `gctree onboard` |
|
|
226
|
+
| Guided durable update for the active gc-branch | `gctree update-global-context` / `gctree ugc` |
|
|
227
|
+
| Show repo-scope rules | `gctree repo-map` |
|
|
228
|
+
| Include/exclude current repo for a gc-branch | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
|
|
229
|
+
| Reset a gc-branch before re-onboarding | `gctree reset-gc-branch --branch <name> --yes` |
|
|
230
|
+
| Scaffold a new environment | `gctree scaffold --host codex --target /path/to/repo` |
|
|
230
231
|
|
|
231
232
|
---
|
|
232
233
|
|