keep-the-caveat-with-the-number
数値とその但し書きは、ひとつの成果物でなければなりません。段落がふたつあれば離れていきますが、コンポーネントひとつなら離れようがありません。
カードを読んだレビュアーが与えるものであり、ファイルが自分について主張するものではありません。信頼できない内容を扱った実行中にエージェントが抽出したカードは汚染された状態で生まれ、取得される前にレビュー待ちとして保留されます。
どんなときに思い出すか
- ベンチマーク結果を公開する
- ページに指標を書き込む
- 数字に前提がいる
- 測定結果をまとめる
価値はたいてい「回避」と「確認」にあります。「実施」は誰でも書ける節です。
上のカード本文は翻訳です。CLI が取り込み、エージェントが実行時に読み、下のハッシュが証明するのは英語の原文です。
トリガー
測定した数値を、読み手の目に触れる場所に置こうとしている場合に当てはまる。READMEやランディングページ、リリースノート、ダッシュボード、レポートなどだ。その数値自体は真実だが、誤解を招かないためにはその隣に一文が必要になる——サンプルが少なかった、対象が簡単な部類だった、効果は有意ではなかった、それは自社のベンチマークだった、といった具合に。
それだけで意味が完結している数値には当てはまらない。「ビルドは41秒で完了した」には何も要らない。
実施
- 数値より先に注記を書く。もし限界を一文で言い表せないなら、まだその測定を公開できるほど理解していないということだ。
- 注記を構造的に結び付ける。同じコンポーネント、同じテーブルの行、同じ関数の戻り値の中に置く——注記なしにはその数値をレンダリングできないような形にする。
- 数値の上、あるいは横に置く。下ではない。
- 数値そのものを導出値にする。測定が生成した成果物から読み取るようにし、測定が変われば数値も動くようにする。
回避
見出しに数値を置き、注記を脚注、アスタリスク、折りたたみセクション、あるいは後続の段落に置くこと。これらはすべて見た目が違うだけの同じバグだ。読み手は先に思い込みを形成してしまい、後から届く訂正は、すでに存在する思い込みを覆さなければならない。
二次的なバージョンも避けること——注記を省略したままその数値をレンダリングできてしまうコンポーネントだ。もし限定条件が省略可能な引数であれば、それは省略される。しかも、意味を変えるつもりなど毛頭ない、単に段落を引き締めようとしただけの誰かによって省略されてしまう。
そして、丁寧に書かれた注記を言い換えないこと。言い換えこそが「単独では有意でない」を「有意に近い」に変えてしまう場所だ。
確認
注記なしでその数値を書こうとして、失敗するのを確認する。限定条件の引数を削除するか、素の数値をページに置いてビルドを実行する。
それでもコンパイルが通るなら、その組み合わせは仕組みではなく単なる慣習であり、慣習は誰も急いでいない間しか生き延びない。
リスク
過剰に適用すると、普通のレポート作成が重くなる。すべての数値がベンチマークというわけではなく、必要のない数値に注記を付けると、人々は注記を読み飛ばすようになってしまう。
より厄介なリスクは、仕組みがあることで答えがすべて出たような気になることだ。何らかの注記を常にレンダリングするコンポーネントは、その注記が正しい注記かどうかまではチェックしない。文章そのものは依然として人が誠実に書かなければならない——この仕組みが防ぐのは、後からそれが落とされることだけだ。
使い方
カードはデータです。リポジトリをクローンし、パスで取り込んでください。ネットワーク経由で届いたものは汚染扱いとなり、承認されるまで保留されます。それが望ましい挙動であり、ここにワンライナーのインストーラーがない理由です。
git clone https://github.com/brcampidelli/chimera-agent.gitchimera skills-import chimera-agent/skills/keep-the-caveat-with-the-number/SKILL.md完全性
公開された状態のファイルの SHA-256。取り込む側は、受け取ったものがこのページに表示されたものと同じか確認できます。
98a524b60de3f913785f477d03a8a49b428afe7f31d9996b72563f17f8b287d6