0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@Haru8989

AIと人の両方が読める中間表現としてHTMLを試してみた

0
Last updated at Posted at 2026-11-03

概要

対応調査やソース解析の結果を、人が確認するためや後続工程でAIに活用するためにMarkdownで蓄積している。

また、既存のExcelやWordで管理された設計資料についても、AIが参照しやすい形へ整理したいという課題がある。

MarkdownはAIとの相性が良く、Git管理もしやすいため一定の効果はあったが、実際に運用すると以下の課題が見えてきた。

  • 関連ドキュメントを横断してたどりにくい
  • 全体像や影響範囲を表現しづらい
  • 概要から詳細への導線を作りづらい
  • 表現方法が限られ、人が理解しにくい場面がある

そこでHTMLベースの管理を試してみた。

その結果、

  • 関連情報をリンクで接続できる
  • 色やレイアウトで視認性を向上できる
  • サマリ図から詳細へ遷移できる
  • 図そのものをナビゲーションとして利用できる
  • HTML構造のためAIも解釈しやすい

といった利点が得られた。

特に「概要→詳細」「影響範囲→個別要素」といった導線を自然に表現できる点は、Markdownにはない強みだと感じた。

もちろん、HTML化による作成・保守コストや、開発・テスト工程における有効性については今後検証が必要である。

一方で、人とAIの双方が利用する知識表現としては十分可能性を感じたため、今回試作内容を整理してみた。

試した構成

今回はシンプルな構成を重視して試作した。

HTML

文章・レイアウト・リンク管理に利用した。

Markdownと比較すると、

  • 色や装飾が利用できる
  • 概要ページを作りやすい
  • 関連ドキュメントへの導線を作りやすい

といった利点がある。

SVG

概要図や影響範囲図の作成に利用した。

SVGはコード形式の画像であるため、

  • Gitで差分管理できる
  • AIが内容を解釈しやすい
  • 各要素へリンクを設定できる

という特徴がある。

今回は概要図から詳細ページへ遷移するナビゲーション用途として利用した。

CSS

小規模な試作であることから、ファイル数を増やしたくなかったため未使用とした。

スタイルはHTML内へ直接記載している。

サンプルでイメージ説明

コンセプト説明用として、サンプル案件を題材に簡易的なサンプルを作成した。

概要ページでは案件全体をサマリとして整理し、影響範囲を表現している。

また、影響箇所の一部を選択すると調査結果ページへ遷移し、要約から詳細へ辿れる構成としている。

概要ページ

検討結果のサマリーを一覧で確認できる。
（今回はサンプルのため、会員登録APIのみ詳細ページへのリンクを設定）
index.png

調査結果ページ

概要ページからリンクを押下すると、対象の調査結果を確認できる。
api.png

まとめと今後の課題

今回の試作では、概要から詳細へ辿れるドキュメント構成をHTMLとSVGで実現できた。

一方で、以下の課題も残っている。

  • HTMLやSVGの作成・更新コストが発生する
  • ExcelやWordと比較すると保守できる人が限定される
  • ソースコードや既存資料を直接参照する場合と比較して、AIの回答品質や生成精度が向上するかは未検証
  • ドキュメント作成コストに見合う効果が得られるか評価が必要
  • 顧客向け成果物や納品物として利用可能かは別途検討が必要

今回はコンセプト検証レベルではあるが、Markdownでは表現しづらかった「要約→詳細」や関連情報への導線を表現する手段としては手応えを感じた。

また、AI向けドキュメントと人向けドキュメントを同じ情報源から表現できる可能性も感じており、今後も継続して試行していきたい。

補足

実際のHTMLコードは以下の通り。

index.html

<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="UTF-8">
    <title>メール通知機能追加</title>

    <style>
        body{
            font-family:sans-serif;
            margin:20px;
            background:#f5f5f5;
        }

        svg{
            width:100%;
            max-width:1200px;
            background:white;
            border:1px solid #ccc;
        }
    </style>

