mcpField
C
commit-archaeologist

commit-archaeologist

github.com/shubhamsaboo開発143.3k531 回インストール1 週間前に更新
リポジトリ

commit-archaeologist について

commit-archaeologistは、ファイルやコード領域の由来を調べる開発者向けのローカルスキルです。Git履歴、共変更ファイル、コミットメッセージの手掛かりを組み合わせ、リポジトリを変更せずに調査します。

主な機能

  1. 01ファイルや行範囲の履歴追跡
  2. 02導入コミットと後続変更の特定
  3. 03繰り返し共変更されたファイルの検出
  4. 04コミットメッセージから意図の手掛かりを抽出
  5. 05オフラインでの読み取り専用実行

活用シーン

  1. 01コード領域が存在する理由の把握
  2. 02リファクタリング前の歴史的制約の確認
  3. 03回避策や意外な設計判断の調査

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/shubhamsaboo/awesome-llm-apps --skill commit-archaeologist

インストール後、Claude Code で/commit-archaeologistを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

README.md
references/
reading-git-history.md
scripts/
archaeologist.py

詳細

Commit Archaeologist

git blame は、ある行を最後に変更した人物を示します。このスキルは、その行が存在する理由を再構成します。ローカルの git 履歴をたどってファイルまたは現在の行範囲の由来と後続の編集を特定し、その行と繰り返し同時に変更されたファイルを見つけ、コミットメッセージから意図の手がかりを抽出します。

すべてローカルで実行されます。ネットワークへの呼び出し、API キー、リポジトリへの書き込みはありません。

使用する場合

  • ユーザーが、ブロック、関数、またはファイルが存在する理由を尋ねている
  • ユーザーが、コードを導入した人物とその後の変更内容を知りたい
  • 書き換えやリファクタリングにあたり、過去の制約や変更のリスクを把握する必要がある
  • 回避策、一時的なブランチ、または意外な設計上の選択について背景を知る必要がある

使用しない場合

  • ユーザーが生の blame 出力またはコミット一覧だけを求めている
  • タスクが git 履歴の統合、削除、または書き換えである
  • リポジトリがリモートにあり、ローカルにクローンされていない
  • 質問が、単一のファイルや領域ではなくプロジェクト全体のアーキテクチャに関するものである

対象を確認する

リポジトリのパスと追跡対象のファイルパスを取得します。ユーザーが現在のブロックまたは関数を指定した場合は、行範囲も使用します。いずれかのパスが不足している場合は、不足している値だけを尋ねます。隣接するリポジトリをスキャンしないでください。

パスはリポジトリからの相対パスとし、スラッシュを使用します。行範囲は、40-72 のように現在の行番号を含む範囲で指定します。

調査を実行する

このスキルのディレクトリから実行します。

python3 scripts/archaeologist.py /path/to/repo src/cache.py --lines 40-72 --json

ファイルの全履歴を調べるには、--lines を省略します。

python3 scripts/archaeologist.py /path/to/repo src/cache.py --json

このスクリプトは読み取り専用です。範囲を指定した場合は git の line-log を使い、指定しない場合は名前変更を追跡しながらファイル履歴を調べます。また、blame で現在の著者情報も読み取ります。パスまたは範囲が拒否された場合は、そのエラーを伝え、対象を修正するよう求めてください。

JSON を解釈する前に、references/reading-git-history.md を読んでください。ここにある確信度のルールに従うことで、blame の所有者情報、相関関係、コミットメッセージの手がかりを、根拠のない確信に変えてしまうのを防げます。

JSON を読む

  • region：正規化されたリポジトリ、現在および過去のパス、モード、範囲、同時変更のしきい値
  • introduced_by：選択した履歴の最古のコミット
  • timeline：最古から最新の順に並んだコミット。カテゴリ、変更ファイル、検出された名前変更を含みます
  • co_changed：選択したコミットのうち、しきい値以上で対象と同時に存在したファイル
  • authors：現在の blame 対象行と過去のコミット数。これらは分けて記録されています
  • intent_signals：コミットメッセージから見つかった、イシューへの参照、リバート、回避策、一時的な目印、未完了作業の目印

シグナルの一覧が空でも、メッセージに理由が記されていないという意味にすぎません。変更に理由がなかったという意味ではありません。

レポートを書く

JSON をもとに、「このコードが存在する理由」を簡潔にまとめたレポートを作成します。

  1. 要点。 最も可能性の高い説明を1～2文で示し、確信度を「高」「中」「低」で付けます。
  2. 由来。 導入コミットのハッシュ、日付、著者、件名、および当初の目的を明確にする周辺ファイルを示します。
  3. タイムライン。 最古から最新の順に記載します。内容の理解に影響しない機械的な編集はまとめてもかまいませんが、リバート、修正、回避策は残します。
  4. 関連ファイル。 繰り返し同時に変更されたファイルを、結合度の手がかりとして説明します。changed_files に一度だけ現れるファイルを依存関係として扱わないでください。
  5. 意図の根拠。 短いコミット件名やシグナル語を引用します。事実を超える結論には、推測であることを明記します。
  6. 変更リスク。 編集前に確認すべき制約、関連ファイル、未解決の一時的な選択を挙げます。

本文中ではハッシュを短くしてください。ただし、識別に十分な文字数は残します。ユーザーから求められない限り、JSON 全体を出力しないでください。

根拠に関するルール

  • 現在の blame の所有者は、元の作者であることの証明にはなりません。
  • 選択したコミットのうち最も古いものは、その領域が導入されたコミットであり、必ずしもファイルの最初のコミットとは限りません。
  • 繰り返し同時に変更されていることは、結びつきの強さを示唆しますが、依存関係を証明するものではありません。
  • コミットの分類は、コミットメッセージに基づく推測であり、検証済みの課題の種類ではありません。
  • 「一時的」や「回避策」は意図を示す強い手がかりですが、その制約が現在も適用されるかどうかを確認できるのは、メッセージの作者または関連する議論だけです。
  • 履歴が乏しい場合やメッセージが曖昧な場合は、設計上の理由を作り上げず、「履歴からは〜がわかります」や「おそらく」と述べてください。

フォローアップ

最後に、次のような関連性のあるフォローアップを1つ提案してください。

  • 「これが意図的なものか、偶発的なものかを評価しましょうか？」
  • 「この領域を変更した場合に、何が壊れる可能性があるかを整理しましょうか？」

意図的な選択かどうかを尋ねられた場合は、繰り返された編集、課題への参照、リバート、明示された制約を考慮してください。変更リスクについて尋ねられた場合は、編集を提案する前に、繰り返し同時に変更されているファイルと、直近で動作を変更したコミットを調査してください。ユーザーから依頼されるまでは、コードを変更しないでください。

ファイル

  • scripts/archaeologist.py：オフラインの Git 履歴ウォーカーおよび JSON レポートビルダー
  • references/reading-git-history.md：解釈と確信度に関するガイド

コメント

Markdown 対応