はじめに
実装から作成し始め、もろもろと観点漏れが出てきたため設計書を作成するようにしました。
作成しては確認してを繰り返していましたが、さすがに毎回やるのは面倒ということで、コマンド1つ叩けば指摘してくれるコマンドを作成しました。
Claudeとのやり取り
Q. 設計書のレビューをできるようにカスタムコマンドを作成したいです。何を準備するか教えてください。
Claudeからの質問と回答:
| Claudeからの質問 | 回答 |
|---|---|
| レビューコマンドは何を対象にしますか? | 設計書内の整合性チェック |
| コマンドの呼び出し方はどうしますか? | 対象ファイルを引数で指定（推奨） |
| レビュー結果の出力形式は? | チャットに指摘事項を列挙するだけ（推奨） |
こういったやり取りをClaudeと行った結果、以下のファイルが作成されました。
作成されたファイル
.claude/commands/design-review.md
---
description: 指定した設計書ファイルを docs/README.md のルールに沿ってレビューする（設計書内の整合性チェック。ファイルは変更しない）
---
# 設計書レビュー
対象ファイル: $ARGUMENTS
引数が指定されていない場合は、ユーザーにレビュー対象の設計書ファイルパス
（例: `docs/basic-design/screens/attendance-index.html`）を確認してください。
## 進め方
1. [docs/README.md](../../docs/README.md) を読み、設計書運用ルール
（基本設計/詳細設計の切り分け基準、対応関係、運用ルール）を把握する。
2. 対象ファイルを読む。
3. 対象が `basic-design/screens/` または `detailed-design/screens/` 配下の
画面設計書なら、`docs/README.md` の「画面設計書の対応関係」表から対になる
ファイル（基本設計⇔詳細設計）を特定し、そちらも読む。
4. 対象が業務ルール（`basic-design/business-rules/`）やテーブル定義
（`basic-design/database/tables/`）の場合は、対になるファイルはないため
単体でチェックする。
5. 以下の観点でチェックする。該当しない観点はスキップしてよい。
### チェック観点
**A. 基本設計⇔詳細設計の対応（画面設計書のみ）**
- 同名ファイルとして両方に存在するか
- 相互リンク（基本設計→詳細設計、詳細設計→基本設計）が張られているか
- 基本設計に書かれた項目仕様・表示条件と、詳細設計のDTOフィールド定義・
実装メモが矛盾していないか（フィールドの過不足など）
**B. screen-flow.html との重複禁止**
- 画面設計書の「基本情報」に、遷移元・遷移先の1行記載を超えるHTTP
エンドポイント一覧や画面遷移フローの詳細が書かれていないか
（`docs/README.md` により重複防止のため screen-flow.html に一元管理するルール）
**C. 基本設計書の非エンジニア向け表現（basic-design/ 配下のみ）**
- 変数名・クラス名・Thymeleaf属性（`th:if` 等）・CSSクラス名・フォームの
`name` 属性が本文に書かれていないか
- 技術的な対応関係の記述が紛れ込んでいないか
（本来は詳細設計側の実装メモに書くべき内容）
- URL・クエリパラメーター名は画面特定情報として許可されている点に注意
（誤検出しない）
**D. 未実装・未確定事項の明記漏れ**
- `proposals/` 由来で採用済みだが実装が伴っていない機能について、
「未実装」である旨が明記されているか
- 業務ルール文書内に「未確定」「スコープ外」等の論点が残っている場合、
対応方針が書かれているか
**E. 用語・体裁の一貫性**
- 同一プロジェクト内の他設計書と項目名・用語が食い違っていないか
（対になるファイルがあれば重点的に）
- 見出し構成やテーブル形式が著しく崩れていないか
6. 実装ファイル（テンプレート・コントローラー・DTO・エンティティ）との
突き合わせは対象外（このコマンドの範囲外）。実装とのずれの棚卸しは
別途 [docs/implementation-gap-audit.md](../../docs/implementation-gap-audit.md)
の形式で行う。
## 出力
ファイルは一切変更しない。チャットに以下の形式で報告する。
- 観点ごとに問題なければ「問題なし」と一言で済ませる（冗長な説明は不要）
- 問題があれば「観点 / 該当箇所（ファイル:行 or 見出し名）/
何がルールに反しているか / 修正方針の提案」を簡潔に示す
- 対応する設計書がある場合、突き合わせた上で見つかった不整合を明示する
- 最後に「指摘件数」を一言でまとめる
実行結果
作成したカスタムスラッシュコマンドを実行すると、こんな指摘をしてくれるようになりました。
/design-review docs/basic-design/screens/attendance-index.html
レビュー結果
A. 基本設計⇔詳細設計の対応 — 2件の不整合あり
1. 休憩時間帯の項目数が食い違っている
基本設計のモックアップ（attendance-index.html:141-146）は「休憩時間帯」に4項目（昼休み・その他休憩1・その他休憩2・深夜休憩）を表示しているが、詳細設計の WorkInfoDto フィールド一覧（attendance-index.html:92-101）には3組しか定義がない（breakStartTime/breakEndTime=昼休み、break2StartTime/break2EndTime=その他休憩1、nightBreakStartTime/nightBreakEndTime=深夜休憩）。「その他休憩2」に対応するフィールドが詳細設計から欠落している。
修正案: 詳細設計に
break3StartTime/break3EndTime（仮）を追加するか、基本設計のモックアップから「その他休憩2」行を削除して1項目に揃える。
2. 「深夜」時間帯の表記が宣言された型と矛盾
基本設計モックアップは深夜の時間帯を 22:00 〜 29:00（24時超えの翌日オーバーフロー表記）と示している（attendance-index.html:136）が、詳細設計では nightStartTime/nightEndTime の型を LocalTime（java.time.LocalTime は0:00〜23:59:59のみ表現可能）と定義している。29:00のような値をこの型でどう扱うか（日またぎの計算ロジック）が明記されていない。
修正案: 型を保持しつつ「翌日フラグ」を別途持たせるか、実装メモに日またぎの扱いを追記する。
B. screen-flow.html との重複
問題なし — 基本情報欄の「遷移先」は1行のみで、エンドポイント一覧の重複記載なし
C. 基本設計書の非エンジニア向け表現
問題なし — 色・書式は自然文で説明されており、th:class・DBカラム名・CSSクラス名などの技術情報は詳細設計側にのみ記載され、綺麗に分離できている
D. 未実装・未確定事項の明記漏れ
問題なし — 「勤務情報パネル」の未実装状態が基本設計・詳細設計の両方で明記され、implementation-gap-audit.md へのリンクも張られている。AttendanceRowDto の未使用フィールドも詳細設計に注記済み
E. 用語・体裁の一貫性
上記A-1を除き、項目名（規定勤務時間・当社規定勤務時間・超過控除判定等）はモックアップとフィールド一覧で一致
指摘件数: 2件（いずれもA. 基本設計⇔詳細設計の対応）
まとめ
毎回観点を言わずとも設計レビューをしてくれるようになりました。
設計レビューだけでなくソースレビューもできるようにやっていこうと思います！