external-research

外部調査

正確性、トークンコスト、リクエストコスト、所要時間を考慮し、信頼性を保てる最小限の方法を選択してください。根拠が不足している、または信頼できない場合にのみ再評価してください。具体的な理由がない限り、同等の情報取得を繰り返したり、必要でないのに関連リポジトリや依存関係を調べたりしないでください。

方法

コストの低い順に並べた選択肢です。

1. ローカルの調査には、glob、grep、read、シェルフィルターを使用します。
2. LSP/MCP/IDE のセマンティックツール（IntelliJ IDEA、Metals LSP）。
3. 利用可能な場合は、JVM 依存関係のパブリック API に cellar スキルを使用します。
4. GitHub と Azure のクエリには、読み取り専用の gh および az サブコマンドを使用します。
5. URL が分かっている場合は、webfetch を使用します。
6. URL が分からない場合は、websearch を使用します（ツールまたはスキルのうち、利用可能なものを使用）。
7. 参照先には git ls-remote を使用し、その後、ソースと履歴の確認にはキャッシュ済み Git クローンを使用します。
8. 公開済みパッケージには、Maven、Gradle、sbt、npm のメタデータ、およびアーカイブツールを使用します。

ルール：

• 利用可能な場合は、cellar などのオプションスキルを使用してください。利用できない場合は、利用可能なツールで進めてください。
• JVM 依存関係のパブリック API を調べる場合、直接回答できるのであれば、利用可能なときは cellar スキルを優先してください。
• gh または az の変更を伴うサブコマンドは使用しないでください。制限事項として報告してください。
• 既知のウェブページで直接回答が得られる場合は、webfetch を使用し、その URL を引用してください。調査用ディレクトリは不要です。内容が空、古い、または不完全な場合は、不足している根拠を得られる可能性が高い情報源にのみ切り替えてください。
• セマンティックな質問、コンパイル、または lint には、直接回答できる、または関連する診断を生成できる場合、利用可能な LSP/MCP/IDE セマンティックツール（IntelliJ IDEA、Metals LSP）を使用し、シンボルまたはソースの位置を引用してください。根拠が得られない、または不十分な場合に限り、クローンまたは取得を行ってください。

永続的な調査キャッシュ

• $HOME/.agents/librarian/ を、実行、セッション、ハーネスをまたいで利用する永続的なキャッシュとして使用してください。必要に応じて作成してください。調査キャッシュにセッションディレクトリや mktemp を使用しないでください。
• 絶対パスを使用してください。クローンしたリポジトリは $HOME/.agents/librarian/repos/<repo-key>/ に、Maven リポジトリは $HOME/.agents/librarian/maven/<library-key>/ に保存してください。
• ネットワーク操作の前に、該当するキャッシュパスを確認してください。一致する既存のクローン、ワークツリー、POM、JAR、ソース JAR、メタデータファイル、またはグラフ出力があれば再利用してください。不足している参照先や成果物のみをダウンロードまたは取得してください。ただし、呼び出し元がリモートの最新情報を明示的に求めている場合は除きます。
• 再利用する前に、キャッシュの同一性を確認してください。リポジトリの場合は、git -C <base-clone> remote get-url origin の結果と要求された URL を比較してください。URL が異なる場合は、既存のディレクトリを上書きしたり再クローンしたりせず、別の安定した <repo-key> を使用してください。
• キャッシュのメンテナンスでは、Git メタデータの更新、ワークツリーの追加、成果物のダウンロードを行えますが、ソースファイルの変更、コミット、プッシュ、リモートの変更、ユーザーのワークスペースの変更は行わないでください。

クローンとワークツリーのワークフロー

リポジトリごとに、パスの1コンポーネントとして使用できる、安定したファイルシステム対応のキーを1つ使用します。cats-effect のように、リポジトリ名を優先してください。名前が重複する可能性がある場合は、github-typelevel-cats-effect のような修飾キーを使用します。永続的なベースクローンの名前は常に main とし、ref 固有のワークツリーはその兄弟ディレクトリに配置します。

タグ v3.7.0 の https://github.com/typelevel/cats-effect/ では、次の手順を正確に実行します。

1. 永続的なリポジトリディレクトリを作成します。

   mkdir -p "$HOME/.agents/librarian/repos"
   mkdir -p "$HOME/.agents/librarian/repos/cats-effect"
   

2. $HOME/.agents/librarian/repos/cats-effect/main がすでに存在するか確認します。存在する場合は、そのリモートとワークツリーの一覧を確認し、git clone を再実行しないでください。存在しない場合は、完全な履歴を含めてリポジトリを一度だけクローンします。

   git clone https://github.com/typelevel/cats-effect/ "$HOME/.agents/librarian/repos/cats-effect/main"
   

3. v3.7.0 がベースクローンで利用可能か、また $HOME/.agents/librarian/repos/cats-effect/v3.7.0 が git worktree list --porcelain に登録済みか確認します。そのワークツリーが存在する場合は、フェッチや追加を行わずに再利用します。

