UIのないAPIに要件定義テンプレートをどう当てはめるか

今日は、個人用メール送信API「api-email-sy」の要件定義に着手した。AWS API Gateway + Lambda + DynamoDB + SES + CloudWatch というサーバーレス構成で、お問い合わせフォームなどのサーバーサイド処理から呼び出す、メール送信専用のAPIだ。Claude Codeの要件定義スキルを使って進めた。

着手前に見つかった小さなズレ

作業を始めてすぐ、成果物を保存するフォルダの採番が実態とズレていることに気づいた。実際のプロジェクトは 10_開発標準 / 20_要件定義 / 30_基本設計書 / 90_ブログ という採番なのに、Claude Codeの設定や共有の開発標準ドキュメントの中身は古い採番（01_開発標準 / 02_要件定義 など）を参照したままだった。

調べてみると、これらの設定・標準ドキュメントは複数の個人開発プロジェクトで共有するテンプレート群で、本来はシンボリックリンクとして配置される想定のものだった。今回のリポジトリではファイルのコピーとして置かれていたため、実態とのズレに気づきにくかったようだ。

「このプロジェクトに合わせて表記を直す」のではなく「テンプレート側（共有の標準）の採番の考え方自体を更新する」という方針を確認し、該当箇所をまとめて新しい採番に揃えてから、本題の要件定義に入った。

ヒアリングで詰めたこと

要件定義を進める中で、いくつかの仕様をヒアリングで確認した。

認証方式：API Gatewayの使用プラン（APIキー）を軸に提案したが、「機能一覧を作るときに一緒に決めたい」ということで、この場では保留にした。要件定義書には「基本設計で最終確定する」前提として明記している
SESの状態：まだ何も設定していない（サンドボックス状態）
呼び出し元：今はホームページのお問い合わせフォームのみだが、今後は複数のサービスから呼ばれる見込み
AWS環境：既存のアカウント・リージョンを使う
送信数の上限：1日100通。JST基準でリセット
上限到達時：自分宛にメール通知が欲しい

すべてを一度に決めきる必要はなく、「今わかっていること」と「基本設計で詰めること」を切り分けて要件定義書に書き分けるのがポイントだと感じた。

UIがないなら「画面設計」はどう書く？

要件定義の標準テンプレートには、画面遷移図・画面一覧表を書く章がある。しかし今回のプロジェクトはUIを持たないAPI単体のアプリケーションなので、画面遷移図をそのまま当てはめても意味がない。

そこで、呼び出し元 → API Gateway → Lambda → DynamoDB/SES → CloudWatch/SNS という処理の流れを、Mermaidのシーケンス図（時間の流れに沿って登場する要素同士のやり取りを矢印で表す図）で表現する形に読み替えることにした。この読み替えは事前にユーザーへ確認し、了承を得てから進めている。

1. 呼び出し元（お問い合わせフォーム等）
     → API Gateway へリクエスト送信（x-api-key、To/Cc/Bcc・件名・本文・添付）

2. API Gateway
     → APIキー認証・レート制限（使用プラン）を通過したら Lambda へ転送

3. Lambda（メール送信処理）
     → リクエストをバリデーション
     → DynamoDB から「本日（JST基準）の送信数」を取得

4. 送信数が100通未満の場合
     → SES でメール送信 → DynamoDB の送信数を +1 → 呼び出し元へ成功レスポンス
     → CloudWatch へ送信結果ログを出力

   送信数が100通に達している場合
     → 送信は行わず、呼び出し元へエラーレスポンス
     → CloudWatch へ上限超過ログを出力

5. CloudWatch
     → 送信数が閾値に到達したアラームを検知したら SNS 経由で開発者本人へ通知メール

テンプレートを機械的に埋めるのではなく、「このプロジェクトにとって画面遷移図が果たすべき役割は何か」を考えたうえで、処理フロー図に置き換えた形だ。

要件定義書とタスク一覧

ヒアリングの内容を踏まえて、要件定義書一式（README + 01_概要〜07_テスト方針の7ファイル）を作成した。基本設計書はまだ空だったので下流への影響はなく、UIを持たないプロジェクトのためモック作成も対象外とした。

最後に、「今積み残っているタスクを、担当（ユーザー／Claude）がわかる形でチェックボックス付きのファイルにしてほしい」という依頼があり、docs/タスク一覧.md を作成した。要件定義書の承認待ち、認証方式や送信数上限の合算方式の最終決定、SESのドメイン検証といったAWS環境準備、実装フェーズでの構成移行などを担当別に並べている。

今日の学び

標準テンプレートは「そのまま埋める」ものではなく、プロジェクトの実態（今回で言えばUIの有無）に応じて何を代替表現にするか判断する対象でもある
複数プロジェクトで共有する設定・標準は、個別プロジェクトの都合で局所的に直すのではなく、「標準側の考え方」を更新する形で直すと、後から同じズレを繰り返さずに済む
仕様のすべてをその場で決めきろうとせず、「今わかっていること」と「次工程で詰めること」を要件定義書に明記して切り分けると、ヒアリングが止まらずに進む

明日は要件定義書の承認を受けて、基本設計に進む予定。認証方式と送信数上限の合算方式をどう決着させるかが次の山場になりそうだ。

本記事は Sonnet 5（claude-sonnet-5）が生成しました。