koment

koment

コードのそばに「なぜ」を残しましょう。チェックされるので、いつの間にか古くなることもありません。

問題

誰かが 3 回ではなく retry 5 times と書きました。それにはちゃんとした理由がありました。半年後には誰も覚えておらず、「簡素化」のために 3 回に戻され、バグが再発します。

それを防ぐはずだったのがコメントです。しかし、コメントは古くなります。コードのそばにあってもコードと結び付いていないため、コードが変わってもコメントが嘘になったことを誰も知らせてくれません。そして AI エージェントはその嘘を読み、それに基づいて動作します。

koment ができること

理由をソースコードの外部に記録し、説明対象の正確な行にひも付けます。すると koment がその行を監視します。行を変更すると、変更を知らせます。

$ koment check
internal/auth/token.go
  drifted   gotcha        internal/auth/token.go  01KZN63VC5SZASDYJBMPDC03WB
    Without it, clients whose clock runs fast get logged out mid-request. Bit
    us in #412.
1 annotation across 1 file: 1 drifted
koment: 1 annotation no longer resolves; revisit it or update the anchor

終了コードは 1 です。ビルドは停止します。コードの説明として成り立たなくなった理由を、誰にも気付かれずに引き継ぐことはありません。

記録は Git リポジトリ内の .koment/ にある YAML ファイルです。データベースも、サービスも、アカウントも必要ありません。記録のきっかけとなった変更と同じプルリクエストでレビューできます。

動作を確認 → — koment 自身のアノテーションを、コピーして使えるワークフローで公開しています。

AI エージェント向け

ここで真価を発揮します。エージェントは説明コメントを頻繁に書き、なぜそのように書かれたのかを確認せずにコードを編集します。koment を使えば、エージェントが作業中のうちに、どちらも即座に失敗させられます。

• コメントを書く → 編集を拒否し、その理由は代わりにアノテーションとして記録するよう指示します。
• 確認せずにアノテーション付きのコードを編集する → アノテーションを再確認するまで、ターンを完了できません。

1 つの MCP サーバーで Claude Code、Cursor、Codex、opencode、Hermes、Zed などに対応するため、すべてのエージェントが同じインターフェースを通じて同じ理由を読み取れます。 セットアップする →

人間もエディターで同じ流れを利用できます。コメントの下に波線が表示され、クイックフィックスからアノテーションに変換するか、記録に残したうえでコメントを維持するかを選べます。

インストール

brew install koment-dev/tap/koment

mise use -g github:koment-dev/koment          # mise
go install github.com/koment-dev/koment/cmd/koment@latest
docker run --rm -v "$PWD:/repo" -w /repo ghcr.io/koment-dev/koment:3 check

1 分で試す

任意の Git リポジトリ内で実行します。

koment bootstrap

これにより .koment/ がセットアップされ、使用するエージェントが連携されます。理由を記録して、チェックされる様子を確認しましょう。

koment add src/auth.go \
  --excerpt 'if token.Expiry.Before(now.Add(-clockSkew)) {' \
  --kind gotcha \
  --title 'Skew subtraction keeps fast clocks logged in' \
  --body 'Without it, clients whose clock runs fast get logged out
          mid-request. Bit us in #412.'

koment check     # ok

次に、その行を編集して koment check をもう一度実行します。 チェックは失敗し、コードと一致しなくなった理由を知らせます。これが製品のすべてです。それ以外は、必要とする人やエージェントに届けるための仕組みです。

koment ui        # read them in a browser
koment show src/auth.go

仕組み

1. スニペットに注釈を付けます。koment は、説明文、正確な抜粋、その周辺のソースコンテキスト、作業中のコミット、作成者を記録します。

2. 記録は .koment/annotations/<id>.yaml に、注釈ごとに1つのファイルとして保存されます。エージェントが同時に作業しても、共有リストを上書きせず、それぞれ独立したファイルを作成します。

3. 解決処理では、現在のファイルからその抜粋を検索し、次のいずれか1つのステータスを出力します。

   	意味	ビルド
   ok	最後に確認された場所で見つかった	成功
   ambiguous	コンテキスト上の候補が複数残っている	失敗
   drifted	ファイルは存在するが、注釈対象のコードがなくなっている	失敗
   orphaned	ファイルがなくなっている	失敗

4. koment check は、ambiguous、drifted、orphaned の場合にゼロ以外の終了コードを返します。仕組みはこれだけです。不確かな根拠を残すより、注釈がない方がよいため、無視できないようにする必要があります。

5. 失敗した場合は、koment reanchor <id> --excerpt '<new text>' で付け直します。IDと作成日はそのままに、コンテキストと行番号を再取得します。自動で再付与されることはありません。根拠が今も有効かどうかは、人が確認します。

アンカーには抜粋を使い、行番号は使いません。行番号は、その上の行が次に編集された時点で古くなるためです。コミットハッシュは記録されますが、履歴を再構築する目的に限られます。注釈が今も適用されるかどうかの判断には使いません。この2つは、仕組みも異なる別々の問いです。

