WEB DESIGN CODE
Yas codeの坩堝

チュートリアル

AIプロンプトはMarkdownで書くべきか？構造化の意味と実務での使い方

AIプロンプトはMarkdownで書くべきか？構造化の意味と実務での使い方

ChatGPT に「いい感じに直して」と投げて、返ってきた文章を見て止まってしまう。意図は伝えたつもりなのに、トーンが違う、情報が足りない、逆に盛りすぎている。仕事で生成AIを使い始めた人ほど、このズレに直面します。

原因の多くは、モデルの性能不足というより 指示の渡し方 にあります。会話の延長で書いた一文には、役割・目的・前提・制約・出力形式が混ざったまま入っています。人間同士なら空気で補えますが、AIは補完の方向を自分で決めてしまいます。決めてほしくないところまで、決めてくるのです。

この記事では、フリーランスのWebディレクター兼エンジニアとして、サイトの企画から HTML / CSS / JavaScript / TypeScript、Next.js、WordPress、API 連携まで見てきた立場から、AIプロンプトを Markdown で構造化する意味 を整理します。結論を先に書くと、Markdown そのものが AI を賢くするわけではありません。見出しや箇条書きで指示を分解すると、人間が読み返しやすくなり、AI が判断に使う情報の関係も明確になります。その結果として、出力の品質と再現性が上がりやすくなります。

読み終えるころには、次ができるようになっているはずです。

  • AIプロンプトが「質問」から「仕事の依頼書」へ変わった理由を説明できる
  • 役割・目的・制約・出力形式を分けて書ける
  • Markdown の見出し・箇条書き・コードブロックを、プロンプトに使える
  • Web制作・実装・ライティングの現場で、自分用の型を作れる

AIプロンプトの役割は「質問」から「仕様書」へ変わった

初期の使い方は、検索の延長でした。「React の useEffect の依存配列って何？」「meta description の適切な文字数は？」一問一答なら、自然文で十分です。

実務に持ち込むと、要求は一気に複合します。例えば次のような依頼です。

  • 既存サイトのファーストビュー文言を、問い合わせにつながる方向へ直す
  • ただし誇張はしない
  • 技術スタックは Next.js の Pages Router
  • 出力は見出し案3つと本文120文字
  • 公開前に人間がファクトチェックする前提

これを一行に詰めると、AI はどれを優先していいか分かりません。優先順位が無い依頼は、毎回違う答えになります。

現場で起きてきた変化は、おおまかに4段階です。

  1. 単純な質問: 用語の確認、短いコードの意味
  2. 具体化: 「あなたはWebディレクターです」「です・ます調で」など、役割と制約を足す
  3. 構造化プロンプト: 目的・前提・禁止事項・出力形式をブロックに分ける
  4. 実務連携: Cursor のような開発ツールや、CMS・フォーム・デプロイ手順まで含めて依頼する

ポイントは「プロンプトを長くすること」ではありません。AIが判断するために必要な情報を、抜け漏れなく、矛盾なく渡すことです。Markdown はその整理を助ける書式であって、知能のブースターではありません。

AIプロンプトの基本は、判断材料を分けて渡すこと

仕事で使うプロンプトは、次のブロックに分けると安定しやすいです。全部を毎回書く必要はありません。足りないものだけ足します。

ブロック

書くこと

無いと起きやすいこと

役割（ROLE）

誰として考えてほしいか

一般論や、関係ない職種の口調になる

目的（OBJECTIVE）

何を達成した状態がゴールか

途中工程だけ丁寧で、成果物が使えない

前提（CONTEXT）

技術、既存方針、やってはいけない創作

存在しない実績やAPIを invent する

制約（CONSTRAINTS）

文字数、トーン、禁止表現、対象読者

盛ったコピーや、実装不能な提案

出力形式（OUTPUT）

見出し構成、表、コード、日本語

前置きが長く、コピペできない

評価基準（EVALUATION）

何をもって良しとするか

「それっぽい」文章で終わる

悪いプロンプトと、改善したプロンプト

まずは、現場でありがちな投げ方です。

コーポレートサイトのトップを良くして。
今っぽくて、SEOも強くて、お問い合わせが増える感じで。
Next.jsです。

