AI を思い通りに制御するための3層のハーネス

Transcript

1. AI を思い通りに 制御するための 3 層のハーネスの作り方 AI が迷うことを減らし、短い距離で正解へ導くための設計 株式会社スマレジ わたり @rapicro
2. わたり @rapicro • 株式会社スマレジ ◦ • • 開発本部プロダクト推進チーム ◦ 現在はPOSシステム開発中心 活動 ◦ PHPカンファレンス関西コアスタッフ他 趣味 ◦ ゲーム全般 ◦ 甘い物 ◦ カメラ ◦ ガチャガチャ
3. 目次 01 解決したい課題と基本方針 02 3 層のハーネスの全体像 03 物理層：コードそのもの 04 運用層：AI エージェント 05 ガバナンス層：人による評価と改善 06 現場導入へのステップ
4. 結論 ループを支えるのは、 3 層の「ハーネス」 物理層 × 運用層 × ガバナンス層 ループが大きく回るほど、AI の迷いも増幅される。 鍵は指示の量ではなく、コード・AI・人の 3 層への情報配置。
5. ループを回し始めて、実際に起きたこと 01 ループが空回りし、AI が正解へたどり着かない 02 ベテランがやると動くが他のメンバーがやるとうまくできない 03 メンバー間の格差は広がるが埋め方がわからない
6. 基本方針：余計なことは書かない AI に期待通りのコードを出させる前提は、迷わせないこと 良かれと思って足した指示が、別の場面で挙動を狂わせることがある 指示の「量」より適切な「場所と責務」
7. 3層のハーネスで制御する AI の制御は指示や設定だけではなく、レイヤーごとに責務を分ける。 1 2 3 物理層 運用層 ガバナンス層 コードそのもの ドメインモデル クラス構造 コメント → AI エージェント AGENTS.md Skills ループ → 人による評価 /調整 レビュー 他の層の改善
8. 物理層 コードそのもの
9. 物理層 コードそのもの ✓ 回避されづらい基本的なハーネス ✓ AI エージェントの種類に左右されない ✓ 作業箇所に最も近い ✓ 関連しない作業のコンテキストを汚染しない
10. 物理層 物理層で目指す状態 Project as Code: コードを「仕様」に近づける ドメインモデルの強化 AIが関連ファイルを探索しなくても、コード構造や周辺コメントから仕様が自明な状態を作る 判断の理由となる 1次情報を記載する コメントで外部API仕様書へのリンクを記載するなど、設計の「なぜ」を記載し逸脱を防ぐ 仕様が先にあり、それをコードに反映する ※「今動いているものを仕様とみなす」のではない
11. 物理層 技術的負債への向き合い方 負債はAIの「視界」を曇らせる レガシーなコードはAIにとって 「誤ったコンテキスト 」として作用する。 利用拡大を避けたいなら「Deprecated: 非推奨」の記載や To-Beの記載によって正しい方向を示す。 AIは負債も増幅するが、方向性があれば改善する。
12. 運用層 AI エージェント
13. 運用層 AI エージェント制御 コードだけで表現しづらいものを扱うレイヤー。 ただし、コンテキストを汚染しないように適切な場所へ隔離する。 ※下記名称は Codex / Claude Code の例だが、多くのエージェントに相当機能がある。 AGENTS.md: ディレクトリごとの役割 オーケストレーション : 役割毎の分担処理 Skills: 構造を超えた指示 hooks: 実行前後のガードレール
14. 運用層 場所と責務を押さえてコンテキストを抑える 「本当」を増やすより「嘘」を減らす コンテキストは増えると薄まる AIにコンテキストを渡せたからといってそれらを全て守ってくれるわけではない AIに任せると量だけが増える AIが分かっていることを書かせると、なくてもAIが分かる情報だけが増えやすい 1行の嘘は千行の嘘になる 間違った1行を前提にAIは千行のコードを生成し、間違いが増幅される
15. 運用層 AGENTS.md の配置例 グローバル（ホームディレクトリ） 個人PC内全体 ~/.codex/AGENTS.md リポジトリルート 共通ルール・共有資産 /AGENTS.md サブディレクトリ 近い指示・汚染を防ぐ /xxx/AGENTS.md チーム共通ルールはリポジトリ内に置いて資産化。
16. 運用層 Skills AGENTS.md だけでは扱いにくい、動的な判断やまとまった手順を切り出す。 明示的に呼び出すスキル 暗黙的に呼び出すスキル まとまった作業手順として使う タスク内容から必要性を判断する 例：レビュースキル ・ブランチ名から Issue を取得する ・仕様と実装が合っているか確認する ・レビュー観点に沿って指摘を出す 用途 ・AGENTS.md では粒度が合わないもの ・特定の作業種別でだけ効かせたいもの ・共通化したいが常時適用したくないもの 例: DDDで同様の構成が並列で存在する場合に有用 暗黙呼び出しを切ることで、呼び出し時以外はコンテキス トに関与しない 段階的開示とはいえ、 関係ない作業でも常にコンテキス トを食う ので用途を絞る
17. 運用層 hooks AI に「守ってほしい」と頼むのではなく、実行前後に決定的な処理を差し込む仕組み。 実行前 PreToolUse 例: 危険なコマンドを検査する 実行後 PostToolUse 例: 変更後のファイルチェックを走らせる 完了前 Stop 例: 応答完了時に全体にカスタムバリデーションを実行する
18. 運用層 オーケストレーション機構 /goalコマンド、 TAKTなど 検証と修正の自律サイクルにより、大規模開発でも設計の一貫性と品質を担保する仕組み ループ終了の目印となるゴールの設計やハーネスが重要 AIが自律的に大きく動くことで良いところも悪いところも増幅される AGENTS.mdやSkillsなどの土台を作り出力を安定化することが必要
19. ガバナンス層 人による評価と改善
20. ガバナンス層 人による評価と改善 オーケストレーションを実行して終わりではない。最終的な品質保証は人が行う。 1 実際の出力を評価し、設計意図とズレていないか見る ↓ 2 期待とズレた理由を分析する ↓ 3 設計、指示・ハーネスのどの部分かなど、どこでどう制御すべきか見直す
21. 実際にあった失敗例 あるメンバーが内容的には xxx/service を修正してほしい状況で、 AI が xxx/templates を変更してその場しのぎの対応をした。 ▼ 修正し、対策として「再発防止して」とAIに指示。 AIがホームディレクトリのスキルに「xxx/service を優先的に変更する」と書いた。 ▼ 次のタスクでは、要件は満たすもののコード配置がおかしい変更が発生。 レビューにより「AIの指示がおかしいのでは？」とホームディレクトリのスキルが発覚。
22. 実例 この失敗に、 3層でどう対処したか 発見はレビューから。対処を適切な層へ配置した。 1 ガバナンス層（人）： レビューで「コードの配置がおかしい」と気づき、原因がホーム ディレクトリの指示だと特定した ↓ 2 運用層（AI エージェント）： ディレクトリの AGENTS.md に責務を記載し、個人環境で はなくリポジトリ内で共有する形にした ↓ 3 物理層（コード）： その場しのぎの変更を、ドメインモデルを意識した形のコードへ修 正（この層の対処は最小限で済んだ）
23. ガバナンス層 メンバーの技術力向上 スキル格差も「増幅」される。見る対象を「 AIの使い方」へ変え、チームで共有する。 レビュー 細かいアルゴリズムより、設計と指示をみる ソフトウェアチーミング（モブプロ） リーダーやメンバーも含め互いのAIの使い方 を見せ合う 輪読会 本や記事をきっかけに共通認識を作り方向性を統一する
24. まとめ： 3 層の使い分け レイヤー 役割 例 物理層（コード） 仕様をコードに埋め込む ドメインモデル、責務分離、 Deprecated 運用層 （AIエージェント） AI へ作業ルールを渡す AGENTS.md、Skills、 hooks、オーケストレーション ガバナンス層（人） 出力を評価し調整する レビュー、評価ループ AI制御とは、指示を増やすことではなく、情報を適切な層へ配置すること
25. Takeaway AIを制御するとは、 指示を増やすことではない。 AI が迷わず正しい判断へ進めるように、 情報を適切なレイヤーへ配置することである。
26. 【非公式】 AI DevEx Conference 2026 スマレジセッション 深掘り会 We are Hiring! メンバー募集中！ カジュアル面談も大歓迎 詳細はQRコードから！ 2026年8月26日(水) 19:00~ ※オンライン ご清聴ありがとうございました Thank you for your attention