ローカルへの書き込みは、すでにレビュー中のチェックアウトを変更します。サーバー経由の書き込みは、レプリカに触れたりデフォルトブランチへプッシュしたりすることはありません。決定論的なブランチに正確な注釈を作成し、そのプルリクエストが作成されてから応答します。静的な公開データは変更不可で、読み取り専用です。

3つの実行方法

いずれか1つを選んでください。それぞれが利用を止める場所であり、順番に進める必要はありません。また、方法を切り替えても移行にはなりません。3つとも git 内の同じ .koment/ を読み込むため、エクスポート、インポート、バックアップは不要です。

複数のリポジトリ

1つのデプロイメントで複数のリポジトリに対応します。IDはプロバイダーのパスとは独立して割り当てられ、更新のたびにブランチを1つの不変なコミットに解決してから、リポジトリのアクティブなスナップショットを置き換えます。

# yaml-language-server: $schema=https://raw.githubusercontent.com/koment-dev/koment/main/schema/server.schema.json
repositories:
  - id: payments
    name: Payments API
    provider: github
    remote: you/payments
    default_branch: main
    default: true
  - id: web
    name: Customer Web
    provider: github
    remote: you/web
    default_branch: main

サービスは、信頼できるプロキシのID、またはスコープ付きベアラートークンのいずれかを備えた、ループバック以外のリスナーがある場合にのみ起動します。プライベートリポジトリとレビュー済みの書き込みには、GitHub トークンも必要です。Helm チャートのドキュメントに、シークレットの形式と境界が記載されています。

ローカルコマンドには、このような設定は不要です。koment は作業ディレクトリから上にたどって、所有するチェックアウトを見つけます。

Kubernetes

koment は OCI Helm チャートを oci://ghcr.io/koment-dev/charts/koment に公開します。

helm install koment oci://ghcr.io/koment-dev/charts/koment \
  --set repositories[0].remote=you/your-repo \
  --set metrics.enabled=true \
  --set metrics.serviceMonitor.enabled=true \
  --set metrics.dashboard.enabled=true

アプリケーションポートでは、ソース、根拠、UI、MCP の認証を行います。公開されるのはライブネスとレディネスのみです。メトリクスには別のリスナーを使用するため、Ingress がアプリケーションの認証を伴わずにメトリクスを誤って公開することはありません。チャートには、Grafana ダッシュボード、ServiceMonitor、セキュリティを強化した Pod のデフォルト設定、オプションの NetworkPolicy と分断制御、ダイジェスト固定の helm test プローブが含まれています。

設定

すべてのフラグは環境変数から設定できます。--flag-name は KOMENT_FLAG_NAME になり、明示的に指定したフラグが常に優先されます。

唯一の正式な記録は Git です。ローカルでの読み取りでは、作業ツリーに対して YAML を直接解決します。破棄可能な読み取りモデルによって Git の状態を復元または上書きすることはできません。

koment <command> --help には、各フラグと対応する環境変数が一覧表示されます。

コードのある場所で作業する

リファレンスの VS Code extension は koment lsp を起動し、アノテーション本文を仮想インラインテキストとして表示し、ドリフトや禁止されたコメントを診断として報告し、ネイティブの追加、再アンカー、変換、明示的な確認アクションを追加します。説明文がソースバッファーに挿入されることはありません。すべてのリリースには署名済み VSIX が添付され、同じ成果物が VS Code Marketplace と Open VSX に公開されます。

他のエディターでも、koment lsp が提供する標準のホバー、診断、コードレンズ、コードアクション、コマンド実行のインターフェイスを利用でき、ストレージやアンカー処理を再実装する必要はありません。

Claude Code では、このリポジトリ独自のプロジェクトスコープのマーケットプレースプラグインをインストールできます。

/plugin marketplace add koment-dev/koment
/plugin install koment@koment-dev

プラグインには書き込み可能な MCP 設定が含まれており、セッション開始時に厳密な手順を挿入し、Claude がターンを終了する前にポリシーゲートを実行します。まずリリース済みの koment バイナリをインストールし、リポジトリ内で koment agents install を実行してください。

OpenCode には、integrations/agent-plugins/opencode/ に並行するプラグインが用意されています。opencode.json の plugin 配列に @koment/opencode-koment を追加すると、OpenCode の起動時にインストールされます。リリース済みの koment バイナリが PATH に必要です。通常の説明的なコメントの意図を拒否し、セッション終了時にポリシーゲートを実行します。ADR 0144 には、パッケージと生成アダプターの境界が記録されています。

Codex には、integrations/agent-plugins/codex/ に同じポリシーインターフェイスがローカルマーケットプレースとして用意されています。codex plugin marketplace add でそのチェックアウトパスをインストールし、続けて codex plugin add koment@koment-dev を実行してください。リリースワークフローでは署名済みアーカイブも生成されます。このプラグインには、書き込み可能な MCP ツール、常時利用可能なスキル、信頼されたライフサイクルフックが含まれています。ADR 0151 には、パッケージの境界が記録されています。

エージェントに渡す

koment agents install
koment mcp --write

生成されたリポジトリアダプターは、エージェントに厳格な手順を示し、書き込み可能な stdio サーバーを構成します。読み取りツールは 3 つあります。

