DXエンジニア向け仕様駆動開発_20261124

DXエンジニアのための仕様駆動開発 Claude Code × Docker × モックで、仕様から試験報告まで うさうさ研修工房｜YouTube／Udemy 兼用・実務講座

この講座のゴール（6つ） STEP1 受講資料 1. 要求を、機能・非機能・受け入れ基準（FR・NFR・AC）に分け、試験できる形にする 2. 仕様・決定（ADR）・未確定事項（OQ）を、目的ごとに分けて管理する 3. Docker の開発環境を作り、フォルダを安全に共有する 4. モックでAPI連携を試験し、失敗を種類ごとに扱う 5. Claude Code に、仕様を先に直す約束を守らせて作業する 6. 試験結果を、仕様の番号に結びつけて報告する 出典：08_corporate-course/00_course-plan.md §2 2

全体の地図：8つのSTEP 講師の整理 難度9 難度6 難度5 難度4 STEP7 Claude Codeに守 らせる 難度3 難度2 STEP5 STEP4 難度1 STEP3 STEP2 STEP1 なぜDXで仕様が要 るか 要求を試験できる 形に 仕様・決定・未確 定を分ける 同じ環境を再現す る モックで連携を試 す 難度3 STEP6 3つの層で試験する STEP8 現場へ持ち帰る 難度は講師の設計（山場はSTEP7）。分数は目安 3

DXの現場で起きる3つのこと STEP1 講師の整理 依頼は「言葉」で来る 合意の理由が消える 報告が「できました」だけ 「一般的な形式」「3時間 ほど」「迷わない」。どこ までできれば完了か、誰に も言えない。 なぜそう決めたかが残らず 、半年後に同じ議論をやり 直す。 何を確かめたのか、何を確 かめていないのかが、読み 取れない。 具体例は受講資料（書籍 第1章）の題材より 4

業務で守る4つの約束 STEP1 受講資料 区分 ルール 秘密情報 APIキーは環境変数などで渡し、ソースや画面に書かない 機密データ 業務の音声・文書を、許可されていない外部サービスに送らない 本番利用 模倣で合格した後、社内の承認を得てから、少量で確かめる 記録 試験結果と報告書に、キーや個人情報を含めない 出典：00_course-plan.md §5。社内規程が優先 5

要求を3つに分ける STEP2 受講資料 区分 意味 例 機能要件 FR 何ができるか FR-03 長い音声を分割して処理する 非機能要件 NFR どれくらい、どの環境で NFR-02 メモリ4〜8GBのPCで抑える 受け入れ基準 AC 完了を判定する文 AC-03 2分の音声を1分単位で処理すると2区 間になる 出典：書籍 第2章（07_spec-driven-book） 6

良い受け入れ基準の条件 STEP2 受講資料 悪い例 良い例 分割できること 2分の音声を1分単位で処理すると、見出しが2つ付く エラーがわかりやすいこと 認証に失敗すると「APIキーが正しくありません（401）」 と表示される 速いこと 1区間の変換が、10分の音声で3秒以内（測定方法を書く） 迷わないこと 3操作（選択・開始・取得）で結果が得られる 出典：特典4 受け入れ基準の書き方チェック。数字は例 7

演習1：議事録の依頼を分解する STEP2 動画を止めて取り組む（目安 10分） 講師の整理 区分 解答例 依頼 「会議の録音から、議事録の下書きを早く作れるようにしてほしい。内容は外に漏 らさないこと。」 NFR-01 録音終了から10分以内に下書きが表示される（測り方：終了時刻と表示時刻をログ で測る） NFR-02 音声の送信先は、社内で許可されたサービスのみ。保存期間は○日（数値は要確認 ） AC-01 30分の録音を渡すと、下書きが1件出力される。出力に見出しが1つ以上ある OQ-01 許可されたサービスの範囲は未確定。確認方法：情報セキュリティ担当へ照会／担 当：自分 課題は演習1。右列は解答例（唯一の正解ではない） 8

仕様の4つの置き場 STEP3 受講資料 仕様 決定（ADR） 未確定（OQ） 実測の記録 FR・NFR・ACの表 と状態。仕様が変わ るとき更新 決めたことと理由。 判断が変わるとき追 記 まだ決まっていない こと。確認できたと き更新 測った数字と測り方 。測り直したとき更 新 出典：書籍 第3章 9