</head>

<body>

    <svg viewBox="0 0 1200 900">

        <!-- タイトル -->

        <rect
            x="20"
            y="20"
            width="1160"
            height="70"
            rx="8"
            fill="#1565c0"/>

        <text
            x="600"
            y="65"
            text-anchor="middle"
            font-size="34"
            fill="white">

            メール通知機能追加

        </text>

        <!-- 概要 -->

        <rect
            x="20"
            y="120"
            width="560"
            height="180"
            fill="#e3f2fd"
            stroke="#1565c0"/>

        <text x="40" y="160" font-size="26">
            概要
        </text>

        <text x="40" y="210" font-size="18">
            会員登録完了時に
        </text>

        <text x="40" y="240" font-size="18">
            メール通知を送信する機能を追加する
        </text>

        <text x="40" y="270" font-size="18">
            ユーザー向け利便性向上を目的とする
        </text>

        <!-- 対応内容 -->

        <rect
            x="620"
            y="120"
            width="560"
            height="180"
            fill="#f1f8e9"
            stroke="#558b2f"/>

        <text x="640" y="160" font-size="26">
            対応内容
        </text>

        <text x="640" y="210" font-size="18">
            ・通知メール送信
        </text>

        <text x="640" y="240" font-size="18">
            ・送信ログ追加
        </text>

        <text x="640" y="270" font-size="18">
            ・障害時の再送考慮
        </text>

        <!-- 影響範囲 -->

        <rect
            x="20"
            y="340"
            width="1160"
            height="320"
            fill="#fafafa"
            stroke="#999"/>

        <text
            x="40"
            y="390"
            font-size="28">

            影響範囲（会員登録APIを選択すると詳細ページへ遷移）

        </text>

        <!-- 画面 -->

        <rect
            x="80"
            y="470"
            width="250"
            height="100"
            rx="10"
            fill="#4caf50"/>

        <text
            x="205"
            y="520"
            text-anchor="middle"
            fill="white"
            font-size="24">

            会員登録画面

        </text>

        <text
            x="205"
            y="555"
            text-anchor="middle"
            fill="white"
            font-size="14">

            影響小

        </text>

        <!-- API -->

        <a href="api.html">

            <rect
                x="470"
                y="450"
                width="260"
                height="140"
                rx="10"
                fill="#ef6c00"/>

            <text
                x="600"
                y="505"
                text-anchor="middle"
                fill="white"
                font-size="32">

                会員登録API

            </text>

            <text
                x="600"
                y="545"
                text-anchor="middle"
                fill="white"
                font-size="18">

                詳細確認

            </text>

            <text
                x="600"
                y="570"
                text-anchor="middle"
                fill="white"
                font-size="14">

                クリック可能

            </text>

        </a>

        <!-- Batch -->

        <rect
            x="870"
            y="470"
            width="250"
            height="100"
            rx="10"
            fill="#d32f2f"/>

        <text
            x="995"
            y="520"
            text-anchor="middle"
            fill="white"
            font-size="24">

            バッチ処理

        </text>

        <text
            x="995"
            y="555"
            text-anchor="middle"
            fill="white"
            font-size="14">

            要影響調査

        </text>

        <!-- リスク -->

        <rect
            x="20"
            y="700"
            width="1160"
            height="150"
            fill="#ffebee"
            stroke="#d32f2f"/>

        <text
            x="40"
            y="745"
            font-size="26"
            fill="#b71c1c">

            主要リスク

        </text>

        <text
            x="40"
            y="790"
            font-size="18"
            fill="#b71c1c">

            ・メール重複送信

        </text>

        <text
            x="40"
            y="820"
            font-size="18"
            fill="#b71c1c">

            ・送信漏れ

        </text>

        <text
            x="400"
            y="790"
            font-size="18"
            fill="#b71c1c">

            ・ログ不足による調査困難

        </text>

    </svg>

