usdm

name	usdm
description	ソフトウェアプロジェクトや仕様書を解析し、USDM要求仕様書をMarkdownで作成してExcelを生成する

以下のガイドに従って $ARGUMENTS を解析対象として USDM 要求仕様書を作成してください。

• 実在する完成例（https://github.com/signal-slot/md2usdm/tree/main/examples）を必ず参考にすること
• 対象がソースコードならガイドの「パターン A」、仕様書・設計書なら「パターン B」で解析すること

---

USDM 要求仕様書作成ガイド（AI エージェント向け）

このドキュメントは、AI エージェントが USDM (Universal Specification Describing Manner) 形式の要求仕様書を Markdown で作成し、Excel ファイルを生成するための手順書です。入力ソースとして ソースコード と 既存の仕様書・設計書 の両方に対応しています。

概要

USDM とは

USDM はソフトウェアの要求を階層的に記述する手法です。以下の構造を持ちます:

コンポーネント（プロジェクト全体の要求）
  └─ 上位要求（大きな機能単位の要求）
       ├─ 理由（なぜこの要求が必要か）
       ├─ 説明（補足情報）
       └─ 下位要求（上位要求を実現するための具体的な要求）
            ├─ 理由
            ├─ 説明
            └─ 仕様（実装レベルの具体的な記述）

ゴール

1. 対象を解析する（ソースコード or 既存仕様書・設計書）
2. 機能・要求を分類し、USDM の階層構造に整理する
3. Markdown ファイル群として記述する
4. ツールで Excel ファイル (.xlsx) を生成する

ツール

# インストール（pip or uv）
pip install md2usdm

# 雛形生成
usdm new <プロジェクト名> <出力先ディレクトリ>

# シート追加
usdm add <出力先ディレクトリ> <シート名>

# Markdown → Excel 変換
md2usdm <出力先ディレクトリ> [出力.xlsx]

---

手順

ステップ 1: 対象を解析する

入力ソースに応じて A（ソースコード） または B（仕様書・設計書） のいずれかを実施する。

パターン A: ソースコードから解析する

対象がソースコードの場合。

A-1. 全体像の把握

• README、ドキュメント、エントリポイント（main関数等）を読む
• プロジェクトの目的・用途を一文で言えるようにする
• 主要な技術スタック（言語、フレームワーク、ライブラリ）を把握する

A-2. 機能の洗い出し

ソースコードのディレクトリ構造、モジュール、クラス、関数を走査し、ユーザー視点の機能を洗い出す。

注意点:

• 実装の内部構造（ユーティリティ関数、ヘルパークラス等）ではなく、外部から見た振る舞いに着目する
• 「何ができるか」「何をするか」を動詞で表現する（例: 「ファイルを読み込む」「結果を出力する」）
• 同じ抽象度の機能をグループ化する

パターン B: 仕様書・設計書から解析する

対象が既存の仕様書、設計書、要件定義書、提案書などのドキュメントの場合。

重要: ドキュメント「を」分析するのではなく、ドキュメント「に書かれているシステム」の要求を USDM にする。 仕様書はあくまで入力情報であり、USDM の対象はそのドキュメントが記述しているソフトウェア・システムである。

例: 「タスク管理アプリの設計書」が入力の場合

• 正: タスク管理アプリの要求（タスク作成、編集、削除、一覧表示 等）を USDM で記述する
• 誤: 設計書の構造（章立て、記述形式、用語定義 等）を USDM で記述する

B-1. ドキュメントの読み込み

• 指定されたファイル（PDF、Word、テキスト、Markdown 等）をすべて読む
• ドキュメントが記述している対象システムを把握する — 「このドキュメントは何を作るために書かれたか？」
• 対象システムの目的・スコープを一文で言えるようにする

B-2. 対象システムの要求を抽出する

ドキュメントを読み、そこに記述されている対象システムが満たすべき要求を洗い出す。

注意点:

• ドキュメント自体の構造ではなく、ドキュメントが言及しているシステムの機能・振る舞いに着目する
• 「〜する」「〜できる」「〜を提供する」という記述から、対象システムへの要求を読み取る
• 暗黙の要求を見落とさない — 前提条件・制約・非機能要件（性能、セキュリティ等）も抽出する
• ドキュメントの章立てがそのまま USDM の階層になるとは限らない — 要求の粒度で再整理する
• 原文の表現をできるだけ活かし、元の仕様書とのトレーサビリティを保つ

