JBS 中級コース 案1
JBS 中級コース 案1
到達点は、1 本の API を設計書から実装し、生成コードを設計書と照合し、実装の根拠を説明できる状態です。残りの実装は Claude に任せ、レビューに回ります。
Day1 完成版から全員同一の起点へ。検証サイクルの確認。[10分]
骨格は一括生成。生成後に ER 図とカラム単位で照合。[25分]
POST /tickets を repository→service→router で実装。[40分]
生成実装を設計書と照合し、受け入れ可否を判定。[15分]
10分
実装は Claude に委譲。誤実装の検出。非開発業務も参加可。[35分]
境界値を指定し、保証内容を言語化。[25分]
Swagger 確認。根拠の説明。トークン消費の振り返り。[15分]
持ち帰る3点と Day3 への宿題。[5分]
Day1 アンケートで多かった「生成物を検証しきれない」「説明責任が持てない」への回答として、Day2 の進め方を組み直しました。
Day1 の到達度には差があったため、Day2 は全員を同じ起点に揃えます。講師が品質を整えた Day1 完成版の設計書を配布します。第1回の各自の作業は day1-myown ブランチに残り、後から参照できます。
自分の Fork リポジトリに、配布された day2-start.zip を取り込みます。次の手順を画面で一緒に進めます。git コマンドは VSCode 下部のターミナルで実行します。Windows / Mac で同じです。
1. 第1回の作業を退避する
2. day2-start.zip を展開する — Finder / エクスプローラで解凍し、中身をリポジトリ直下に上書きコピーします（Windows / Mac 共通の操作）。
3. Day2 の作業ブランチを作る
実行中の操作は Ctrl + C でキャンセルします。現在地は pwd、ブランチは git branch --show-current で確認します。長い出力で画面が止まったら q で抜けます。迷ったら手を止めて講師に声をかけてください。
「プロンプトを打つ → 出力を Apply する → 次へ」は繰り返しません。1 ブロックごとに次の 4 ステップを回します。
「レビューしきれない」は、見る観点が言語化されていない状態です。STEP 1 で正解条件を書けば、STEP 3 で見る箇所が決まります。「説明責任が持てない」は、根拠の出どころを追っていない状態です。STEP 1 で設計書のどこ由来かを指せば、根拠を示せます。
骨格とモデルは定型のため一括生成します。要点は、生成後に設計書とカラム単位で照合することです。
生成前に合格条件をメモに1行書きます。例：「CLAUDE.md のディレクトリ構成と一致、ruff と mypy が通り、pytest は既存1件のみ緑」。
ruff は書式・コーディング規約のチェッカー、mypy は型の整合性チェッカーです。どちらも CI で自動実行され、違反があるとジョブが赤になります。手元では ruff check app/ と mypy app/ で事前確認します。
この範囲は設計書とコードが1対1で対応するため、一括生成でも検証が機械的にできます。
docs/data_model.md 第2節のカラム定義表を開き、生成された app/models/ticket.py と並べて、下のチェックリストを上から確認してください。
status の default が "open" になっているか（設計書の状態遷移は open 始まり）priority の default が "medium" かassignee_id が nullable、reporter_id と category_id が NOT NULL かresolved_at が nullable か（未解決のチケットでは NULL）created_at が timezone 付き datetime かstatus priority assignee_id に index が付いているか（data_model.md 第5節）差し戻した場合は再生成し、同じチェックリストを再確認します。起点がずれると後続がすべてずれるため、ここは時間をかけます。
cannot import name 'Mapped' → SQLAlchemy が 2.0 系でない。pip show sqlalchemy で確認PRAGMA foreign_keys=ON を有効化Column(...) 旧記法が混ざる → 差し戻し。CLAUDE.md で禁止と明記してあるPOST /tickets の1本を repository → service → router の3層で実装し、実装の根拠を説明できる状態にします。
生成前に docs/sequence_diagrams.md の「1. チケット起票」と docs/openapi.yaml の TicketCreate を読み、合格条件をメモに書きます。最低限の4項目：
1プロンプトでまとめず、次の順に1ファイルずつ依頼し、都度検証します。
3層を1プロンプトで生成すると、Claude が app/ 全体を読み直して差分が長くなり、読み返せないまま消費が増えます。範囲を1ファイルに絞ると、読む量・出る量・修正回数が減ります。
if len(...) 等が紛れていないかsession.add が直接書かれていないか{"error":{"code","message"}} 形式で、code が openapi.yaml の一覧と一致するかClaude に書かせず、自分で1件書きます。次の内容で tests/unit/test_ticket_create.py を新規作成し、保存後にコマンドを実行します。client フィクスチャが未整備なら、Claude に「tests/conftest.py に非同期 TestClient の client フィクスチャを追加してください」と依頼します。
GET /api/tickets/{id}（詳細取得）を、同じ3層・同じ検証サイクルで追加します。存在しない id で 404 と統一エラー形式が返ることを検証チェックリストに加えてください。
Session 03 の後、「title 検証が router でなく service にある理由」を自分で声に出して30秒で説明します。説明できない箇所が復習対象です。Session 07 で再度確認します。
ここから、生成された実装を設計書と照合して判定する作業に移ります。状態遷移は Claude が誤りやすい題材です。
生成物を見る前に docs/requirements.md 第6節と docs/data_model.md 第3節を読み、許される遷移と禁止される遷移をメモに書き出します。先に書き出さずにコードを見ると、出力に引きずられて「それらしいので OK」と流しがちです。
仕様書を参照させても、遷移表を完全に守る保証はありません。次の検証で確かめます。
closed → open を 409 で弾いているか（最終状態。ここを通す実装が一番多い）resolved → open は許可されているか（再オープン運用。逆に弾いていたら過剰）open → resolved の飛び越しを弾いているか（in_progress を経由する）欠陥が見つかったら、修正箇所と理由を指定して差し戻します。丸投げせず、直す対象を限定します。
この演習は実装スキルではなく、仕様と成果物を照合して欠陥を指摘するスキルです。要件定義や設計レビューが主業務の方は、コードの細部より「仕様のどこに違反しているか」を日本語で示せれば十分です。
残りの実装は Claude に任せ、レビューに回ります。SLA は公開デモが誤実装していた箇所です。Claude が同じ誤りをしないか確認します。
SLA は対応の時間目標です。本題材では優先度ごとに「初回応答までの時間」と「解決までの時間」が決まっており（requirements.md 第5節）、超過したチケットを違反として検出します。営業時間外と土日を経過時間に数えないのが要点です。
Day1 で観察した公開デモの SLA は「created_at から一律1時間で違反」という誤実装でした。生成物が同じ誤りをしていないか確認します。
差し戻して直した場合、「最初の生成物がどこを間違えたか」を1行メモに残してください。Session 07 と Day3 で使います。
SLA 違反一覧を overdue_minutes の降順に並べる実装（requirements.md C-2）を追加し、並び順を保証するテストを1件書いてください。
カバレッジの数字あわせのテストは書きません。保証内容を説明できるテストだけを書きます。
「テストを書いて」と丸投げすると、保証内容の不明なテストが大量に出ます。先に、壊れてほしくない境界を3つ挙げます。例：
カバレッジ数値は確認しますが目的化しません。80%未満でも、説明できるテストが積み上がっていれば Day2 は合格です。CI のカバレッジは未達でも fail しない設定です（architecture_constraints.md）。
実装を Swagger で確認し、根拠を説明できるか自分で確かめます。
Swagger UI は、実装した API をブラウザから手動で叩ける画面です（/docs で開きます）。目的は実機での挙動確認です。各エンドポイントの「Try it out」→ パラメータ入力 → Execute で、返るステータスコードとレスポンスを確認します。設計書どおりの値・形式が返れば成功です。
http://127.0.0.1:8000/docs を開き、Session 03〜05 で実装した起票・状態遷移・SLA を叩きます。Day1 で触った公開デモ https://0514-28cc.give-app.net/docs（改善対象の実装）と比べ、自分の実装では title 空文字が弾かれること、SLA が優先度別であることを確認します。
次の3問に、設計書の根拠を含めて30秒で答えます。答えられない問いが復習対象です。
3問とも「docs のここに書いてある」と示せれば、上司や顧客に説明できます。AI が出したからではなく、要件に照らして自分が判定した、と言える状態です。
Day1 で「想定以上に消費した」という声がありました。本日は範囲を1ファイルに絞りました。Claude Code で /cost を実行し、Day1 との差を各自確認します。
Dockerfile を一読し、マルチステージ構成の意図を確認するDay3(5/28)は本日の実装を Docker でパッケージ化し、CI に docker-build と trivy を追加します。@claude メンションの自動 PR も、本日と同じ生成→検証→判定で受け入れ可否を決めます。Day3 前日までに必要な環境設定（OAuth トークン登録など）は受講者ポータルに手順があります。