Verify Change

目的

完了を報告する前に、変更が想定どおりに動くことを実際に確かめる。

テストや型チェックが通っても、利用者が使う経路で動くとは限らない。 確かめずに「動くはず」と報告しない。

この skill は、ユーザーに言われるのを待たずに使う。

使うタイミング

• コードや設定を変更し、完了を報告する前
• 変更が動くかどうかを聞かれたとき。自分が変更していない場合も含む

動作を問わない調査や質問への回答では使わない。

Workflow

1. 確かめる振る舞いを決める
2. 確かめ方を決める
3. 期待する結果を先に決め、実行して観察する
4. repository で要求されるテスト・型チェック・lint・build を実行する
5. 後片付けをする
6. 結果に応じて、報告するか問題を直す

1. 確かめる振る舞い

次の振る舞いを確かめる。

• 依頼で求められた振る舞い
• 変更が影響する既存の振る舞い
• バグ修正の場合は、元の再現手順

2. 確かめ方

変更の影響を確かめられる方法のうち、最も軽いものを選ぶ。

• 利用者が使う経路に影響する変更: アプリケーションを起動し、CLI、API、画面の操作で確かめる
• モジュール間の契約に影響する変更: integration test や E2E test で確かめる
• 内部に閉じた変更: unit test、型チェック、lint で確かめる
• 文書だけの変更: repository が定める lint などで確かめる

迷った場合は、利用者に近い方法を選ぶ。

起動方法は、repository の指示、README、build 設定から判断する。 起動手順を定めた skill や文書があれば、それに従う。

起動する前に、接続先の設定を確かめる。 本番環境や実在の外部サービスに接続する設定なら、起動前にユーザーへ確認する。

3. 実行と観察

期待する結果を先に決め、実際の結果と比べる。

出力、終了コード、画面、ログを確認する。 今回の変更後に実行した結果だけを証拠にする。 一度でも失敗した結果は、再実行で通っても報告に残す。

4. テスト・型チェック・lint・build

repository で要求される項目を検証する。 手順 3 で同じ検証を済ませていれば、繰り返さない。

5. 後片付け

• 確認のために起動したプロセスやコンテナを止める
• 確認用に加えた一時的な変更を取り消す
• 取り消すのは自分が加えた差分だけにし、Git の破壊的な操作で戻さない

止められなかったものや残したものは、報告に書く。

6. 結果に応じた進め方

• 想定どおり: 報告する
• 想定と違う、または失敗した: 「問題が見つかった場合」に従う
• 実行できない: 「確かめられない場合」に従う

問題が見つかった場合

今回の作業で加えた変更が原因なら、言われるのを待たずに直す。 それ以外が原因なら、原因と直し方の案を報告する。直すかどうかはユーザーが決める。

直すときは、次に従う。

1. 原因を特定してから直す。当てずっぽうで直さない
2. 症状を抑えるだけの修正はしない 例: 例外を握りつぶす、retry や sleep で失敗を隠す、テストの期待値を誤った実装に合わせる
3. うまくいかなかった修正は、次を試す前に戻す
4. 既存のテストで再現できない問題は、利用側から見える振る舞いを検証する回帰テストを追加する
5. 直したら、影響を受けた部分を Workflow の手順 1 から確かめ直す

止まる判断

次の場合は、直すのをやめてユーザーに報告する。

• 修正を試すたびに、問題が残るか別の箇所が壊れ、それが 3 回続いた
• 再現しない失敗で、原因を絞る手がかりがなくなった
• 依頼や既存の仕様を超えて、利用者から見える振る舞い、公開仕様、互換性、データの扱いを変える必要がある
• 権限や credentials が足りない
• 破壊的・不可逆な操作が必要になる

報告には、試したこと、それぞれの結果、分かったこと、残る仮説を書く。

確かめられない場合

依存関係の未インストールやローカルのサービスの未起動など、ローカルで解決できる不足は自分で解決する。

権限、credentials、外部サービスの不足は回避しない。次の順で対応する。

1. 最も近い代替手段で確かめる 例: 外部境界を fake で置き換える、dry-run を使う、一部の経路だけを実行する
2. 確かめられなかった範囲と理由を記録する
3. ユーザーが確かめるための手順を報告に含める

判断の範囲

次のことは自分で判断して進める。

• 確かめる振る舞いと確かめ方
• テストデータ、一時ファイル、ローカルでの起動
• 技術的な直し方の選択

次のことはユーザーに確認する。

• 「止まる判断」に当てはまること
• 本番環境や外部サービスへの書き込みなど、外部に影響する操作
• 観察結果が仕様どおりか、既存の仕様や依頼から判断できない場合

報告

完了報告では、次の項目を分けて書く。

• 確かめたこと: 実行したコマンドや操作と、観察した結果
• 原因と修正: 見つけた問題、その原因、直した内容。直していない場合は直し方の案
• 判断したこと: 自分で決めたことと、その理由
• 未確認のこと: 確かめられなかった範囲、理由、確かめる手順、一度だけ失敗した結果

問題が見つからなかった場合は「原因と修正」を省略する。 credentials などの秘密情報は、報告や出力に含めない。