filing-bug-reports

バグ報告の作成

問題の再現に必要な情報をすべて受け取る側の開発者に伝える、自己完結型のバグ報告を Markdown ファイルとして作成します。根本原因や解決策を指示してはいけません。

使用する場合

• ユーザーがバグの報告、作成、記録を求めている
• ユーザーが別の開発者に不具合の調査を引き継ぎたい
• ユーザーが予期しない動作を再現可能な記録として残したい

使用しない場合

• ユーザーが今すぐ自分でデバッグして修正したい場合 — 直接支援してください
• ユーザーが設計レビューやコードレビューを求めている場合 — 代わりに code-review スキルを使用してください

出力規約

• ファイル： issues/BUG-<NNN>-<slug>.md（次に利用可能な番号を使い、タイトルからケバブケースのスラッグを作成）
• issues/ ディレクトリが存在しない場合は、作成します
• 1 ファイルにつき 1 件のバグ — 複数のバグをまとめてはいけません

ワークフロー

1. 会話の文脈から状況を再構成します。 バグが発生したとき、あなたはその場にいました。会話履歴から次の情報を抽出してください。

   • ユーザーが行っていたこと（操作と意図）
   • 実際に起きたこと（エラーメッセージ、ツールの出力、予期しない動作）
   • 期待されていたこと（ユーザーの目的から推測します。たとえば、モデルの読み込みを依頼してエラーになった場合、期待される動作は正常に読み込めることです）

2. 環境の詳細をプログラムで収集します。 調べられる情報をユーザーに尋ねないでください。

   • エージェントのワークスペースのルート、OS、アーキテクチャ：システムコンテキストから取得します

   スキルの状態を表す用語。 スキル仕様では段階的な開示を採用しています。メタデータ（名前と説明）は常にコンテキストに含まれ、本文はスキルが呼び出された場合にのみ読み込まれます。以下の用語は観察可能な状態を表し、エージェントの種類に依存しません。Claude Code に限らず、Agent Skills 標準を実装するホストであればどれでも当てはまります。

   • 登録済み — このセッションで、ホストエージェントの利用可能なスキル一覧にスキルが表示されている状態です。

   • 説明あり — 登録済みで、メタデータに空ではない description がある状態です。（デフォルトの状態で、記号はありません。）

   • 名前のみ（⊘）— 名前だけで登録され、エージェントの登録エントリーに description フィールドがない状態です。名前のみのスキルを記録したら、そこで止めてください。説明の有無を確認するために、ディスク上の SKILL.md ファイルを読んではいけません。バグ報告で記録する状態は、利用可能なスキル一覧に表示されているものだけです。ソースのフロントマターを読むことは原因調査にあたり、対象範囲外です。

     注：ホストエージェントによっては、スキルのテキスト全体が内部の予算を超えると、一覧から説明が自動的に削除されます。たとえば、Claude Code ではコンテキストウィンドウのサイズに応じた文字数の予算が設定されており、その予算を超えると、最後に呼び出されたスキルから順に説明が削除されます。そのため、多数のスキルが読み込まれたセッションで名前のみになるのは、SATK の不具合ではなく、ホストの想定される動作であることがよくあります。状態は記録しますが、同じスキルが予算を明らかに超えていないセッション（スキル数が少ない場合、またはホストが切り詰めを報告していない場合）でも名前のみでない限り、「SATK のスキル登録が壊れている」といった形でバグ報告しないでください。

   • 呼び出し済み（▶）— このセッションで、スキルの本文がエージェントのコンテキストに読み込まれた状態です。

   • 未登録の SATK スキル（✗）— ツールキットの skills-catalog/ 内に SKILL.md が存在するにもかかわらず、利用可能なスキル一覧に表示されない状態です。✗ の対象は SATK のみです。他のソースの未登録スキルは追跡しません。 これらの定義に基づき、次の手順を実行してください。

   • スキル（スタックビュー）：利用可能なスキルの一覧を直接読み取り（過去のバグ報告やドキュメントは参照せず）、用語集に従って登録済みの各スキルを記載してください。✗の場合は、ツールキットのルートにある SATK スキルマニフェストも参照し、そこに宣言されているスキルのうち、登録済みの一覧にないものを記載してください。assets/bug-report-template.md の Skills サブセクションに従って出力してください。

   • スキルの競合分析：SATK の model-based-design-core スキルのうち、本文がすでにコンテキストに含まれているものだけを対象にしてください。また、作業中にそれらの間でこのバグに関連する可能性のある競合に気付いた場合に限ります。競合を探すためにスキル本文を読み直さないでください。自然に気付いた競合がなければ、「N/A — 」と記載してください。

   • 利用可能な MCP ツール：利用できる MCP ツールを一覧にしてください。

   • 関連するソースファイル：失敗に関係するファイルを読み取ってください。

   SATK 固有の項目（Simulink MCP ツールが利用可能な場合）：

   • SATK のバージョン：SATK のルートにある VERSION ファイルを読み取ってください。存在せず、.git/ フォルダーがある場合は、最新のコミットハッシュを読み取り、「開発ビルド（）」と記載してください。どちらも存在しない場合は、使用中の Simulink Agentic Toolkit のバージョンをユーザーに尋ねてください。
   • MATLAB：evaluate_matlab_code → disp(version); ver('simulink'); disp(pwd); disp(computer('arch'))
   • SATK ツールボックスの状態：evaluate_matlab_code → which('model_read')（出力が空の場合、ツールボックスはインストールされていません）
   • コネクター：evaluate_matlab_code → try; disp(connector.securePort); catch; disp('not running'); end
   • MCP の設定：.vscode/mcp.json を読み取り、サーバーモードとバイナリパスを確認してください。
   • レイアウトの問題で、SATK の状態に問題がない場合：最初に匿名化されたレイアウト情報の共有に同意するかユーザーに尋ねてから、evaluate_matlab_code → layout.LayoutStateManager.instance().getAnonymizedLayoutSnapshotsPath() を実行してください。ユーザーの許可を得た場合、getAnonymizedLayoutSnapshotsPath が返したパスにあるファイルの内容を読み取らず、ツール呼び出しを使ってこの非常に大きなファイルをバグ報告に直接追記してください。