何が弱いかは明確です。

  • 「良くして」の定義が無い（デザインなのか、文言なのか、速度なのか）
  • 「今っぽい」は検証できない
  • SEO と CV は両立できるが、優先順位が無い
  • 既存の強み・禁止事項（受賞、顧客数など）が無いので、AI が数字を作りやすい

同じ依頼を、Markdown で分解した例です。

# ROLE
あなたはWebディレクター兼フロントエンドエンジニアです。
実装可能性を優先し、確認できない実績は書きません。

# OBJECTIVE
コーポレートサイトのファーストビュー文言を改善し、
「制作の相談をする」クリックへつなげる。

# CONTEXT
- 構成: Next.js（Pages Router）
- 既存の訴求: 企画から実装・運用まで一貫して対応できる
- 禁止: 架空の受賞、顧客数、売上、導入社数

# CONSTRAINTS
- です・ます調
- 「今っぽい」「絶対」「爆速」などの曖昧語・煽りは使わない
- 数字は、このプロンプトに無い限り出さない

# OUTPUT
1. 改善方針を3行
2. キャッチ案を3つ（各28文字以内）
3. リード文を120文字前後
4. 採用案を1つ選び、理由を2行

# EVALUATION
公開前に人間がファクトチェックできること。
「それっぽさ」より、相談のハードルが下がることを優先する。

後者でも AI は間違えることがあります。ただし どこを直せばよいかが人間に見える のが、構造化の実務的な価値です。「キャッチが弱い」のか「禁止事項を破った」のか、ブロック単位で差し替えられます。

Markdown形式のプロンプトとは、記法ではなく情報の骨格である

Markdown は、見出し・箇条書き・強調・コード・区切り線といった、ごく短い記号で文書構造を表す記法です。ブログ本文にも使いますし、GitHub の README にも使います。プロンプトに使う場合も、やっていることは同じです。

よく使う記号と、プロンプトでの使いどころです。

記法

書き方

プロンプトでの使いどころ

見出し

# ## ###

役割・目的・制約など、ブロックの境界

箇条書き

- または 1.

前提条件、禁止事項、手順

太字

重要

破ってほしくない条件を一目で示す

インラインコード

` getStaticProps `

ファイル名、関数名、API名の取り違え防止

コードブロック

