pavedpath-code

PavedPath Code

PavedPath Code（代码版）は、エージェントがソフトウェアエンジニアリングの問題に対する解決策を一から作り直すのを防ぎます。GitHub やオープンソースの情報を検索して、実績のある実装方法を見つけ、最も有力なパターンを、最小限で検証可能な変更によってローカルのコードベースに適用します。

GitHub はリンクを大量に並べるのではなく、主要な根拠情報源として活用してください。目的は、ローカルのコードの問題を明確にし、公開リポジトリ、イシュー、プルリクエスト、ディスカッション、サンプル、リリースノート、ソースコードから、すでに実践された方法を探し、その根拠の強さを評価してから、最も有力なパターンを小規模なローカル修正、実装手順、または検証計画に落とし込むことです。

これは PavedPath のコードに特化したエディションです。将来の汎用版 PavedPath に対象を広げないでください。バグ、ランタイムエラー、ビルド／テスト／デプロイの失敗、依存関係の問題、フレームワークや API の使用方法、統合の妨げとなる問題、実装パターン、エンジニアリングツールの選定、オープンソースの解決策の適用など、ソフトウェアエンジニアリングの作業を対象とします。

使用する場面

• ランタイム、ビルド、テスト、デプロイ、パッケージ、SDK、API、依存関係、フレームワーク、または統合に関するエラー。
• 不明確なエッジケース、使用パターンの欠如、バージョンによる挙動の違い、または不確かな API 契約によって、機能の実装が進められない場合。
• ローカルの問題と似た事例があり、メンテナーや他のオープンソースユーザーがイシュー、PR、サンプル、コード、リリースノート、ディスカッションで解決している可能性がある場合。
• GitHub やオープンソースプロジェクトで、具体的なエンジニアリング上の問題がすでに解決されているか、ユーザーが尋ねている場合。
• 成熟した実装例や再利用可能なプロジェクトによって、特定の機能に関する不確実性を減らせる場合。
• 適切な GitHub リポジトリを比較し、実績のある方法をローカルでどのように応用するか説明する必要がある場合。

コピーの修正、コードベースがすでに答えを示しているローカル限定のリファクタリング、コード以外の人生上の選択、セルフメディアのワークフロー、学習方法、消費者向けの購入判断、またはウェブ／GitHub の調査を明示的に禁止する依頼には、PavedPath Code を使用しないでください。ユーザーが明示的に対象範囲を指定し、アクセスを許可していない限り、プライベートリポジトリを調査しないでください。

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

