USDMをYAMLで書いてみた

Posted at 2025-05-27

この記事のまとめ

この記事は、ExcelやWoedでかかれがちな要求仕様を、YAML + JSON Schemaを活用して構造的に管理できるようにする試みの紹介です。

メリット：

Gitなどでの構成管理が容易に
階層構造が自然に記述できる
自動補完やバリデーションが可能になる

デメリット：

スキーマ記述の学習コストがある
YAML構造を理解していないと読みづらくなる可能性
エディタ環境がある程度必要

USDMとは

USDM（Universal Specification Describing Manner）は、要求と仕様を明確かつ構造的に記述するためのフレームワークで、株式会社システムクリエイツの清水吉男氏によって提唱されました。

USDMの目的は、要求者と作り手（開発者や設計者）との認識のズレを防ぎ、手戻りや仕様の曖昧さを減らすことです。要求から仕様を導出するという形で、階層化して要求仕様を表現します。

USDMの基本構成要素は次の4つです：

要求：目的語＋動詞の形式で、何をしてほしいかを明確に記述する
理由：その要求がなぜ必要なのか、背景や目的を記述する
説明：用語定義や具体例など補足的な情報を任意で記述する
仕様：要求を実現するための具体的な実装方法や制約を記述する

USDMの目的は、要求者と作り手（開発者や設計者）との認識のズレを防ぎ、手戻りや仕様の曖昧さを減らすことです。要求を決められたフォーマットに従って記述することによって要求が漏れてしまうことを防ぎ、その要求もとにして仕様を記述することによって要求に対する誤解や仕様の衝突などの問題をいち早く検出することができます。

参考：

YAMLとは

YAML（YAML Ain't Markup Language）は、階層構造を簡潔に書けるデータ記述フォーマットで、JSONの上位互換的に使われることが多いです。

YAMLの利点：

人間が読み書きしやすい
PythonやNode.jsなど多くの言語で扱いやすい
JSON Schemaによる構文チェックや補完が可能

もともとYAMLは設定ファイルやデータ定義向けに設計されたフォーマットであり、ドキュメントを書くための言語ではありませんが、構造を明示できる特性が今回の用途（要求・仕様の構造化）にも適していると感じました。

今回のプロジェクトでは、このYAMLにUSDMベースの要求仕様構造を定義しました。

参考：

YAMLの利点

私が経験してきた開発プロジェクトでは要求仕様は主にExcelやMarkdownで管理されてきました。Excelは視覚的に見やすく非エンジニアにも扱いやすい一方で、Gitによる差分管理が困難であり、入れ子や階層構造の表現にも限界があります。Markdownは柔軟に記述できる利点がありますが、構造的なバリデーションやツール連携に乏しく、複雑な構造を記述するには不向きです。

そこで、データ記述に使っているYAMLで書けないかなと考えました。

仕様書の管理によく使われるExcelやWord、Markdownを比較してみると以下のようになります。

項目	Excel	Word	Markdown	YAML
記述フォーマットの維持	△	△	△	○
階層構造の表現	△	×	△	○
変更管理（Git連携）	×	×	○	○
学習コスト	○	○	△	△

○ = 優れている / △ = ある程度対応可能 / × = 不向き・難しい

YAMLは多少学習のコストや慣れは必要になるかもしれませんが、構造の明確さや変更管理のしやすさといった点で、要求仕様書には適していそうです。

スキーマの概要

スキーマ構成：

feature:
  feature_name: string                   　　# 機能の名称（例: "印刷機能"）
  req_groups:                            　　# 複数の要求をまとめる論理グループ（任意）
    - group_name: string                　　 # 要求グループ名（例: "操作に関する要求"）
      description: markdown             　　 # 要求グループの説明（任意）
      requirements:                      
        - req_id: string              　　   # 要求ID（例: "CH-02"）
          requirement: markdown        　　  # 要求の内容（なにをしたいか）
          reason: markdown            　　   # 要求の理由（なぜ必要か）
          description: markdown       　　   # 補足説明（背景、用語など）
          spec_groups:                　　   # 要求を満たす仕様のグループ
            - group_name: string      　　   # 仕様グループの名前（例: "チェックのタイミング"）
              description: markdown   　　   # 仕様グループの説明（任意）
              specifications:
                - spec_id: string      　　  # 仕様ID（例: "CH-02-1"）
                  specification: markdown　　# 実現手段・実装内容
                  reason: markdown       　　# なぜこの仕様かの理由（任意）
                  description: markdown  　　# 補足（任意）

