repo-skillopt

RepoSkillOpt — 標準スキル

目的

このスキルは、エビデンスに基づく分析と人間のフィードバックによる改善を通じて、コーディングエージェントがレガシーリポジトリを理解できるよう支援します。構造化されたリポジトリ仕様を作成し、人間による修正を第一級の入力として受け付けます。また、繰り返し寄せられるフィードバックを要約し、スキル自体に対するレビュー可能な編集へ反映する、範囲を限定したループにも対応します。このスキルはベンダー中立であり、特定のコーディングエージェントのランタイムには依存しません。

トリガー条件

ユーザーがリポジトリの理解、マッピング、文書化、オンボーディング、リファクタリング、変更、評価を依頼した場合、またはそれらの動詞に相当する表現（例：「このコードベースを説明して」、「アーキテクチャを要約して」、「もし…したら何が変わりますか」、「…しても安全ですか」）を使った場合は、このスキルを有効にします。

上記の動詞に該当しない依頼（例：一般的なチャット、無関係な執筆タスク、リポジトリ全体の理解を必要としない単一ファイルの編集）では、このスキルを有効にしないでください。その場合は通常のエージェントの動作を続けます。

運用原則

• README ファイルだけに依存しないでください。 README の内容はエビデンスの一つであり、全てではありません。古くなっていたり、理想を述べているだけだったり、誤っていたりする可能性があります。必ずコード、設定、テスト、コマンド出力と照合してください。
• 主要な主張は全て、リポジトリのエビデンスに基づかせてください。 一般的な説明よりも、具体的なパス、シンボル、設定、テスト、コマンド出力を優先してください。主要な主張とは、リポジトリ仕様のセクションにある重要な項目（エントリーポイントの特定、技術の選択、依存関係、制御フローまたはデータフローの手順、統合対象、リスクに関する記述）を満たす主張、またはメンテナンス担当者が行動に移すような単独の主張です。単なる記載（ファイルの文字どおりの内容、未加工の設定ダンプ、構文の言い換え）は主要な主張ではありません。
• 検証済みの事実と仮説を分けてください。 主要な主張にはそれぞれ、出力規律以下で定義する4つのラベルのうち、必ず1つだけを付けます。**[fact]**、**[inference]**、**[unknown]**、**[human]**。
• 不確実性を明示してください。 調査しても情報を特定できない場合は、推測せずに「不明点と未解決の質問」にその不足を記録してください。自信のある誤答よりも、正直に「不明」とする方が有用です。
• 学習データのパターン照合よりも、具体的なエビデンスを優先してください。 同じエコシステムに属する2つのリポジトリでも、パターン照合では見落とす違いがある可能性があります。このリポジトリを調査してください。
• 表面的な調査からアーキテクチャを誇張して述べないでください。 マニフェストと少数のエントリーポイントしか読んでいない場合は、レイヤーやデータフローを追跡済みであるかのように説明しないでください。
• 適切な範囲に限定されている場合にのみ、人間のフィードバックを再利用可能な知識として保持してください。 リポジトリ固有の事実はそのリポジトリ内に限定します。汎用化の候補として明示されたフィードバックだけが、このスキル自体を対象とする収束パイプラインに入り、しかも承認済みのスキル編集提案を経た場合に限ります。

リポジトリ理解ワークフロー

以下のステージを順番に実行してください。ステージを省略したり、順番を入れ替えたりすると、後続セクションが依存する証拠の連鎖が弱まります。

(a) リポジトリの構成をトリアージする。 トップレベルのディレクトリを一覧表示します。src/、テスト、ドキュメント、デプロイ用ファイル、CI 設定、複数のサブプロジェクト（モノレポの兆候）の有無を記録します。

(b) 言語、フレームワーク、パッケージマネージャー、ランタイムを特定する。 マニフェスト（pyproject.toml、package.json、go.mod、pom.xml、Cargo.toml、Gemfile、composer.json など）を読みます。バージョンとランタイムの制約を記録します。

