AI駆動開発におけるハーネスエンジニアリングの勘所

1. AI駆動開発における ハーネスエンジニアリングの勘所 クラウド事業統括本部プロフェッショナルサービス事業本部 コンサルティング1部モダンアプリコンサルチーム つくぼし
2. ⾃⼰紹介 職種歴： 1. インフラエンジニア：3年 2. クラウドエンジニア：3.5年 3. バックエンドエンジニア：2年 • 部署 ◦ クラウド事業本部 ◦ モダンアプリコンサルタント • ニックネーム ◦ • 今まで推していたAWSサービス ◦ • つくぼし AWS App Runner SNS/ブログ ◦ X(@tsukuboshi0755) ◦ DevelopersIO(つくぼし) 2
3. はじめに みなさんはClaude Codeに同じ注意を何回してますか？ 3
4. 今⽇話したい事 リンター‧テスト‧レビューの3つの観点で、 AIがミスした箇所を⼆度と繰り返させない「仕組み」に変える勘所 4
5. 注意事項 今回は私⾃⾝の開発経験に基づくハーネスエンジニアリング⼿法が 含まれているため、今回の資料だけが正解とは限りません。 ぜひ皆さんのハーネスエンジニアリング⼿法も教えてください。 5
6. 対象者 • Claude Codeなどで、AI駆動開発を始めたばかりの⽅ • CLAUDE.mdに書いたルールが守られなくてモヤモヤしてい る⽅ • AIが書いたコードのテストやレビューをどこまでやるか迷っ ている⽅ 6
7. ⽬次 1. プロンプトを短くする代わりにリンターを設定しよう 2. テストの作成をAIに任せる前に要件を洗い出そう 3. コードレビューは観点ごとの別エージェントに分けよう 4. まとめ 7
8. プロンプトを短くする代わりに リンターを設定しよう 8
9. CLAUDE.mdやAGENTS.mdに 「〇〇必須」「〇〇禁⽌」って書いてませんかね？ 9
10. AIの弱点 • どんなに精度の良いAIでも、どうしても出⼒結果にブレが出 る • コンテキストが⻑くなると、指⽰を無視する場⾯が出てくる • Claude Codeの公式も、コンテキストは「厳密に守られる保 証はない」と明記している →実⾏結果を100%保証するわけではないので別の⼿段が必要 10
11. リンターのススメ • 何回実⾏しても全く同じ実⾏結果が返る ◦ これはAIエージェントでは実現できない • 実⾏するまでコンテキストを消費しない ◦ その分CLAUDE.mdやAGENTS.mdの記述量を削れる • ルールを増やしても検出漏れが起きない ◦ AIは指⽰が増えると守らなくなりがち →AIと組み合わせる事で、⾃律的にリンターを回せる 11
12. AIとリンターは相性が良い 完了 エラーなし AIがコードを編集 hookで リンターを実⾏ エラー⽂ （直し⽅つき） 通るまでループさせる AIが読んで直す 12
13. リンターのポイント①：実⾏速度の早いリンターを優先しよう • AIは編集のたびにリンターを回すので、待ち時間が積み重な る • ⾃動実⾏するなら速さが⽋かせない • Rust製のリンターは既存のものより桁違いに速いので積極的 に採⽤するべき ◦ Oxlint: ESLintの50〜100倍と⾔われる ◦ Ruff: Flake8の10〜100倍と⾔われる 13
14. リンターのポイント②：できる限り厳しい標準ルールを設定しよう • ⼈間には細かすぎるルールも、AIは嫌がらずに直してくれる • 新規リポジトリではリンターを初期設定のまま使わず、拡張 含めて⼀旦全部採⽤したい ◦ Oxlint: -D allで全カテゴリを有効にできる ◦ Ruff: select = ["ALL"]で全ルールを有効にできる • 開発を進める中で、リポジトリに合わないルールを個別に外 す運⽤をすると良い 14
15. リンターのポイント③：カスタムルールを作りこむとなお良し • プロジェクトや業務固有の約束事はカスタムルールに切り出せるとさ らにコードの品質が上がる ◦ 例: ast-grepなら、多⾔語対応かつYAMLで構⽂パターンを書くだけ • 正解はないがアンチパターンがあるものも、warningにすればAIにト ライ&エラーを促せる • カスタムルール⾃体もコードベースや過去の会話履歴を読み取らせて AIに書かせれば作成も簡単 15
16. 補⾜：textlintでドキュメントも整形できる • コードだけでなく、AIが書く⽂章にもリンターをかけられる ◦ 例：README、CLAUDE.md、設計書、PRの説明 • 表記ゆれは辞書（prh）で統⼀できる ◦ 例：「サーバ」「サーバー」が混ざっていたら「サー バー」に⾃動で揃える • 独⾃の⾔い回しはカスタムルールの⾃作で対応できる →最近話題の「AI臭い⽂章」対策にもオススメ 16
17. 「〇〇をして欲しい」ならプロンプト 「〇〇をしろ/するな」ならリンターで設定する 17
18. テストの作成をAIに任せる前に 要件を洗い出そう 18
19. 要件を洗い出さずに AIに本番アプリを作らせてませんかね？ 19
20. 要件なしのテスト実⾏は、模範解答なしの試験採点と同じです • 要件がないと、AIは今の実装を模範解答(100点)としてテス トを書いてしまう • テストを通すために、AIがテスト側を書き換えることもある →要件があれば、実装とテストのどちらが間違いかを判断でき る 20
21. 要件ドキュメントがない場合とある場合の違い 要件なし 要件あり 要件定義書なし 要件定義書（受け⼊れ基準）＝模範解答 正解を確認 何が正解？ 要件を 知らない⼈ テストコード 検証？ 要件を 知らない⼈ 本体コード テストコード 検証 本体コード 21
22. 要件ドキュメントのポイント①：最初は核となる要件だけ洗い出そう • 最初は壊れたらユーザー信⽤に直結する⼤事な要件だけ洗い出す ◦ 例：業務アプリなら、ログイン‧データ登録‧承認‧閲覧権限 • 要件ドキュメントは⼈間がレビューできる量に保つ ◦ あまり量を増やしすぎるとレビューされないので注意 • 細かい要件は、機能1つ分の要件→テスト→実装→レビューを1周とし て徐々に⾜していく 22
23. 要件ドキュメントのポイント②：EARS記法で要件の曖昧さを排除しよう 要件ID 型 条件（〜のとき） システムの振る舞い REQ-001 状態駆動 カートが空のとき 購入ボタンを無効にする REQ-002 イベント駆動 商品が追加されたとき カートの合計金額を更新する REQ-003 状態駆動 在庫が0のとき カート追加ボタンを無効にする REQ-004 イベント駆動 購入ボタンが押されたとき 注文確定画面を表示する REQ-005 イベント駆動 決済が完了したとき 確認メールを送信する →条件と振る舞いが分かれるので、そのまま検証しやすい 23
24. 要件ドキュメントのポイント③：要件をテストで守らせよう • まずは⾃動化しやすい単体‧結合テストで守れないかを考える ◦ 例: REQ-001の「カートが空なら購⼊ボタンを無効」は単体で 書ける • 核となる要件はE2Eで導線ごと守る ◦ 例: REQ-004の購⼊から注⽂確定画⾯までの流れ • ⾃動化しにくい要件も、⼿順と期待結果を要件IDと⼀緒に残す ◦ 例: REQ-005の確認メール。⼿順があればAIにブラウザ操作を 代⾏させられる 24
25. 要件ドキュメントのポイント④：トレーサビリティマトリクスでテスト漏れを防ごう 要件ID 要件（EARS記法） テストID 種別 状態 REQ-001 カートが空のとき、システムは購入ボタンを無効にす る UT-001 単体 通過 REQ-002 商品が追加されたとき、システムはカートの合計金額 を更新する UT-002 IT-001 単体・結合 通過 REQ-003 在庫が0のとき、システムはカート追加ボタンを無効に ― する ― テストなし REQ-004 購入ボタンが押されたとき、システムは注文確定画面 を表示する E2E-001 E2E 通過 REQ-005 決済が完了したとき、システムは確認メールを送信す る MT-001 手動 未実施 →要件とテストを対応づければ、REQ-003のようなテスト漏れが⼀⽬で分かる 25
26. 補⾜：要件なしでいきなりモックから作り始めるのは本当にダメなのか？ • 結論からいうと、指⽰者が異常系テストの作り⽅を分かっていれば、い きなり作ったモックを本番化してもある程度の品質は保てる • AIは正常系テストを作るのは得意だが、異常系テストを作るのは苦⼿ ◦ 異常系テストが不⾜していると本番障害につながる事があるが、も し指⽰者側でここをカバーできるなら品質が⼤きく上がる • ただしどこに何の異常系テストを作るかの知識は、どうしても開発経験 の量に左右される ◦ もし開発経験が不⾜している場合、モックを本番化しようとするな らまずは要件洗い出しから始めてください 26
27. 最初に軽量版の要件ドキュメントを作る事 そこからテストコードと本体コードを⽣成して育てる 27
28. コードレビューは観点ごとの 別エージェントに分けよう 28
29. コードを書いたAIにそのまま レビューまで頼んでませんかね？ 29
30. 実⾏役とレビュー役は別エージェントに分けたい • LLMは⾃分の出⼒をひいきする ◦ 別エージェントに分けると実装の経緯を知らないので、書 いた本⼈の思い込みに引きずられない • ⾃⼰評価は⽢くなるので、別の評価役を厳しくする⽅が簡単 • Claude Code公式も、書く役とレビュー役の分業を勧めてい る 30
31. 観点ごとのエージェントで並列にレビューする 独⽴したコンテキスト 独⽴したコンテキスト 差分と観点だけ渡す メインセッション （実⾏役） エージェントA /code-review（バグ‧品質） 要約だけ返す 独⽴したコンテキスト 指摘をまとめて修正 差分と観点だけ渡す エージェントB /security-review（セキュリティ） 要約だけ返す 31
32. レビューのポイント①：サブエージェントまたはツール単位で分けよう • 観点ごとにサブエージェントを分けると、コンテキストが独⽴するの で思い込みに引きずられない ◦ 例：品質は/code-review、セキュリティは/security-review • 別のエージェントツールに⾒せれば、モデルの癖ごと⼊れ替えられる ◦ 例：Claude Codeで書いて、Codexでレビューする • PRに常駐して⾃動でレビューするツールもオススメ ◦ 例：GitHub Copilot 32
33. レビューのポイント②：レビュー中にリンターとテストをhookで通そう • リンターやテストで分かる指摘に、レビューを使わない事 • 編集のたびにリンター、ターンの終わりにテストをhookで 回す ◦ Stopのhookでテストを回せば、通るまでAIは作業を終え られない • レビュー指摘を直すときも、同じチェックが毎回かかる 33
34. レビューのポイント③：判定基準と証拠を渡してレビューさせよう • 「レビューして」ではなく、何に対して何を指摘するかを渡す ◦ 例: 要件定義書の受け⼊れ基準に対して、満たす∕満たさないを判 定して • 指摘と合否には証拠を付けさせる ◦ 例: 該当⾏の引⽤、テスト出⼒、実際に動かしたスクショ • 重⼤度に閾値を決め、全部は直さない ◦ 例: /code-review lowは確信度の⾼い指摘だけ 34
35. 補⾜：AI駆動開発⾃体に⼈間は何をレビューすべきか？ • 要件そのものが正しいか ◦ 要件が正しいかは⼈間にしか分からない • ハーネスエンジニアリング⾃体の設計が妥当か ◦ ITのベストプラクティスはもちろん、組織や業務の暗黙の事情を取り⼊ れられているかも⼤事 • 今回採⽤したアーキテクチャのメリット‧デメリットを説明できそうか ◦ 今後コードを書ける必要はないが、アーキテクチャの「理解負債」を作 らないためにエンジニアリングの知識が必要になる 35
36. レビュー中にリンターとテストをhookで通し、 観点ごとにエージェントを分ける 36
37. まとめ 37
38. 結論 • 「〇〇をして欲しい」ならプロンプト、「〇〇をしろ/する な」ならリンターで設定する • 最初に軽量版の要件ドキュメントを作る事、そこからテスト コードと本体コードを⽣成して育てる • レビュー中にリンターとテストをhookで通し、観点ごとに エージェントを分ける 38
39. 次AIにこのように指⽰してみよう 今のコードベースや過去の 会話履歴を踏まえて、 リンター‧テスト‧ レビューの設定を 改善できませんか？ 39
40. アンケートにご協⼒お願いします！ DevIO Passから回答が可能です
42. Appendix：本資料におけるハーネスエンジニアリングの定義 • AIがミスをしたら、⼆度と同じミスをしない仕組みを作るこ と • エージェント = モデル + ハーネス ◦ ハーネスはモデルの周りにある指⽰‧ツール‧チェック の全部 • 2026年2⽉にMitchell Hashimotoが提唱した ◦ https://mitchellh.com/writing/my-ai-adoption-journey 42