1. まずローカルのコードの問題を整理します。 目的、症状、エラーの特徴、再現手順、バージョン、実行環境、依存関係やフレームワークの名称、最近の変更、制約、試した修正方法を記録します。調べれば分かる情報が不足している場合は、質問する前にローカルのファイルやログを確認します。
2. 証拠の種類を選びます。 エラーやリグレッションについては、まずイシュー、PR、リリース、コードを検索します。機能やツールが必要な場合は、まずリポジトリの候補を検索します。機能を実装する場合は、リポジトリの候補と、イシュー／PR／コードの両方の証拠を使います。
3. サブエージェントが役立つか評価します。 本格的な GitHub 調査の前に、条件付きのサブエージェント作業によって、調査範囲、証拠の質、レビューの網羅性が向上するか判断します。サブエージェントを使わない場合は、調査経路を報告する際に理由を簡潔に述べます。
4. 対象を絞った検索を行います。 正確なエラー文、パッケージ／API 名、バージョン番号、フレームワークと症状の組み合わせ、ファイル名、設定キー、スタックトレースの一部、失敗したコマンド名、機能とフレームワーク／実行環境／API 名の組み合わせを優先します。
5. 関連する場合は、適切な GitHub プロジェクトを探します。 適合度が高く、Star 数が多く、活発に開発され、アーカイブされておらず、ライセンスが明確で、実例があるリポジトリを優先します。Star 数の多い候補が広範すぎる場合や、問題にぴったり合うものがない場合は、Star 数の基準を下げます。
6. オープンソースの証拠を探します。 関連するオープンソースリポジトリのイシュー、PR、ディスカッション、コード、実例、リリースノート、公式プロジェクトドキュメントを活用します。プロジェクト自体が問題を解決できる可能性がある場合は、リポジトリの検索が必須です。
7. まず問題への適合度で順位付けし、Star 数は成熟度の指標として使います。 Star 数が多いリポジトリは調査候補として有力ですが、メンテナーが確認したイシュー、マージ済みの PR、リリース済みの修正、公式の実例、完全に一致するコードは、人気はあっても関連性が隣接するだけのプロジェクトよりも有力な証拠です。順位付けが重要な場合は、research-rubric.md を使用します。
8. 有力なプロジェクトと証拠を詳しく読み込みます。 extraction-playbook.md を使って、プロジェクトの基本情報、再利用可能な要素、根本原因や実装パターン、バージョンの制約、リスク、適用時の境界、検証手順を抽出します。
9. 最小限の適応でローカル作業に落とし込みます。 実証済みのワークフロー、API、設定の形式、アーキテクチャのうち適合するものを維持します。ユーザーのローカルなインターフェース、設定、データ／認証モデル、デプロイ先、言語／実行環境に必要な部分だけを適応させます。
10. 成功を主張する前に検証します。 ローカルの問題に応じて、テスト、ビルド、再現コマンド、実際のリクエスト、ログ、ブラウザーでの確認、手動検査を行います。
11. 証拠が弱い場合は、その旨を伝えます。 弱い一致を、確信のある推奨へと無理に結び付けてはいけません。オープンソースの証拠が不十分な場合は、推奨が第一原理に基づくもの、またはローカル環境限定のものであることを明示します。

サブエージェント／並行調査のガイダンス

サブエージェントは条件に応じて利用する調査補助であり、常に必要なものではありません。問題の設定、範囲の管理、エビデンスの評価、ローカル環境への適用、最終確認は引き続きコントローラーが担当します。

次のいずれかに該当する場合は、サブエージェントを使用してください。

• 問題が、相互に独立した2つ以上のエコシステム、フレームワーク、言語、ツール、デプロイ先、またはGitHubコミュニティにまたがる。
• リポジトリの調査で、複数のクエリ群にわたる幅広い候補の確認が必要である。
• Issue、PR、ディスカッション、コード、リリース、サンプルのエビデンスを、プロジェクト、バージョン、または検索対象ごとに明確に分割できる。
• 最終的な推奨に、独立したエビデンスのレビュー、リスクのレビュー、または候補を却下するためのレビューが有効である。

次のいずれかに該当する場合は、サブエージェントを使用しないでください。

• 問題が限定的なエラーで、該当するパッケージ、リポジトリ、API、またはメンテナーの窓口が明らかに1つである。
• 外部調査の範囲を安全に定める前に、ローカルリポジトリのコンテキスト、ログ、設定、または再現手順を把握する必要がある。
• GitHubのレート制限、認可境界、プライベートリポジトリ、シークレット、本番データ、または機密ログにより、委任がリスクを伴う。
• サブエージェントが同じ検索を繰り返したり、同じローカルファイルを編集したりすることが大半を占める。

サブエージェントを使用する場合、コントローラーは次のことを行う必要があります。

• 各サブエージェントについて、クエリ群、リポジトリの範囲、エビデンスの対象、制約、許可された書き込み範囲、期待する出力を定義する。
• 直接リンク、確認済みのメタデータ、問題との適合性の根拠、リスクに関する注記、明示的な却下理由を含めるよう求める。
• 独立した実装フェーズで書き込み範囲を限定的に許可する場合を除き、サブエージェントは読み取り専用にする。
• 順位付けの前に結果を統合して重複を除去する。同じIssue、PR、コードパス、またはリポジトリに関する重複報告を、独立したエビデンスとして数えない。
• 最終決定の前に、gh、ソースの読み込み、テスト、ログ、実際のリクエスト、または公式ドキュメントを用いて、最も有力な主張を直接確認する。

GitHub CLIを優先する

