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