</body>
</html>

api.html

<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="UTF-8">
    <title>会員登録API調査結果</title>

    <style>
        body{
            font-family:sans-serif;
            margin:20px;
            background:#f5f5f5;
        }

        svg{
            width:100%;
            max-width:1200px;
            background:white;
            border:1px solid #ccc;
        }
    </style>

</head>

<body>

    <svg viewBox="0 0 1200 900">

        <!-- 戻る -->

        <a href="index.html">

            <rect
                x="20"
                y="20"
                width="160"
                height="50"
                rx="8"
                fill="#666"/>

            <text
                x="100"
                y="52"
                text-anchor="middle"
                fill="white">

                戻る

            </text>

        </a>

        <!-- タイトル -->

        <rect
            x="220"
            y="20"
            width="940"
            height="70"
            fill="#ef6c00"
            rx="8"/>

        <text
            x="690"
            y="65"
            text-anchor="middle"
            fill="white"
            font-size="32">

            会員登録API 調査結果

        </text>

        <!-- 調査結果 -->

        <rect
            x="20"
            y="120"
            width="1140"
            height="120"
            fill="#ffebee"
            stroke="#d32f2f"/>

        <text
            x="40"
            y="165"
            font-size="26"
            fill="#c62828">

            調査結果

        </text>

        <text
            x="40"
            y="215"
            font-size="22">

            要修正

        </text>

        <text
            x="250"
            y="215"
            font-size="18">

            メール通知機能追加に伴い改修対象

        </text>

        <!-- 修正内容 -->

        <rect
            x="20"
            y="280"
            width="560"
            height="220"
            fill="#fff3e0"
            stroke="#ef6c00"/>

        <text
            x="40"
            y="320"
            font-size="26">

            修正内容

        </text>

        <text
            x="40"
            y="380"
            font-size="18">

            ・メール送信呼出追加

        </text>

        <text
            x="40"
            y="420"
            font-size="18">

            ・送信結果ログ追加

        </text>

        <text
            x="40"
            y="460"
            font-size="18">

            ・エラー処理追加

        </text>

        <!-- 関連要素 -->

        <rect
            x="620"
            y="280"
            width="540"
            height="220"
            fill="#e3f2fd"
            stroke="#1565c0"/>

        <text
            x="640"
            y="320"
            font-size="26">

            関連要素

        </text>

        <text
            x="640"
            y="380"
            font-size="18">

            ・UserRegisterApi

        </text>

        <text
            x="640"
            y="420"
            font-size="18">

            ・MailService

        </text>

        <text
            x="640"
            y="460"
            font-size="18">

            ・MailLog

        </text>

        <!-- 影響調査結果 -->

        <rect
            x="20"
            y="540"
            width="1140"
            height="140"
            fill="#f1f8e9"
            stroke="#2e7d32"/>

        <text
            x="40"
            y="585"
            font-size="26">

            影響調査結果

        </text>

        <text
            x="40"
            y="640"
            font-size="18">

            会員登録完了後の処理を確認した結果、

            メール送信機能は未実装であることを確認した。

        </text>

        <!-- 注意事項 -->

        <rect
            x="20"
            y="720"
            width="1140"
            height="140"
            fill="#ffebee"
            stroke="#d32f2f"/>

        <text
            x="40"
            y="765"
            font-size="26"
            fill="#b71c1c">

            注意事項

        </text>

        <text
            x="40"
            y="815"
            font-size="18"
            fill="#b71c1c">

            ・メール重複送信防止

        </text>

        <text
            x="380"
            y="815"
            font-size="18"
            fill="#b71c1c">

            ・送信失敗時のリトライ制御

        </text>

        <text
            x="760"
            y="815"
            font-size="18"
            fill="#b71c1c">

            ・監査ログ出力確認

        </text>

    </svg>

</body>
</html>
0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?