状態を正直に書く STEP3 受講資料 記号 意味 書く場所の例 実装済み・試験済み 仕様の状態欄 実装済み・一部未検証 仕様の状態欄＋OQ 未達（できていない） 仕様の状態欄＋ADR（代替案と当面の 対策） 未着手 仕様の状態欄 出典：特典1 仕様書テンプレート／書籍 第3・4章 10

ADRとOQの書き方 STEP3 受講資料 ADR-004：ブラウザで全体を展開する方式は、 3時間の要件を満たさない 状態：未達（FR-04、NFR-02） 背景：decodeAudioData は音声全体を 非圧縮で展開する 代替案：A ストリーミング B ffmpeg.wasm C 利用者による事前分割 当面の対策：ADR-009（事前分割の運用） OQ-01（未解消） 未確定：APIの項目名・版（仮定のまま） 影響：FR-02 確認方法：公式で確認し、1件だけ 送って形を確かめる 担当：自分 ルール：解消しても消さない。 「解消（日付・結果）」と書く 出典：特典2・3・書籍 第4章（ADR-004の例） 11

Docker：フォルダを共有する STEP4 動画を止めて取り組む（目安 5分） 受講資料 # 演習3 echo "hello" > host-check.txt docker run --rm -v "$PWD:/work" -w /work \ <イメージ名> sh -c "echo from-container > c.txt" 要点（受講資料より） 1. バインドマウントは既定で読み書き可 → コンテナ内の変更はホストに反映 2. -v を付けないと、ホストのフォルダは見えない 3. WSL 2 では、プロジェクトを Linux 側 のファイルシステム（例：~/）に置く 4. 業務ファイルを Windows 側に置くと 遅くなることがある cat c.txt ※コマンドは設計例。講座内で実行確認します docker run --rm -v "$PWD:/work" -w /work \ <イメージ名> cat host-check.txt 公式：docs.docker.com の Bind mounts／WSL best practices（受講資料の確認記録 2026-11-13。今回は再確認していません） 12

チャット型APIの形と、モック STEP5 未確認 向き 項目（受講資料の説明） メモ 送る 認証ヘッダー／model／messages（role と content の組） キーは環境変数から 受け取る choices の先頭の message.content に返事／ usage 応答の形を確かめてから使う 模倣との違 い 値は本物と同じとは限らない。usage は文字数 で近似 模倣の目的は、本物を使わず 送信処理と画面を試すこと R7 OpenAI Chat Completions リファレンス。項目名・usage の数え方は変わりやすい＝公式最新版で要確認 13

失敗の種類と、再試行の可否 STEP5 実行確認済み 種類 再試行 理由 401（認証） しない キーを直さない限り同じ結果 429（上限） する 時間を置けば回復するかもしれない 5xx（障害） する 一時的な障害の可能性 通信断・タイムアウト する 一時的な失敗として扱う 形式不正（JSONでない 等） しない 同じ入力を送っても直らない HTTPの一般的な意味。サンプルキットの app/retry.py を実行して確認（4件合格） 14

試験の3つの層 STEP6 講師の整理 本物で少量確認 承認後・1件だけ。少なく・高い 画面の試験（Playwright） ブラウザで操作。送信・案内・無害化 契約の試験（unittest等） 速く・安く・多く。送る形・認証・失敗の扱い 下ほど 速く・安く・多く 出典：受講資料 L07（契約・画面）に、本物での少量確認を加えた整理 15

試験名に番号を付ける STEP6 実行確認済み class Contract(unittest.TestCase): def test_AC_02_429_stops_at_3_tries(self): r = send_with_retry(lambda: 429, sleep=nosleep) self.assertEqual( r, {"tries": 3, "kind": "rate_limit"}) 壊しに行く試験の例（書籍 第6章） 1. 拡張子が mp3 でも中身が文字のファイル 2. 途中で切れた WAV 3. 本文の途中で切れた応答 4. 開始ボタンの連打 5. HTML を含むファイル名 「壊れない」は判定できる形で書く 例：例外で止まらない／案内を出す／ 二重に送らない 左：サンプルキット tests/test_contract.py（実行確認済み）。右：書籍 第6章 16