B-3. 重複・矛盾の整理

• 複数ドキュメントに同じ要求がある場合は統合する
• 矛盾する記述がある場合はコメントとして残す（### 説明 に記載）

1-3. 階層構造の設計（共通）

洗い出した機能を以下の階層に整理する:

レベル	USDM 用語	粒度の目安	例
シート	カテゴリ	大分類（3〜5個程度）	入力処理、データ変換、出力処理
上位要求	機能要求	シート内の主要機能（シートあたり2〜5個）	ファイル読み込み、形式検証
下位要求	詳細要求	上位要求の構成要素（上位あたり1〜5個）	CSV パース、エンコーディング検出
仕様	実装仕様	テスト可能な具体的記述（下位あたり2〜8個）	UTF-8 と Shift_JIS を自動判別する

設計の指針:

• 上位要求は「なぜ必要か（理由）」を説明できるレベル
• 下位要求は「具体的に何をするか」を説明できるレベル
• 仕様は「テストで検証できる」レベル
• 階層が深くなりすぎないようにする（下位要求の下にさらに下位要求は作らない）

---

ステップ 2: プロジェクトの雛形を生成する

usdm new <プロジェクト名> <出力先ディレクトリ>

例:

usdm new MyApp examples/myapp

生成されるファイル:

examples/myapp/
├── index.md          # ヘッダーテーブル + シート一覧
├── MyApp.md          # コンポーネント（プロジェクト全体の要求）
├── MyApp.xlsx        # 生成済み Excel
└── sheet01/
    ├── index.md
    └── MyApp_R01/
        ├── MyApp_R01.md
        └── MyApp_R01.DM01.md

---

ステップ 3: シートを追加する

ステップ 1-3 で設計したカテゴリの数だけシートを追加する。雛形生成時に sheet01 が 1 つ作られているので、2 つ目以降を追加する。

# 2 つ目のシート
usdm add examples/myapp "2.データ変換"

# 3 つ目のシート
usdm add examples/myapp "3.出力処理"

シート名の書式: {番号}.{カテゴリ名}（例: 1.入力処理、2.データ変換）

---

ステップ 4: Markdown ファイルを記述する

以下の順序で各ファイルを編集・作成する。

4-0. ディレクトリ構造（完成形）

examples/myapp/
├── index.md                                    # [自動生成済み] 編集不要
├── MyApp.md                                    # コンポーネント
├── sheet01/
│   ├── index.md                                # シート index
│   ├── MyApp_R01/
│   │   ├── MyApp_R01.md                        # 上位要求 (u-file)
│   │   ├── MyApp_R01.DM01.md                   # 下位要求 (uu-file)
│   │   └── MyApp_R01.DM02.md                   # 下位要求 (uu-file)
│   └── MyApp_R02/
│       ├── MyApp_R02.md
│       └── MyApp_R02.DM01.md
├── sheet02/
│   ├── index.md
│   └── MyApp_R03/
│       ├── MyApp_R03.md
│       └── MyApp_R03.DM01.md
└── sheet03/
    └── ...

命名規則:

• 上位要求: {プロジェクト名}_R{連番:02d} — プロジェクト全体で通し番号
• 下位要求: {上位要求ID}.DM{連番:02d}
• 仕様番号: 【{下位要求ID}-{連番:02d}】

4-1. コンポーネントファイル（{プロジェクト名}.md）

プロジェクト全体の要求を 1 文で記述する。雛形のプレースホルダーを書き換える。

# 【MyApp】タスク管理アプリケーション

## 要求

タスクの作成・編集・削除・一覧表示を行うWebアプリケーションを提供する

### 理由

チームのタスク管理を効率化し、進捗を可視化するため

### 説明

記載無し

書式ルール:

• # 【{プロジェクト名}】{タイトル} — 見出しに仕様番号を【】で囲んで記載
• ## 要求 — 要求の本文（1〜3 文）
• ### 理由 — なぜこの要求が必要か（1〜2 文）
• ### 説明 — 補足説明。不要なら 記載無し と書く（Excel 上では空セルになる）

4-2. シート index（sheetNN/index.md）

usdm.py add で自動生成されたものを編集する。上位要求のリンク一覧を記述する。

