generate-requirement-drafts

要件ドラフトの生成

環境でサポートされている最も充実したアーティファクトを使用して、Simulink モデルから要件のドラフトを生成します。すべての出力はドラフトであり、ベースライン化の前に人によるレビューと承認が必要です。

使用する場合

• Simulink モデルから要件をドラフトまたは更新する場合
• .slreqx または .yaml の要件アーティファクトを作成する場合
• モデルと要件のトレーサビリティを確立する場合

使用しない場合

• 既存の信頼できる情報源（ReqIF、DOORS、Word、Excel）から要件をインポートする場合 — Requirements Toolbox のインポート API を直接使用してください
• テストを作成または実行する場合 — testing-simulink-models スキルを使用してください
• 保存するアーティファクトのない自由形式の文章メモの場合
• ユーザーが別のテキスト形式（markdown、Word）を明示的に希望している場合

出力規約

• デフォルトのファイル名：<Model>_Requirements.slreqx または <model>_requirements.yaml
• 安定した ID：REQ_<SYSTEM>_001、REQ_<SYSTEM>_002、… — サブシステムごとに異なる場合でも、プロジェクト全体で一貫した単一のプレフィックスを使用し、すべての要件に通し番号を付けます。サブシステムごとのプレフィックスや階層的な小数点番号（例：CB-1.1、TP-1.1）に切り替えないでください。
• .slreqx または .yaml ファイルがすでに存在する場合は、リポジトリの規約に従ってください
• 既存のアーティファクトを更新する場合は既存の ID を維持し、新しい ID を追加してください。番号を振り直してはいけません
• 生成するすべての要件にドラフトのマークを付けてください — Keywords に "draft" を使用するか、YAML で status: Draft と keywords: [draft] を使用します

良い要件の書き方

要件にはモデルのトポロジー（どのように実装されるか）を言い換えるのではなく、振る舞いの意図（システムが何をするべきか）を記述します。理由は Rationale に記載します。**EARS（Easy Approach to Requirements Syntax）**パターンを使用してください。

EARS パターン

モデルの振る舞いに最も適したパターンを選択してください。

パターン	テンプレート	使用する場合
ユビキタス	The <system> shall <response>.	常時有効な振る舞い、不変条件
イベント駆動	When <trigger>, the <system> shall <response>.	一時的なトリガーが一度限りの応答を引き起こす場合：入力イベント、Stateflow 状態への遷移（遷移そのもの）
状態駆動	While <state>, the <system> shall <response>.	Stateflow の状態またはモードにある間、継続的に維持される振る舞い — 遷移時の応答ではなく、継続的な応答
望ましくない振る舞い	If <condition>, then the <system> shall <response>.	エラー処理、安全制限、飽和
オプション機能	Where <feature>, the <system> shall <response>.	バリアントサブシステム、設定可能な機能
複合	While <state>, when <trigger>, the <system> shall <response>.	状態とイベントの組み合わせ

例 — モデルの概念から EARS 要件へ

❌ 悪い例 — 実装を言い換えている	✅ 良い例 — EARS パターン
"Saturation block limits output to [0,1]"	"スロットル指令が ThrottleMax（1.0）を超えるか、ThrottleMin（0.0）を下回る場合、コントローラーは出力を有効範囲内に制限するものとします。"
"BrakeLogic subsystem disengages controller"	"ブレーキペダル入力が BrakeThreshold（0.0）を超えたとき、コントローラーはクルーズコントロールを解除するものとします。"
"Gain block multiplies by 2.5"	"クルーズコントロールが有効な間、コントローラーは速度誤差に Kp（2.5）を乗じて比例補正を算出するものとします。"
"Stateflow chart transitions to Idle"	"ドライバーがオフボタンを押したとき、システムは Idle 状態に遷移するものとします。"
"Defrost state runs the heater at full power"	"Defrost 状態にある間、システムはヒーターを最大出力で動作させるものとします。"
"Variant subsystem selects Algorithm A"	"アダプティブモードが有効な場合、コントローラーは予測アルゴリズムを使用するものとします。"

