chimera-ground-it-in-the-source
シグネチャは記憶からではなく、インストール済みのバージョンから取ること——もっともらしい API は、実行するまで本物と見分けがつきません。
カードを読んだレビュアーが与えるものであり、ファイルが自分について主張するものではありません。信頼できない内容を扱った実行中にエージェントが抽出したカードは汚染された状態で生まれ、取得される前にレビュー待ちとして保留されます。
どんなときに思い出すか
- 自分が書いていないライブラリを呼ぶ
- 引数名は何だったか
- バージョン間で API が変わった
- 記憶を頼りにフレームワークを書く
- あるはずのメソッドで AttributeError
価値はたいてい「回避」と「確認」にあります。「実施」は誰でも書ける節です。
上のカード本文は翻訳です。CLI が取り込み、エージェントが実行時に読み、下のハッシュが証明するのは英語の原文です。
トリガー
他人のライブラリ、フレームワーク、CLI への呼び出しをこれから書こうとしている場合に当てはまる。メソッド名、キーワード引数、設定キー、戻り値の形、フラグなどだ。これは記憶が確信として感じられるときにこそ最も鋭く当てはまる。確信は、その API が実在するかどうかに関わらず同じ仕組みで生み出されるからだ。
日常的に使い倒している言語自体の組み込み機能には当てはまらないし、dict.get を書く前にドキュメントを取ってこいという指示でもない。線引きは、間違っていた場合に、次に実行するもので即座に捕捉されるかどうかだ。
実施
- 読んだ記憶のあるバージョンではなく、実際にインストールされているバージョンを取得する。
uv pip show <pkg>、あるいはpython -c "import pkg; print(pkg.__version__)"。 - インストールされている実物を読む。
python -c "import inspect, pkg; print(inspect.signature(pkg.fn))"、site-packages配下のファイルを開く、あるいは PATH 上のバイナリに--helpを実行する。これが権威である。なぜなら、それが実際に実行されるコードだからだ。 - ブログ記事、ウェブ上の README、あるいは自分の記憶を使う場合は、それを仮説として扱い、手順2に照らして確認する。ドキュメントサイトは最新リリースを説明しており、あなたのロックファイルはそれを固定していないかもしれない。
- 想定した戻り値に添字でアクセスするコードを書く前に、使い捨てのスニペットで一度その呼び出しを実行し、実際の戻り値を出力する。入れ子になった形——
["choices"][0]["message"]——こそ、記憶が最も当てにならず、しかも派手に失敗してくれない場所だ。 - 証拠をコードの隣に残す。バージョンと、読んだシグネチャまたは help の出力だ。コメントか PR の本文で十分であり、それは次の読み手に、そのコードが何に対して書かれたのかを伝える。
回避
API らしく見えるテキストを書くこと。この失敗はタイプミスではない——タイプミスは即座に例外を出し、数秒で直る。問題は、そのライブラリの命名規約をすべて満たしていながら実在しない名前だ:
このリポジトリでの実例であり、重要なのはその形だ——その推測は突飛ではなく、もっともらしかった:
from chimera.core.checkpoint import WorkspaceGuard, diff_snapshots # ImportError
# Where it actually is. One grep, before writing the line, would have found it.
from chimera.core.checkpoint import WorkspaceGuard
from chimera.evolution.diff_gate import diff_snapshots
コストは例外そのものではなかった——ImportError は騒がしく、そして安い。問題は、挙動についての同じ確信に満ちた推測が静かに失敗し、それが生んだ数値が間違っていたと判明したときにしか気づけないことだ。
誤ったバージョンに根拠を求めることも避けること。メジャーバージョンが2つ前で固定されているパッケージについて最新のドキュメントを読むと、自分が動かしていないライブラリについては正しいコードができあがる——そしてエラーメッセージは、出たとしても、その食い違いではなくあなたの呼び出しを指し示す。
そして、パッケージがスタブを同梱していない場合に、型チェッカーが通ったことを根拠として受け入れることも避けること。型のない依存関係に対しては Any が、あなたの発明したあらゆる属性を飲み込む。チェックが成功を報告するのは、チェックすべきものが何もなかったからだ。
確認
差分の中の自明でない呼び出しそれぞれについて、どこでそれを見たのかを指し示せるか——出力したシグネチャ、site-packages 内の行、実行した --help。そのいずれかについて正直な答えが「正しそうに思えた」であるなら、その呼び出しは未検証であり、そう述べるコストは一文である。
より強い確認は実行可能なものだ。手順4のスニペットをインストール済みのバージョンに対して実行し、その出力を貼ること。import が解決することと、呼び出しが期待した形を返すことは別々の事実であり、依拠しているのは後者の方だ。
リスク
何にでも適用すると、日常的なコードが調査作業になり、何の利得もなく作業が遅くなる。これは馴染みのない呼び出し、バージョンに敏感な呼び出し、入れ子になった戻り値の形に費やすべきであって、その周囲の百行に費やすものではない。
より微妙なリスクは、文字通りすぎる根拠づけだ。インストールされたソースは _internal_helper を平然と見せてくれる。それは実在し、今日は動作し、そして誰の約束でもない。ソースは何がそこにあるかを教え、ドキュメントは何がサポートされているかを教える。両者が食い違うときは、ドキュメント化された表面を優先すること。そしてそれを承知の上で越えるなら、次の読み手にそれが公認されたものだと思わせるのではなく、コメントにそう書くこと。
使い方
カードはデータです。リポジトリをクローンし、パスで取り込んでください。ネットワーク経由で届いたものは汚染扱いとなり、承認されるまで保留されます。それが望ましい挙動であり、ここにワンライナーのインストーラーがない理由です。
git clone https://github.com/brcampidelli/chimera-agent.gitchimera skills-import chimera-agent/skills/chimera-ground-it-in-the-source/SKILL.md完全性
公開された状態のファイルの SHA-256。取り込む側は、受け取ったものがこのページに表示されたものと同じか確認できます。
9a51bb6b117c736dba1de11a166efed09ad200134e153ad553f4701302025398