YAMLとは？AIプロンプトとデザインシステムの土台になった『構造化テキスト』の入門

「.yml で終わるファイルが社内に増えてきた」「Claude や Cursor の設定ファイルが YAML だった」「GitHub Actions の編集を任されたが、name:…

「.yml で終わるファイルが社内に増えてきた」「Claude や Cursor の設定ファイルが YAML だった」「GitHub Actions の編集を任されたが、name: の後にスペースが要るのかわからない」——AI時代に入って、エンジニアでない人にも YAML を読み書きする場面が急増しています。本記事では、プログラマでなくても 30分で YAML が読めるようになることをゴールに、構文の基本から、実務で必ず踏む落とし穴までを実例ベースで解説します。

YAMLとは — 「人間が読める構造化テキスト」

YAML（ヤムル）は 「データ構造を、人間が読みやすい形で書くためのテキスト形式」 です。正式名は YAML Ain't Markup Language（YAMLはマークアップ言語ではない）という再帰的略語で、2001年に Clark Evans らによって策定されました。

もともとは XML や JSON といった「機械向けに最適化されたデータ形式」が、人間が手で書くには記号が多すぎて辛い、という問題意識から生まれています。波括弧やカンマやクオートを書かなくても、インデント（字下げ）と改行だけで階層構造を表現できるのが YAML の最大の特徴です。

技術的には YAML 1.2 は JSON のスーパーセット（JSON を YAML として読み込める）と位置付けられており、設定ファイル・データシリアライゼーション・テンプレートエンジンへの入力など、幅広い用途で使われています。

なぜ今、非エンジニアまでYAMLを学ぶ必要があるのか

YAML は長らく「インフラエンジニア・DevOps エンジニアの道具」でした。状況が変わったのは、ここ2〜3年の AI ツール群の普及 です。AI に振る舞いを教えるための設定ファイル、AI エージェントの定義、AI に読ませるデザインシステム——これらが揃いも揃って YAML（あるいは YAML フロントマター + Markdown）で書かれているからです。

AIまわりで非エンジニアが触ることになる主なYAML

Claude Code / Cursor のエージェント定義（.claude/agents/.md の YAML フロントマター）／DESIGN.md（Google提唱、AI が UI を生成する際の設計仕様）／GitHub Actions（.github/workflows/.yml、AI 駆動の CI/CD の設定）／Docker Compose（docker-compose.yml、社内 SaaS の起動定義）／Kubernetes マニフェスト（クラウド上の AI ワークロードのデプロイ設定）。「いずれも誰かが書いてくれていた」では済まなくなっています。

つまり「AI を本気で業務に組み込む」と決めた瞬間から、プロダクトマネージャ・DX 推進担当・経営層も含めて、YAML を読み書きできるリテラシーが必要になります。Excel が読めない経営層はもういないのと同じで、これからは YAML が読めないと AI 時代の業務設計が見えません。

YAMLの基本構文（5つだけ覚える）

YAML は「5つの記法」さえ覚えれば、世の中の .yml ファイルの 9 割は読めるようになります。順番に見ていきましょう。

① キー: 値（コロンの後に半角スペース1つ）

yamlbasic.yml
name: 宮澤
role: CEO
age: 35

もっとも基本の形。「コロンの後には必ず半角スペースを1つ入れる」が鉄則です。name:宮澤 のようにスペースを忘れると、ほとんどのパーサーはエラーを返します。

② インデント（半角スペース2つ）で階層を表す

yamlnested.yml
company:
  name: はてなベース株式会社
  address:
    city: 福岡市
    postal: 810-0001

「親の下にぶら下がる子は、半角スペース2つ下げる」だけのルールです。JSON の { } のかわりに、ただ字下げするだけ。これが YAML が人間にやさしい最大の理由です。なお タブ文字は使用禁止。エディタの「タブを2スペースに変換」設定だけは必ず ON にしておきましょう。

③ リスト（先頭にハイフンとスペース）

yamllist.yml
members:
  - 宮澤
  - 田中
  - 佐藤

順序のある複数の値はハイフン - で並べます。これも - の ハイフンの後に半角スペースが必須 です。

④ リストの中身がオブジェクト

yamllist-of-objects.yml
members:
  - name: 宮澤
    role: CEO
  - name: 田中
    role: CTO

実務でいちばん使うパターン。ハイフンの行（最初のキー）に揃えて、後続のキーをインデントします。AI エージェント定義やワークフロー定義は、ほぼこの形です。

