mcpField
R
repo-intent-documenter

repo-intent-documenter

github.com/jpcaparasエージェントワークフロー5669 回インストール1 日前に更新
リポジトリ

repo-intent-documenter について

リポジトリの文書、コード、テスト、設定をもとに、目的、前提、未解決の問いを明確にするREPO_INTENT.mdの作成・更新をエージェント向けに支援するスキルです。直接的な証拠と推論を分け、重要な主張に根拠と確度を示します。

主な機能

  1. 01リポジトリの文書やコードの手掛かりを調査
  2. 02テンプレートに沿って意図文書を作成・更新
  3. 03主張に確度ラベルを付与
  4. 04重要な主張に証拠を紐付け
  5. 05未解決の問いを確認事項として記録

活用シーン

  1. 01リポジトリの意図文書を作成
  2. 02新しい証拠に基づいて既存文書を更新
  3. 03ファイルを作成せずチャットで意図を説明

インストール

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

$npx skills add https://github.com/jpcaparas/skills --skill repo-intent-documenter

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

同梱ファイル

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

AGENTS.md
metadata.json
README.md
skill-card.prompt.md
agents/
.gitkeep
assets/
.gitkeep
evals/
evals.json
references/
document-contract.md
gotchas.md
methodology.md
scripts/
repo_intent_inventory.py
test_repo_intent_inventory.py
test_skill.py
validate.py
templates/
repo-intent.md

詳細

リポジトリ意図ドキュメント作成者

プロジェクトの目的、前提、未解決の疑問が将来のエージェントに明確に伝わる、根拠に基づいたリポジトリ意図ドキュメントを作成します。

判断ツリー

ユーザーは何を求めていますか？

  • リポジトリ意図ドキュメントを作成または更新する scripts/repo_intent_inventory.py を実行し、コードベースを調査してから、REPO_INTENT.md を作成または更新します。

  • ファイルを書かずに意図をインラインで説明する 同じ根拠モデルを使い、チャットで回答します。有用な場合に限り、ドキュメントの保存先も提示します。

  • 既存の意図ドキュメントを引き継いで作業する まず既存のドキュメントを読み、確認済みの記述を維持します。現在の根拠と矛盾する主張だけを修正します。

  • 下書き後にドキュメントを開いてほしい 先にドキュメントを書き、その後、利用可能なローカルの方法で開きます。デスクトップで開く手段がない場合は、絶対パスを伝えます。

  • リポジトリが存在しない、またはアクセスできない リポジトリのパスまたはファイルを求めます。プロジェクト名だけから意図を推測してはいけません。

クイックリファレンス

必要なこと実施内容
リポジトリを素早く把握するpython3 scripts/repo_intent_inventory.py <repo> --json
根拠のルールreferences/methodology.md を読む
出力形式templates/repo-intent.md をひな形として使い、references/document-contract.md を読む
曖昧さへの対処最初の調査の前ではなく、下書きの後に的を絞った質問をする
失敗しやすい点references/gotchas.md を読む

デフォルトのワークフロー

  1. リポジトリのルートを特定します。現在の作業ディレクトリに .git、マニフェスト、または既存のプロジェクトドキュメントがある場合は、そこを優先します。
  2. python3 scripts/repo_intent_inventory.py <repo> --json を実行し、ドキュメント、マニフェスト、テスト、CI、エントリーポイント、エージェント向け指示の初回調査結果を収集します。
  3. 最も情報量の多いファイルを自分で読みます。ルートの README、AGENTS または CLAUDE ファイル、パッケージマニフェスト、CI ワークフロー、ソースコードのトップレベルのエントリーポイント、テスト、サンプル、既存のドキュメントが対象です。
  4. templates/repo-intent.md を使って REPO_INTENT.md の下書きを作成します。
  5. 主張には Certain、Strong inference、Tentative、Open question のいずれかを付けます。重要な主張にはすべて根拠となる箇所を示します。
  6. 暫定的な主張を確認済みにするために必要な質問だけをユーザーに尋ねます。
  7. ユーザーの回答後、ドキュメントを更新し、レビュー履歴に確認内容を記録します。
  8. 希望があれば、書き込み後にドキュメントを開いてレビューできるようにします。

根拠の基準

直接的な根拠と解釈を分けます。

  • Certain は、ソースファイル、README、マニフェスト、テスト、または設定ファイルに明記されています。
  • Strong inference は、複数の独立した手がかりが同じ意図を示しています。
  • Tentative は、もっともらしいものの、根拠が弱いか、単一の情報源に基づいています。
  • Open question は、ユーザーが回答するまで、エージェントが事実として提示してはいけない内容です。

可能な限り、README.md、package.json、src/server.ts、tests/auth.test.ts のようにファイルを根拠として示します。手軽に取得できる場合は、行番号も含めます。

出力先のポリシー

デフォルトでは、将来のエージェントがルートレベルの意図ファイルを見つけやすいため、リポジトリのルートに REPO_INTENT.md を作成します。リポジトリ内の永続的なプロジェクトドキュメントがすべて docs/ に置かれており、ルートレベルのドキュメントがローカルの慣例に反することが明らかな場合に限り、docs/repo-intent.md を使います。

ユーザーから依頼されない限り、AGENTS.md、CLAUDE.md、その他の永続的なエージェント向け指示ファイルを自動編集してはいけません。代わりに、エージェント向け指示からリンクすると役立つ場合は、意図ドキュメントに短い「統合の提案」メモを追加します。

質問の進め方

最初の下書きができてから質問します。ユーザーが具体的な成果物を確認して修正できるようにするためです。

質問は次のようにします。

  • 根拠と結び付ける：曖昧さの原因となったファイルや手がかりを示します
  • 回答しやすくする：短い選択肢、または事実確認を優先します
  • 優先順位を付ける：将来のエージェントの動作を実質的に改善するための最小限の質問に絞ります
  • 作業を止めない：ユーザーが回答する準備ができていない場合は、未解決の質問をドキュメントに残します

注意点

  1. ディレクトリ名からプロダクト戦略を導き出さないでください。src/app から分かるのは構成であり、顧客の意図ではありません。
  2. 不確実性を曖昧にしないでください。根拠のない自信に満ちた文より、未解決の疑問を明示するほうが適切です。
  3. リポジトリを読む前に、広範な探索的質問をしないでください。まずエージェントに一次調査をさせることが目的です。
  4. 現在のコードが不完全だからといって、確認済みの人間の意図を上書きしないでください。
  5. 実際の目的を、長いアーキテクチャの一覧の下に埋もれさせないでください。アーキテクチャは意図を支えるものであり、意図そのものではありません。

読み方ガイド

必要な情報参照先
詳細な調査方法、根拠の評価順、確信度ラベルreferences/methodology.md
必須のドキュメントセクション、保存先のルール、レビューの反復手順references/document-contract.md
落とし穴と対処パターンreferences/gotchas.md
Markdown の初期テンプレートtemplates/repo-intent.md

コメント

Markdown 対応