デモ：仕様照合表を機械が作る STEP6 実行確認済み AC 要件 正常時 不具合を入れた時 受け入れ基準 AC-01 FR-02 合格 合格 401は再試行せず1回で止まる AC-02 FR-03 合格 不合格 429が続くと3回で止まる AC-03 FR-03 合格 合格 503の後に200で、2回目でok AC-04 FR-02 合格 合格 想定外の状態418は再試行しない AC-05 NFR-01 未実施 未実施 待ち時間が試行ごとに増える サンプルキット run_tests.py → trace.py を実行。上：正常／下：429を再試行しない不具合を意図的に入れた場合 17

山場：AIの約束は「文脈」 STEP7 公式 CLAUDE.md は文脈 具体的で簡潔に 強制したいなら仕組みで CLAUDE.md と auto memory は毎回の開始時に 読み込まれるが、強制され る設定ではなく「文脈」と して扱われる（公式） 指示が具体的で簡潔なほど 、守られやすい（公式） 行動を確実に止めたいとき は PreToolUse フック等を 使う（公式）。権限は settings の permissions 公式：code.claude.com/docs/en/memory（2026-11-14 確認） 18

CLAUDE.mdの書き方（公式） STEP7 公式 論点 公式の記述（要約） 読み込み 作業ディレクトリより上の階層の CLAUDE.md は起動時に読む。サブディレ クトリのものは、そこのファイルを扱うときに読む 長さ 1ファイルあたり200行未満が目安。長いと遵守率が下がる。一部にだけ要る 指示は path-scoped rules へ 分割 @path/to/file で他のファイルを取り込める（相対パス・最大4段） 矛盾 指示が矛盾すると、どちらかが任意に選ばれることがある。定期的に見直す 始め方 /init で初期の CLAUDE.md を自動生成できる 公式：code.claude.com/docs/en/memory（2026-11-14 確認）。表現は要約 19