この構成では、USDMの構造を反映し要求と仕様の対応を明示的に階層化しています。

feature は要求仕様書内の「章」にあたり、システム内の機能として単一ドキュメントの塊と考えてください。
requirement には理由（reason）、説明（description）などの情報を記述します。
requirement の子要素として specification を記述します
req_groups や req_groups によって関連する要求や仕様をグルーピングすることもできます

記述例：

  feature:
    feature_name: 印刷機能
    requirements:
      - req_id: CH-02
        requirement: 印刷開始時にインクの残量を調べて、最後まで印刷できない可能性があれば印刷依頼者のPC上に知らせてほしい
        reason: 印刷内容を知っている人に、最初に印刷できない可能性を知らせたい
        description: 印刷途中の監視機能は既に提供されており、これは印刷開始時に知らせるもの
        spec_groups:
          - group_name: チェックのタイミング
            specifications:
              - spec_id: CH-02-1
                specification: 刷開始の操作を完了した時点でプリンターと交信してインクの残量（全カートリッジ分）を知る
                reason: 印刷ボリュームと比べて判断する必要があるから
          - group_name: 確認操作
            specifications:
              - spec_id: CH-02-2
                specification: 『注意』または『警告』のアナウンスを出したときは、『確認』の操作によって印刷処理を続ける
                description: インクの交換はこの間に行い、交換後に『確認』操作によって印刷を続ける

こちらの例は、技術評論社刊『【改訂第２版】［入門＋実践］要求を仕様化する技術・表現する技術～仕様が書けていますか？』（著：清水吉男、ISBN: 978-4-7741-4257-9）で示されている要求記述をもとに構成されています。

JSON Schema定義ファイルはGitHubにて公開しています。
https://github.com/Yoshihiko-Shimizu/Structured_Specs

このスキーマは開発現場ごとの表現ニーズに応じて柔軟に編集できます。たとえば、要求の一階層上に「UserStory」や「品質要求」などの項目を追加したり、各項目に「ステータス」や「担当者」などのプロパティを加えることで、実際のワークフローや品質管理プロセスにフィットするようカスタマイズが可能です。

VS Codeで構文チェック

YAMLを書く際におすすめなのが、VS Code + YAML Language Server 拡張です。

使い方：

# yaml-language-server: $schema=.schema/schema.yaml

上記をYAMLファイルの冒頭に書くだけで：

スキーマに基づく補完候補の表示
構文・データ型のチェック
説明や例のツールチップ表示

が実現できます。

以下は実際の拡張機能のスクリーンショットです（Red Hat提供）：

この拡張機能を有効にしておけば、補完が効いた状態で仕様書が書けるため、
YAML初心者でもミスなく記述できるうえに、スキーマの意図も明確に伝わります。

詳細： YAML Language Support by Red Hat - Marketplace

今後やりたいこと

AS-IS / TO-BE のなど、要求や仕様の内容を構造的に書けるようにする
設計情報やテスト仕様などとの関連付けをできるようにする
CLIツールでYAML→Excel変換を簡易に実行できるようにする
GPTなどの生成AIを使って自動でドラフトを作成する

まとめ

YAML + JSON Schemaを使うことで、USDMベースの要求仕様を：

構造的に整理でき
ツールによる支援を受けながら記述でき
チームで共有・再利用しやすくなる

というメリットを感じられました。

Gitで管理できる仕様書を書きたいという方は、ぜひ試してみてください！

ご意見・フィードバックは GitHub Issues またはコメントでお待ちしています！

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up