⑤ コメント（行頭の #）

yamlcomment.yml
# ↓ 本番環境の設定
environment: production
replicas: 3  # 同時起動数。負荷に応じて増減

コメントが書けるのが YAML の大きな利点 です（後述するように JSON は書けません）。意図を残せるので、運用ドキュメントを兼ねた設定ファイルが作れます。

JSON との違い・使い分け

「JSON でもデータ構造は書けるよね？」とよく聞かれます。事実そのとおりで、両者は機械的にはほぼ同じ表現力を持ちます。違いは 「誰のために書くか」 にあります。

主な用途人間が手で書く設定ファイルプログラム同士のデータ交換
コメント書ける（#）書けない
記号の量少ない（改行・インデント中心）多い（{ } [ ] , "）
可読性高い（縦に流れる）ネストが深いと読みにくい
パース速度やや遅い速い
典型ファイル.yml .yaml .github/workflows/*.yml*.json package.json REST API レスポンス

使い分けの原則：「人間が編集するなら YAML、機械が送受信するなら JSON」。AI エージェントの設定や CI/CD パイプラインは前者、Web API のレスポンスやデータベース連携は後者、と覚えればだいたい合っています。

実例で読む：身近な5つのYAML

ここからは、実務で目にする可能性が高い YAML を 5 つ並べて、それぞれが何を表現しているかを解説します。

① Claude Code のサブエージェント定義（YAMLフロントマター）

yaml.claude/agents/code-reviewer.md
---
name: code-reviewer
description: コードレビュー専門のサブエージェント。PR の差分を読み、設計・セキュリティ・パフォーマンス観点で指摘する
model: opus
tools:
  - Read
  - Grep
  - Bash
---

# 役割

あなたはシニアソフトウェアエンジニアです。提示された差分を ...（以下、人間が読む指示を Markdown で記述）

--- で囲まれた上部が YAML フロントマター、下が Markdown 本文という構成。これは AI に「あなたは誰で、何をする道具を持っているか」を機械可読な形で伝え、本文で「具体的に何をしてほしいか」を人間の言葉で書くという設計です。多くの AI エージェント定義はこの形を採用しています。

② DESIGN.md（Google が提唱するAI時代のデザインシステム）

yamlDESIGN.md（先頭部分）
---
colors:
  primary: "#2A5772"
  accent: "#FFE066"
  text: "#212529"
typography:
  base_font: "Zen Kaku Gothic New"
  heading_font: "Jost"
spacing:
  unit: 8
  scale: [0, 4, 8, 16, 24, 32, 48, 64]
---

# Hatenabase Design System

（以下、ガイドラインを Markdown で記述）

AI に UI を生成させると、色や余白がバラバラになりがちです。DESIGN.md は 「機械が確実に守れるトークンは YAML で」「人間が判断する原則は Markdown で」と二層に分ける設計思想。Claude や GPT に「この DESIGN.md に従ってダッシュボードを作って」と渡せば、一貫した UI が生成されます。

③ GitHub Actions（CI/CD の定義）

yaml.github/workflows/deploy.yml
name: Deploy to production
on:
  push:
    branches: [main]
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: npm ci
      - name: Build
        run: npm run build
      - name: Deploy
        run: ./scripts/deploy.sh

「main ブランチに push されたら、Ubuntu の上で npm ci → npm run build → デプロイスクリプトを順に実行する」という指示。条件・実行環境・手順を YAML 一枚で宣言するのが GitHub Actions の作法です。

④ Docker Compose（社内 SaaS の起動定義）

yamldocker-compose.yml
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - db-data:/var/lib/postgresql/data
volumes:
  db-data:

Web サーバ（nginx）とデータベース（PostgreSQL）の 2 つのコンテナを起動する設定。社内で動かす AI ツールや小規模 SaaS は、ほぼこの形で配布されます。「触れる人がメンテナンスできる」のは大きな価値です。

⑤ Hugo / Jekyll などのブログ記事フロントマター

yamlblog/posts/2026-05-12-hello.md
---
title: "YAMLとは？"
date: 2026-05-12
categories:
  - AI
  - DX
tags:
  - YAML
  - DESIGN.md
draft: false
---

本文をここに書く ...

静的サイトジェネレータの記事ファイルもこの形。メタデータ（タイトル・日付・カテゴリ）を YAML で、本文を Markdown で書く。AI エージェント定義と同じ構造であることに気づくはずです。

YAMLの落とし穴（実務で必ず踏むやつ）

便利な YAML ですが、長年運用されてきたぶん 「ハマりどころ」も明確 です。代表的な 4 つだけ押さえておきましょう。

落とし穴1: インデントが揃っていない

スペースが揃っていないだけで全壊する

ある行は半角スペース 2 つ、別の行は 3 つ、というように インデント幅が混ざるとパーサーが構造を取り違えます。エディタで「不可視文字を表示」する設定にして、空白文字を可視化しておくのが最大の予防策です。

落とし穴2: 「Norway問題」— 文字列が勝手に真偽値になる

yamlnorway-problem.yml
countries:
  - JP
  - NO   # ← これが false に変換されてしまう（YAML 1.1）
  - DE

YAML 1.1 では NO・YES・ON・OFF などが 暗黙的に真偽値に変換 されます。「ノルウェーの国コード NO を書いたら false になった」事例が有名で、業界では 「Norway 問題」 と呼ばれています。対策はシンプルで、文字列として確定させたいときはダブルクォートで囲む（"NO"）。YAML 1.2 では解消されているものの、いまだに 1.1 ベースのパーサーが多く、保険のためにクオートを付けるのが安全です。

落とし穴3: タブ文字はそもそも禁止

YAML はインデントに タブ文字を一切認めません。半角スペースだけです。多くのエディタは「Tab キーを押したらスペース2つを挿入」する設定が選べるので、.yml を開くプロジェクトでは必ず ON にしておきましょう。

落とし穴4: 複数行文字列の | と > の違い

yamlmultiline.yml
literal_block: |
  1行目
  2行目
  3行目

folded_block: >
  この行と
  次の行は
  1行にまとめられる

|（リテラル）は 改行をそのまま保持、>（フォールド）は 改行を半角スペースに変換して1行にまとめる。プロンプトの本文を YAML に埋め込むときに「改行が消えて意図が伝わらない」のは、ほぼこの取り違えが原因です。改行を保持したいときは | と覚えてください。

AI時代のYAML活用 — 「AIに渡す型」をつくる

ここまで読めば、もう「設定ファイルとしての YAML」は読めるはずです。最後に、AI 時代ならではの YAML の使い方を 1 つだけ紹介します。それは 「Claude や GPT への指示自体を YAML で構造化する」という発想です。

自由文で書いたプロンプトは、AI が解釈にばらつきを生みます。一方、YAML で「役割・入力・期待出力・制約条件」を構造化して渡すと、出力の安定性が劇的に上がります。たとえば次のような形です。

yamlprompt.yml
role: シニアアナリスト
task: 月次売上レポートの要約
input:
  format: CSV
  rows: 1200
constraints:
  - 数値は千円単位で記載
  - 前月比を必ず添える
  - 1セクション300字以内
output:
  format: Markdown
  sections:
    - 全体サマリ
    - 注目すべき変化
    - ネクストアクション

これを Claude や GPT に「次の YAML 仕様に従ってレポートを作ってください」と渡すだけで、出力ブレが大きく抑えられます。DESIGN.md がデザインの再現性を担保したように、プロンプトを YAML 化することで「業務の AI 委託」の再現性が上がる。これが AI 時代の YAML 活用の本丸です。

はてなベースの活用例

はてなベース社内では、AI 活用のあらゆる層で YAML を使っています。

  • DESIGN.md — コーポレートサイト・LP・社内ツールのデザイントークンを YAML で一元管理。Claude Code に「この DESIGN.md に従って画面を作って」と渡すだけで、ブランド統一が保たれる
  • CLAUDE.md フロントマター — 各プロジェクトで「このリポジトリでは何を守るべきか」を YAML+Markdown で記述。新任メンバーも AI も同じドキュメントを読む
  • Claude Code サブエージェント定義 — 「ブログ記事の校閲」「kintone プラグインのレビュー」「会計データの異常検知」など、業務別の AI エージェントを .claude/agents/*.md の YAML フロントマターで定義
  • GitHub Actions — ブログ記事の自動投稿・kintone との連携・LP の自動デプロイなど、業務フローを YAML で記述し AI が編集できる状態を維持

重要なのは、「これらの YAML ファイルが、エンジニア専用の聖域になっていない」こと。PM も DX 担当も、必要に応じて自分で開いて編集します。AI 時代の業務設計は、もはや「設定ファイルを読み書きできる人だけが触れる聖域」を許容できません。