Jia-Ethan/pavedpath-code

PavedPath Code

PavedPath Code は、エージェントがソフトウェアエンジニアリングの問題に対して車輪の再発明をするのを防ぎます。GitHub とオープンソースのエビデンスを検索して実証済みの実装パスを見つけ、最も強力なパターンをローカルコードベースに最小限の検証可能な変更で適応させます。

GitHub を一次的なエビデンスソースとして使用し、リンクのダンプとして使用しないでください。目標は、ローカルのコード問題を定義し、公開リポジトリ、Issue、Pull Request、ディスカッション、例、リリースノート、ソースコード内で既に歩まれているパスを見つけ、そのエビデンスの強度を評価し、最も強力なパターンを小さなローカル修正、実装パス、または検証計画に変換することです。

これは PavedPath のコード特化版エディションです。将来の汎用 PavedPath に拡大しないでください。これはソフトウェアエンジニアリング作業専用です：バグ、ランタイムエラー、ビルド/テスト/デプロイの失敗、依存関係の問題、フレームワークまたは API の使用法、統合ブロッカー、実装パターン、エンジニアリングツールの選択、オープンソースソリューションの適応。

使用するタイミング

• ランタイム、ビルド、テスト、デプロイ、パッケージ、SDK、API、依存関係、フレームワーク、または統合エラー。
• 機能実装が、不明確なエッジケース、欠落している使用パターン、バージョンの動作、または不確かな API 契約によってブロックされている。
• ローカルの問題が、メンテナーや他のオープンソースユーザーが Issue、PR、例、コード、リリースノート、またはディスカッションで解決した可能性があるものに類似している。
• ユーザーが、GitHub またはオープンソースプロジェクトが具体的なエンジニアリング問題を既に解決しているかどうかを尋ねている。
• 成熟した実装例や再利用可能なプロジェクトがあれば、特定の機能に対する不確実性が軽減される。
• 回答では、適切な GitHub リポジトリを比較し、実証済みのパスの1つをローカルに適応する方法を説明する必要がある。

PavedPath Code をコピー編集、コードベースが既に答えを示している純粋にローカルなリファクタリング、非コードの生活上の決定、セルフメディアワークフロー、学習方法、消費者の購入決定、またはウェブ/GitHub調査を明示的に禁止するリクエストには使用しないでください。ユーザーが明示的にスコープを定義しアクセスを許可しない限り、プライベートリポジトリを調査しないでください。

デフォルトワークフロー

1. 最初にローカルのコード問題を明確にする。 目標、症状、エラーシグネチャ、再現パス、バージョン、ランタイム、依存関係/フレームワーク名、最近の変更、制約、試行した修正を把握する。確認可能な事実が不足している場合は、質問する前にローカルファイル/ログを調査する。
2. エビデンスモードを選択する。 エラー/回帰の場合は、まず Issue、PR、リリース、コードを検索する。機能やツールのニーズの場合は、最初にリポジトリ候補を検索する。機能実装の場合は、リポジトリ候補と Issue/PR/コードエビデンスの両方を使用する。
3. サブエージェントの有用性を評価する。 本格的な GitHub 調査の前に、条件付きサブエージェント作業が調査範囲、エビデンス品質、またはレビュー範囲を改善するかどうかを判断する。サブエージェントを使用しない場合は、検索パスを報告する際にその理由を簡潔に述べる。
4. ターゲットを絞った検索を作成する。 正確なエラーテキスト、パッケージ/API名、バージョン番号、フレームワーク＋症状、ファイル名、設定キー、スタックトレースの断片、失敗したコマンド名、または機能＋フレームワーク/ランタイム/API名を優先する。
5. 該当する場合は適切な GitHub プロジェクトを見つける。 適合度、スター数、アクティブ、アーカイブされていない、明確なライセンスと実際の例があるリポジトリを優先する。高スターセットが広すぎる場合や正確な問題を見逃している場合は、スターのしきい値を下げる。
6. オープンソースのエビデンスサーフェスを検索する。 関連するオープンソースリポジトリ内で、Issue、PR、ディスカッション、コード、例、リリースノート、公式プロジェクトドキュメントを使用する。プロジェクト自体が問題を解決する可能性がある場合は、リポジトリ検索が必要です。
7. まず問題への適合度でランク付けし、スターは成熟度のシグナルとして使用する。 高スターのリポジトリは調査の有力な候補ですが、メンテナーが確認した Issue、マージされた PR、リリースされた修正、公式の例、および完全に一致するコードは、人気のある隣接プロジェクトよりも優先されます。ランク付けが重要な場合は、research-rubric.md を使用する。
8. 最も強力なプロジェクトとエビデンスを深く読む。 extraction-playbook.md を使用して、プロジェクトの基本、再利用可能なサーフェス、根本原因または実装パターン、バージョン制約、リスク、適応範囲、検証手順を抽出する。
9. 最小限の適応でローカル作業に変換する。 実証済みのワークフロー、API、設定形状、またはアーキテクチャが適合する場合はそれを維持する。ユーザーのローカルインターフェース、設定、データ/認証モデル、デプロイターゲット、または言語/ランタイムによって要求される部分のみを適応する。
10. 成功を主張する前に検証する。 ローカルの問題に適したテスト、ビルド、再現コマンド、実際のリクエスト、ログ、ブラウザチェック、または手動検査を使用する。
11. エビデンスが弱い場合は、その旨を伝える。 弱い一致を自信のある推奨事項に引き伸ばさない。オープンソースのエビデンスが不十分な場合は、推奨事項を第一原理またはローカルのみとしてマークする。