権限で守る：denyと、その限界 STEP7 公式 論点 公式の記述（要約） 書き方の例 Read(./.env) や Read(./secrets/**) の deny ルールで、ファイルツールの読 み取りを止める 評価順 deny → ask → allow の順。最初に一致したものが結果。allow で deny の例 外は作れない 置き場所 プロジェクト設定は .claude/settings.json。チームで共有できる 限界 Read の deny は、ファイルを名指ししないコマンド（例：grep -r）や、スク リプトが自分でファイルを開く場合には効かない より強く 全プロセスを止めたいときは、サンドボックスを有効にする 公式：code.claude.com/docs/en/permissions（2026-11-14 確認）。表現は要約 20

★ハンズオン：仕様を先に直させる STEP7 動画を止めて取り組む（目安 15分） 未確認 ★1 CLAUDE.md と deny を置く - 読む仕様：docs/spec.md ほか - ルール1：仕様を変えるときは先に spec.md - ルール6：完了報告は ACの番号ごと - .claude/settings.json に Read の deny ★2 次の指示を出す 「実装の前に docs/spec.md の該当要件と ACを更新して。実装はまだ始めないで」 完了報告の指示（特典8） 「完了を報告するときは、関係する受け入れ基準を 番号ごとに、合格・不合格・未実施で書いて。 実行していない試験を合格と書かないで」 確かめること 1. spec.md が先に変わったか 2. 報告が AC 番号ごとか 3. 未実施が正直に書かれているか 4. 照合表（trace.py）の結果と報告が一致か プロンプトは受講資料 特典8・CLAUDE.md は特典6。Claude Code上での実行は今回未確認（収録時に必ず通し確認） 21

現場に持ち帰る：3つの確認 STEP8 受講資料 配る前に3つ 証跡を残す 版を番号で管理 1. キーや音声が入っていな い 2. 試験結果と未確認が 分けて書いてある 3. 仕様 と試験の番号が一致 試験の実行ごとに、結果と 報告書を日付のフォルダへ 。判定欄は人が記入 zipに番号と版を付ける。 Gitは版ごとにタグ。変更 内容は仕様の変更履歴へ 出典：書籍 第9章（配布と証跡）。承認フローは各社の規程に従う 22

よくある失敗パターン（抜粋6） STEP8 受講資料 No. 失敗 対処 1 要求をそのまま仕様にした FR・NFR・ACに分解し、番号を振る 2 仕様に「できた」と書いた（未達なのに） 未達は 3 推測を確定値として書いた OQに移し、確認方法を書く 6 正常系だけ試験した 壊しに行く試験を仕様の一部にする 8 結果を人が書いた 結果はJSONから機械的に作る 12 AIに「できました」と言わせた ACの番号ごとに報告させる とADRに残す 出典：特典7 失敗パターン集（12件のうち6件） 23

修了課題と採点 STEP8 動画を止めて取り組む（目安 60分） 受講資料 区分 必須項目 配点 仕様 ACに入力・結果・判定があり、番号が付く／数字に測り方 25 未確定・決定 OQ 2件以上／ADR 1件（代替案2つと根拠） 25 試験 ACと試験名が対応／失敗（401・429等）の試験 25 報告・ CLAUDE.md 未実施・未確認を正直に／完了の定義と番号ごとの報告 15 秘密（必須） 提出物にキーや個人情報が1つでもあれば不合格 必須 出典：assessment/final-assessment.md（合計90点。70点以上＋秘密の項目） 24

次の案件で最初にやる8つ STEP8 受講資料 1. 要求を、FR・NFR・ACに分けて表にする 2. 未確定事項を、OQとして書き出す 3. 大きな決定を、ADRとして書く 4. フォルダの構成を決め、仕様の置き場所を作る 5. 受け入れ基準の番号を、試験の名前に付ける 6. 最初の受け入れ基準を満たす、小さな機能から作る 7. 試験の結果を、JSONにまとめる 8. 結果を、仕様の照合表に結びつける 出典：書籍 第11章 25

確認したこと／未確認のこと 公式 区分 内容 確認した（公式） CLAUDE.md の読み込み・200行目安・@import・文脈であること／Read の deny・評価順・限界（2026-11-14） 確認した（実行） サンプルキット：試験4件合格、不具合を入れると AC-02 が不合格、AC05 は未実施と出る 受講資料の記録に 依存 Docker・WSL の記述（2026-11-13 確認の記録。今回再確認なし） 未確認 OpenAI の項目名・usage／Claude Code 上のハンズオン全体／R9〜R12 の本文／実APIでの動作 出典：code.claude.com/docs/en/memory・/permissions（2026-11-14）／docs.docker.com／learn.microsoft.com／platform.openai.com 26

この資料の使い方 講師の整理 1. スライド1〜26は講師用と同じ番号です。台本の【スライドN】と対応します 2. の場面（8・12・21・24）は、動画を止めて手を動かしてください 3. 青字の「公式」は公式の事実、「講師の整理」は講師の解釈です。分けて読みましょう 4. 「未確認」の印は、受講前に公式で確かめてください 5. 演習の解答例は唯一の正解ではありません 受講生用のみ。講師用と番号は同じ（27以降が追加） 27

考えてみよう（5問） 講師の整理 1. 「迷わないこと」を、試験できる受け入れ基準に直すと？ 2. 未達の機能を、仕様の表と ADR にどう書きますか 3. 429 は再試行し、401 は再試行しない理由は？ 4. CLAUDE.md に「キーを読むな」と書けば、読まれないと言えますか 5. AI が「できました」と報告したとき、最初に何を求めますか 答えの目安は次のスライド 28

答えの目安 講師の整理 1. 例：3操作（選択・開始・取得）で結果が得られる。入力・結果・判定があるか確認 2. 状態欄に 、ADRに代替案と当面の対策。「できた」と書かない 3. 429は時間を置けば回復しうる。401はキーを直さない限り同じ結果 4. 言えない。CLAUDE.mdは文脈で強制ではない（公式）。deny等の仕組みで止める。限界も ある 5. 受け入れ基準の番号ごとの合否と、実行した試験の結果。未実施は未実施と 目安であり、唯一の正解ではない 29

用語集 講師の整理 用語 意味 FR / NFR / AC 機能要件／非機能要件／受け入れ基準 ADR 決めたことと理由の記録（Architecture Decision Record） OQ 未確定事項（Open Question）。確認方法と担当を書く モック 本物の代わりに決まった規則で応答する練習用サーバー バインドマウント ホストのフォルダをコンテナに割り当てる仕組み deny ルール 指定した操作を止める権限設定。評価順は deny→ask→allow 講座内での意味 30