ルール

• モデルの動作に合ったパターンを選び、EARS パターンを使って要件を記述します
• ブロック／サブシステム名（例：Saturation、BrakeLogic）は Rationale、Description、または出典に関する注記でのみ使用し、要件の Summary では決して使用しません。（VarName (value) の形式で表示されるワークスペースのパラメーターは、Summary に記載する必要があり、ブロック名ではありません。）
• 数値を参照する場合は、ワークスペース変数名と解決後の値を含めます：VarName (value)。モデルで変数を使わずリテラルを使用している場合は、その数値リテラルを直接記録します
• 要件文ではなく、Rationale に理由を記載します
• 1 つのサブシステムが、動作要件を 0 個、1 個、または複数個支える場合があります。1 対 1 の対応を無理に求めないでください
• Stateflow の状態またはモードについては、その状態への遷移とその状態にある間の動作を分けます。状態への遷移はイベント駆動型（When <trigger>, … shall transition to <state>）ですが、モード全体で維持される動作は状態駆動型（While <state>, … shall <response>）です。モードの動作を求められた場合は、While <state> 形式を優先し、状態への遷移を表す When 文にまとめないでください

バックエンドの選択ゲート

最初に一度選択し、その後は選択した方法を継続します。

状況	バックエンド
ユーザーが .slreqx またはトレーサビリティビューを明示的に求めている、あるいはリポジトリですでに .slreqx を使用している	Requirements Toolbox — プローブに失敗した場合は、Requirements Toolbox が利用できないことをユーザーに伝えます。黙って切り替えてはいけません
ユーザーが .yaml を明示的に求めている、あるいはリポジトリですでに .yaml の要件を使用している	Structured YAML
形式が指定されていない — Requirements Toolbox のプローブを実行します	プローブに成功した場合は Requirements Toolbox
形式が指定されておらず、プローブに失敗した場合	Structured YAML（ユーザーに希望がなかった場合は、黙って切り替えてもかまいません）

プローブ（evaluate_matlab_code で実行）：

hasSlreq = ~isempty(which('slreq.new'));
if hasSlreq, try, slreq.find(Type="Link"); catch, hasSlreq = false; end, end
disp(hasSlreq)

ワークフロー

• model_overview、model_read、model_query_params、model_resolve_params は MCP ツールとして呼び出します。それらの名前を evaluate_matlab_code に渡してはいけません
• evaluate_matlab_code は、バックエンドのプローブや Path A の slreq.* API など、MATLAB コードにのみ使用します

1. モデルを理解する — model_overview ツールと model_read ツールを使って、サブシステム、インターフェイス、制御ロジックを理解します。

2. パラメーターを抽出する — model_query_params／model_resolve_params ツールを使い、要件の文面に含めるしきい値、ゲイン、サンプル時間を取得します。変数名と解決後の値の両方を記録します。

3. 取得テーブルを作成する（バックエンドに依存しません）：

   Id	ParentId	Summary	Description	SourceBlock	Rationale	ASIL	Priority	Keywords

4. バックエンドの方法を実行する（以下の A または B）。

5. 以下のゲートに従ってレビューする。

Path A — Requirements Toolbox（.slreqx）

プローブに成功した場合に使用します。API の詳しいパターンについては、references/slreq-patterns.md を参照してください。

model = "CruiseControl";
load_system(model);
rs = slreq.new(model + "_Requirements");

% Add requirements with hierarchy — note behavioral "shall" statements
req = add(rs, Id="REQ_CC_001", ...
    Summary="If throttle command exceeds ThrottleMax (1.0) or falls below ThrottleMin (0.0), then the controller shall clamp the output to the valid range.", ...
    Description="Derived from CruiseControl/ThrottleCmd.");
req.Rationale = "Prevents invalid actuator commands that could damage the throttle body.";
req.Keywords = ["draft","auto-generated","control","safety"];