サブエージェント / 並列調査ガイダンス

サブエージェントは条件付きの調査支援であり、デフォルトの要件ではありません。コントローラーは、問題のフレーミング、スコープ制御、エビデンスのランク付け、ローカル適応、および最終検証の責任を引き続き負います。

次の少なくとも1つが該当する場合にサブエージェントを使用します。

• 問題が2つ以上の独立したエコシステム、フレームワーク、言語、ツール、デプロイサーフェス、または GitHub コミュニティにまたがっている。
• リポジトリ発見に、複数のクエリファミリーにわたる幅広い候補カバレッジが必要である。
• Issue、PR、ディスカッション、コード、リリース、および例のエビデンスを、プロジェクト、バージョン、または検索サーフェスごとに明確に分割できる。
• 最終的な推奨事項が、独立したエビデンスレビュー、リスクレビュー、または候補却下レビューから恩恵を受ける。

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

• タスクが1つの明白なパッケージ、リポジトリ、API、またはメンテナーサーフェスを持つ狭いエラーである。
• 外部調査を安全にスコープ化する前に、ローカルリポジトリコンテキスト、ログ、設定、または再現の詳細を理解する必要がある。
• 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 を優先してください。このスキルにバンドルされた検索スクリプトを追加したり依存したりしないでください。

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

git search repos "<query>" --archived=false --sort stars --order desc --limit 10 --json fullName,url,description,stargazersCount,forksCount,language,license,pushedAt,isArchived,openIssuesCount
git search issues "<query>" --repo owner/repo --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
git search prs "<query>" --repo owner/repo --merged --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
git search code "<query>" --repo owner/repo --limit 10 --json path,url,repository,sha
git repo view owner/repo --json nameWithOwner,url,description,stargazerCount,forkCount,licenseInfo,primaryLanguage,pushedAt,repositoryTopics,homepageUrl
git 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 を返した場合は、再試行、範囲の縮小、またはエンドポイントの切り替えを行う前に、発行されたレート制限または認可コンテキストを検査します。トークン、クッキー、プライベートリポジトリの内容、または資格情報をプロンプト、ファイル、ログ、またはメモリに貼り付けたり保持したりしないでください。

検索戦略

• 狭く始める：正確なエラー文字列、例外クラス、CLI 出力、パッケージ＋メソッド名、設定キー、またはスタックトレースの断片。
• 制約を追加する：パッケージ/フレームワークのバージョン、言語、プラットフォーム、デプロイターゲット、バンドラー、データベース、認証プロバイダー、またはランタイム。
• 該当する場合、次の順序でサーフェスを検索する：Issue/PR/ディスカッション、マージされた修正、リリースノート/変更ログ、例/テンプレート、ソースコード、次にリポジトリレベルの候補。
• エラーなしの実装ブロッカーの場合は、目的の機能とフレームワーク/ランタイム/API名を組み合わせて検索する。
• トレンド、ホットリスト、トピック検索、エンゲージメントメトリクスなどの公開プラットフォームデータのニーズについては、ビジュアルブラウザスクレイピングから始めないでください。最初に再利用可能なパブリックエンドポイント、オープンソースクローラー、アーカイブデータセット、APIフィールドの証拠を探します。次に、最小限の実際のリクエストで選択したソースを検証し、匿名のホットリストデータとログイン済みの検索/トピックデータを明確に分離します。
• 再利用可能なプロジェクト発見の場合は、スター順にソートされたリポジトリを検索し、ローカルの問題に一致する候補のみを深く読み込む。スター、フォーク、言語、ライセンス、アクティビティ、および基本的なコンテンツを記録する。
• 古い、バージョン不一致、アーカイブ済み、未解決、推測的、またはユーザーの推測のみに基づく一致は格下げする。
• スター/フォークは、補助的な成熟度コンテキストおよび同程度に適合するリポジトリ間のタイブレーカーとしてのみ使用する。問題適合度、メンテナー確認済みエビデンス、マージされたPR、リリースノート、公式の例、または再現可能なコードをオーバーライドしない。
• セキュリティ、認証、支払い、インフラストラクチャ、または本番運用については、事実が変更された可能性がある場合、オープンソースの調査結果を現在の公式ドキュメントまたはリポジトリとクロスチェックする。