↑ [MyApp](../index.md)

# 【MyApp】1.入力処理

## 要求

[MyApp: タスク管理アプリケーション](../MyApp.md "【MyApp】")

## 下位要求

- [R01 ファイル読み込み](./MyApp_R01/MyApp_R01.md "【MyApp_R01】")
- [R02 入力検証](./MyApp_R02/MyApp_R02.md "【MyApp_R02】")

書式ルール:

• 1 行目: ↑ [プロジェクト名](../index.md) — 親へのナビゲーション
• ## 要求 の下: コンポーネントファイルへのリンク（[表示名](パス "【仕様番号】")）
• ## 下位要求 の下: 上位要求へのリンク一覧（- [ID タイトル](パス "【仕様番号】")）

4-3. 上位要求ファイル（u-file: {ID}.md）

各上位要求を 1 ファイルで記述する。ディレクトリを作成してから中にファイルを置く。

↑ [1.入力処理](../index.md)

# 【MyApp_R01】ファイル読み込み

## 要求

各種形式のファイルを読み込み、内部データ構造に変換する

### 理由

複数のファイル形式をサポートし、ユーザーの既存データを取り込むため

### 説明

記載無し

## 下位要求

- [01 CSVパース](./MyApp_R01.DM01.md "【MyApp_R01.DM01】")
- [02 JSONパース](./MyApp_R01.DM02.md "【MyApp_R01.DM02】")

書式ルール:

• 1 行目: ↑ [シート名](../index.md) — 親シートへのナビゲーション
• # 【{仕様番号}】{タイトル} — 仕様番号は【】で囲む
• ## 要求 / ### 理由 / ### 説明 — コンポーネントと同じ構造
• ## 下位要求 — 下位要求へのリンク一覧

4-4. 下位要求ファイル（uu-file: {ID}.DM{XX}.md）

各下位要求と、その仕様一覧を記述する。

↑ [【MyApp_R01】ファイル読み込み](./MyApp_R01.md "【MyApp_R01】")

# 【MyApp_R01.DM01】CSVパース

## 要求

CSV形式のファイルをパースし、ヘッダー行とデータ行を分離して内部構造に格納する

### 理由

CSVはデータ交換で最も一般的な形式であり、対応が必須であるため

### 説明

記載無し

## 仕様

| 種別 | 内容 | 仕様番号 |
| --- | --- | --- |
| 仕様 | カンマ区切りのCSVファイルを読み込む | 【MyApp_R01.DM01-01】 |
| 仕様 | 1行目をヘッダー行として認識する | 【MyApp_R01.DM01-02】 |
| 仕様 | ダブルクォートで囲まれたフィールド内のカンマをエスケープ処理する | 【MyApp_R01.DM01-03】 |
| 仕様 | UTF-8 と Shift_JIS のエンコーディングを自動判別する | 【MyApp_R01.DM01-04】 |
| 仕様 | パースエラー時にはエラー行番号と内容を報告する | 【MyApp_R01.DM01-05】 |

書式ルール:

• 1 行目: ↑ [【{親仕様番号}】{親タイトル}](./{親ファイル}.md "【{親仕様番号}】") — 親上位要求へのナビゲーション
• ## 仕様 — Markdown テーブル形式の仕様一覧
• 仕様テーブルの列: | 種別 | 内容 | 仕様番号 |
• 種別は通常 仕様 とする
• 仕様番号: 【{下位要求ID}-{連番:02d}】

---

ステップ 5: Excel を生成する

すべての Markdown ファイルを記述したら、Excel を生成する。

md2usdm examples/myapp

examples/myapp/MyApp.xlsx が生成（または更新）される。

---

記述のガイドライン

要求の書き方

• 主語を省略して動詞で始める:「～を行う」「～を提供する」「～を検出する」
• 1 つの要求に 1 つの責務: 「AとBを行う」ではなく、A と B を別の要求にする
• テスト可能な記述: 仕様は「Yes/No で判定できる」レベルの具体性を持たせる

理由の書き方

• 「〜するため」で終わる: 「データの整合性を保証するため」
• ビジネス価値または技術的必要性を述べる: 「なぜこれが必要なのか」を説明する
• 実装の詳細は書かない: 「MySQLを使うため」ではなく「永続的にデータを保存するため」

説明の書き方