4. タグがない場合は、そのタグだけをフェッチします。リクエストのたびにリポジトリをフェッチしないでください。

   git -C "$HOME/.agents/librarian/repos/cats-effect/main" fetch origin "refs/tags/v3.7.0:refs/tags/v3.7.0"
   

5. タグが利用可能でワークツリーがない場合は、兄弟ワークツリーを作成して確認します。

   git -C "$HOME/.agents/librarian/repos/cats-effect/main" worktree add "$HOME/.agents/librarian/repos/cats-effect/v3.7.0" v3.7.0
   # Inspect with glob, grep, read, or git -C "$HOME/.agents/librarian/repos/cats-effect/v3.7.0" ...
   

   これは main ワークツリーから git worktree add ../v3.7.0 v3.7.0 を実行するのと同等ですが、絶対パスを使うことで Bash の現在のディレクトリに依存しなくなります。

6. ブランチの場合も、同じ手順を使用します。リモート追跡 ref がない場合に限りブランチをフェッチし、その後、兄弟ワークツリーを追加します。リモート追跡ブランチからローカルブランチを作成する必要がある場合は、git worktree add -b <branch> <absolute-worktree-path> origin/<branch> を使用します。

7. 要求されたパスが存在しても登録済みワークツリーではない場合、またはリモートが一致しない場合は、上書きしないでください。正確なパスを報告し、別の安定したキーが別のリポジトリを指すことを確認した場合に限り、そのキーを使用します。

ref を確認するために git checkout を使用したり、ベースクローンのブランチを切り替えたりしないでください。git worktree remove、git worktree prune、git reset、git clean、またはソースファイルを変更するコマンドは実行しないでください。プッシュやリモートの変更も行わないでください。

クローン、フェッチ、またはワークツリーの追加に失敗した場合は、正確なエラーを報告してください。別の保存先で再試行したり、同じリポジトリを再クローンしたりしないでください。

Maven アーティファクトのワークフロー

• JVM 依存関係の公開 API を確認する場合は、利用可能で、最小かつ信頼できる方法であれば cellar を優先してください。JAR、ソース JAR、POM、メタデータ、または依存関係グラフの確認により適している場合は、この Maven キャッシュのワークフローを使用します。
• cats-effect のような安定したライブラリキーを選び、Maven の永続的なローカルリポジトリとして $HOME/.agents/librarian/maven/cats-effect/ を使用します。解決する前に、そこに対象の座標のファイルがあるか正確に確認してください。ダウンロード先として、デフォルトの ~/.m2/repository を使用しないでください。
• 直接アーティファクトを1つ取得する場合は、-Dtransitive=false を指定して Maven を使用し、合成プロジェクトは作成しないでください。推移的なグラフや実効解決を取得する場合は、ライブラリキャッシュの下にリクエストディレクトリを作成し、そこに POM を書き込んで、-f <absolute-pom-path> を指定して Maven を実行します。
• リクエスト POM とグラフ出力は、$HOME/.agents/librarian/maven/<library-key>/requests/<request-key>/ の下に保持します。同じ座標とリポジトリ定義の既存リクエストを再利用し、再解決しないでください。

たとえば、Cats-Effect 3.7.0 のソース JAR を確認するには、次の手順を使用します。

mkdir -p "$HOME/.agents/librarian/maven/cats-effect"
mvn -B dependency:get -Dartifact=org.typelevel:cats-effect_3:3.7.0:jar:sources -Dtransitive=false "-Dmaven.repo.local=$HOME/.agents/librarian/maven/cats-effect"
jar tf "$HOME/.agents/librarian/maven/cats-effect/org/typelevel/cats-effect_3/3.7.0/cats-effect_3-3.7.0-sources.jar"

対象の JAR がすでに存在する場合は、mvn を実行せず、その JAR を直接確認します。バイナリ JAR、POM、および javadoc classifier にも同じキャッシュを使用します。mvn -v が失敗した場合は、Maven を利用できないことを報告し、このワークフローを試みないでください。

グラフの場合は、一時的なタスクディレクトリではなく、永続的なリクエストディレクトリを使用します。

mkdir -p "$HOME/.agents/librarian/maven/cats-effect/requests/3.7.0-graph"
cat > "$HOME/.agents/librarian/maven/cats-effect/requests/3.7.0-graph/pom.xml" <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>agents.research</groupId>
  <artifactId>cats-effect-evidence</artifactId>
  <version>1.0.0</version>
  <dependencies>
    <dependency>
      <groupId>org.typelevel</groupId>
      <artifactId>cats-effect_3</artifactId>
      <version>3.7.0</version>
    </dependency>
  </dependencies>
</project>
EOF
mvn -B -q -f "$HOME/.agents/librarian/maven/cats-effect/requests/3.7.0-graph/pom.xml" dependency:tree -Dverbose -DoutputType=text "-DoutputFile=$HOME/.agents/librarian/maven/cats-effect/requests/3.7.0-graph/tree.txt" "-Dmaven.repo.local=$HOME/.agents/librarian/maven/cats-effect"

応答する前に、永続的な出力と解決済みファイルを確認してください。

報告

URL、アーティファクト座標、Git ref、およびリポジトリ相対のパス／行範囲を引用します。検証済みの事実と推論を分け、不確実性を明記してください。