CommitLore

CommitLore

同じ誤ったアイデアを何度もレビューするのはやめましょう。

Git が管理する、コーディングエージェントのための意思決定の根拠。
制約、却下した代替案、警告を Git に保存し、現在も有効なものだけを届けます。これにより、リポジトリですでに覆された判断をエージェントに渡さずに済みます。

ホスト型のメモリーはありません。記録はリポジトリが管理します。

English · 한국어 · 日本語 · 简体中文

一度インストール。 あとは、使いたい各リポジトリで初期化します。

curl -fsSL https://raw.githubusercontent.com/MongLong0214/commitlore/v1.7.5/install.sh | sh -s v1.7.5

curl -fsSLO https://raw.githubusercontent.com/MongLong0214/commitlore/v1.7.5/install.sh
sh install.sh v1.7.5

# Or skip the script: the checkout it makes is one you can make yourself.
git clone --depth 1 --branch v1.7.5 https://github.com/MongLong0214/commitlore
node commitlore/dist/commitlore.mjs --version

コードは残ります。判断の根拠は残りません。

エージェントがあるアプローチを提案します。チームは、見落としやすい制約を理由にそれを却下します。最終的なコードには結論が反映されますが、通常、代替案を却下した理由までは残りません。後から別のエージェントがコードだけを見て、同じアイデアを再び提案します。

CommitLore は、その判断の根拠をコードと一緒に保持します。

CommitLore の機能

ほとんどのコミットに記録は必要ありません。CommitLore は、コードでは保持できない判断の根拠のためのものであり、変更のすべてを説明するためのものではありません。

60 秒で判断を理解するエージェントを導入

1. CLI をインストール

macOS と Linux：

curl -fsSL https://raw.githubusercontent.com/MongLong0214/commitlore/v1.7.5/install.sh | sh -s v1.7.5

Windows：

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/MongLong0214/commitlore/v1.7.5/install.ps1))) v1.7.5

Node.js 22.23.2+ と Git が必要です。スクリプトは何かを書き込む前に、両方があることを確認します。

2. エージェントを接続

Claude Code：

/plugin marketplace add MongLong0214/commitlore
/plugin install commitlore@commitlore

Codex：

commitlore plugin install-codex

プラグインは commitlore を PATH に追加しないため、以下のコマンドを使うには CLI もインストールする必要があります。インストーラーは、安全に設定できる場合、対応する MCP ホストも検出して接続します。対応状況の一覧は以下をご覧ください。

3. リポジトリを初期化する

cd your-repository
commitlore init
commitlore context .

プラグインをインストールまたは更新した後は、新しいエージェントセッションを開始してください。実行中のセッションでは、読み込み済みのランタイムがそのまま使用されます。

その後は、通常どおり作業してコミットできます。対応するスキル統合では、通常のコミット依頼時に CommitLore が考慮され、記録する価値があるものがなければ何も行いません。コミットのたびに CommitLore を指定する必要はありません。

受け入れた記録を、記録ごとの確認なしでステージングしたい場合は、リポジトリで一度だけ commitlore auto on を有効にできます。このポリシーはリポジトリが管理し、チーム全体に適用されるため、このページによって暗黙的に有効になることはありません。

エージェントが受け取る内容

src/pricing.ts を編集する前に：

commitlore: active records for src/pricing.ts

Limit
  [claim]      r-price01  a1b2c3d4  calculatePrice owns final checkout pricing only

Ruled-out
  [claim]      r-price01  a1b2c3d4  Reuse it for admin quotes | eligibility and rounding semantics differ

[claim] は「情報として考慮する」という意味です。リポジトリでは、より強い署名付き権限モードを有効にできます。情報を渡すことでエージェントにコンテキストを提供しますが、編集を妨げることはありません。

セキュリティモデル →

なぜ Git なのか？

リポジトリが、そのコードに関する判断を管理するべきです。

CommitLore は通常の Git トレーラーとノートに記録を保存するため、記録はブランチ、マージ、クローン、レビューが可能で、説明対象のコードとともにプロバイダーの変更後も保持されます。

SQLite は再構築可能なインデックスにすぎません。削除しても、記録は Git に残ります。

過去の判断を見つけるだけでは不十分です

一般的なメモリーシステムや検索システムでは、次のように尋ねます。

関連しているように見える過去のテキストはどれですか？

CommitLore では、次のように尋ねます。

記録された判断のうち、今このパスに適用されるものはどれですか？

置き換えられた判断は非常に関連性が高くても、現在の指針としては誤っている可能性があります。関連性と権限は別の問題です。

仕組み

