--- name: evidence-driven-engineering description: 不具合の調査や原因診断、挙動を変える実装とレビュー、繰り返し起きるエージェントの失敗の是正、作業の委任で使う。主張をコードと実行中の挙動で裏付け、検証を再現できる形で残し、同じ指摘を仕組みで防ぐ。typo修正のような小さな変更では、必要な確認だけに留める。 --- # Evidence-Driven Engineering ## 目的 エージェントの作業を、確信ではなく証拠で信頼できるものにする。 主張と実際の挙動のあいだのループを閉じ、次のエージェントが同じ検証を繰り返せる状態を残す。 このskillは判断のための既定値であり、固定手順ではない。 ## 適用の範囲 - 明示的なタスク指示、適用される `AGENTS.md`、リポジトリの制約を優先する。 - 確認の重さはタスクに合わせる。説明にはコード上の根拠、挙動の変更には動かしての確認、typo修正には該当文書と差分の確認で足りる。 - 検証ツールの作成、feature map の整備、skillの評価は、必要な場面でだけ行う条件付きの作業であり、毎回の前提ではない。 - 根本原因の修正、既存コードと公式文書を判断根拠にすること、制約を独断で緩めないことは `git-development-rules` に従う。ここでは繰り返さない。 ## 証拠で主張を裏付ける - 原因を述べる前に、該当する実装を読み、関係する呼び出しやデータの流れを追う。根拠にしたコードと観測を示し、試していない説明は仮説と明記する。 - 不具合は、修正前に報告どおりの挙動を再現し、修正後に同じ手順を繰り返す。再現できない場合は、足りないアクセス、入力、環境と、残る不確実性を報告する。 - ユーザーが実際に使うインターフェース（UI、API、CLI、デバイス上の操作）を動かす。ビルドや型チェックが通っても、実行時の挙動が正しいことにはならない。 - 証拠の種類を主張に合わせる。見た目はスクリーンショットで示せるが、操作の主張には実際に操作した手順が要る。性能の主張には、比較可能な計測、トレース、プロファイルが要る。 - 正しく動くことと、保守しやすく効率的な実装であることは別に確認する。 ## 検証を再現できる形にする - リポジトリにある実際のセットアップ、起動、テスト、診断の手段を探して使う。検証コマンドを推測で作らない。 - feature map（ユーザーから見える機能と、入口、前提条件、操作手順、関連コード、期待結果の対応表）があれば参照し、該当する記述を動いているアプリで確かめる。 - エージェントが同じ機能で繰り返し迷うなら、実際に確認できた到達手順を既存のプロジェクト文書に書き足す。小さな修正のためにアプリ全体を地図化しない。 - 繰り返す手作業の確認は、タスクに見合う場合に再利用できる手順にする。セットアップ、入力、期待結果、証拠の置き場所、後片付けを記録し、製品が変わったら手順も更新する。 - 検証ツールを新しく作るときは、まずローカルなど観察できる環境で動かし、動作と失敗を確かめてから無人で使う。 ## コードベースと履歴を記憶として扱う エージェントは見つけた例から学ぶ。今日の近道は明日の慣習になる。 - 実装前に、近くのコードと文書化された規約を読む。パターンの理由がわからないときは履歴を調べる。 - パターンを真似る前に、それが今も正しいかを確かめる。多く使われていることは正しさの根拠にならない。 - やむを得ず回避策を入れるときは、その限界と取り除く条件を書く。 - 作業で入れた一時的な足場は取り除く。自明でない制約の説明は残すが、一度きりのレビュー指摘を恒久的なコメントや汎用ルールにしない。 ## 同じ指摘を仕組みで防ぐ 同じ誤りが再発しうるなら、それを許している環境を改善する。 設計で防ぐ、型・lint・CIで検出する、ルールに書く、skillにする、のうち最小で効く手段を選ぶ。 推奨される実装経路（正規のヘルパーやモジュール）を健全に保ち、競合する実装を増やさない。 判断基準と手順は [references/durable-constraints.md](references/durable-constraints.md) を参照する。 タスクの範囲を超える設計変更は、範囲を区切った後続作業として提案する。 ## レビューできる形で渡す - 自明でないタスクでは、問題、重要な前提、成功を示す観測を最初に述べる。依頼に含まれる定型的な判断は確認せずに進める。 - 重要な判断は、関係するコードと観測した挙動を使って説明する。レビューする人がセッションを再構成しなくても判断できるだけの文脈を渡す。 - 独立した変更は分けておく。コミットやPRには、挙動をなぜ変えたかを書き、調査や差し戻しに使える履歴にする。 - コード量やPR数ではなく、レビュー済みで動く成果を目指す。 ## 条件付きの作業 - 作業を他のエージェントに委任する、または並列に進めるときは [references/delegation.md](references/delegation.md) を参照する。 - エージェント向けの指示、skill、検証手順を作成または変更するときは [references/evaluating-instructions.md](references/evaluating-instructions.md) を参照する。 - 典型的な失敗と期待する振る舞いは [references/examples.md](references/examples.md) にある。評価ケースとしても使える。 ## 完了報告 結果、実際に行った確認、参照できる証拠、残る制約を、タスクに見合う長さで報告する。 観測した結果と仮説を区別し、委任先が報告した結果と自分で確認した結果を区別する。 英語版は [SKILL.en.md](SKILL.en.md) を参照する。