\\\`markdown など

出力してほしい型、既存コード、プロンプト自体

区切り線

---

長い指示のセクション分け

引用

>

「守ってほしい方針」を本文と区別する

本質は記号ではありません。人間が後から読んで、同じ依頼を再現できるかです。チャットの履歴に埋もれた口語指示は、1週間後の自分ですら再現できません。Markdown ファイルにしておけば、チームで共有もできます。

短い確認なら、わざわざ見出しを付ける必要はありません。「このエラーメッセージの意味を、原因候補3つで」で足りる作業は、それで進めます。構造化は、複合した依頼のための道具です。

Markdown形式のプロンプトは、魔法ではない

ここを外すと、記事も運用も壊れます。

Markdown そのものが、AI の性能や知能を向上させるわけではありません。

モデルは、見出し記号を見たから賢くなるわけではありません。有効なのは、次のような運用上の効果です。

  • 指示の抜けに気づきやすい（制約の見出しが空なら、まだ書いていないと分かる）
  • 役割と目的が逆転しにくい
  • 長いプロンプトを、ファイルとして管理・差分・使い回しできる
  • 「前回うまくいった型」を、案件ごとに中身だけ差し替えられる

逆に、Markdown が向かない・過剰なケースもあります。

  • 単語の意味、一行コードの説明など、単発の確認
  • ブロックを増やしすぎて、指示同士が矛盾している
  • 見た目を整えることが目的になり、目的（OBJECTIVE）が薄い
  • コードブロックの言語名や閉じ記号が崩れて、指示の一部が本文扱いになる

「Markdown で書けば精度が上がる」ではなく、複雑な要求を、AI と人間の両方に読める形へ落とす。この理解で使うと、現場に定着します。

実務で使えるMarkdownプロンプトのテンプレートと事例

基本形は、この骨組みで足りることが多いです。使わない見出しは削除してかまいません。短い方が、矛盾が減ります。

# ROLE
（誰として考えてほしいか）

# OBJECTIVE
（終わったときに、何ができていればよいか）

# CONTEXT
- 対象:
- 技術:
- 既存方針:
- 確認できていない情報の扱い: 創作しない

# CONSTRAINTS
- トーン:
- 禁止:
- 分量:

# OUTPUT
- 形式:
- 言語:
- コードを出す場合の前提（Pages Router / App Router など）:

# EVALUATION
- 合格条件:
- 人間が必ず確認すること:

以下は、この型を実務の3領域に落とした例です。コピーして中身だけ差し替えてください。

事例1：Web制作（ファーストビューと導線）

デザインカンプを「おしゃれにして」と頼むと、装飾は増えても問い合わせは増えません。ディレクターとして渡すなら、誰が・何を判断して・どこをクリックするかまで書きます。

# ROLE
Webディレクター。見た目の新しさより、初見の理解と次アクションを優先する。

# OBJECTIVE
サービスサイトのヒーロー周りを見直し、
「相談する」ボタンまで迷わず到達できるようにする。

# CONTEXT
- 読者: 制作会社へ依頼するか迷っている事業担当者
- できること: 企画、UI、実装、運用まで一貫対応
- できないこと: この指示に無い実績の提示
- 既存の弱い点: 技術用語が先に出て、依頼後の流れが見えない

# CONSTRAINTS
- です・ます調
- 賞・件数・売上は出さない
- ボタン文言は8文字以内を3案

# OUTPUT
1. 現状の問題を箇条書き3つ（推測ではなく、指示内の情報だけ）
2. 情報の出す順（誰向け → 何ができる → どう依頼するか）
3. ヒーロー見出し3案
4. リード120文字
5. ボタン文言3案

# EVALUATION
初見3秒で「誰に何を頼めるか」が分かること。

事例2：ライティング（この記事のような構成）

「SEOに強い記事を書いて」は、検索意図が無い依頼です。キーワード、読後の状態、書いてはいけないことを先に固定します。

# ROLE
SEOライター兼、制作実務が分かるWebディレクター。

# OBJECTIVE
「AI プロンプト Markdown」で来る読者が、
自分の仕事用プロンプトを1つ作れる状態にする。

# CONTEXT
- 一次キーワード: AI プロンプト Markdown
- 読者: 仕事でChatGPTを使うが、出力が安定しない人
- 重要方針: MarkdownがAIを賢くする、とは書かない
- 実績: 与えた事実以外は創作しない

# CONSTRAINTS
- です・ます調。煽らない
- 悪い例と良い例を1セット以上
- 見出しは検索意図に沿わせ、キーワードの詰め込みはしない

# OUTPUT
- H2/H3構成
- 導入で結論の方向を示す
- 最後に次の行動（自分で試す / 相談する）

# EVALUATION
読み手が「明日使うプロンプトの見出し」を書き始められること。

事例3：プログラミング（実装方針を先に固定する）

コード生成で一番高いのは、動かないことより 前提の取り違え です。App Router 向けのコードを Pages Router のリポジトリへ出される、環境変数をクライアントに露出する、確認できない仕様を断定する。実装プロンプトでは、スタックと禁止事項を先にロックします。

# ROLE
Next.js（Pages Router）に詳しいフロントエンドエンジニア。
推測でライブラリを増やさない。

# OBJECTIVE
ブログ一覧から、未公開の下書き記事を除外して表示する。

# CONTEXT
- Next.js Pages Router
- コンテンツは microCMS のリストAPI
- 公開の目安は publishedAt が入っていること
- 下書き取得権限が強いAPIキーだと、公開APIでも下書きが返ることがある

# CONSTRAINTS
- App Router の書き方は出さない
- 秘密情報を next.config の env でクライアントへ出さない
- 動かないPoCや攻撃手順は書かない

# OUTPUT
1. 原因の切り分け（CMS側 / 取得クエリ / 表示側）
2. 推奨する filters の方針
3. 変更ファイル名と、関数単位のパッチ方針
4. 残る運用上の注意（APIキー権限）

# EVALUATION
コピーしたコードが、既存の Pages Router 実装に載ること。
「とりあえず新しい構成へ移行」は不合格。

この3つに共通しているのは、コードや文章の上手さより、判断材料の境界です。境界が先にあると、Cursor に渡しても、チャットに貼っても、同じ型で回せます。

現場でハマりがちな注意点

構造化を始めた人が、同じ場所で止まります。先に知っておくと、プロンプトが自己目的化しにくいです。

指示を細かくしすぎて、矛盾させる

「簡潔に」と「事例を10個」は同時に成り立ちません。「カジュアル」と「です・ます調で専門的に」も衝突します。ブロックを増やしたあと、必ず OBJECTIVE と CONSTRAINTS を音読 してください。矛盾していれば、AI は片方を無視するか、平均的な無難さに逃げます。

目的が無いと、体裁だけ整う

見出しが揃っているのに成果物が使えないときは、OBJECTIVE が「記事を書く」「コードを出す」で止まっています。読後の状態、マージしてよいか、公開してよいかまで書いてください。

ハルシネーションを、文体で上書きしない

構造化しても、モデルは存在しない API、古い関数、架空の実績を出すことがあります。対策はプロンプト側でもできます。

  • 「確認できない固有名詞・数字・仕様は書かない。不明なら不明と書く」
  • 公式ドキュメントの URL を CONTEXT に貼る（ある場合のみ）
  • 出力に「根拠（指示内 / 要確認）」列を要求する
  • 生成後は、人間が一次情報を当たる。ここを省略した運用は、どれだけMarkdownでも危険です

Web制作では特に、受賞・顧客名・件数 が混ざりやすいです。プロンプトに無い事実は出させない。この一文を CONSTRAINTS に常備する価値があります。

Markdownを使うこと自体が目的になる

記号を増やしても、中身が「いい感じに」のままなら、最初の悪い例と変わりません。ファイル名を prompt.md にしても同じです。使う記号は、見出しと箇条書きとコードブロックだけで十分なことが多いです。

関連ツール：プロンプトを「会話」から「資産」へ移す

プロンプトが仕事の一部になったら、チャットの入力欄だけに置かない方がよいです。実在するツールの範囲で、使い分けは次のようになります。

  • ChatGPT / Claude などのチャットUI: 探索、壁打ち、短い確認。確定した型はファイルへ退避する
  • Cursor: リポジトリのコードを前提に、実装・リファクタ・説明を依頼できる。プロジェクト用の指示をファイルで持てるため、Markdown プロンプトとの相性が良い
  • GitHub: プロンプトや開発ルールをバージョン管理する。うまくいった指示の差分が残る
  • microCMS などのヘッドレスCMS: 公開文は CMS の本文へ。プロンプトはリポジトリか社内ドキュメントへ。生成文をそのまま公開せず、編集する

ツールを増やすことより、再現できる場所に置くことが先です。うまくいった依頼を1つ、Markdown で保存する。それだけで、翌週の自分が楽になります。

AI を企画・実装・運用の流れに載せたい場合は、プロンプトの型づくりから一緒に整理できます。サイト制作やリファクタと切り離さず、どこまでを人が確認するかを先に決めるのが実務的です。

まとめ：構造化した指示は、AIと人間の両方のための仕様書

AIプロンプトを Markdown で書く意味は、モデルを洗脳することではありません。役割・目的・前提・制約・出力形式を分け、複雑な仕事を依頼可能な粒度に落とすことです。

  • 単発の質問は、自然文のままでよい
  • 複合した仕事は、仕様書として構造化する
  • Markdown は整理・再利用・共有のための器である
  • 長さより、判断に必要な情報と、矛盾の無さ
  • 生成結果のファクトチェックは、人間の工程として残す

まずは、今うまくいっていない依頼を1つ選んでください。ROLE と OBJECTIVE と CONSTRAINTS と OUTPUT の4見出しだけ書いて、同じチャットに投げ直す。その差分が、この記事の成果です。

制作・実装・AI活用の進め方を、サイトの都合に合わせて整理したい場合は、相談・お問い合わせからどうぞ。内容が固まっていなくても構いません。