AIに既存システムを理解させる技術 ～レガシーを見捨てないハーネスエンジニアリング入門～

生成AIによる開発支援が広がる一方で、実務の現場には「古い構成」「巨大なソース」「散らばった設定ファイル」「暗黙知だらけの業務ロジック」を抱えた既存システムが多く残っています。

そうしたレガシーシステムを無理に作り直すのではなく、AIが安全に理解・変更・検証できる状態へ整えるための ハーネスエンジニアリング を紹介します。
C#バックエンド、HTML/CSS/JavaScriptフロント、XML/JSON/config設定ファイル、MVC構成の既存システムを例に、AGENTS.md、DESIGN.md、ARCHITECTURE.md、CODING_RULES.md、機能対応表、依存関係図、設定キー一覧、変更パターン集をどう用意するかを整理します。 AIに「全部読ませる」のではなく、AIが迷わないための地図を作る。 レガシーを捨てる前に、AIと一緒に保守できる形へ変えていくための実践的な考え方を共有します。

Transcript

1. HARNESS ENGINEERING AIに既存システムを理解させる技術：レガシーを見捨てないハーネ スエンジニアリング入門 AI導入ではコード生成力より再現可能な 開発環境が要る 巨大なコードベースと散在する設定 暗黙知と再現不能な検証手順 地図 既存MVC 検証 C# / View / JS / config 境界 AI導入ではコード生成力より再現可能な開発環境が要る HARNESS ENGINEERING 1
2. PROFILE 自己紹介 ちなみにゲームのハンドルネームです Ochtum（オクトゥム） 猫とゲームを愛するエンジニアです。IT関連の情報発信と、 ゲームや日常をポストしています。よかったらフォローしてくださ い!! X ochtum18 Qiita ochtum GitHub ochtum Speaker Deck ochtum PrairieCards ochtum PROFILE SNS・プロフィール 2
3. INTRO 今日の到達点 保守担当者は30分後にGitHub Copilotへ安 全な一件目を任せる準備を説明できる 残す地図 地図：必要な証拠への入口 / 道具：再現できる実行と検 証 / 機能対応表の1行 任せる条件 地図：必要な証拠への入口 検証コマンドと完了条件 道具：再現できる実行と検証 保守担当者は30分後にGitHub Copilotへ安全な一件目を任せる準備を説明できる INTRO 3
4. SESSION 30分の道筋 保守担当者は判断材料から継続保守までの六 段階をたどる 中央例 既存システム P.5– 判断材料 7 コード外に散らばる 理由 P.8– ハーネス 13 役割・失敗・環境・ 安全 P.14– 知識経路 20 入口から正本と証 拠へ P.21– 変更地図 26 MVC一件の安全 な変更経路 P.27– 継続保守 27 仕組みに戻る完了 条件 P.28– 明日の一件 28 小さな変更からの 開始 判断材料 → ハーネス → 知識経路 変更地図 → 継続保守 → 明日の一件 到着点: 安全な一件目 保守担当者は判断材料から継続保守までの六段階をたどる SESSION 4
5. 判断材料 まず結論：AIに渡すべきなのはコードだけではない 入力 目的・対象・完了条件 保守担当者はコード以外の判断材料をGitHub Copilotへ渡す 01 目的・対象・完了条件 03 02 → 実行手順・制約・承認 → 保守担当者はコード以 境界 外の判断材料を GitHub Copilotへ渡す 出力 保守担当者はコード以外の判断材料をGitHub Copilotへ渡す 保守担当者はコード以外の判断材料をGitHub Copilotへ渡す 判断材料 5
6. 判断材料 1. なぜ既存システムへのAI導入は難しいのか 保守担当者は影響確認の起点をGitHub Copilotへ示す AIによる変更時に確認する影響範囲 「変更する場所」ではなく「影響の有無を確認する場所」をたどれるようにする Controller / API 入力 View / 画⾯ URL・リクエスト 表⽰・⼊⼒・権限差 業務処理 既存の責務・規則 中央例：商品一覧の在庫状態追加 変更依頼 判断 JavaScript / CSS UI動作・⾒た⽬ Viewからログまでの影響確認 中央例：商品一覧の在庫状態追加 Viewからログまでの影響確認 ⼀覧に項⽬を追加 変更前に影響の有無を確認 config 定義・使⽤箇所・環境差分 データアクセス DB・外部連携 テスト・ログ 認証・権限 動作と結果を検証 承認が必要な操作 ⽮印は「変更する」ではなく「影響の有無を確認する」を表す 保守担当者は影響確認の起点をGitHub Copilotへ示す 判断材料 6
7. 判断材料 AIが読めない知識は、作業の判断材料にならない 入力 リポジトリ外の知識は実行中に参照不能 保守担当者は暗黙知をリポジトリの判断材料へ 変える 01 02 03 保守担当者は暗黙知を リポジトリ外の知識は実 → 小さく頻繁で検証しやす → リポジトリの判断材料へ 行中に参照不能 い機能から開始 変える 出力 保守担当者は暗黙知をリポジトリの判断材料へ変える 保守担当者は暗黙知をリポジトリの判断材料へ変える 判断材料 7
8. ハーネス 2. ハーネスエンジニアリングとは何か チームは人間とGitHub Copilotの担当境界を 決める ハーネスは、失敗を次の成功率へ変える ⼈間とAIの分担を、検証と継続改善のループでつなぐ 入力 人間：意図・制約・承認 判断 ⼈間 AIエージェント 検証結果 ⽬的・優先順位 調査・影響確認・実装 期待どおり動くか 失敗を分類 仕様 受け⼊れ条件・制約 テスト・レビュー・修正 テスト・ログ・画⾯を確認 知識・テスト 承認が必要な判断 結果を報告 不⾜を発⾒ ツール・権限 チームは人間とGitHub Copilotの担当境界を決める 人間：意図・制約・承認 Copilot：調査・実装・検証・報告 ハーネスへ反映 受け⼊れ条件 / ドキュメント / テスト / 実⾏ツール / 権限 / 運⽤ルール 次回のAI作業が、より安全で再現可能になる チームは人間とGitHub Copilotの担当境界を決める ハーネス 8
9. ハーネス 失敗を5種類に分類して、仕組みへ戻す チームはAIの失敗を五つの改善先へ戻す 仕様・知識・テスト ツール・権限 失敗 典型例 改善先 仕様不足 異常系がない 完了条件 知識不足 設定を発見できない 機能・設定地図 テスト不足 UI崩れを検出不能 回帰・E2E ツール不足 起動を再現不能 スクリプト・モック 権限不足 本番判断が不能 承認境界 チームはAIの失敗を五つの改善先へ戻す ハーネス 9
10. ハーネス Tips：受け入れ条件は、AIに任せる前の安全装置です 保守担当者は受け入れ条件をGitHub Copilotの安全装置にする task.md text 目的: 商品一覧へ在庫状態を表示 対象: /products と関連 ViewModel 受け入れ条件: 権限別表示と回帰 テスト 非対象: 在庫更新処理 検証: build / test / 画面確 認 判断の保留: 本番設定は人間が承 認 目的・対象・非対象・制約 注目 受け入れ条件 / 非対象 / 判断の保留 守る条件 正常系・異常系・権限別の検証 正常系・異常系・権限別の検証 保守担当者は受け入れ条件をGitHub Copilotの安全装置にする ハーネス 10
11. ハーネス 再現可能な開発・検証環境を用意する 入力 バージョン・初期化・起動・テスト チームは人間とGitHub Copilotが再現できる開 発環境を用意する 01 02 03 チームは人間とGitHub バージョン・初期化・起 → モック・秘密情報・分離 → Copilotが再現できる開 動・テスト 環境 発環境を用意する 出力 チームは人間とGitHub Copilotが再現できる開発環境を用意する チームは人間とGitHub Copilotが再現できる開発環境を用意する ハーネス 11
12. ハーネス テストハーネスと観測可能性を「実装の外」に置かない チームは実行結果を機械判定できる証拠として 残す ログ・メトリクス・画像・再現手順 確認対象 用意する証拠 正しさ 単体・結合・E2E・回帰 外部依存 テストデータ・モック・スタブ 品質 build・lint・脆弱性・schema 実行結果 ログ・画像・動画・再現手順 チームは実行結果を機械判定できる証拠として残す ハーネス 12
13. ハーネス 権限・安全性・レビューを設計する チームは本番影響のある操作を人間の承認へ戻 す 自動でよい 人間へ戻す 調査・参照検索 本番・削除・課金 build・test・lint 権限・認証・DB 差分と結果の報告 互換性とrollback 秘密情報・削除・課金・権限変更 PR・レビュー・エスカレーション 共通の判断軸 本番影響と不可逆性 チームは本番影響のある操作を人間の承認へ戻す ハーネス 13
14. 知識経路 3. AIが理解できないものを明文化する 保守担当者はAGENTS.mdから役割別の正本 へ知識経路をつなぐ AIが必要な資料をたどる知識ベース AGENTS.mdを巨⼤な⼿引きにせず、⽬的別の正本へ案内する 入力 AGENTS.md（⼊⼝） 読む順番・禁⽌事項・必須検証・リンク 短い入口：AGENTS.md 判断 詳細の正本：設計・規約・機能・検証 短い入口：AGENTS.md 詳細の正本：設計・規約・機能・検証 ARCHITECTURE.md CODING_RULES.md DESIGN.md 構成・責務・依存⽅向 C# / View / JS / CSS / config の規約 UIルール・トークン・アクセシビリティ 05_feature_map.md 06_config_map.md 12_build_test_run.md 画⾯・実装・設定・テストの対応 設定キー・使⽤箇所・環境差分 起動・テスト・確認⼿順 必要な情報を、必要な時に、リポジトリ内で⾒つけられる状態にする 保守担当者はAGENTS.mdから役割別の正本へ知識経路をつなぐ 知識経路 14
15. 知識経路 4つの代表ドキュメントを分けて管理する 保守担当者は四つの正本を役割ごとに分ける AGENTS.md・ARCHITECTURE.md CODING_RULES.md・DESIGN.md 正本 記載すること 混ぜないこと AGENTS.md 読む順・禁止・検証 全設計本文 ARCHITECTURE.md 現行構成・依存 UI仕様 CODING_RULES.md 言語別の実装判断 全体依存図 DESIGN.md UIトークン・部品 MVC責務 保守担当者は四つの正本を役割ごとに分ける 知識経路 15
16. 知識経路 AGENTS.mdの最小構成例 保守担当者はAGENTS.mdを短い目次として保 つ AGENTS.md MD # AGENTS.md ## 読む順番 1. 00_system_overview.md 2. ARCHITECTURE.md 3. 05_feature_map.md 4. 12_build_test_run.md ## 禁止 - 公開APIの無断変更 - 秘密情報の出力 最初に読む資料の順序 注目 最初に読む資料 / 変更時の基本ルール / 行ってはいけないこと 守る条件 基本ルール・禁止事項・必須検証 基本ルール・禁止事項・必須検証 保守担当者はAGENTS.mdを短い目次として保つ 知識経路 16
17. 知識経路 DESIGN.mdはアーキテクチャ資料と分ける 保守担当者はUI規則と依存規則を別々の正 本へ分ける DESIGN.md ARCHITECTURE.md 色・文字・余白 Controllerの責務 UI部品とa11y 許可する依存方向 JSフックとDo/Don't データ境界 DESIGN.md：UIトークンと利用文脈 ARCHITECTURE.md：責務と依存方向 共通の判断軸 正本ごとに変更責任を一つにする 保守担当者はUI規則と依存規則を別々の正本へ分ける 知識経路 17
18. 知識経路 システム理解に必要な資料を揃える 保守担当者は変更判断に必要な資料を索引 化する パス 00_system_overvie w.md 03_folder_structu re.md 05_feature_map.md 06_config_map.md 08_auth_and_secur ity.md 09_error_logging. md 目的・利用者・非対象 型・使用箇所・環境差 機能・設定・データ・権限の地図 実行・外部連携・注意点の地図 役割と読む理由 12_build_test_run .md 起動・検証 パスの責務 role別の許可 画面・実装・設定・test logと禁止情報 14_known_pitfalls .md 消せない契約 保守担当者は変更判断に必要な資料を索引化する 知識経路 18
19. 知識経路 コーディング規約・変更パターン・既知の注意点を実装に結 び付ける 保守担当者は変更パターンを実在する実装先へ 結び付ける 01 02 03 04 一覧項目 入力項目 バリデーション 設定値 担当: Copilot 担当: Copilot 担当: Copilot Modelから View・testまで確 認 検証・DB・権限 まで確認 正常・異常系を 検証 担当: 人＋ Copilot 環境差・ rollback・監視を 確認 一覧・入力・検証・設定の四パターン 既知の注意点と削除禁止の契約 保守担当者は変更パターンを実在する実装先へ結び付ける 知識経路 19
20. 知識経路 大規模リポジトリでは、文脈を選別する 入力 全読込ではなく機能単位の証拠 保守担当者は巨大リポジトリから変更に必要な 証拠を選別する 01 02 03 保守担当者は巨大リポ 全読込ではなく機能単 → 生成物の除外と依存グ → ジトリから変更に必要な 位の証拠 ラフの活用 証拠を選別する 出力 保守担当者は巨大リポジトリから変更に必要な証拠を選別する 保守担当者は巨大リポジトリから変更に必要な証拠を選別する 知識経路 20
21. 変更地図 4. MVCシステムで構造資料と変更パターンを用意する 保守担当者は現行MVCの依存方向を変更地 図へ記録する 変更を機能単位でたどる：商品⼀覧に在庫状態を追加 実在する構成だけを対応表に記載し、影響の有無を確認する 入力 商品⼀覧：在庫状態を追加 存在する層だけを記録 JavaScript API / DOM / 初期化 View ⼀覧表⽰・⼊⼒ CSS トークン・表⽰状態 判断 商品一覧の変更確認マップ 存在する層だけを記録 ViewModel Controller 業務処理 データアクセス 表⽰⽤データ リクエスト・応答 既存の責務・規則 DB・外部連携 商品一覧の変更確認マップ 設定（必要な場合） テスト・動作確認 モデル 定義・使⽤箇所・環境差分 画⾯・API・権限・ログ 在庫状態のデータ ※ Service / Repository などの層は、対象システムに実在する場合だけ確認対象にする 保守担当者は現行MVCの依存方向を変更地図へ記録する 変更地図 21
22. 変更地図 View、JavaScript、CSSを安全に連携させる 保守担当者は見た目用classとJavaScriptフッ クを分ける Edit.cshtml + product.js HTML+JS <button class="btn-primary js-submit-button">登録 </button> const button = document.querySelector( ".js-submit-button"); .btn-primary：見た目の契約 注目 btn-primary / js-submit-button 守る条件 .js-submit-button：動作の契約 .js-submit-button：動作の契約 保守担当者は見た目用classとJavaScriptフックを分ける 変更地図 22
23. 変更地図 フォルダ・依存関係・クラス図は「変更に使える粒度」にする 入力 フォルダ責務→依存→機能対応 保守担当者は構造資料を変更判断に使える粒 度へ絞る 01 02 03 保守担当者は構造資 フォルダ責務→依存→ → 主要ドメインだけのクラス → 料を変更判断に使える 機能対応 図 粒度へ絞る 出力 保守担当者は構造資料を変更判断に使える粒度へ絞る 保守担当者は構造資料を変更判断に使える粒度へ絞る 変更地図 23
24. 変更地図 フロントエンドのデザインシステムをAIが使える規則にする 保守担当者はUI規則を機械検証できるトークン へ変える 色・文字・余白・角丸のトークン design-theme.css css :root { --color-primary: #2563eb; --color-danger: #dc2626; --color-warning: #d97706; --color-success: #16a34a; --color-bg: #ffffff; --color-text: #111827; } 注目 --color-primary / --color-danger / -color-text 守る条件 アクセシビリティ・export・差分検証 アクセシビリティ・export・差分検証 保守担当者はUI規則を機械検証できるトークンへ変える 変更地図 24
25. 変更地図 困ったときは：資料を一気に完成させようとしない 保守担当者は一つの変更から資料と検証を育 てる 01 02 03 04 機能対応表 の一行 受け入れ条件 実行・検証手 順 失敗の反映 担当: 人＋ Copilot 対象・非対象・ 権限が明確 担当: Copilot 規約・test・資料 へ戻る 担当: 人 画面・実装・設 定・testが並ぶ 機能対応表→受け入れ条件 同じ手順を再実 行できる 担当: チーム 実行手順→失敗の反映 保守担当者は一つの変更から資料と検証を育てる 変更地図 25
26. 変更地図 必要な資料は、AIにたたき台を作らせてよい 人間はAIの資料案を実在するコードと照合する 01 02 03 04 対象範囲と保 留 根拠付きの草 案 実在確認 担当: 人 担当: Copilot 担当: 人＋ Copilot 確認済みの正 本 調査境界が明 確 code・config・ testを引用 架空名と古い手 順がない 担当: 人 AGENTS.mdか ら参照可能 AI：コード・設定・テストから草案 人間：推測を除き確認済みだけ正本化 人間はAIの資料案を実在するコードと照合する 変更地図 26
27. 継続保守 5. 実装・運用の完了条件を定義し、継続的に保守する チームは完了条件とハーネスを継続的に更新する 01 02 03 04 差分と受け入 れ 機械検証の 証拠 地図と手順の 更新 失敗要因の 反映 担当: 人＋ Copilot 担当: Copilot 担当: Copilot 担当: チーム build・test・lint 結果を保存 リンクと現実が一 致 次回の仕組みへ 戻る 対象と非対象に 一致 差分・検証・文書・人間判断 リンク切れ・古い手順・反復失敗の検出 チームは完了条件とハーネスを継続的に更新する 継続保守 27
28. 明日の一件 6. まとめ：レガシーを捨てずにAI活用を始める第一歩 保守担当者は小さな変更からGitHub Copilot の地図と道具を作る 01 02 03 04 目的・対象・ 非対象 機能対応表 の一行 実行・検証の 証拠 承認境界 担当: 人 担当: 人＋ Copilot 担当: Copilot 本番影響を自動 化しない 依頼の境界が読 める 証拠へたどれる 変更結果を再確 認できる 担当: 人 コード量より判断材料の散在 一件の変更を地図・実行・検証・承認で完走 保守担当者は小さな変更からGitHub Copilotの地図と道具を作る 明日の一件 28
29. TAKEAWAY ありがとうございました Ochtum 今回のスライドはQiita記事でもお読みいただけます。 ハーネスを組み込んだサンプルソースを ご用意いたしましたのでよければご活用ください→ 本資料はAI(SlideDeckCreator)で作成いたしました→ TAKEAWAY 29
30. REFERENCE 参考資料 出典 読者はハーネスとDESIGN.mdの一次資料を確 認できる 一次資料 URL [1] OpenAI｜Harness engineering openai.com/index/harness-engineering [2] Google Labs｜ DESIGN.md Format specification github.com/.../spec.md [3] Google Labs｜Stitch DESIGN.md解説 blog.google/.../stitch-design-md 読者はハーネスとDESIGN.mdの一次資料を確認できる 出典 [1] [2] [3] REFERENCE 30