株式会社ウエスタンカンパニーAIの成果物を人間が理解するための3ステップ実践法
Claudeがコードだけでなく設計書やドキュメントまで書いてくれる時代になりました。便利になった一方で、成果物の説明責任は今も人間の側にあります。「AIが生成した」ことと「人間が理解した」ことはまったく別物であり、理解していない資料はレビューもお客様への説明もできません。本記事では、社内共有会で扱った「AIの成果物をどう理解するか」というテーマを、実際に使えるプロンプト例やコマンドとともに紹介します。
背景 ── AIが書き、人間が説明責任を負う時代
AIコーディングツールの普及により、コードだけでなく設計書やドキュメントもAIが下書きしてくれるようになりました。しかし、成果物をお客様や社内に説明する責任は変わらず人間にあります。設計内容を十分に理解しないまま説明の場に立てば、質問に答えられないという事態も起こりえます。「AIの成果物をどう理解するか」は、AIコーディングを本格活用するチームが一度は向き合うべき課題です。
そのMarkdown、本当に「読めて」いますか？
ドキュメント整備は手軽さからMarkdownで行うことが多いですが、長いMarkdownファイルは流し読みになりがちです。プレビュー表示にしても文字の羅列である以上、読みにくさは大きく変わりません。「生成された」ことと「理解した」ことはまったく別物であり、この差を放置すると後工程でのレビューや説明で必ずつまずきます。
この点についてAnthropic公式ブログでも同様の指摘があります。Claude Codeチームに所属するThariq Shihipar氏が2026年5月20日に公開した記事「The unreasonable effectiveness of HTML」では、「100行を超えるMarkdownファイルは、実際にはほとんど読まない（I tend to not actually read more than a 100-line Markdown file）」と述べられています。人間が読む最終成果物には、Markdownよりも見やすいHTMLが適していると同記事は主張しています（出典: claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html）。
理解のための3ステップ ── HTML化・読み解く・深掘りする
AIの成果物を自分のものにするには、次の3ステップで取り組むのが有効です。
- HTMLにする ── 自分が読みやすい形に変換し、全体像を掴む
- 読み解く ── 構造と設計意図を最後まで読み切る
- 深掘りする ── 不明点は質問して残さず潰す
ポイントは、いきなり次の作業に戻るのではなく「まず自分が理解する」時間を明確に取ることです。説明できる状態を作ってから、次の工程に進みます。
実践1: AIの成果物をHTMLにする
最初のステップは、AIが生成したMarkdownや設計ドキュメントを、人間が読みやすいHTML資料に変換することです。Claude Codeに変換を依頼する際は、次のように具体的な要望を伝えると精度が上がります。
Claude Codeへの指示例
この設計ドキュメント一式を、内容は変えずに
読みやすい社内向けHTML資料にまとめてください。
・図解や表を使って視覚的に分かりやすくする
・外部CDNを読み込まない構成にする（セキュリティ対応）
・長い場合は目次をつける
・印刷してPDF化することを想定した見た目にする「内容は変えずに」と明示するのは、AIが変換の過程で解釈を加えて内容を書き換えてしまうことを防ぐためです。既存の社内テンプレートがある場合は、そのテンプレートのパスも合わせて伝えると配色や体裁が統一されます。
「作っただけ」で満足しない ── MarkdownとHTMLの役割の違い
HTML化はあくまで手段であり、「人が読める資料になった」時点で初めて意味を持ちます。情報量が多いまま変換しただけでは、HTMLであっても読みづらい資料になってしまいます。次のように役割を分けて考えると判断しやすくなります。
- Markdown ── AIが読むもの。情報を詰め込んでよい
- HTML ── 人が読むもの。読みやすいかどうかを常に意識する
文字を減らし、図解や画像で見せることが最大のメリットです。資料が長くなった場合は、全文を1つのHTMLに詰め込むのではなく、要点を集約した「まとめHTML」を別に作るという判断も有効です。
つまずきポイント ── 図解の崩れと所要時間
実際にHTML化を運用してみると、次のような点でつまずきやすいです。
- 図解（フローチャートや構成図）はテキストの長さによって文字が重なるなど、レイアウトが崩れやすい。生成後に一度プレビューし、崩れている箇所は指示を出し直す調整がほぼ毎回必要になる
- ドキュメント化そのものに時間がかかる。目安として、Markdownで1分程度で済む内容でも、図解や体裁を整えたHTMLにすると3〜5分程度かかる感覚がある。「HTML化する時間」自体を作業の見積もりに含めておくとよい
実践2: 深掘りで理解を完成させる
HTML化して読みやすくなった資料も、読んで分からない箇所を残したまま先に進んでしまうと意味がありません。「なんとなく分かった」で止めず、不明点はそのままClaudeに聞いて深掘りします。次のような質問の型を持っておくと、抜け漏れなく確認できます。
この設計を選んだ理由と、検討した代替案は？
このデータはどこで作られ、どこで使われる？
障害時やエッジケースではどう動くか？
お客様に説明するとき、リスクになる点は？この4つは「意図」「データフロー」「異常系」「説明リスク」という異なる観点をカバーしています。資料を読んで違和感なく答えられるかどうかを、自分自身への確認テストとして使うとよいでしょう。
実践3: 共有・提出の使い分け ── Artifact と HTML→PDF
理解のために作ったHTML資料は、そのまま社内共有や客先提出にも活用できます。ただし、共有先によって適切な手段は異なります。
チーム共有はArtifact
Claude Team契約下では、ClaudeのArtifact機能を使ってHTMLをそのままメンバーに共有できます。ファイルを添付する必要がなく、URLを送るだけで済み、更新した内容も同じURLに反映されます。Artifactは既定で非公開のため、チームに公開する前に機密情報が含まれていないか必ず確認してください。
客先提出はHTML→PDF
お客様は社内のClaude Team環境にログインできないため、Artifactでの共有はできません。この場合は、社内理解用に作ったHTMLをそのままPDF化して提出します。ローカルにGoogle Chromeが入っていれば、次のようにヘッドレスモードでコマンド一発でPDF化できます。
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
--headless \
--disable-gpu \
--print-to-pdf=report.pdf \
--no-pdf-header-footer \
report.htmlWindowsのコマンドプロンプトでは、chrome.exe のパスに置き換え、行末の「\」を外して1行で実行してください（インストール場所は環境により異なるため、実際のパスに置き換えてください）。ブラウザの「印刷」メニューから手動でPDF保存する方法でも構いません。提出前には、社内理解用の資料と同様に機密情報の有無と誤記のチェックを必ず行います。
つまずきポイント ── ページ送りの調整
HTMLをそのままPDF化すると、ページの切れ目が中途半端になり、表や図解が2ページに分断されてしまうことがよくあります。1ページに収めたいブロックは、CSSのpage-break-inside: avoid;を指定するか、Claudeに「このセクションは1ページに収まるように調整してください」と具体的に指示して調整するのがおすすめです。
まとめ ── 今日から実践すること
AIの成果物を「作った」で終わらせず、「理解して説明できる」状態にするために、次の4点を実践しましょう。
- AIの成果物はHTMLにして読む
- 理解できない箇所は全て深掘りする
- チームへの共有はArtifactで
- お客様への提出はHTML→PDFで
HTML化にはひと手間かかりますが、その分「理解して説明できる」状態を早く作れます。当社ではAIツールを活用したドキュメント整備や開発フローの構築に関するご相談を承っております。お気軽にお問い合わせください。