検索と確認には、デフォルトでGitHub CLI（gh）を使用してください。ブラウザーでのスクレイピングや独自スクリプトを使う前に、gh search repos、gh search issues、gh search prs、gh search code、gh repo view、gh issue view、gh pr view、gh apiを優先してください。このスキル用に、同梱の検索スクリプトを追加したり、それに依存したりしないでください。

次の短いコマンドテンプレートを出発点として使用し、ローカルの問題に合わせてクエリ、リポジトリ、フィールド、上限を調整してください。

gh search repos "<query>" --archived=false --sort stars --order desc --limit 10 --json fullName,url,description,stargazersCount,forksCount,language,license,pushedAt,isArchived,openIssuesCount
gh search issues "<query>" --repo owner/repo --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
gh search prs "<query>" --repo owner/repo --merged --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
gh search code "<query>" --repo owner/repo --limit 10 --json path,url,repository,sha
gh repo view owner/repo --json nameWithOwner,url,description,stargazerCount,forkCount,licenseInfo,primaryLanguage,pushedAt,repositoryTopics,homepageUrl
gh api -X GET search/repositories -f q='<query> archived:false' -f sort=stars -f order=desc

コマンドが403、429、プライベートリポジトリの認可エラー、またはghの未認証を明示するメッセージで失敗した場合に限り、gh auth statusを実行してください。GitHubが403／429を返した場合は、再試行したり、検索範囲を狭めたり、エンドポイントを切り替えたりする前に、出力されたレート制限または認可のコンテキストを確認してください。トークン、Cookie、プライベートリポジトリの内容、認証情報をプロンプト、ファイル、ログ、メモリに貼り付けたり保存したりしないでください。

検索戦略

• まず検索範囲を絞ります。エラー文字列、例外クラス、CLI の出力、パッケージ名とメソッド名、設定キー、スタックトレースの一部などを検索します。
• 制約を加えます。パッケージ／フレームワークのバージョン、言語、プラットフォーム、デプロイ先、バンドラー、データベース、認証プロバイダー、ランタイムなどを指定します。
• 関連する場合は、次の順で検索します。Issue／PR／ディスカッション、マージ済みの修正、リリースノート／変更履歴、サンプル／テンプレート、ソースコード、最後にリポジトリ全体の候補です。
• エラーのない実装上の障害については、実現したい機能とフレームワーク／ランタイム／API 名を組み合わせて検索します。
• トレンド、人気リスト、トピック検索、エンゲージメント指標など、公開プラットフォームデータが必要な場合は、ブラウザーの表示内容をスクレイピングする方法から始めないでください。まず再利用可能な公開エンドポイント、オープンソースのクローラー、アーカイブ済みデータセット、API フィールドの根拠を探します。その後、最小限の実リクエストで選択したデータソースを検証し、匿名で取得できる人気リストデータと、ログインが必要な検索／トピックデータを明確に区別します。
• 再利用可能なプロジェクトを探す場合は、リポジトリを Stars の多い順に検索し、ローカルの課題に合致する候補だけを詳しく調べます。Stars、フォーク数、言語、ライセンス、活動状況、基本的な内容を記録します。
• 古いもの、バージョンが一致しないもの、アーカイブ済みのもの、未解決のもの、推測に基づくものは、候補としての優先度を下げます。
• Stars／フォーク数は、同程度に適合するリポジトリ間で、成熟度を判断する補助材料や絞り込みの基準としてのみ使用します。課題への適合性、メンテナーによる確認、マージ済み PR、リリースノート、公式サンプル、再現可能なコードより優先してはいけません。
• セキュリティ、認証、決済、インフラストラクチャ、本番環境の運用に関する場合、情報が変更されている可能性があるため、オープンソースの調査結果を最新の公式ドキュメントやリポジトリと照合します。

エビデンス基準

信頼できるエビデンス項目ごとに、次の点を明らかにします。