1. 記録 — エージェントは、差分からは分からない判断のコンテキストだけを下書きします。
2. 検証 — CommitLore は、下書きをセッションおよびステージ済み差分と照合します。
3. 保持 — 受け入れられた記録は、識別情報とライフサイクル情報とともに Git に保存されます。
4. 提供 — 以降の編集前に、そのパスに有効な記録だけが返されます。

ほとんどのコミットには記録がありません。コミットフックは、記録がある場合にそれを検証します。記録を作り出すことはありません。

既存のフックは上書きされません。commitlore init は core.hooksPath を尊重し、すでにインストールされているフックを <hook>.commitlore-chained に移動して、先に呼び出します。commitlore hooks uninstall を実行すると元に戻ります。

自動で行われること

「利用可能」とは、prepare → verify → stage のワークフローが存在することを意味します。対象となるすべてのコミットが自動的に評価されるという意味ではありません。

対応するスキルホストのユーザーは、コミットのたびに「CommitLore に記録して」と伝える必要はありません。残る制約はホスト側での開始方法であり、記録ごとにユーザーがコマンドを指定する必要はありません。

スカッシュマージするリポジトリ

スカッシュマージでは、ブランチのコミットが新しい1つのコミットに置き換えられます。そのコミットには、ブランチのトレーラーは引き継がれません。リポジトリでスカッシュボタンを使ってマージする場合、ブランチ上で作成された記録は、スカッシュしたコミットに何かが引き継がない限り、マージ時に失われます。

この問題には2つの対処方法があり、そのうち1つは一度だけセットアップが必要です。

GitHub は独自のサーバー上でこのマージを実行するため、ローカルの git フックは一切実行されず、マージを認識できません。その時点で必要な情報、つまりプルリクエスト、そのコミット群、そしてそれらがスカッシュされた先のコミットをすべて持っているのは、この Action だけです。

.github/workflows/commitlore-preserve.yml を追加してください。

name: CommitLore squash inheritance

# pull_request_target, not pull_request: a pull request from a fork gets a
# read-only token on pull_request, so the job would build the record and then
# fail to publish it.
on:
  pull_request_target:
    types: [closed]

permissions:
  contents: write   # the one push to refs/notes/commitlore

concurrency:
  group: commitlore-notes
  cancel-in-progress: false

jobs:
  preserve:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          # the merge commit is on the base branch, and a closed pull request
          # has no merge ref left to check out
          ref: ${{ github.event.pull_request.base.ref }}
          fetch-depth: 0

      # the mirror this action writes; publishing from a checkout that never
      # read it would fork the notes history
      - run: git fetch --no-tags origin '+refs/notes/commitlore:refs/notes/commitlore'

      # a squash merge usually deletes the branch, and then the pull request's
      # own ref is the only one still reaching the commits that carry records
      - run: git fetch --no-tags --force origin
          '+refs/pull/${{ github.event.pull_request.number }}/head:refs/commitlore/pr-head'

      # The action runs CommitLore from a checkout of this repository: the
      # package is private, so there is no published npm name to fall back to.
      # `dist/` is committed (ADR-0011), so nothing needs building.
      - uses: actions/checkout@v4
        with:
          repository: MongLong0214/commitlore
          ref: v1.7.5
          path: .commitlore-cli
          persist-credentials: false

      - uses: MongLong0214/commitlore/action/[email protected]
        with:
          cli-path: .commitlore-cli/dist/cli.js

次にこの設定を編集する人のために、2つのルールがあります。pull_request_target は書き込み可能なトークンで実行されるためです。ここではプルリクエストの head をチェックアウトしないこと、また refs/commitlore/pr-head から到達できるものを絶対に実行しないことです。フォークのコミットは、実行するコードではなく、トレーラーを読み取るためのデータとして扱ってください。

commitlore doctor は、squash inheritance の項目で、この設定が有効になっているかを報告します。記録が失われる前にそのことを示します。すでに失われた記録を報告する行は squash conservation です。

マージコミットまたはリベースでマージする場合、記録は自動的に残るため、この設定は不要です。

測定結果ではなく、ある現場の報告

無関係なリポジトリで、v1.2.1 を初めてインストールした人による、ある1回の実行結果です。ここに書かれていることは何も測定されておらず、証拠ログにも含まれていません。このページに載せているのは、上の段落が、ここにあるどの表にも含まれていないループについて述べているからです。

その人はエージェントに丸め誤差のバグを修正するよう頼み、ある十進数ライブラリはすでに検討され、採用を見送ったことをついでに伝え、最後に「コミットして」と指示しました。CommitLore の名前は一度も出ていません。コミットに含まれていた内容の一部です。

Ruled-out: adopting a decimal library such as Decimal.js | the backend is a
  number contract, so it is meaningless