(c) マニフェスト、設定、テスト、デプロイ用ファイル、エントリーポイントを調べる。 少なくとも次を読みます：ビルド／ランタイム設定、環境変数のテンプレート、CI ワークフロー定義、テストランナーの設定、デプロイマニフェスト、エントリーポイントとして特定されたファイル（CLI スクリプト、HTTP ルート登録、ライブラリの __init__／index ファイル）。

(d) モジュール、レイヤー、依存関係、ドメイン概念、データフローをマッピングする。 ソースツリーをたどり、各モジュールの役割を割り当て、レイヤー間の依存関係の方向を特定し、このコードベースでドメインの専門家が使う名称を記録します。リポジトリ内で定義されているすべての関数とクラスを列挙し、漏れがないようにします（Repository Specification Format のシンボルの計上ルールを参照）。

(e) エントリーポイントからコアロジック、永続化または副作用まで、具体的な動作を追跡する。 ユーザーに関係する動作を少なくとも1つ選び、各段階（エントリーポイント → ミドルウェア → サービス → リポジトリ → 副作用／ストレージ）を列挙した番号付きのトレースを作成し、各段階でファイルとシンボルを引用します。

(f) Repository Specification を段階的にディスク上に作成する。 templates/repository-specification.md にある Repository Specification テンプレートを使い、Output Discipline のラベル付けと引用のルールに従って、必須の19セクションすべてに記入します。各セクションを完成させたら、その都度仕様書ファイルに書き込み、すでに書き込んだセクションを作業コンテキストに保持しないでください。セクションを永続化したら、その内容を作業セットから破棄し、現在作成中のセクションと、それに必要な証拠だけを保持します。後のセクションで前のセクションを参照する必要がある場合（たとえば Evidence index の重複排除）、文書全体をコンテキストに保持せず、ファイルから読み戻します。これにより、作業コンテキストは増え続ける仕様書全体ではなく、現在のセクションだけに抑えられるため、小さなコンテキストウィンドウでも大規模なリポジトリにワークフローを適用できます。正本となる仕様書は常にディスク上のファイルであり、コンテキスト内のコピーではありません。

(g) リスク、不明点、安全な次の手順を特定する。 Known risks には、一般的なものではなく、リポジトリ固有のリスクを証拠と結び付けて記載します。Unknowns and unresolved questions には、ステージ (a)～(f) で見つかったすべての不足事項を記載します。重要な不明点を解消するために人が実行できる、具体的な次の手順を提案します。

(h) シンボルの網羅性を保証する（決定論的 — 最終アクション）。 完了する前に、Symbols not yet analyzed の一覧を完全かつ機械的なものにします。まだ説明していない関数とクラスをすべてファイルごとにまとめ、件数の行も記載します。この一覧は手作業で転記せず、リポジトリ内のシンボルを列挙し、分析で言及されていないものを一覧化する網羅性チェック用ヘルパーを実行して、決定論的に生成します。あなたの役割は前述の分析であり、このステップでは計上を保証して、何も見落とされないようにします。

Repository Specification Format

Repository Specification のテンプレートは templates/repository-specification.md にあります。エージェントは、テンプレートに一致し、次の順序ですべての19セクションを含むファイルを必ず作成する必要があります。

1. リポジトリの概要
2. 技術スタック
3. ビルドおよびランタイムのコマンド
4. 主なエントリーポイント
5. アーキテクチャレイヤー
6. コアモジュール
7. ドメインモデル
8. データモデル
9. 外部連携
10. 制御フローのトレース
11. データフローのトレース
12. 依存関係マップ
13. 構成マップ
14. テスト戦略
15. デプロイの前提条件
16. 変更影響マップ
17. 既知のリスク
18. 未解決の問題と不明点
19. 根拠インデックス

