@mcgrapeng/ccg 3.1.0 → 4.1.0

package/README.ja.md

@@ -1,220 +0,0 @@
-# ccg — Code Divergence Detector
-
-> Claude Code のスラッシュコマンド。一度インストールして、diff の上で `/ccg` と入力するだけ。
-
-[![Tests](https://img.shields.io/badge/tests-99%20passing-brightgreen.svg)]()
-[![npm](https://img.shields.io/npm/v/@mcgrapeng/ccg.svg)](https://www.npmjs.com/package/@mcgrapeng/ccg)
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-
-[English](README.md) ｜ [简体中文](README.zh-CN.md) ｜ **日本語** ｜ [한국어](README.ko.md)　·　[アーキテクチャ →](docs/ARCHITECTURE.ja.md)
-
----
-
-## ccg とは
-
-あなたは `auth/login.go` を編集し終え、マージしようとしています。念のため確認したい。今の選択肢は 3 つしかなく、全て欠点があります：
-
-- **単一モデルのレビュー**（Copilot、Cursor `/review`、Aider）は **1 つの視点** しか提供しません。Claude が timing attack を見逃せば、あなたも一緒に見逃します。
-- **複数モデル集約ツール**（zen-mcp-server 等）は意見を **平均化** してしまい、優秀なモデル同士が意見を異にした箇所——人間が本当に助けを必要とする箇所——を覆い隠してしまいます。
-- **手動の二重チェック** は時間が無限にあればやりますが、ありませんね。
-
-ccg は Claude Code 用の `/ccg` スラッシュコマンドで、この 3 つを本当に解決します。任意の diff に対して：
-
-1. 同じ prompt を **Codex（OpenAI）** と **Gemini（Google）** に並列で送信
-2. **Claude** に両方のレポートを読ませ、**両者が意見を異にした箇所を浮かび上がらせる**——そこが人間の判断が必要な場所
-3. コストを記録、リスクに応じて最安充足モデルを自動選択、過去のレビュー履歴を保持
-
-**例え話**：別チームの 2 人のシニアエンジニアに同じ PR をレビューさせ、テックリードに統合させる：「ここは両方同意、ここは意見が分かれた——あなたが決めて、私の見解は以下」。
-
-## いつ ccg を使うか
-
-トリガーは **領域** ではなく **感覚** です。書き終えた自分の diff を見ながら、心の中で次のように考えていたら、ccg の場面です：
-
-| 心の中の独り言 | ccg を使う？ |
-|---|---|
-| 「これを間違えたら午前 3 時に呼び出される」 | ✅ Yes |
-| 「これは判断問題 — 明らかに正しい答えはない」 | ✅ Yes |
-| 「誰か他に先に見てほしい」 | ✅ Yes |
-| 「変数の名前を変えただけ」 | ❌ No |
-| 「ドキュメント変更だけ」 | ❌ No |
-| 「単一モデルとストリーミング対話したい」 | ❌ No（CLI を直接使う） |
-
-**ドメイン横断の実例** —— auth / 暗号ではないが、すべて「シニア 2 人が意見を異にしうる」瞬間：
-
-- **ソーシャルプラットフォーム** —— フィードに新エンゲージメントシグナルを追加して再ランキング · コメントツリー fan-out 戦略 · A/B テストバケッティングロジック · 反スパムレート制限ポリシー · フォロー関係のグラフ DB スキーマ
-- **データ / AI インフラ** —— embedding モデル切替（再インデックスする？） · chunking 戦略変更 · RAG 検索スコアリング · prompt injection 防御レイヤリング
-- **フロントエンド** —— 新ページに SSR vs ISR vs RSC · キャッシュ無効化戦略 · 状態管理リファクタリング · アクセシビリティのトレードオフ
-- **API 設計** —— cursor vs offset ページング · エラーレスポンスモデル · バージョニング方式 · 冪等性キーの扱い
-- **分散システム** —— タイムアウト / 再試行ポリシー · cache TTL vs イベント駆動無効化 · partition tolerance トレードオフ · leader election のセマンティクス
-- **データベース** —— マルチステップマイグレーションの順序 · ホットパスのインデックス選択 · トランザクション分離レベル · 論理削除 vs 物理削除
-- **セキュリティ** —— ええ、auth / 暗号 / 決済もここ —— ただし多くのドメインの 1 つに過ぎない
-
-**パターン**：「妥当なエンジニアが選択肢 A を選ぶこともあれば、別の妥当なエンジニアが B を選ぶこともある」変更 —— これが分岐検出が $0.04 を稼ぐ瞬間。
-
-## なぜ ccg なのか（他ツールとの比較）
-
-**1. 意見の相違こそがシグナル、ノイズではない。**
-Codex が「`subtle.ConstantTimeCompare` を使え」と言い、Gemini が「bcrypt は既に恒定時間、それは cargo-cult」と言った時、**そここそ考える必要がある場所**。他のツールはこれを「timing attack に注意」とぼやかして混ぜます。ccg は両者の生の言葉を見せます。
-
-**2. コスト可視化が組み込み。**
-Codex / Gemini CLI は支出を教えません。ccg は全呼び出しを記録、リスクに応じて最安充足モデルを自動選択（リスクルーティング）、同一プロンプトは 24h キャッシュでゼロコスト。`ccg_usage --this-month` が「今月いくら使った？」に即答。
-
-**3. セッションを跨いで残るレビュー履歴。**
-「2 週間前、モデルは `src/auth.ts` について何と言ったか？」——ccg の追記専用台帳がこれに答えます。ステートレスなツールには不可能です。
-
-## インストール
-
-どちらかを選択：
-
-```bash
-# npm (推奨)
-npx @mcgrapeng/ccg install
-
-# または curl ワンライナー、Node 不要
-curl -fsSL https://raw.githubusercontent.com/mcgrapeng/ccg/main/scripts/curl-install.sh | bash
-```
-
-次に AI CLI を一度だけインストール：
-
-```bash
-npm i -g @openai/codex @google/gemini-cli
-echo 'export GEMINI_API_KEY="<your-key>"' >> ~/.zshenv
-```
-
-確認：
-
-```bash
-npx @mcgrapeng/ccg doctor      # Codex / Gemini / API key をチェック
-npx @mcgrapeng/ccg about       # 7 層の機能と現在の環境状態を表示
-```
-
-## 使い方の完全な例
-
-`auth/login.go` を編集したとします：
-
-```go
-// before                                            // after
-func Login(user, pw string) bool {                   func Login(user, pw string) bool {
-    u := lookupUser(user)                                u := lookupUser(user)
--   return u.Hash == sha256.Sum256([]byte(pw))           hashed, err := bcrypt.GenerateFromPassword([]byte(pw), 12)
-+                                                        if err != nil { return false }
-+                                                        return subtle.ConstantTimeCompare(u.Hash, hashed) == 1
-}
-```
-
-Claude Code を開いて入力：
-
-```
-/ccg
-```
-
-約 30 秒後に表示されるもの——**実際の出力例**、プレースホルダーではない：
-
-```
-📍 範囲：worktree · 1 ファイル · +4 -1 行
-🎯 モード：quality  (risk=65 · auth+35 size>0+5 crypto-mention+25)
-🩺 両レビュアー正常：Codex ✓ · Gemini ✓
-💰 コスト：$0.041
-
-═══ AGREEMENT (2) — 両方が指摘、低シグナル ═══
-• auth/login.go:3 — sha256 はパスワードハッシュでない；bcrypt が正しい
-• auth/login.go:5 — bcrypt エラーは明示的に処理（やっている）
-
-═══ DIVERGENCE (1) — 両モデルが意見不一致 ★ あなたが決定 ═══
-
-▸ auth/login.go:6 — bcrypt ハッシュの比較方法
-  🔵 Codex： 「bcrypt を使っても timing attack を防ぐため
-              subtle.ConstantTimeCompare でラップせよ」
-  🟢 Gemini：「bcrypt.CompareHashAndPassword は既に恒定時間。
-              ラッピングは cargo-cult、長さ不一致 panic を生み得る」
-  ⚖️ Claude： Gemini が正しい。bcrypt.CompareHashAndPassword が標準的な
-              比較方法；その生の出力に対する ConstantTimeCompare は
-              カテゴリ誤り——「ハッシュした pw」と「保存されたハッシュ」を
-              比較しているが、bcrypt は毎回新しいソルトを使うので
-              直接比較は常に false を返す。
-  ➡️ アクション：ConstantTimeCompare 行を以下に置換：
-              `err := bcrypt.CompareHashAndPassword(u.Hash, []byte(pw))`
-              `return err == nil`
-
-═══ BLINDSPOT (1) — どちらも見ていないが Claude が疑う ═══
-• エラーパス：bcrypt エラー時に false を返すのは呼び出し側には正しいが、
-  インフラエラー（bcrypt OOM 等）を静かに飲み込む。ログを追加せよ。
-
-═══ VERDICT: fix-required ═══
-現在の比較ロジックは正しいパスワードを常に拒否する。DIVERGENCE の
-アクションを適用 + エラーログ追加で、マージ可能。
-```
-
-### この出力をどう読むか
-
-| セクション | 意味 | 何をすべきか |
-|---|---|---|
-| **AGREEMENT** | Codex と Gemini の両方が同じ問題を指摘。単一の Claude でも見つかる可能性が高い——**新規情報量低**。 | 流し読み、未修正なら修正。 |
-| **DIVERGENCE** ★ | 両モデルが意見不一致。**これが ccg の存在意義**。Claude の「アクション」行が推奨をくれるが、最終判断はあなた。 | 注意深く読む、Claude の判断を受け入れるかオーバーライド。 |
-| **BLINDSPOT** | どちらのモデルも気付かなかったが Claude が合成時に疑った。**控えめに**——1 回あたり最大 2 件。 | ヒントとして扱う、聖典ではない。 |
-| **VERDICT** | `merge` / `fix-required` / `discuss`。1 行サマリー。 | マージゲートとして使用。 |
-
-レビュー後、`ccg_ledger_record` が JSONL 1 行を台帳に書きます。2 週間後：
-
-```bash
-source ~/.claude/commands/ccg.sh
-ccg_ledger_query "auth/login.go"
-# → "auth/login.go: 3 レビュー · 最新 2026-05-23 (fix-required) · 2026-05-09 (merge) · 2026-04-28 (discuss)"
-```
-
-## 設定（デフォルトで通常は十分）
-
-モードとモデルの選択は自動です。必要なときだけ上書き：
-
-```bash
-CCG_MODE=quality /ccg          # 任意の diff で quality モデルを強制
-CCG_CODEX_MODEL=o3 /ccg        # 1 つのモデルだけ上書き
-CCG_NO_CACHE=1 /ccg            # この呼び出しのみ 24h キャッシュをスキップ
-```
-
-よく使うもの（全部は [アーキテクチャ §5](docs/ARCHITECTURE.ja.md#5-拡張ポイント)）：
-
-| 変数 | デフォルト | 用途 |
-|---|---|---|
-| `CCG_MODE` | `auto` | `auto` / `cost` / `balanced` / `quality` |
-| `CCG_CACHE_TTL_HOURS` | `24` | キャッシュ TTL |
-| `CCG_MAX_PROMPT_KB` | `100` | 1 回あたりのプロンプトサイズ上限 |
-
-コスト目安（USD / 呼び出し、キャッシュヒット後）：
-
-| モード | Codex | Gemini | 標準コスト |
-|---|---|---|---|
-| `cost`     | gpt-5-nano  | gemini-2.5-flash-lite | ~$0.0007 |
-| `balanced` | gpt-5-mini  | gemini-2.5-flash      | ~$0.0046 |
-| `quality`  | gpt-5       | gemini-2.5-pro        | ~$0.0440 |
-
-累計支出はいつでも確認可能：
-
-```bash
-source ~/.claude/commands/ccg.sh
-ccg_usage --this-month
-```
-
-## 適さない用途
-
-- Claude Code 以外の IDE（[zen-mcp-server](https://github.com/BeehiveInnovations/zen-mcp-server) を試してください）
-- 静的解析の置き換え（Semgrep / CodeQL と併用してください）
-- 全 PR で自動実行（ccg はトリアージツール、ボットではありません）
-- ストリーミング出力やマルチターン会話
-
-## アーキテクチャとコントリビュート
-
-ccg は **7 層** で構成されており、「分岐検出」は最上位 1 層にすぎません。下の 6 層（キャッシュ、台帳、使用量、リスクルーティング、スマート diff、安全な CLI スケジューリング）はそれぞれ独立して実問題を解決します。`ccg.sh` を変更する前に [docs/ARCHITECTURE.ja.md](docs/ARCHITECTURE.ja.md) を読んでください。
-
-テスト：
-
-```bash
-bash tests/test_ccg.sh                # 99 個の回帰テスト、~31s
-REAL_CLI=1 bash tests/test_ccg.sh     # +2 個のライブ API テスト（課金あり）
-```
-
-## ライセンスと謝辞
-
-MIT —— [LICENSE](LICENSE) を参照。
-
-[oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) の元々の `/ccg` コンセプト · Claude Code · OpenAI Codex CLI · Google Gemini CLI を基に構築。

package/README.ko.md

@@ -1,219 +0,0 @@
-# ccg — Code Divergence Detector
-
-> Claude Code 슬래시 명령. 한 번 설치하고 diff 위에서 `/ccg`를 입력하세요.
-
-[![Tests](https://img.shields.io/badge/tests-99%20passing-brightgreen.svg)]()
-[![npm](https://img.shields.io/npm/v/@mcgrapeng/ccg.svg)](https://www.npmjs.com/package/@mcgrapeng/ccg)
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-
-[English](README.md) ｜ [简体中文](README.zh-CN.md) ｜ [日本語](README.ja.md) ｜ **한국어**　·　[아키텍처 →](docs/ARCHITECTURE.ko.md)
-
----
-
-## ccg란
-
-`auth/login.go` 변경 후 머지하려고 합니다. 안전 점검을 하고 싶습니다. 오늘 선택지는 세 가지뿐이고, 모두 결함이 있습니다:
-
-- **단일 모델 리뷰**(Copilot, Cursor `/review`, Aider)는 **한 가지 관점**만 제공합니다. Claude가 timing attack을 놓치면 당신도 함께 놓칩니다.
-- **다중 모델 게이트웨이**(zen-mcp-server 등)는 의견을 **평균화**하여, 똑똑한 모델들이 의견을 달리한 곳 — 인간이 정말로 도움이 필요한 유일한 곳 — 을 정확히 가립니다.
-- **수동 교차 검증**은 시간이 무한하다면 할 일. 당신에겐 없습니다.
-
-ccg는 Claude Code용 `/ccg` 슬래시 명령으로, 이 세 가지 모두를 진짜로 해결합니다. 임의의 diff에 대해:
-
-1. 같은 prompt를 **Codex(OpenAI)** 와 **Gemini(Google)** 에 병렬 전송
-2. **Claude** 가 두 보고서를 읽고 **그들이 의견을 달리하는 곳을 부각** —— 인간 판단이 필요한 곳
-3. 비용 추적, 위험 수준에 적합한 가장 저렴한 모델 자동 선택, 과거 리뷰 기억
-
-**비유**: 다른 팀의 시니어 엔지니어 두 명에게 같은 PR을 리뷰시키고, 테크 리드가 종합: "이건 둘 다 동의, 이건 의견이 갈렸음 — 당신이 결정, 내 견해는 다음".
-
-## 언제 ccg를 사용할까
-
-트리거는 **도메인**이 아니라 **느낌**입니다. 방금 작성한 diff를 보면서 마음속으로 다음과 같이 생각하고 있다면 — ccg의 순간입니다:
-
-| 마음속 독백 | ccg 사용? |
-|---|---|
-| "이걸 잘못하면 새벽 3시에 호출됨." | ✅ 예 |
-| "이건 판단의 문제 — 명백히 정답이 있는 게 아님." | ✅ 예 |
-| "누가 먼저 봐줬으면 좋겠다." | ✅ 예 |
-| "변수 이름만 바꿨다." | ❌ 아니요 |
-| "문서만 편집." | ❌ 아니요 |
-| "단일 모델과 스트리밍 대화하고 싶음." | ❌ 아니요 (CLI 직접 사용) |
-
-**도메인 횡단 실제 예시** — 모두 auth/암호화가 아니지만, 모두 "시니어 엔지니어 두 명이 의견이 갈릴" 순간입니다:
-
-- **소셜 플랫폼** — 새 참여 신호로 피드 재정렬 · 댓글 트리 fan-out 전략 · A/B 테스트 버킷팅 로직 · 어뷰즈 방지 레이트 리밋 정책 · 팔로우 관계의 그래프 DB 스키마
-- **데이터 / AI 인프라** — embedding 모델 교체(재인덱싱?) · 청킹 전략 변경 · RAG 검색 점수 · 프롬프트 인젝션 방어 레이어링
-- **프론트엔드** — 새 페이지에 SSR vs ISR vs RSC · 캐시 무효화 전략 · 상태 관리 리팩토링 · 접근성 트레이드오프
-- **API 설계** — 페이지네이션 cursor vs offset · 에러 응답 모델 · 버전 관리 방식 · 멱등성 키 처리
-- **분산 시스템** — 타임아웃 / 재시도 정책 · cache TTL vs 이벤트 기반 무효화 · 분할 내성 트레이드오프 · 리더 선출 의미론
-- **데이터베이스** — 다단계 마이그레이션 순서 · 핫 패스 인덱스 선택 · 트랜잭션 격리 수준 · 소프트 삭제 vs 하드 삭제
-- **보안** — 네, auth / 암호화 / 결제도 여기 — 하지만 많은 도메인 중 하나일 뿐
-
-**패턴**: 합리적인 엔지니어 한 명은 A를 선택하고 다른 합리적인 엔지니어는 B를 선택할 수 있는 모든 변경 — 그게 분기 검출이 $0.04를 회수하는 순간.
-
-## 왜 ccg인가 (다른 도구와의 비교)
-
-**1. 의견 불일치가 신호, 잡음이 아님.**
-Codex가 "`subtle.ConstantTimeCompare`를 사용하라"고 하고 Gemini가 "bcrypt는 이미 constant-time, 그건 cargo-cult"라고 할 때, *그곳이* 당신이 생각해야 할 곳입니다. 다른 도구는 이런 충돌을 모호한 "timing attack 주의"로 섞어버립니다. ccg는 양쪽의 말을 그대로 보여줍니다.
-
-**2. 내장 비용 텔레메트리.**
-Codex / Gemini CLI는 지출을 알려주지 않습니다. ccg는 모든 호출을 기록하고, 위험에 따라 가장 저렴하고 충분한 모델을 자동 선택(위험 라우팅)하며, 같은 prompt는 24h 캐시로 비용 0. `ccg_usage --this-month`가 "지금까지 얼마 썼지?"에 답합니다.
-
-**3. 세션 간에 살아남는 리뷰 이력.**
-"2주 전에 모델이 `src/auth.ts`에 대해 뭐라고 했지?" —— ccg의 추가 전용 원장이 답합니다. 어떤 무상태 도구도 못 합니다.
-
-## 설치
-
-둘 중 선택:
-
-```bash
-# npm (권장)
-npx @mcgrapeng/ccg install
-
-# 또는 curl 한 줄 설치, Node 불필요
-curl -fsSL https://raw.githubusercontent.com/mcgrapeng/ccg/main/scripts/curl-install.sh | bash
-```
-
-그다음 AI CLI를 한 번 설치:
-
-```bash
-npm i -g @openai/codex @google/gemini-cli
-echo 'export GEMINI_API_KEY="<your-key>"' >> ~/.zshenv
-```
-
-확인:
-
-```bash
-npx @mcgrapeng/ccg doctor      # Codex / Gemini / API key 점검
-npx @mcgrapeng/ccg about       # 7개 계층의 기능과 현재 환경 상태 확인
-```
-
-## 사용법 — 완전한 예제
-
-`auth/login.go`를 막 편집했다고 해봅시다:
-
-```go
-// before                                            // after
-func Login(user, pw string) bool {                   func Login(user, pw string) bool {
-    u := lookupUser(user)                                u := lookupUser(user)
--   return u.Hash == sha256.Sum256([]byte(pw))           hashed, err := bcrypt.GenerateFromPassword([]byte(pw), 12)
-+                                                        if err != nil { return false }
-+                                                        return subtle.ConstantTimeCompare(u.Hash, hashed) == 1
-}
-```
-
-Claude Code를 열고 입력:
-
-```
-/ccg
-```
-
-약 30초 후 다음과 같은 출력 —— **실제 출력**, 플레이스홀더 아님:
-
-```
-📍 범위: worktree · 1 파일 · +4 -1 줄
-🎯 모드: quality  (risk=65 · auth+35 size>0+5 crypto-mention+25)
-🩺 두 리뷰어 정상: Codex ✓ · Gemini ✓
-💰 비용: $0.041
-
-═══ AGREEMENT (2) — 양쪽 모두 지적, 낮은 신호 ═══
-• auth/login.go:3 — sha256은 비밀번호 해시 아님; bcrypt가 맞음
-• auth/login.go:5 — bcrypt 에러 명시적 처리 (당신이 했음)
-
-═══ DIVERGENCE (1) — 두 모델이 의견 불일치 ★ 당신이 결정 ═══
-
-▸ auth/login.go:6 — bcrypt 해시 비교 방법
-  🔵 Codex:  "bcrypt를 사용해도 timing attack 방지를 위해
-              subtle.ConstantTimeCompare로 감싸라."
-  🟢 Gemini: "bcrypt.CompareHashAndPassword는 이미 constant-time.
-              감싸는 것은 cargo-cult이고 길이 불일치 panic을 유발할 수 있다."
-  ⚖️ Claude: Gemini가 맞다. bcrypt.CompareHashAndPassword가 표준 비교
-              방법; 그 원시 출력에 ConstantTimeCompare는 카테고리 오류 ——
-              "막 해시한 pw"와 "저장된 해시"를 비교하지만 bcrypt는
-              매번 새 솔트를 쓰므로 직접 비교는 항상 false 반환.
-  ➡️ 액션:   ConstantTimeCompare 줄을 다음으로 교체:
-              `err := bcrypt.CompareHashAndPassword(u.Hash, []byte(pw))`
-              `return err == nil`
-
-═══ BLINDSPOT (1) — 둘 다 못 봤지만 Claude 의심 ═══
-• 에러 경로: bcrypt 오류 시 false 반환은 호출자에겐 맞지만,
-  인프라 오류(bcrypt OOM 등)를 조용히 삼킴. 로그를 추가하라.
-
-═══ VERDICT: fix-required ═══
-현재 비교 로직은 유효한 비밀번호도 항상 거부한다. DIVERGENCE 액션
-적용 + 오류 로깅 추가 후 머지 가능.
-```
-
-### 이 출력을 어떻게 읽는가
-
-| 섹션 | 의미 | 무엇을 할까 |
-|---|---|---|
-| **AGREEMENT** | Codex와 Gemini 둘 다 같은 것을 지적. 단일 소스 Claude도 잡을 가능성 높음 —— **새로운 정보량 낮음**. | 훑어보고, 미수정 시 수정. |
-| **DIVERGENCE** ★ | 두 모델이 의견 불일치. **ccg가 존재하는 진짜 이유**. Claude의 "액션" 줄이 추천을 주지만 최종 결정자는 당신. | 주의 깊게 읽고, Claude 판단 수용 또는 재정의. |
-| **BLINDSPOT** | 어떤 모델도 제기하지 않았지만 Claude가 합성하면서 의심. **신중히 사용** —— 호출당 최대 2건. | 힌트로 다루고, 절대 진리 아님. |
-| **VERDICT** | `merge` / `fix-required` / `discuss`. 한 줄 요약. | 머지 게이트로 사용. |
-
-리뷰 후 `ccg_ledger_record`가 원장에 JSONL 한 줄 기록. 2주 후:
-
-```bash
-source ~/.claude/commands/ccg.sh
-ccg_ledger_query "auth/login.go"
-# → "auth/login.go: 3 리뷰 · 최신 2026-05-23 (fix-required) · 2026-05-09 (merge) · 2026-04-28 (discuss)"
-```
-
-## 설정 (기본값으로 보통 충분)
-
-모드와 모델 선택은 자동입니다. 필요할 때만 재정의:
-
-```bash
-CCG_MODE=quality /ccg          # 모든 diff에 quality 모델 강제
-CCG_CODEX_MODEL=o3 /ccg        # 단일 모델만 재정의
-CCG_NO_CACHE=1 /ccg            # 이번 호출만 24h 캐시 우회
-```
-
-자주 쓰는 것 (전체는 [아키텍처 §5](docs/ARCHITECTURE.ko.md#5-확장-지점)):
-
-| 변수 | 기본값 | 용도 |
-|---|---|---|
-| `CCG_MODE` | `auto` | `auto` / `cost` / `balanced` / `quality` |
-| `CCG_CACHE_TTL_HOURS` | `24` | 캐시 TTL |
-| `CCG_MAX_PROMPT_KB` | `100` | 호출당 프롬프트 크기 상한 |
-
-비용 참고 (USD / 호출, 캐시 적중 후):
-
-| 모드 | Codex | Gemini | 표준 비용 |
-|---|---|---|---|
-| `cost`     | gpt-5-nano  | gemini-2.5-flash-lite | ~$0.0007 |
-| `balanced` | gpt-5-mini  | gemini-2.5-flash      | ~$0.0046 |
-| `quality`  | gpt-5       | gemini-2.5-pro        | ~$0.0440 |
-
-누적 지출은 언제든:
-
-```bash
-source ~/.claude/commands/ccg.sh
-ccg_usage --this-month
-```
-
-## 적합하지 않은 경우
-
-- Claude Code 이외의 IDE ([zen-mcp-server](https://github.com/BeehiveInnovations/zen-mcp-server) 시도)
-- 정적 분석 대체 (Semgrep / CodeQL과 함께 사용)
-- 모든 PR에 자동 실행 (ccg는 트리아지 도구, 봇이 아닙니다)
-- 스트리밍 출력 또는 멀티턴 대화
-
-## 아키텍처 및 기여
-
-ccg는 **7개 계층**으로 구성되며, "분기 검출"은 최상위 1개 계층일 뿐입니다. 아래 6개 계층(캐시, 원장, 사용량, 위험 라우팅, 스마트 diff, 안전한 CLI 스케줄링)은 각각 독립적으로 실제 문제를 해결합니다. `ccg.sh`를 변경하기 전에 [docs/ARCHITECTURE.ko.md](docs/ARCHITECTURE.ko.md)를 읽어주세요.
-
-테스트:
-
-```bash
-bash tests/test_ccg.sh                # 99개 회귀 테스트, ~31s
-REAL_CLI=1 bash tests/test_ccg.sh     # +2개 실제 API 테스트 (비용 발생)
-```
-
-## 라이선스 및 감사의 말
-
-MIT —— [LICENSE](LICENSE) 참조.
-
-[oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode)의 원래 `/ccg` 컨셉 · Claude Code · OpenAI Codex CLI · Google Gemini CLI 기반.

package/README.zh-CN.md

@@ -1,219 +0,0 @@
-# ccg — 代码分歧检测器
-
-> Claude Code 的 slash command。装一次，在 diff 上输入 `/ccg`。
-
-[![Tests](https://img.shields.io/badge/tests-99%20passing-brightgreen.svg)]()
-[![npm](https://img.shields.io/npm/v/@mcgrapeng/ccg.svg)](https://www.npmjs.com/package/@mcgrapeng/ccg)
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-
-[English](README.md) ｜ **简体中文** ｜ [日本語](README.ja.md) ｜ [한국어](README.ko.md)　·　[架构文档 →](docs/ARCHITECTURE.zh-CN.md)
-
----
-
-## ccg 是什么
-
-你刚改完 `auth/login.go`，准备 merge。你想"保险一下"再走。今天你只有三种选择，每种都有硬伤：
-
-- **单模型 review**（Copilot、Cursor `/review`、Aider）只给**一种视角**。如果 Claude 漏看了 timing attack，你也会一起漏。
-- **多模型聚合工具**（zen-mcp-server 等）把多个模型的意见**平均化**，恰好遮盖了它们意见分歧的地方——而那才是你真正需要思考的位置。
-- **手工双查**理论上最稳，但你没那个时间。
-
-ccg 是 Claude Code 的 `/ccg` slash command，针对这三件事都做了真正的解决：
-
-1. 把同一个 prompt **并行**发给 **Codex（OpenAI）** 和 **Gemini（Google）**
-2. 让 **Claude** 读完两份报告，**聚焦它们意见不一致的地方**——人需要拍板的就在那里
-3. 自动按代码风险选最便宜够用的模型、记录每次调用成本、保留历史评审账本
-
-**类比理解**：就像让两个不同团队的 senior 工程师 review 同一份 PR，再让一个 tech lead 综合："这几点他们都同意，这一点他们意见不一致——你来定，下面是我的看法。"
-
-## 什么时候用 ccg
-
-触发条件不是**领域**，而是**感觉**。当你看着自己刚写完的 diff，心里冒出下面这种念头，就是 ccg 的场景：
-
-| 你心里在想 | 用 ccg？ |
-|---|---|
-| "这个改错了，我凌晨会被叫起来" | ✅ 用 |
-| "这是个判断题，没有一定对的答案" | ✅ 用 |
-| "我希望有第二个人帮我看一眼" | ✅ 用 |
-| "我就是改了个变量名" | ❌ 不用 |
-| "只改了文档" | ❌ 不用 |
-| "我想跟单个模型流式对话" | ❌ 不用（直接用 CLI） |
-
-**跨领域真实例子** —— 都不是 auth / 加密的场景，但都是"两个资深工程师真会吵起来"的瞬间：
-
-- **社交平台** —— feed 排序换了新的互动信号 · 评论树 fan-out 策略 · A/B 实验分桶逻辑 · 反滥用限流策略 · 关注关系的图数据库 schema
-- **数据 / AI 基建** —— 换 embedding 模型（向量库要不要重建？） · 改 chunking 策略 · RAG 检索打分 · prompt injection 防御分层
-- **前端** —— 新页面用 SSR 还是 ISR 还是 RSC · 缓存失效策略 · 状态管理重构 · 可访问性取舍
-- **API 设计** —— 分页用 cursor 还是 offset · 错误响应模型 · 版本管理策略 · 幂等性 key 处理
-- **分布式系统** —— 超时 / 重试策略 · cache TTL vs 事件驱动失效 · 分区容忍度取舍 · leader election 语义
-- **数据库** —— 多步迁移的拆分顺序 · 热点路径的索引选择 · 事务隔离级别 · 软删 vs 硬删
-- **安全** —— 对，auth / 加密 / 支付也属于这类 —— 但只是众多领域之一
-
-**判断标准**：任何一个"合理的工程师可能选 A、另一个合理的工程师可能选 B"的改动，就是分歧检测赚回 $0.04 的时刻。
-
-## 为什么是 ccg（和其他工具的对比）
-
-**1. 分歧才是信号，不是噪音。**
-当 Codex 说"加上 `subtle.ConstantTimeCompare` 防 timing attack"，而 Gemini 说"bcrypt 自己就是恒定时间的，加包装是 cargo-cult"——**这才是你需要思考的地方**。别的工具会把这种冲突糊成一句模糊的"注意 timing 攻击"。ccg 把两边原话端给你。
-
-**2. 内置成本可见性。**
-Codex / Gemini CLI 都不告诉你花了多少钱。ccg 记录每次调用，按风险自动选最便宜够用的模型（risk-aware routing），相同 prompt 24h 内命中缓存零成本。`ccg_usage --this-month` 立刻回答"这个月我花了多少？"。
-
-**3. 跨会话保留的评审历史。**
-"两周前模型对 `src/auth.ts` 说了什么？"——ccg 的 append-only 账本能回答。任何无状态工具都做不到。
-
-## 怎么安装
-
-二选一：
-
-```bash
-# npm（推荐）
-npx @mcgrapeng/ccg install
-
-# 或 curl 一行装，无需 Node
-curl -fsSL https://raw.githubusercontent.com/mcgrapeng/ccg/main/scripts/curl-install.sh | bash
-```
-
-再装两个 AI CLI（一次性）：
-
-```bash
-npm i -g @openai/codex @google/gemini-cli
-echo 'export GEMINI_API_KEY="<你的-key>"' >> ~/.zshenv
-```
-
-验证：
-
-```bash
-npx @mcgrapeng/ccg doctor      # 检查 Codex / Gemini / API key
-npx @mcgrapeng/ccg about       # 看 7 层能力 + 当前环境状态
-```
-
-## 完整使用示例
-
-假设你刚改了 `auth/login.go`：
-
-```go
-// 改前                                              // 改后
-func Login(user, pw string) bool {                   func Login(user, pw string) bool {
-    u := lookupUser(user)                                u := lookupUser(user)
--   return u.Hash == sha256.Sum256([]byte(pw))           hashed, err := bcrypt.GenerateFromPassword([]byte(pw), 12)
-+                                                        if err != nil { return false }
-+                                                        return subtle.ConstantTimeCompare(u.Hash, hashed) == 1
-}
-```
-
-你在 Claude Code 输入：
-
-```
-/ccg
-```
-
-约 30 秒后你会看到——**真实输出示例**，不是占位符：
-
-```
-📍 范围：worktree · 1 个文件 · +4 -1 行
-🎯 模式：quality  (风险=65 · auth+35 size>0+5 crypto-mention+25)
-🩺 两个评审者都正常：Codex ✓ · Gemini ✓
-💰 成本：$0.041
-
-═══ AGREEMENT (2) — 两边都标记，信号弱 ═══
-• auth/login.go:3 — sha256 不是密码哈希；换成 bcrypt 是对的
-• auth/login.go:5 — bcrypt 错误要显式处理（你做了）
-
-═══ DIVERGENCE (1) — 两个模型不一致 ★ 你来决定 ═══
-
-▸ auth/login.go:6 — 怎么比较 bcrypt 哈希
-  🔵 Codex 说： "外包一层 subtle.ConstantTimeCompare 防 timing 攻击，
-                即使用了 bcrypt 也要加。"
-  🟢 Gemini 说："bcrypt.CompareHashAndPassword 自身就是恒定时间的。
-                外包一层是 cargo-cult，反而可能因为长度不一致 panic。"
-  ⚖️ Claude 综合：Gemini 是对的。bcrypt.CompareHashAndPassword 才是
-                标准比较方式；对它的原始输出做 ConstantTimeCompare 是
-                根本性错误——你比较的是"刚 hash 的 pw"和"存储的 hash"，
-                而 bcrypt 每次 hash 都用新的盐，所以直接比较永远返回 false。
-  ➡️ 建议动作： 把 ConstantTimeCompare 那行替换为：
-                `err := bcrypt.CompareHashAndPassword(u.Hash, []byte(pw))`
-                `return err == nil`
-
-═══ BLINDSPOT (1) — 两边都没看到 Claude 怀疑 ═══
-• 错误处理路径：bcrypt 出错时返回 false 对调用方是对的，但是会静默吞掉
-  基础设施错误（比如 bcrypt OOM）。建议加日志。
-
-═══ VERDICT: fix-required ═══
-当前比较逻辑会永远拒绝合法密码。按 DIVERGENCE 的建议改完 + 加错误日志，
-就可以 merge 了。
-```
-
-### 怎么看懂这份输出
-
-| 段落 | 是什么意思 | 你该怎么办 |
-|---|---|---|
-| **AGREEMENT** | Codex 和 Gemini 都标记的同一个问题。你单源用 Claude 也大概率能发现——**新信息量低**。 | 扫一眼，没改的就改。 |
-| **DIVERGENCE** ★ | 两个模型意见不一致。**这才是 ccg 存在的真正原因。** Claude 的"建议动作"给你推荐，但你是最终拍板的人。 | 仔细读，接受 Claude 判断或自己覆盖。 |
-| **BLINDSPOT** | 两个模型都没看到，但 Claude 综合时怀疑。**慎用**——每次最多 2 条。 | 当提示看，不是金科玉律。 |
-| **VERDICT** | `merge` / `fix-required` / `discuss`。一句话结论。 | 当 merge 门禁用。 |
-
-评审完，`ccg_ledger_record` 会写一行 JSONL 到账本。两周后你可以：
-
-```bash
-source ~/.claude/commands/ccg.sh
-ccg_ledger_query "auth/login.go"
-# → "auth/login.go: 3 次评审 · 最近 2026-05-23 (fix-required) · 2026-05-09 (merge) · 2026-04-28 (discuss)"
-```
-
-## 配置（默认值通常够用）
-
-模式和模型都是自动的。需要时再覆盖：
-
-```bash
-CCG_MODE=quality /ccg          # 任意 diff 都强制 quality 模型
-CCG_CODEX_MODEL=o3 /ccg        # 单独换某个模型
-CCG_NO_CACHE=1 /ccg            # 本次跳过 24h 缓存
-```
-
-常用配置（全部在 [架构文档 § 5](docs/ARCHITECTURE.zh-CN.md#5-扩展点)）：
-
-| 变量 | 默认 | 用途 |
-|---|---|---|
-| `CCG_MODE` | `auto` | `auto` / `cost` / `balanced` / `quality` |
-| `CCG_CACHE_TTL_HOURS` | `24` | 缓存 TTL |
-| `CCG_MAX_PROMPT_KB` | `100` | 单次 prompt 大小硬上限 |
-
-成本参考（USD / 次，缓存命中 $0）：
-
-| 模式 | Codex | Gemini | 单次典型 |
-|---|---|---|---|
-| `cost`     | gpt-5-nano  | gemini-2.5-flash-lite | ~$0.0007 |
-| `balanced` | gpt-5-mini  | gemini-2.5-flash      | ~$0.0046 |
-| `quality`  | gpt-5       | gemini-2.5-pro        | ~$0.0440 |
-
-随时查累计：
-
-```bash
-source ~/.claude/commands/ccg.sh
-ccg_usage --this-month
-```
-
-## 不适合的场景
-
-- Claude Code 之外的 IDE（试试 [zen-mcp-server](https://github.com/BeehiveInnovations/zen-mcp-server)）
-- 替代静态分析（要配合 Semgrep / CodeQL 用）
-- 每个 PR 自动跑（ccg 是分诊工具，不是机器人）
-- 流式输出或多轮对话
-
-## 架构与贡献
-
-ccg 一共 **7 层**，"分歧检测"只是最上面一层。下面 6 层（缓存、账本、用量、风险路由、智能 diff、安全 CLI 调度）各自独立解决真问题。改 `ccg.sh` 之前先读 [docs/ARCHITECTURE.zh-CN.md](docs/ARCHITECTURE.zh-CN.md)。
-
-测试：
-
-```bash
-bash tests/test_ccg.sh                # 99 个回归测试，~31s
-REAL_CLI=1 bash tests/test_ccg.sh     # +2 个真实 API 测试（会扣费）
-```
-
-## 许可证与致谢
-
-MIT —— 见 [LICENSE](LICENSE)。
-
-基于 [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) 最初的 `/ccg` 概念 · Claude Code · OpenAI Codex CLI · Google Gemini CLI。