Warn: do not revert the test file to console.assert: it exits 0 even on
  failure, so CI passes silently
Provenance: drafted

Warn はエージェントに指示されたものではありません。作業中に落とし穴に気づき、次に作業する人のために残したものです。Provenance: drafted は、記録を人間が読んでいないことを示しており、そのため claim と評価されます。これは命令ではなく、判断材料として検討すべき報告として提示されます。

共有履歴のない後のセッションで、今度は十進数ライブラリを採用するよう求められました。エージェントは採用せず、その理由としてこの記録を挙げました。また、評価も確認しています。claim は指示ではないため、同意する前に、記載された理由をコードと照らし合わせて確認しました。

メモリーストレージとの違い

CommitLore は意図的に対象を絞っています。一般的なユーザーメモリーシステムでも、会話アーカイブでも、ベクトルデータベースの代替でもありません。

エビデンス

インデックスの構築時間は、コミット数ではなくレコード数に応じて増加します。負荷の高い処理はレコードごとに 1 回実行されるため、レコードの記録が少ない長い履歴のほうが、レコードが密集した短い履歴よりも速く構築できます。

大きな履歴がモデルに届かないようにするのは、パスのスコープです。#167 のコーパスでは、10,002 件のレコードのうち、モデルに届いたのは 2 件だけでした。

これは、レコード数を 2 件に固定した場合の情報露出と再現率を測定したものであり、トークンコスト、請求額、精度、エージェントの振る舞いを測定したものではありません。1 つのコーパス、1 つのクエリ、固定された 1 つの埋め込みモデルに基づいています。

エージェントの研究は、あらゆるモデルに共通する効果を示すものではありません。情報が提供されたことは、モデルがレコードを読んだ、またはそれに従った証明にはなりません。

手法、完全な表、除外項目、否定的な結果 →

制限、信頼性、プライバシー

• キャプチャは支援機能であり、決定論的ではありません。 対応するスキルは通常のコミット要求を考慮しますが、対象となるすべてのコミットを評価できると認定されたホストはありません。
• デフォルトのディレクティブモードは認証ではありません。 コミットの作成者ヘッダーと照合しますが、コミットを書き込める人なら誰でもそのヘッダーを設定できるため、デフォルトモードでの [directive] はポリシーメタデータであり、本人確認の証明ではありません。 署名モードではさらに、Git 自身の検証済みステータスと、リポジトリローカルの commitlore.trustedSigner 許可リストとの一致が必要です。署名者の許可リストが存在しない、空である、または読み取れない場合は誰も許可されず、このモードはフェイルクローズします。
• ガードは実験的な助言機能であり、安全網ではありません。 417 件の判断コーパスにおける適合率は 44.8％（95％ Wilson 信頼区間 32.7％～57.5％）、再現率は 22.0％です。ガード結果が空でも、安全性が保証されたわけではありません。
• 配信では、一致するツール呼び出しごとにトークンを消費します。 編集前フックは Edit、Write、MultiEdit、NotebookEdit だけでなく Read の際にも起動するため、編集エージェントがコミットする頻度を大幅に上回ります。起動するたびに、デフォルトで 800 トークンのペイロード予算を上限として消費します。この上限は --budget で変更できます。レコードのないリポジトリでは何も消費されません。つまり、このコストはインストール時ではなく、利用が始まってから発生します。
• 回答が一部のみの場合があります。 カバレッジは開示されます。一部のみの結果に記録が含まれていなくても、その記録が存在しない証拠にはなりません。commitlore coverage はスキャンが到達した範囲を報告します。
• コミットトレーラーはクローンとともに移行しますが、ノートは移行しません。 Git はデフォルトでは refs/notes/* をフェッチしないため、refs/notes/commitlore 内のレコードは、commitlore init でそのミラーを設定するまで通常のクローンには含まれません。
• ホスト型バックエンドはありません。 ただし、サーバーまたはフックがコンテキストを返した後は、ホストが自身のポリシーに従ってそのコンテキストを処理します。CommitLore はそのデータフローを制御しません。

セキュリティ · 互換性 · エビデンス

履歴のあるリポジトリでお試しください。
_{パスの範囲、ライフサイクル、キャプチャ、インストールで問題が発生する箇所をお知らせください。}

失敗事例を報告する · 自己監査を読む

• インストール、アップグレード、アンインストール
• CLI リファレンス
• キャプチャのワークフロー
• 記録プロトコル
• セキュリティモデル
• 証拠と制限事項
• 本番環境向けの契約

コントリビューション

CONTRIBUTING.md では、このリポジトリが遵守する記録プロトコル、リリースゲート、および証拠を再現する方法について説明しています。

ライセンス

MIT — LICENSE を参照してください。