設計上空のセクションでは、「既知のものはありません」または「該当なし」と明記します。空のセクションを黙って省略してはいけません。根拠インデックスには、文書内に登場する引用を重複なくすべて記載します。

シンボルの集計（黙って省略しない）。 リポジトリ内で定義されているすべての関数とクラスを必ず記録します。分析上の主張や引用で参照するか、コアモジュール内の 「未分析のシンボル」 サブセクションに記載します（ファイルごとに分類し、大規模なリポジトリではファイルごとの件数でもかまいません）。件数を — 定義数 N、分析数 M、一覧に記載した数 N−M — のように示し、情報が隠されていないことを読者が確認できるようにします。生成されたディレクトリやベンダー提供のディレクトリは除外します。

リポジトリのオントロジー（まずこれを構築）。 ドメインモデルとデータモデルを記述する前に、リポジトリのオントロジーを構築します。オントロジーには、固定された種類のエンティティ（モジュール、クラス、関数、データエンティティ、ルート、ジョブ、抽象化）の一覧を含め、それぞれを file:line に紐付けます。また、関係（インポート、継承、外部キー、ルートの登録、スケジュール設定）も含めます。高速なスキャナー（利用可能であれば rg、そうでなければ grep／git ls-files）で対象を特定し、引用する一致行だけを読みます。ファイル全体を読み込んではいけません。ドメインモデルには、概要レベルのエンティティマップ表（種類・件数・引用付きの例）と関係 graph を掲載します。抽象化エンティティは、固定されたリポジトリ固有の名前リストではなく、構造に基づいて検出します。つまり、2つ以上のクラスに継承される基底クラスを抽象化として扱います。関係の参照先が既知のエンティティに解決できない場合は **[inference]**／**[unknown]** とし、確定したエッジとして描いてはいけません。

データモデル図。 リポジトリにデータベースまたは永続スキーマがある場合、データモデルセクションには、実際のテーブル／モデル、それらの主なカラム、外部キー関係を示す erDiagram を含むフェンス付きの ```mermaid ブロックを必ず含めます。各エンティティは、それを定義するスキーマファイル（マイグレーション、DDL、または ORM モデル）まで追跡できるようにします。この erDiagram は、オントロジーのデータエンティティ部分です。永続スキーマがない場合は「該当なし」と明記し、実在しないスキーマを作成してはいけません。

ビジネスワークフロー（すべてのビジネスパイプライン）。 ビジネスワークフローでは、すべてのビジネスエントリーポイント（HTTP ルート、スケジュールされたジョブ、CLI コマンド）を黙って省略せず列挙します。列挙表には種類ごとの件数と合計件数を記載し、各エントリーポイントを file:line に紐付けます。そのうえで、リポジトリのオントロジーに基づき、それぞれの実行経路を一連の処理（エントリーポイント → サービス呼び出し → 副作用／永続化）として追跡します。高速なスキャナー（rg／grep）でエントリーポイントを特定し、一致したハンドラーの該当範囲だけを読みます。各フローは、mermaid の flowchart（視覚表現。引用なし）に続けて、根拠を示した正式な番号付き手順で説明します。静的に解決できないホップ（動的ディスパッチ、間接参照）は、理由を添えて **[unknown]** とし、省略してはいけません。これは制御フローのトレースに対応するビジネスプロセスの網羅的な一覧です。トレースは例示であり、こちらは網羅的な列挙です。

表示形式。 仕様書は人が読むものです。ひと目で把握できる構成を優先してください。

• テンプレートの順序に従い、番号付きのセクション見出しを使用します — ## 1. Repository overview … ## 19. Evidence index。
• 本質的に表形式のセクションは、Evidence 列（path:line の引用）と Label 列（[fact]／[inference]／[unknown]）を含む Markdown テーブルとして記述します。対象は、Technology stack、Dependency map、Configuration map、Data model のフィールド一覧、Evidence index です。
• Control-flow traces と Data-flow traces は、処理の最初から最後までを示すフェンス付きの ```mermaid flowchart から始め、その後に、根拠を示す引用付きの番号付き手順を、ラベルを付けて列挙します。
• 図（flowchart、erDiagram）は視覚的な補助であり、引用は不要です。図に示すすべての手順やエンティティは、図による根拠付けに影響しないよう、根拠を示す引用付きのラベル付き行またはテーブル行にも記載する必要があります。

