はじめに
先日、担当しているシステムに 2FA（二要素認証）を導入しました。
今回は「設計に詳しい先輩が初期設計を作る → その設計をもとに Claude Code と対話しながら設計を詰める → Claude Code に実装させる → Claude Code にテストさせる → 最後に人が画面で確認する」という流れで進めたところ、実装にかかる時間を大きく削減できました。
この記事では、その進め方と、やってみて感じたポイントを共有します。
背景
セキュリティ要件の強化に伴い、ログイン時の認証を ID・パスワードだけでなく、TOTP による二要素認証に対応させることになりました。
対象システムの概要は以下のとおりです。
- フロントエンド：React（TypeScript）
- バックエンド：Express（TypeScript）
- 導入する方式：TOTP（Google Authenticator などの認証アプリで生成するワンタイムパスワード）
- 使用した AI：Claude Code
今回の進め方（全体像）
① 先輩による初期設計
↓
② 初期設計をもとに、Claude Code と対話しながら設計をブラッシュアップ
↓
③ Claude Code による実装
↓
④ Claude Code によるテスト
↓
⑤ 人による画面テスト
ポイントは、AI に「ゼロから設計させる」のではなく、経験のある人が作った初期設計を出発点にしたことです。
① 先輩による初期設計
まず、設計経験の豊富な先輩が初期設計を作成しました。章立ては次のとおりです。
- 方式
- 適用範囲
- システム構成
- ドメイン設計
- 認証とトークン設計
- フロントエンド設計
- バックエンド設計
- API設計
- 業務状態遷移
- シーケンス設計
- トランザクションと競合制御
- 設定設計
- セキュリティ設計
各章の詳細はここでは割愛しますが、方式の選定からセキュリティ設計まで、全体の骨格が一通り決まっている状態でした。この「骨格がある」ことが、後の AI との対話の質を大きく左右しました。
② 初期設計をもとに Claude Code と対話する
次に、初期設計を Claude Code に渡し、既存の認証まわりのコードを実際に読ませたうえで、対話しながら設計を詰めていきました。
コードを貼り付ける必要がなく、Claude Code 自身が関連ファイルを探して読んでくれるので、影響範囲の洗い出しが非常にスムーズでした。
対話の中で、例えば次のような点が補完・改善されました。
- TOTP コードの使い回し対策：有効期間内に同じコードが再利用されないようにする（リプレイ攻撃対策）
- 既存コードとの整合性：既存の認証処理に合わせて、設計を適切に調整
- 画面構成の見直し：当初は既存ページに 2FA 機能を追加する設計だったが、実際の画面構成を確認したうえで「既存ページへの追加は適さない」と判断し、2FA 設定用のページを新規作成する形に変更
- ユーザビリティの向上：リカバリーコードに「コピー」「テキストで保存」ボタンを付ける提案
- ER 図に基づく判断と提案：既存テーブル同士の関連を踏まえ、どのテーブルにどう持たせるべきかを判断・提案
特に画面構成の変更は、設計書だけを見ていては気づきにくい点でした。一般論としての 2FA 設計ではなく、「このシステムの既存コードと既存データ構造にどう組み込むか」というレベルで具体化できたのが大きかったです。
③ Claude Code による実装
実装は次の流れで進めました。
- Claude Code に初期設計を読み込ませる
- 既存コードを踏まえて実現可能性を分析させる
- 設計からの変更点を Claude Code が提示し、人が一つずつ確認・判断する
- 変更点が確定したら、フロントエンド・バックエンドをまとめて一気に実装させる
実装に入る前に「何をどう変えるか」を人が確認しているため、一気に実装させても方向性が大きくずれることはありませんでした。いきなり実装を任せるのではなく、分析 → 確認 → 実装という順番を踏むことが大事だと感じました。
④ Claude Code によるテスト
実装後、テストコードの作成と実行も Claude Code に任せました。正しいコードでログインできること、誤ったコードや使用済みのコードが弾かれること、リカバリーコードでログインできることなど、正常系・異常系を一通り確認させ、失敗したテストがあれば Claude Code 自身が原因を調べて修正しました。
⑤ 人による画面テスト
最後に、実際に画面を操作して確認しました。認証アプリで QR コードを読み取る、コードを入力するといった実際の操作や画面遷移は、やはり人の目で確かめる必要があります。
今回は特に大きな問題は見つかりませんでした。
効果
今回いちばん大きく削減できたのは、コードを書く時間です。
設計をしっかり作り、それをもとに AI と細かく詰めておけば、実装そのものは Claude Code にほぼ任せられます。人がやるべきことは、設計を考えることと、AI の出力をレビュー・確認することに集中できました。
逆に言えば、設計が曖昧なまま AI に実装を任せても、意図とずれたコードが出てきて手戻りが増えるだけです。時間短縮の前提は「良い設計」と「AI との十分なすり合わせ」にあると感じました。
やってみて感じたこと
初期設計の質がすべての土台になる。
AI に丸投げで設計させると、もっともらしいけれどシステムに合わない設計が出てくることがあります。経験のある人が方針を決めておくことで、AI は「補完・具体化」の役割に集中でき、精度が上がりました。
AI に既存コードを読ませることが重要。
設計書だけでは見えない「既存システムとの相性」を、AI がコードを読んだうえで指摘してくれます。今回の「既存ページではなく新規ページにする」という判断がまさにその例でした。
セキュリティ観点の最終判断は人が行う。
2FA は認証に関わる機能なので、AI の提案をそのまま採用せず、人が妥当性を確認することが欠かせません。
画面デザインは、こだわるなら事前に指定する。
今回は画面デザインについて特に要件を出していなかったため、見た目は AI 任せになりました。仕上がりの好みは人それぞれなので、デザインにこだわりがある場合は、設計の段階で明記しておくのがよいと思います。
画面テストは省略できない。
自動テストが通っても、実際の操作でしか気づけないことはあります。最後は人の目で確認する工程を残しておくべきです。
まとめ
「経験者による初期設計」と「AI との対話」を組み合わせることで、設計の精度を上げつつ、実装の時間を大幅に短縮できました。
AI に全部任せるのでも、人が全部やるのでもなく、人が骨格を作り、AI が肉付けと作業を担い、最後に人が確認する。この分担が、今回いちばんうまくいったポイントだと思います。