エビデンス基準

重要なエビデンス項目ごとに、以下を特定します。

• 完全一致：同じエラー、動作、API、バージョン、環境、またはワークフロー。
• エビデンス強度：メンテナーによる確認、マージされたPR、リリースされた修正、再現可能なコード例、テストフィクスチャ、または繰り返しの独立したレポート。
• 適用可能性：ソリューションを適用するためにローカルで一致する必要がある条件。
• 実装価値：適応する価値のあるパッチ、設定、APIの使用法、依存関係バージョン、ワークフロー、テスト、または運用パターン。
• リポジトリが候補である場合のプロジェクト基本情報：名前、URL、スター、フォーク、言語、ライセンス、アクティビティ、基本的なコンテンツ、適合の根拠、適応コスト。
• リスク：古いバージョン、未解決の問題、安全でない回避策、ライセンス上の懸念、セキュリティ/プライバシーへの影響、デプロイの不一致、または過度に広範な変更。

出力契約

PavedPath Code が回答に実質的に影響を与える場合、以下を含めます。

• ローカル問題プロファイル：目標、症状/エラー、バージョン/環境、ローカル制約。
• 検索パス：使用したクエリまたは発見方法、検索した GitHub/オープンソースサーフェス、サブエージェントを使用したかスキップしたか。
• サブエージェントトレース（サブエージェントを使用した場合）：各サブエージェントのスコープ、エビデンスサーフェス、主要な発見、却下された候補、重複排除結果、コントローラーが直接検証した主張。
• プロジェクト候補（GitHub プロジェクト自体が関連する場合）：リポジトリリンク、スター、フォーク、言語、ライセンス、アクティビティ、基本的なコンテンツ、一致の根拠、ローカルで使用する方法。
• 主要なエビデンス：Issue、PR、コード、例、リリース、またはリポジトリへのリンク（一致根拠付き）。
• 推奨ソリューション：直接再利用するもの、ローカルで適応するもの、コピーを避けるもの、およびその理由。
• 却下されたリスクのあるオプション：なぜ適用されないか、または注意が必要か。
• 検証基準：修正を確認するために必要なテスト、ビルド、再現コマンド、実際のリクエスト、または手動チェック。
• 信頼度ラベル：エビデンスが弱い場合、または強力なオープンソースソリューションが見つからなかった場合。

リポジトリレベルのソリューションが関連する場合は、コンパクトなプロジェクトテーブルを含めます。純粋な Issue/PR/コード修正の場合、テーブルはオプションですが、信頼性や適用可能性に影響する場合はリポジトリコンテキストを含めます。

リンク、スター、または人気ランキングのみで回答しないでください。リンクされたエビデンスなしで「一般的なGitHubパターン」と書かないでください。外部の例がローカル制約をオーバーライドすることを許可しないでください。

ウェブサイト、SaaS、ランディングページ、テーマ、またはフロントエンドテンプレートの候補調査の場合、重要な候補ごとにリポジトリURLとライブプレビュー/デモURLの両方を含めます。プレビューが利用可能でないか確認できない場合は、その旨を明記し、候補を格下げします。

移行に関する注意

github-solution-research は PavedPath Code に名称変更されました。以前の動作は維持されています。これは PavedPath のコード特化版エディションの命名およびポジショニングの更新です。新しいインストールでは、pavedpath-code スキル名とターゲットエージェントランタイムのアクティブなスキル/命令ディレクトリを使用する必要があります。

安全境界

• コードをコピーするよりも、パターンを読み取り、既存の公開インターフェースを再利用することを優先します。コードの再利用が必要な場合は、ライセンスを確認し、帰属/義務のリスクを可視化しておきます。
• 既存のオープンソースソリューションの大規模な書き換えは避けてください。その実証済みのフローをそのまま維持し、ユーザーの問題に必要なローカル適応のみを行います。
• リポジトリ、README、Issue、PR、またはドキュメントからの大規模な逐語的な引用は避けてください。
• GitHub トークン、クッキー、プライベートリポジトリの内容、または資格情報を出力、ログ、スキル、メモリに保存しないでください。
• トークン、クッキー、プライベートリポジトリの内容、機密ログ、シークレット、本番データ、または資格情報をサブエージェントに渡さないでください。
• ネットワークアクセスが利用できない場合は、オープンソース調査を実行できなかったことを述べ、推奨事項をローカルのみとしてマークします。