• 完全一致：同じエラー、動作、API、バージョン、環境、またはワークフローであること。
• エビデンスの強さ：メンテナーによる確認、マージ済み PR、リリース済みの修正、再現可能なコード例、テストフィクスチャ、または独立した複数の報告であること。
• 適用可能性：解決策を適用するために、ローカルでどのような条件が一致している必要があるか。
• 実装上の価値：応用する価値のあるパッチ、設定、API の使用方法、依存関係のバージョン、ワークフロー、テスト、または運用パターン。
• リポジトリが候補の場合の基本情報：名前、URL、Stars、フォーク数、言語、ライセンス、活動状況、基本的な内容、適合する理由、応用にかかるコスト。
• リスク：古いバージョン、未解決の Issue、安全でない回避策、ライセンス上の懸念、セキュリティ／プライバシーへの影響、デプロイ環境との不一致、または変更範囲が広すぎること。

出力要件

PavedPath Code が回答に実質的な影響を与える場合は、次の内容を含めてください。

• ローカルの問題プロファイル：目標、症状／エラー、バージョン／環境、ローカルの制約。
• 検索経路：使用した検索語句や調査方法、検索した GitHub／オープンソースの情報源、サブエージェントを使用したか、使用しなかったか。
• サブエージェントの追跡情報（サブエージェントを使用した場合）：各サブエージェントの担当範囲、調査した情報源、主な調査結果、候補から除外したもの、重複排除の結果、コントローラーが直接検証した主張。
• プロジェクト候補（GitHub プロジェクト自体が関連する場合）：リポジトリへのリンク、スター数、フォーク数、言語、ライセンス、活動状況、基本的な内容、適合する理由、ローカルでの活用方法。
• 主な根拠：該当する理由を添えた、Issue、PR、コード、例、リリース、リポジトリへのリンク。
• 推奨する解決策：直接再利用するもの、ローカル向けに調整するもの、流用を避けるもの、および適合する理由。
• 除外した選択肢、またはリスクのある選択肢：適用できない理由、または注意が必要な理由。
• 検証基準：修正を確認するために必要なテスト、ビルド、再現コマンド、実際のリクエスト、または手動チェック。
• 根拠が弱い場合、または有力なオープンソースの解決策が見つからなかった場合は、確信度ラベル。

リポジトリレベルの解決策が関連する場合は、簡潔なプロジェクト表を含めてください。Issue／PR／コードの修正だけの場合は表は任意ですが、信頼性や適用可能性に影響する場合はリポジトリの背景情報を含めてください。

リンク、スター数、人気ランキングだけで回答しないでください。根拠を示すリンクなしに「GitHub でよくあるパターン」と書かないでください。外部の事例をローカルの制約より優先しないでください。

ウェブサイト、SaaS、ランディングページ、テーマ、またはフロントエンドテンプレートの候補を調査する場合は、有力な候補それぞれについて、リポジトリの URL とライブプレビュー／デモの URL の両方を含めてください。プレビューを利用できない場合、または確認できていない場合は、その旨を明記し、候補の評価を下げてください。

移行に関する注意

github-solution-research は PavedPath Code に名称変更されました。以前の動作は維持されています。これは、PavedPath のコード特化版における名称と位置づけの変更です。新規インストールでは、pavedpath-code というスキル名と、対象エージェントランタイムの有効なスキル／指示ディレクトリを使用してください。

安全上の境界

• コードをコピーするよりも、既存のパターンを読み取り、公開済みのインターフェースを再利用することを優先してください。コードの再利用が必要な場合は、ライセンスを確認し、帰属表示や義務に関するリスクを明示してください。
• 既存のオープンソースソリューションを大幅に書き換えないでください。実証済みの処理フローを維持し、ユーザーの問題に必要な範囲だけローカル向けに調整してください。
• リポジトリ、README、Issue、PR、ドキュメントから長文をそのまま転載しないでください。
• GitHub トークン、Cookie、プライベートリポジトリの内容、または認証情報を、出力、ログ、スキル、メモリに保存しないでください。
• トークン、Cookie、プライベートリポジトリの内容、機密ログ、シークレット、本番データ、または認証情報をサブエージェントに渡さないでください。
• ネットワークにアクセスできない場合は、オープンソースの調査を実施できなかったことを明記し、推奨内容をローカルのみのものとして示してください。