CodeClone について
CodeCloneは、Python開発者、レビュアー、CI向けの決定論的な構造レビュー ツールです。リポジトリのベースラインと変更を比較して新たな回帰を特定し、2.1 alphaではAIエージェントの編集範囲を定めて検証するMCP制御機能も加わります。
主な機能
- 01重複、複雑度、結合度を分析
- 02既存の問題と新たな回帰を区別
- 03統一レポートを複数形式で出力
- 04CIで構造変更とAPI破壊をゲート
- 052.1 alphaでエージェントの変更を制御・検証
活用シーン
- 01CIで新たな構造回帰を防止
- 02エージェントが宣言範囲を超えたか確認
- 03モジュール依存関係と構造上のホットスポットを調査
MCP 対応
CodeCloneは読み取り専用のMCP制御インターフェースを提供し、2.1 alphaでは変更意図、影響範囲、編集境界、パッチ検証のツールも公開します。MCP応答には決定論的な次のツールの案内が含まれます。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
ツール
ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。
詳細
AI を活用した Python 開発向けの決定論的な構造変更コントローラー
エージェントは迅速に作業できます。
構造変更を明示的かつ限定的にし、検証可能な状態に保ちます。
重要
2.1 alphaと記されたセクションには、 CodeClone 2.1 prerelease が必要です。 それ以外はすべて、現在の安定版である CodeClone 2.0.2 で動作します。
CodeClone とは？
CodeClone を使うと、開発者は構造変更の制御を失うことなく、AI コーディングエージェントを活用できます。
エージェントがコードを編集する前に、CodeClone は意図された変更を記録し、構造上の影響範囲をマッピングして、 明示的な編集境界を設定します。編集後は、実際のパッチと宣言された範囲を比較し、構造上の リグレッションを検証して、監査可能なレビュー記録を残します。
CodeClone はソースファイルを生成または書き換えず、構造変更が安全かどうかを判断するよう LLM に依頼することもありません。あらゆる指摘とゲートは、 エージェント、ヒューマンレビュアー、IDE、レポート、CI で共有される決定論的なリポジトリ情報に基づいています。
| 機能 | 提供内容 |
|---|---|
| 正規構造解析 | クローン、複雑度、結合度、凝集度、デッドコード、モジュールマップ、API インベントリ、カバレッジの関連付けを含む単一の決定論的レポート |
| ベースラインを考慮したガバナンス | 許容済みの既存の負債を記録し、現在の変更によって生じたリグレッションと区別します |
| 1 つのレポートを多様な形式で提供 | 1 つの正規ペイロードから、CLI、HTML、JSON、Markdown、SARIF、MCP、IDE 連携、GitHub Actions を提供します |
構造変更コントローラー — 2.1 alpha | 意図を先に定める変更管理、影響範囲、明示的な編集境界、パッチ検証、レビュー記録 |
ライブ実装コンテキスト — 2.1 alpha | 現在の解析実行から提供される、リアルタイムの構造および呼び出しグラフのコンテキスト — 古くなったインデックスの保守は不要 |
エンジニアリングメモリー — 2.1 alpha | ローカルに保存される、型付けされ、根拠と関連付けられたプロジェクト知識と、過去の管理された変更の再利用可能な履歴 |
エージェント連携 — 2.1 alpha | 競合を防止するマルチエージェントの意図、キュー、復旧、ワークスペースの整理 |
CodeClone の利用にホスト型サービスやクラウドアカウントは不要です。解析状態、コントローラー状態、エンジニアリングメモリー、 軌跡はローカルに保存されます。
差分を見る前に意図を確認する理由
ほとんどのレビュー ツールは、パッチができてから動き始めます。CodeClone はその前から始めます：
task request
→ declared intent
→ structural blast radius
→ explicit boundary
→ actual patch
→ deterministic verification
エージェントのスコープ拡大は、最終的な差分では妥当に見えることがあります。範囲の狭いタスクが、共有ヘルパー、 テスト、構成、パブリック API、または無関係なモジュールにいつの間にか広がることがあります。
その拡大が最終的な差分に現れる頃には、すでに意図的な変更のように見えます。CodeClone は、エージェントが変更すると述べた内容と実際に変更した内容を比較し、宣言された 境界でその拡大を検出します。
クイックスタート
Python 3.10 以降が必要です。
1. リポジトリを分析する
インストールせずに、安定版リリースを実行します：
uvx codeclone@latest .
ブラウザーで確認できるレポートをお求めですか？HTML ビューを生成して開きます：
uvx codeclone@latest . --html --open-html-report
定期的に使うようになったら、ローカルツールとしてインストールします：
uv tool install codeclone
codeclone .
2. 現在の構造ベースラインを記録する
エージェントにリポジトリの変更を依頼する前に、承認済みの状態を一度記録します：
codeclone . --update-baseline
git add codeclone.baseline.json
git commit -m "chore: add CodeClone structural baseline"
ベースラインには、すでに存在する構造的負債が記録されます。これにより、今後の分析では新たなリグレッションと既存の検出結果を区別できるため、エージェントとレビュー担当者は現在の変更で生じた問題に集中できます。
ベースラインの更新は、明示的なガバナンス上の操作です。失敗したチェックを通すためだけに再生成しないでください。
3. AI エージェントを接続する — 2.1 alpha
以下のエージェント変更管理に進み、MCP 制御インターフェースをインストールして、 CodeClone を Claude Code、Cursor、VS Code、Codex、または Claude Desktop に接続します。
唯一の標準構造レポート
CodeClone は決定論的な分析を一度実行し、サポートされているすべてのインターフェースで同じ標準レポートを表示します。
レポートには次の項目が含まれます：
- 関数、ブロック、セグメントのクローン；
- クローンの乖離と重複する分岐ファミリー；
- 複雑度、結合度、凝集度、依存関係の循環、デッドコード；
- モジュールマップ — 循環、ハブ、過負荷モジュール、解消候補のビューを備えたパッケージ／モジュール依存関係グラフ；
- ガイド付き検出結果レビュー — 優先順位付きレビューキューと、共通の検出結果カード、フィルター、進捗管理；
- パブリック API インベントリーと、ベースラインを考慮した API 変更検出；
- 外部カバレッジと構造的ホットスポットの統合；
- 決定論的な構造的健全性とレビューの優先事項。
codeclone . --json --html --md --sarif --text
ベースラインを考慮したガバナンスと CI
ベースラインは、リポジトリの承認済み構造状態を記録する、バージョン管理され整合性が検証された仕様です。
CodeClone と接続されたエージェントは、次の項目を区別できます：
- すでに存在していた検出結果；
- 現在の変更によって生じたリグレッション；
- ユーザーが承認した意図的なベースライン更新。
今後の変更を、コミット済みのベースラインと照らし合わせて確認します：
codeclone . --ci
GitHub Actions で CodeClone を使用します：
- uses: orenlab/codeclone/.github/actions/codeclone@v2
with:
fail-on-new: "true"
sarif: "true"
pr-comment: "true"
CI では、既存のリポジトリを事前にクリーンな状態にする必要なく、新たに導入されたクローン、メトリクスのリグレッション、API の破壊的変更、カバレッジのリグレッションを拒否できます。
CodeClone の特徴
リンターはファイルごとにスタイルと正確性をチェックします。クローン検出ツールは重複を報告するだけで、その先には進みません。ホスト型のレビュー ボットは、完成した差分についてモデルに意見を求めます。
CodeClone は、CFG ベースのクローン検出、複数指標によるベースライン管理、読み取り専用の MCP 制御インターフェースを、ローカルファーストのオープンソースパッケージに統合し、編集が行われた後だけでなく、編集が行われる前にも適用します。構造上の事実は決定論的に計算されるため、ターミナルでも CI でもエージェントのループ内でも、同じ入力から常に同じ判定が得られます。
エージェントの変更管理 — 2.1 alpha
MCP 制御インターフェースをインストールする
uv tool install --prerelease allow "codeclone[mcp]"
codeclone-mcp --transport stdio
このサーバーは、分析、変更管理、影響範囲、メモリ、診断を網羅する38 個の MCP ツールを提供します。応答はエージェントのループ向けに構成されています。決定論的なnext_toolの案内、トークン予算を考慮したペイロード、必須の制御情報をインラインに保ちながら詳細確認用の完全な根拠へのリンクを含む応答を提供します。
エージェントや CI のゲートを設定する前に、[tool.codeclone]とローカルの gitignore の状態を確認してください。
codeclone setup status
codeclone setup plan
codeclone setup apply # or: codeclone setup wizard
リポジトリのセットアップと準備状況を参照してください。
クライアントに接続する
| クライアント | セットアップ |
|---|---|
| VS Code | 拡張機能のセットアップ |
| Cursor | プラグインとスキル |
| Claude Code | プラグインのセットアップ |
| Codex | プラグインのセットアップ |
| Claude Desktop | バンドルのセットアップ |
すべてのクライアントは、同じ MCP インターフェースと正規の構造上の事実を使用します。
管理された変更のワークフロー
エージェントの通常のワークフローは次のとおりです。
analyze → start → edit → finish
分析。 CodeClone はリポジトリの正規の構造レポートを作成し、承認済みのベースラインと比較します。
開始。 start_controlled_changeは次の処理を行います。
- エージェントの意図を記録します。
- 構造上の影響範囲をマッピングします。
- 編集可能なパス、レビュー用のコンテキスト、変更禁止の境界を分けます。
- 承認済みのベースラインに対する回帰予算を提示します。
- 権威ある
edit_allowedの結果を返します。
編集。 エージェントがコードを書き込みます。CodeClone はソースファイルを生成したり書き換えたりしません。ホストがフックに対応している場合、edit_allowed=trueでない限り編集を停止するよう、連携機能を設定できます。編集時には、広範な検索でリポジトリを再調査するのではなく、実装時のライブコンテキストを通じてエージェントが状況を把握します。
完了。 finish_controlled_changeは次の処理を行います。
- 実際に変更されたファイルを特定します。
- 宣言された範囲を実際のパッチと照合します。
- 構造上の変更を検証します。
- 任意のレビュー主張を検証します。
- Patch Trail の証拠を記録します。
- 監査可能なレビュー証明書を作成します。
パッチが宣言された境界を越えた場合や、予算を超える回帰が発生した場合、検証は失敗し、証明書にはその箇所と理由が正確に記録されます。この結果は、パッチに対する AI の意見ではありません。宣言された意図、リポジトリの構造、承認済みのベースライン、実際の変更を決定論的に比較したものです。
ライブ実装コンテキスト
get_implementation_context は、現在の分析実行からタスクの範囲に限定したコンテキストをエージェントに直接提供します。
- 宣言された編集範囲の構造的コンテキストと呼び出し関係
- コントラクトを中心とした真実のマップとテストのアンカー
- 鮮度シグナルと有効な意図の境界
コードの裏で別のベクターデータベースが独立して変化することも、ツリーを再インデックスするウォッチャーデーモンもありません。コンテキストは、検出結果とゲートを生成するものと同じ分析から得られます。つまり、エージェントが読み取る内容を検証器もチェックします。コンテキストは読み取り専用です。編集の参考にはなりますが、編集を許可するものではありません。
2.1 系列のその他の機能
- プラットフォームの可観測性 — CLI、MCP、分析フェーズ、データベースのアクティビティ、ペイロードの負荷を開発時にトレースできます。CodeClone 自体の動作と、そのコストを確認できます。
- コーパス分析 — 記録された制御変更を対象に、オフラインで意図をクラスタリングして解釈します。バージョン管理されたプロファイルと、調査可能な JSON/HTML 出力を利用できます。
エンジニアリングメモリー — 2.1 alpha
エンジニアリングメモリーは、モデルの出力をプロジェクトの真実として扱うことなく、エージェントに永続的なリポジトリ固有のコンテキストを提供します。
ローカルの SQLite ストアには、次の情報を保存できます。
- アーキテクチャとコントラクトに関するメモ
- リスク、テストのアンカー、公開サーフェス
- git と変更管理の来歴
- 過去の軌跡と Patch Trail の証拠
- Experiences と呼ばれる、繰り返し現れる助言パターン
エージェントが作成したレコードは、人間が承認するまでドラフトとして保持されます。
codeclone memory init --root .
codeclone memory search "baseline schema" --match all
検索にはハイブリッド方式を採用しています。FTS5/BM25 による語彙検索、オプションの LanceDB ベクター検索、および両者を組み合わせる Reciprocal Rank Fusion を使用し、ランキングを完全に再現できます。
メモリーはエージェントの指針として利用できます。ただし、編集を許可したり、影響範囲を上書きしたり、ゲートを変更したり、正規のレポート事実に取って代わったりすることはできません。
エンジニアリングメモリーのドキュメント · 軌跡と Experiences
信頼境界
- 構造分析の検出結果とゲートは、LLM の判断ではなく、決定論的な分析に基づきます。
edit_allowedは明示的なコントローラーの結果です。ステータスや助言の所有権によって編集権限が付与されることはありません。- 読み取り専用の分析コマンドは、ソースコードやプロジェクトのガバナンス状態を変更しません。
- ベースラインの更新は、ユーザーが明示的に承認するガバナンス操作です。
- コントローラーとメモリーの操作は、明示的に指定されたローカル状態ストアにのみ書き込みます。
- メモリー、軌跡、実装コンテキストの証拠は、引き続き助言として扱われます。
- ローカルクライアントには
stdioの使用を推奨します。 - リモート HTTP への公開には、明示的な
--allow-remoteが必要です。
貢献
バグ報告、機能に関する議論、プルリクエストを歓迎します。Issues または Discussions から始めるか、 Discord に参加してください。
ソースからリポジトリのバージョンを実行します。
git clone https://github.com/orenlab/codeclone.git
cd codeclone
uv sync --all-extras
uv run codeclone .
ドキュメント
ライセンス
- コード： MPL-2.0
- ドキュメント： MIT
ライセンスの適用範囲については、LICENSES.md を参照してください。
Links
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。