仕様ヘッダーと品質チェックリスト。 タイトルの下に、構造化仕様の慣例に倣い、短いヘッダーブロックを記載します — Target repository（名前 · コミット）、Status、Generated by（スキルのバージョン · アダプター）、および Grounding の行です。Repository Specification と併せて、.reposkillopt/specs/repository-specification-checklist.md にある templates/repository-specification-checklist.md から Specification Quality Checklist を作成します。根拠付け、完全性、図、準備状況に関する CHK### 形式のチェックリストとします。根拠付け、完全性、図に関する項目は決定的なメトリクスに対応しており、すべての項目が合格なら、引用による根拠付け、セクションの完全性、シンボルの網羅率、図の根拠付けがそれぞれ 100％になっている必要があります。

このスキルが生成する作業用成果物は、対象リポジトリ（このスキルを提供するプロジェクトではなく、分析対象のリポジトリ）のルートにある .reposkillopt/ ディレクトリ内に、次の固定サブディレクトリを作成して保存します。

• .reposkillopt/specs/ — Repository Specifications
• .reposkillopt/feedback/ — Feedback Items
• .reposkillopt/rollouts/ — Rollout Logs
• .reposkillopt/proposals/ — Skill Edit Proposals

Human Feedback Loop

Human Feedback テンプレートは templates/human-feedback.md にあります。Rollout Log テンプレートは templates/rollout-log.md にあります。

Repository Specification に対して人間からフィードバックがあった場合：

1. 適用する前にフィードバックを記録します。 テンプレートを使用して、.reposkillopt/feedback/FB-YYYY-MM-DD-NNN-<slug>.md に Feedback Item を作成します。11 種類の type 値（correction、confirmation、missing-context、terminology、quality-rating、avoid-path、deeper-analysis、criticism-of-claim、format、detail-level、cross-agent-difference）から 1 つを割り当てます。scope を割り当てます。コードベース固有の事実には repository-scoped、このスキルへの将来的な編集が必要となる可能性のあるパターンには candidate-for-generic を指定します。

2. 現在の Repository Specification を改訂します。 フィードバックを反映します。変更された **[fact]** の主張については、引用を更新します。置き換えられた主張は、その場で superseded と明記します。履歴を黙って書き換えてはいけません。仕様の revision を増やし、revised を更新して、適用した Feedback Item の ID を記載した行を仕様の Change log 付録に追加します。

3. セッションの Rollout Log を更新します。 Human feedback received this session に Feedback Item の ID を列挙し、それぞれに (applied)、(deferred)、または (withdrawn) を付記します。改訂した仕様のセクションを Revisions applied に記載します。

4. リポジトリ固有の事実を、この標準スキルに黙って取り込んではいけません。 scope: repository-scoped のフィードバックは、対象リポジトリの成果物内にのみ保持します。標準コンテンツへの反映には、後述する Skill Convergence Loop を通じて作成された Skill Edit Proposal が承認される必要があります。

人間からのフィードバックは、現在の Repository Specification の即時改善と、スキルの収束に向けた長期的な情報の両方に同時に利用します。

スキルの収束ループ

スキル編集提案のテンプレートは templates/skill-edit-proposal.md にあります。

繰り返し寄せられるフィードバック（通常、1 つ以上のセッションにわたる関連する Feedback Item が 3 件以上）から、このスキル自体の弱点が示唆された場合：

1. パターンを要約します。 根拠となる Feedback Item 全体に繰り返し見られる傾向を特定します。そのパターンが一般化可能であること（他のリポジトリやタスクにも役立つこと）を確認してください。現在のコードベースに固有の一度限りの詳細ではないことが条件です。

