Unwritten

Unwritten

自分や AI エージェントが変更し忘れたファイルを見つけます。 Unwritten は git の履歴から、どのファイルが一緒に変更されることが多いかを学習し、編集対象から漏れているファイルがあると警告します。「OrderService.cs を変更しましたが、OrderServiceTests.cs は変更していません。この 2 つは 94% の確率で一緒に変更されています」という具合です。こうした変更漏れのあるファイルを 穴 と呼び、すべての警告に確信度スコアと、証拠となる実際のコミット例を添えます。

1 possible hole(s):

  src/Orders/OrderServiceTests.cs
    expected because you changed src/Orders/OrderService.cs
    confidence 0.826 (90 co-changes in 100 changes)
    e.g. 3f2a1c9 Add surcharge handling to freight calculation

FAIL: at least one hole at confidence >= 0.70.

AI コーディングエージェント（Claude Code、Copilot）がセッション中に自分の編集内容を確認できるよう、MCP サーバーとして動作します。また、コミット前フック用の CLI としても使えます。dotnet tool execute を 1 回実行すれば、.unwritten/ にインデックスが作成されます。サーバーもサブスクリプションもトークンも不要です。

どの言語でも使えます。 ファイル単位のルールには git の履歴しか必要ないため、Python、TypeScript、Go、または複数の言語が混在するリポジトリでも、同じように変更漏れを検出できます。C# リポジトリでは、さらにメソッド単位のルールと表面的な編集のフィルタリングが利用できます。JSON ファイルでは、キー単位でノイズをフィルタリングできます。ツールの実行には .NET SDK（10 以降）が必要ですが、分析対象のリポジトリはどのようなものでもかまいません。

クイックスタート

リポジトリのルートから実行します。

1. インデックスを事前に準備します（任意です。どのコマンドも初回実行時にインデックスを作成し、その後は自動で最新の状態に保つため、これは最初のクエリを速くするだけです）。

dotnet tool execute Unwritten --yes -- reindex

2. MCP サーバーとして登録します（Claude Code）。

claude mcp add unwritten -- dotnet tool execute Unwritten --yes -- mcp

3. （Claude Code を使用する場合に推奨）チェックを確実に実行できるようにします。git の pre-commit フックと Claude Code の Stop フックを使い、コミット前に失敗した穴をエージェントにフィードバックします。

dotnet tool execute Unwritten --yes -- install-hook --git --claude-code

これで完了です。エージェントは編集後に check_holes を呼び出せるようになり、フックによって変更し忘れを検出できます。

解説動画

https://github.com/user-attachments/assets/4ae7a22d-c611-458f-8c48-08f87eca1d29

動作例

stats を実行すると、ツールが学習した内容が表示されます。ここでは、ファイルのペアが 1 つ、コミットをブロックするほど強く連動しています（確信度 ≥ 0.7）。片方の変更が漏れている場合にブロックされます。

そのペアの片方を編集すると、もう一方のファイルが漏れていると check が警告し、対処方法を 3 つ示します。もう一方も更新する、変更をコミットする、またはルールを無効にする、のいずれかです。

pre-commit フックをインストールすると、同じチェックがすべてのコミットで自動的に実行され、もう一方のファイルが漏れている間はコミットがブロックされます。

ドキュメント

その他の内容はすべて docs/README.md にあります。

• 背景と、このツールの着想となった研究
• このしきい値を採用した理由（実データでの検証）
• 使い方：MCP サーバー、CLI、フック、誤ったルールの無効化
• 設定リファレンス
• 仕組み
• このツールでできないこと（現時点）

License

MIT