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