• koment_get(file, repository?) — エージェントが編集しようとしているファイルの注釈
• koment_search(query, repository?) — トピックごとに理由を検索します。repository を省略すると、すべてのリポジトリが検索対象になります
• koment_repositories() — このデプロイメントで提供されている内容と件数

書き込みモードでは、4 つのツールが追加されます。

• koment_add — エージェント名義の理由を作成します
• koment_reanchor — 既存のアンカーを明示的に移動します
• koment_convert_comment — コメントを理由として記録してから、コメントを削除します
• koment_acknowledge_comment — 明示的に承認した場合に限り、例外的なコメントを残します

この 4 つの変更ツールは、ローカルのチェックアウトに対して動作します。認証された MCP サービスからは koment_add が利用でき、決定的なブランチ名、コミット、プルリクエストの URL が返されます。エージェントの別個のワークツリーをサービスが上書きできないよう、ソースを変更する変換とアンカーの再設定はローカルで行います。

すべての注釈には、解決状況とリポジトリの両方が含まれるため、古い注釈が現行のものとして表示されることはなく、検索結果がその対象範囲から切り離されることもありません。複数のリポジトリに同じパスが存在する場合、koment_get は推測せず、候補を示して処理を拒否します。

公開する

レビュアーは何もインストールしません。URL を共有してください。1 つのワークフローファイルですべての注釈を静的 HTML、annotations.json、search.json にレンダリングし、設計が必要なサーバー、データベース、認証なしで、変更されないスナップショットを GitHub Pages に配置します。

- uses: actions/checkout@v7
- uses: koment-dev/koment@v3
- run: koment check
- run: koment site --out dist

各ページにはレンダリング元のコミットが記載されるため、スナップショットが現在のツリーであるかのように見えることはありません。同じワークフロー内で koment check を実行するため、公開対象にずれがあるビルドは、公開前に失敗します。

そのままコピーできるワークフロー全体 →

サイトではソースと注釈の両方がレンダリングされるため、プライベートリポジトリからサイトを公開すると、そのソースも公開されます。複数のリポジトリをまとめて公開する場合は、リポジトリごとに 1 つのスナップショットをレンダリングし、通常のリポジトリ切り替え機能で相互に接続します。セレクター用のランディングページはありません。

ドキュメント

• 公開 — コピーして貼り付けるワークフローと、後からサービス提供インスタンスに移行する方法
• コントリビューターのセットアップ — 検証済みの開発用チェックアウトを用意します
• はじめに · よい注釈を書く · CLI リファレンス · CI

koment が対象としないもの

• 汎用的なプロジェクトドキュメントではありません。 koment が保持するのは、コード内の特定の箇所に結び付いたナレッジです。プロジェクト全体に関するガイダンスは、チームがすでに使用しているドキュメントシステムに記載してください。
• メモリーシステムではありません。 情報を統合するストアは、言い換えや統合を行い、やがて忘れてしまいます。koment は記録であり、信念ではありません。
• 行単位の正確な指定には対応していません。 アンカーはスニペットです。

先行事例

Codetations / Magic Markup は最も近い既存の取り組みで、LLM による再アンカー機能を備えた、ドキュメント外の注釈です。アンカーの問題は Microsoft Research、2001 年にまでさかのぼり、一般的な場合には今も解決されていません。UI の形状は konflate に着想を得ています。konflate は Flux の見えないレイヤーを可視化します。koment が理由のために試みているのと同じです。

ライセンス

integrations/editors/zed/ を除くリポジトリには、オープンソースライセンスとして AGPL-3.0-or-later が適用されます。この拡張機能のコードのみ GPL-3.0-or-later が適用されます。これにより、Zed はこの拡張機能をレジストリ経由でビルドして 配布できます。拡張機能が起動する koment バイナリには、引き続き AGPL が適用されます。 どちらのライセンスファイルも原文のままであり、自動スキャナーが正しく識別できます。 ADR 0145 に この限定的な例外が記録されています。

完全な対応ソースコードはこのリポジトリです。 https://github.com/koment-dev/koment。これにより、ネットワーク経由で koment サーバーを 利用するすべての人に対する AGPL §13 の義務を満たしています。

AGPL を方針上採用できない組織や、保証または補償を希望する組織向けに、 商用ライセンスをリクエストに応じて提供しています。[email protected] までお問い合わせください。

v0.6.0 以前のリリースは MIT ライセンスで配布されており、今後も永久に MIT ライセンスが適用されます。 最後に MIT タグが付いたソースは、v0.6.0 から、 今後も無期限にこれらの条件でフォークできます。この決定は ADR 0117 に記録されています。

koment を使うと、自分のコードに AGPL が適用されますか？ いいえ。koment は ツール です。koment が書き込むアノテーションはデータであり、ツールの二次的著作物ではありません。これは、GCC でプログラムをコンパイルする場合と同じ法的区分です。ツールのライセンスが適用されるのはツールであり、そのツールで作成したものではありません。外部入力を処理する、OSI 承認の AGPL のあらゆる導入において、これが意図されています。組織の顧問弁護士が異なる見解を示す場合は、商用ライセンスで解決できます。