child = add(req, Id="REQ_CC_002", ...
    Summary="When brake pedal input exceeds BrakeThreshold (0.0), the controller shall disengage cruise control.", ...
    Description="Derived from CruiseControl/BrakeLogic.");
child.Keywords = ["draft","auto-generated","safety","brake"];

% Create traceability links: use block handle from SID (blk_X → X) for robustness
lnk = slreq.createLink(Simulink.ID.getHandle(model + ":5"), req);
slreq.createLink(Simulink.ID.getHandle(model + ":8"), child);

save(rs);
% Save all link sets
linkSets = slreq.find(Type="LinkSet");
for i = 1:numel(linkSets), save(linkSets(i)); end

リンクのルール：

• Source = model element、destination = requirement の場合、リンクタイプは自動的に Implement になります
• サブシステムレベルのリンクを優先し、要件が特定のブロックに限定される場合にのみブロックレベルのリンクを使用します
• モデルから導出したすべての要件には、少なくとも 1 つのトレーサビリティリンクが必要です
• ブロックパスを使ってリンクを作成する前に、モデルを読み込み（load_system）必要があります

Path B — Structured YAML へのフォールバック

Requirements Toolbox が利用できない場合に使用します。スキーマとフィールドのルールについては、references/yaml-requirements.md を参照してください。

1. 取得テーブルから <model>_requirements.yaml ファイルを生成します
2. status: Draft を設定し、各要件の keywords に draft を含めます
3. 自己レビューを行います。必須フィールドがすべて設定されていること、asil／status／priority が有効な値であること、ID が連続していること、derived_from が有効な ID または null を参照していることを確認します
4. 検証します：

python -c "import yaml, sys; yaml.safe_load(open(sys.argv[1])); print('OK')" path/to/requirements.yaml

ガードレール

必ず行うこと	行ってはいけないこと
生成するすべての要件に DRAFT を付ける	.slreqx が利用可能で、テキスト形式が要求されていない場合に、Markdownやその場しのぎのテキストを出力する
EARS パターンを使用して要件を記述する	ブロックのトポロジーを要件の要約として言い換える
パラメーター名と値を含める：VarName (value)	ユーザーが両方を求めていない限り、.slreqx と .yaml の両方を作成する
リンクの方向：モデル要素 → 要件	リンクの方向を逆にする（要件 → ブロック）
トレーサビリティリンクを作成する前に load_system を実行する	すべてのプリミティブブロックに過剰にリンクする — サブシステムへのリンクを優先する
R2023a以降のAPIのみを使用する	ユーザーが明示的に .slreqx を要求した場合に、黙って YAML に切り替える
既存のリポジトリ形式との一貫性を保つ	再生成時に既存の要件 ID を振り直す

レビューチェック

完了前に、両方のバックエンドについて次を確認してください。

• すべての要件に Id、Summary、Description がある
• すべての要件に DRAFT が付いている（Keywords またはステータスフィールドを使用）
• 要約は、ブロックのトポロジーを言い換えたものではなく、EARS パターンを使用している
• ワークスペース変数がある場合、数値にはパラメーター名と値が含まれている
• ID は安定しており連番になっている。再生成時には既存の ID が保持されている

slreq の場合のみ：

• モデルから導出された要件に、ソースモデル要素へのトレーサビリティリンクがある
• リンクの方向がモデル要素 → 要件になっている（逆向きではない）
• ブロックレベルよりサブシステムレベルのリンクが優先されている
• 要件セットとすべてのリンクセットが保存されている

YAML の場合のみ：

• ファイルがエラーなく解析できる
• asil と priority が有効な列挙値を使用している（不明な場合は Unset）

参考資料

• references/slreq-patterns.md — Requirements Toolbox API クックブック
• references/yaml-requirements.md — 構造化 YAML スキーマとフィールドのルール
• assets/slreq_from_model.m — slreq の一連の処理を示す例
• assets/requirements.yaml — 構造化 YAML の例

---

Copyright 2026 The MathWorks, Inc.

---