chimera-write-the-check-before-the-code
実装の後に書かれた基準は、その実装を記述しているだけです。まず失敗するチェックを書き、それが失敗するのを確認してから作ってください。
カードを読んだレビュアーが与えるものであり、ファイルが自分について主張するものではありません。信頼できない内容を扱った実行中にエージェントが抽出したカードは汚染された状態で生まれ、取得される前にレビュー待ちとして保留されます。
どんなときに思い出すか
- これから機能を実装する
- 完了の定義を決める
- コードの後にテストを書く
- 受け入れ条件がないタスク
価値はたいてい「回避」と「確認」にあります。「実施」は誰でも書ける節です。
上のカード本文は翻訳です。CLI が取り込み、エージェントが実行時に読み、下のハッシュが証明するのは英語の原文です。
トリガー
「完了」がまだ観測可能でないものを実装しようとしている場合に当てはまる。機能、バグ修正、挙動を保つと謳うリファクタリングなどだ。これは、書き手と唯一のレビュアーが同じプロセスであるとき——単独で作業するエージェント、誰も読まない一人きりのコミット——に最も強く噛みつく。
スパイクには当てはまらない。そもそも何が可能なのかを見つけ出すための探索には、まだ受け入れ基準がなく、先に基準をでっち上げるのは、最初の思いつきに自分を縛るだけだ。チェックは、スパイクが終わって本番の作業が始まるときに書くこと。
このカードは、まだ存在しないチェックについてのものだ。その姉妹版である chimera-prove-the-test-discriminates は、すでに存在していて中身が空かもしれないチェックについてのものであり、そちらには修正の後、それなしにテストが失敗することを示すために手を伸ばす。同じ本能の、作業の逆の端である。
実施
- 実装に手を付ける前に、失敗しうるものとして基準を書く。テスト、アサーション、終了コードが反転するコマンド、期待する行を伴うクエリなどだ。文章はチェックではない——「エンドポイントはもっと速くなるべきだ」はチェックではなく、「既存のベンチコマンドで測定して、フィクスチャ集合に対し p95 が 200 ms 未満」はチェックである。
- 観測がどこから来るのかを述べる。差分についての自分の読みではなく、マシンからだ。
- そのチェックを今すぐ、変更前のコードに対して実行する。失敗しなければならない。通ってしまうなら、その挙動はすでに存在している——その場合は手を止めること、作るものは何もない——か、そのチェックが自分の思っているものを検証していないかのどちらかだ。
- 失敗メッセージを読む。それは意図した理由で失敗していなければならず、import エラーでも、フィクスチャの欠落でも、テスト名のタイプミスでもいけない。誤った原因から来た赤は、装いを変えた緑である。
- チェックを実装より前に、独立したコミットとして投入する。実装が存在してしまえば、チェックはそれに合わせて編集可能なものになり、そして実際に編集される。
- 実装する。完了とは、チェックが通ることであって、コードが出来上がって見えることではない。
回避
アサーションを後から、出力を見て書くこと:
normalize(" Foo ") # -> "foo"
# test transcribed from that observation
assert normalize(" Foo ") == "foo"
そのアサーションは、それが写し取られた元のコードに対しては失敗しえない。要件ではなく挙動を記録しているため、実装が内部的に一貫している限り、どんなバグを通り抜けても緑のままである。要件が NFKC 正規化であり、出荷したのが strip().lower() だったとしても、このテストは永遠にあなたに同意し続ける。
変更の言い換えにすぎない基準も避けること——「関数が追加されたら完了」「マイグレーションが走ったら完了」といったものだ。どちらも空の実装で満たされてしまう。
確認
リポジトリから答えられる、二者択一の問いが2つ:
- 実装が存在する前に、そのチェックが失敗するところを見たか。赤だった瞬間が存在しないなら、それが赤になりうるという証拠はない。
- その機能がまったく別の方法で作られていたとしても、そのチェックは依然として正しいか。内部——プライベートな呼び出し、ログ行、正確な SQL 文字列——を名指しするチェックは、要件ではなく自分の解法に固定されており、次のリファクタリングを妨げながら何も捕捉しない。
具体的には: git log はチェックが実装と同時かそれ以前に投入されたことを示し、実装のコミットだけを巻き戻すとスイートが赤くなる。
リスク
まだ理解していない要件を、先に書いたチェックで固定することはできない。間違ったものについて精密なアサーションを書き、それに向けて実装することになる——チェックがないよりも悪い。誤解を、レビュアーが信頼する緑のスイートへとロンダリングしてしまうからだ。基準が本当に分からないとき、それはテストの形で推測する合図ではなく、一度に1つずつ質問しに行く合図である。
素朴なコストもある。タイポの修正やドキュメントの編集にとって、先にチェックを書くことは、誰も対価を払わない儀式だ。このカードが元を取るのは、「完了」が間違っていることで誰かが被害を受ける程度に、その挙動が重要な場合である。
使い方
カードはデータです。リポジトリをクローンし、パスで取り込んでください。ネットワーク経由で届いたものは汚染扱いとなり、承認されるまで保留されます。それが望ましい挙動であり、ここにワンライナーのインストーラーがない理由です。
git clone https://github.com/brcampidelli/chimera-agent.gitchimera skills-import chimera-agent/skills/chimera-write-the-check-before-the-code/SKILL.md完全性
公開された状態のファイルの SHA-256。取り込む側は、受け取ったものがこのページに表示されたものと同じか確認できます。
95d0a1b750e25af7651e85d26106a91f02f563ab1a1422edc4133d16942b67d7