3. バグを再現します。 失敗した操作を再実行し、再現可能であることを確認して、正確な出力を記録してください。再試行で成功した場合は、断続的に発生することを記載し、何が異なるのか特定してください。

4. 最小限の再現手順に絞り込みます。 バグの発生に不要な手順、ファイル、変数をすべて取り除いてください。失敗を引き起こす最小の入力を見つけることが目標です。

5. ユーザーには、特定できない情報だけを尋ねてください。

   • 期待される動作 — 出力が妥当に見える一方で、ユーザーが誤りだと言っており、何が正しいのか判断できない場合に限ります
   • 深刻度／ビジネスへの影響 — 曖昧な場合に限ります（明らかなクラッシュは明らかに高く、書式上の軽微な問題は明らかに低くなります）
   • このセッション外の情報 — ユーザーが、このセッションでは確認できなかった情報に言及した場合

6. 報告書を作成します。 assets/bug-report-template.md のテンプレートを使用してください。必須セクションをすべて記入してください。該当しない任意のセクションには「N/A」と記載してください。

7. 保存前に確認します。 次の点を確認してください。

   • プロジェクトに詳しくない開発者でも、質問をせずに手順をたどれること
   • 根本原因や修正方法が記載されていないこと（所見や仮説は Notes セクションのみに記載すること）
   • エラーメッセージとログが言い換えではなく、正確なコピーであること
   • タイトルが次の形式に従っていること：[Area] — Action — Unexpected result

ガードレール

• 必ず実行すること： 既知のクリーンな状態から始まる、正確な再現手順を含めてください
• 必ず実行すること： エラーメッセージとログ出力を逐語的に含めてください（決して言い換えないでください）
• 必ず実行すること： 環境（バージョン、OS、プラットフォーム）を明記してください
• 禁止事項： 根本原因を断定しないでください。原因の調査は調査担当者が行います
• 禁止事項： 報告書本文で修正方法を提案しないでください（仮説は Notes にのみ、推測であることを明記して記載してください）
• 禁止事項： シークレット、トークン、パスワード、個人を特定できる情報（PII）を含めないでください。<REDACTED> で伏せてください

参考資料

• assets/bug-report-template.md — 出力テンプレート（必ずこの構成を使用してください）

---

Copyright 2026 The MathWorks, Inc.

---