2. 範囲を限定した編集を 1 件以上提案します。 各提案は、レビュー担当者が 5 分以内に判断できる小ささ（review_time_estimate_minutes ≤ 5）で、個別に採否を決められる単位とします。提案の範囲が収まらない場合は、分割してください。

3. 各提案を分類します。 6 種類の edit_kind のうち 1 つを使用します。

   • ADD — 新しい内容を追加
   • REPLACE — 既存の内容を置き換え
   • DELETE — 内容を削除
   • REORDER — 既存の内容の順序を変更
   • SPECIALIZE — 既存のルールを特定のケースに絞る
   • GENERALIZE — 既存のルールを拡張し、より多くのケースに適用する

4. スコープを明記します。 scope: generic のみが正式採用の対象です。scope: repository-scoped の提案は、一般化するように書き直すか、却下するか、リポジトリごとのスコープ判断用成果物に回す必要があります。

5. 却下した提案を保持します。 status: rejected を設定し、decision_rationale に判断理由を記入します。削除しないでください。却下した提案も監査証跡の一部です。

6. 採用前にゲートを通過させます。 scope: generic の提案を status: accepted にできるのは、検証ゲートに合格した後に限ります。提案を候補スキルバージョンに適用し、提案の根拠となったリポジトリとは重複しない保留済みの参照セットに対して仕様を再生成します。その際、各次元のルーブリックスコアが低下せず、決定論的チェックにも引き続き合格し、提案が期待する効果が少なくとも 1 つの次元で実現していること（または明示的に免除されていること）が必要です。実行結果は Validation Gate Report に記録し、提案から参照します。このゲートは採用を許可するものであり、以下の採用フローに代わるものではありません。

7. 採用した提案を正式なスキルに適用します。 status: accepted（合格したゲートへの参照付き）になった場合、提案の差分をこの SKILL.md に適用します。正式バージョンは Keep-A-Changelog と semver に従って更新します。差分がアダプター同等性チェックリストを破る場合はメジャー、新しい内容の追加であればマイナー、明確化であればパッチとします。skills/repo-skillopt/CHANGELOG.md に項目を追加します。

8. 一般化できる編集を優先します。 提案された変更によって汎用スキルが単一のリポジトリ向けに特化する場合は、その点を指摘するか、一般化するように書き直してください。この成果物では、リポジトリ固有の改善よりも一般化できる改善を優先します。

出力の規律

Repository Specification（またはロールアウトで生成されたテキスト）における重要な主張には、主張の前に次の 4 種類のラベルのうち 1 つを付けます。

• **[fact]** — 調査によって確認済みです。次のいずれかの形式の引用を少なくとも 1 つ直後に必ず付けます。
  • path/to/file.ext:line
  • path/to/file.ext:start-end
  • path/to/file.ext:Symbol
  • path/to/file.ext:Symbol:line
  • cmd: <command> に続けて output: <verbatim output>
• **[inference]** — 不完全な情報から導き出されたものです。根拠（例：「根拠：src/auth.py:7 に flask_login のインポートがある」）を記載します。
• **[unknown]** — 明示的に未確定としたものです。未解決の不明点と質問にも記載するか、そこで参照します。
• **[human]** — フィードバックループを通じて人間から提供されたものです。元の Feedback Item id（形式：FB-YYYY-MM-DD-NNN）を引用します。

仮説を事実として提示するのは不備です。引用のない事実も不備です。検証不可能な主張に **[inference]** または **[unknown]** のラベルが付いていない場合も不備です。出力は実際のエンジニアにとって有用であることが目的です。つまり、見栄えよりも信頼性が重要です。

単純な再掲（ファイル内容の逐語的な記載、設定の生データのダンプ、構文上の言い換え）は重要な主張ではないため、ラベルは不要です。