• 補足が不要なら 記載無し と書く（必ずこの 4 文字。Excel 上で空セルになる）
• 補足がある場合は、要求の背景・前提条件・制約を記述する

リッチテキスト

仕様テーブルの内容に書式を付けることができる:

Markdown	Excel での表示
**テキスト**	赤フォント（変更箇所の強調等に使用）
~~テキスト~~	取消線（廃止項目の表示等に使用）
**~~テキスト~~**	赤フォント + 取消線

---

完全な実行例

以下は「電卓アプリ」を対象にした実行例です。

1. 雛形生成

usdm new Calc examples/calc

2. シート追加

usdm add examples/calc "2.計算処理"

この時点で sheet01（「1.要件」）と sheet02（「2.計算処理」）ができている。 sheet01 のシート名を変更するには examples/calc/index.md と examples/calc/sheet01/index.md を編集する。

3. index.md のシート名修正

examples/calc/index.md のシート一覧:

- [1.入力処理](./sheet01/index.md)
- [2.計算処理](./sheet02/index.md)

4. コンポーネントファイル

examples/calc/Calc.md:

# 【Calc】電卓アプリケーション

## 要求

四則演算と関数計算を行う電卓アプリケーションを提供する

### 理由

数値計算を手軽に行える環境を提供するため

### 説明

記載無し

5. sheet01/index.md

↑ [Calc](../index.md)

# 【Calc】1.入力処理

## 要求

[Calc: 電卓アプリケーション](../Calc.md "【Calc】")

## 下位要求

- [R01 数式入力](./Calc_R01/Calc_R01.md "【Calc_R01】")

6. 上位要求ファイル（u-file）

examples/calc/sheet01/Calc_R01/Calc_R01.md:

↑ [1.入力処理](../index.md)

# 【Calc_R01】数式入力

## 要求

ユーザーが入力した数式文字列を解析し、計算可能な構造に変換する

### 理由

自然な数式表記を受け付けることで直感的な操作を実現するため

### 説明

記載無し

## 下位要求

- [01 字句解析](./Calc_R01.DM01.md "【Calc_R01.DM01】")

7. 下位要求ファイル（uu-file）

examples/calc/sheet01/Calc_R01/Calc_R01.DM01.md:

↑ [【Calc_R01】数式入力](./Calc_R01.md "【Calc_R01】")

# 【Calc_R01.DM01】字句解析

## 要求

数式文字列をトークン列に分割する

### 理由

演算子の優先順位や括弧のネストを正しく処理するため

### 説明

記載無し

## 仕様

| 種別 | 内容 | 仕様番号 |
| --- | --- | --- |
| 仕様 | 数値リテラル（整数・小数）をトークンとして認識する | 【Calc_R01.DM01-01】 |
| 仕様 | 演算子（+, -, *, /）をトークンとして認識する | 【Calc_R01.DM01-02】 |
| 仕様 | 括弧（(, )）をトークンとして認識する | 【Calc_R01.DM01-03】 |
| 仕様 | 不正な文字が含まれる場合はエラーを返す | 【Calc_R01.DM01-04】 |

8. Excel 生成

md2usdm examples/calc

---

チェックリスト

Excel 生成前に以下を確認する:

• コンポーネントファイル（{プロジェクト名}.md）が存在し、# 【{名前}】 の見出しがある
• 各シートの index.md に ## 下位要求 があり、上位要求へのリンクが正しい
• 各上位要求ファイルに ## 下位要求 があり、下位要求へのリンクが正しい
• 各下位要求ファイルに ## 仕様 テーブルがある
• 仕様番号が 【{ID}-{連番}】 形式で、下位要求内で連番が重複していない
• 理由・説明が空の場合は 記載無し と記載している
• ナビゲーションリンク（↑）が各ファイルの 1 行目にある
• リンクの相対パスが正しい（./ や ../ の階層が合っている）

---

実在する完成例

USDM ツールリポジトリの examples/ ディレクトリに完成例が 2 つある:

ディレクトリ	対象	シート数	上位要求	下位要求	仕様数
examples/md2usdm/	md2usdm.py（Markdown→Excel変換）	3	9	12	69
examples/usdm2md/	usdm2md.py（Excel→Markdown変換）	3	7	11	77

これらのファイルを参考にして、記述スタイルやファイル構成を模倣すること。