検査データの集計は、いまも多くの現場でExcelの手作業か、自作のマクロによって行われています。手作業は時間がかかり、転記の途中で数字がずれます。マクロはマクロで、使い込むうちに中身が込み入っていき、後から開いても何をしているのか読み取れないスクリプトが残ります。しかもたいていは一つの様式に合わせて組まれているため、別の様式の成績書が来ると、そのままでは動きません。
検査成績書は、品目ごとに様式が異なり、数も多いです。データを集めて管理するという、一見ありふれた作業でありながら、そこに社内独自の様式や項目が絡むことで、自動化がなかなか実現できない。
この記事では、その手詰まりに対して、プロンプト仕様駆動開発（以下、PSDD）でどう設計を進めたかを、実際にできあがった仕様書とともに解説します。手順そのものの全体像は別の記事にまとめてあるので、初めての方はそちらを先に読んでみてください。
※注意：この記事で扱うデータ・品名・測定値は、すべて架空のものです。実在の企業・製品とは関係ありません。
多品目の製造現場のトレンド分析には自動処理する仕組みが必要
手作業の集計が、品目ごとに毎月発生している
今回の仮想事例は、金属部品を製造する中小製造業で品質・検査の集計を担当する1〜2名のケースです。品目ごとに複数のロットがあり、ロットごとの検査成績書がExcelファイルとして保存されています。月次・四半期で品質の傾向を見るたびに、ファイルを開いて平均値を集計表へ転記し、グラフを作る——この作業を手で行っています。
取り扱う品目は数十から百近くにのぼります。品目ごとに専用の集計ツールを一つずつ作るのは、現実的ではありません。だから、様式の違う成績書を一つの仕組みでまとめて処理する、という方向が必要になります。
同じ検査成績書でも、品目ごとに様式が大きく異なる
作るものが違えば、測定すべき項目も違います。六角ナットなら二面幅と高さ、シャフトなら外径と全長、というように、品目ごとに記録すべき項目が異なります。項目が違えば表の作りも変わり、結果として測定値の並べ方まで品目ごとに異なってきます。今回はその代表として、3つの様式を用意しました。
| A：六角ナット | B：シャフト | C：プレート | |
|---|---|---|---|
| 測定値の並べ方 | 横並び（1項目=1行） | 縦並び（1項目=1列） | 積み上げ（項目ごとに下へ） |
| メタ情報の位置 | 左上 | 右上 | 左上 |
| 平均の出し方 | 各行の右端 | 一番下の行 | 別枠の集計 |
製品Aのテンプレート
製品Bのテンプレート
製品Cのテンプレート
様式が違えば、測定値のセルの位置も平均の出し方も変わります。ここで「どんなExcelも自動で読む」という作り方をすると、測定値を取り違えても、それらしいグラフを描いてしまいます。揃ったデータだけを前提にすると、現場の実物が来た瞬間に成り立たなくなる。だから最初から、様式を選ばず、かつ取り違えない読み取り方を考えます。これが今回の中心的な課題です。
2. 検査成績書を読み込むツールの要求仕様書を、問診形式のプロンプトで作る
問診プロンプトに答えて、要求を引き出す
PSDDの最初の一歩は、コードではなく要求仕様書です。これが、後の設計・テスト工程に渡す「種」になります。使うのは、要求を問診形式で引き出すプロンプトです。これをWeb版のClaudeに渡し、質問に1〜2問ずつ答えていくと、必要な項目が少しずつ埋まっていきます。専門用語は使わず、非エンジニアの言葉で答えれば進みます。
使用したプロンプト一覧
要求仕様書プロンプト
あなたは、非エンジニアの私から「作りたい道具」の要求を問診で引き出し、
最後に「要求仕様書」まで書き上げる相談相手です。
私はまだ、何をどう書けばいいか分かっていません。あなたの質問に答えるうちに、
要求仕様書に必要な項目が自然に埋まり、そのまま要求仕様書になる--そんな進め方をしてください。
【最終的な成果物】
問診で集めた内容をもとに、下の「要求仕様書の構成」に沿った要求仕様書を出力する。
これが、後の設計・テスト工程に渡す「種」になります。
【問診の進め方】
- 一度に聞くのは1〜2項目まで。私が答えやすいよう、噛み砕いて聞く。
- 専門用語は使わない。私の言葉で返す。
- 私の答えが曖昧・抽象的なときは、具体例や数字を促して掘り下げる。
- 私が機能を欲張りそうなときは、「それは今回やらないことに回せませんか」と提案する。
- 判断に事実が要るとき（業界の相場・実態など）は、調べることを提案する。
- 矛盾や抜けに気づいたら、その場で指摘する。
- 結論を押し付けない。最後に決めるのは私。選択肢と、あなたの推しを添える。
- 入力データは特に具体的に詰める。後でテスト用のデータを作る大本になるので、
「どんなファイルか・どこに何の値が入るか・見出しやラベルの文字列・様式は何種類あるか」まで聞く。
実際のサンプルデータが1つでもあれば、添付してもらう（テストの基準になる）。
無ければ、テスト用データを作れる粒度まで、形式を一緒に確定する。
【問診で埋める12項目】
1. 誰のための、何の道具か
2. いま何に困っているか（具体・数字）
3. この道具で何をしたいか（ゴール）
4. なぜ今ある方法では足りないか
5. 何人で使い、画面はどんな方針か
6. 何を渡すか（入力データ）。ファイル形式・項目名・型に加えて、データの様式まで。
実サンプルが1つあれば見せてもらう。無ければ、テスト用データを作れる粒度で形式を確定する
（どのセル／列・行に何が入るか、見出し・ラベルの文字列、レイアウトのパターン、数式があればその形）
7. 何が返ると嬉しいか（出力：形式・見せ方）
8. 判定や計算で使う基準・ルール（数字で決めたいこと）
9. うまくいかない入力（不備）をどう扱うか
10. 今回やらないこと
11. 使う人に持たせたい安心
12. 前提にする技術・道具（要求から事実上決まるもの）。画面の作り方（ローカルのデスクトップ画面なら
tkinter など）、入出力のファイルを扱うライブラリ（Excelの読み書き・グラフなら openpyxl など）、
クラウドを使わない等の制約。「既存のツールと揃えたいか」も聞く。
ここを決めておかないと、設計フェーズで技術選定を聞かれ、テスト設計でも入力フィクスチャを
作るライブラリや、手動確認する画面の種類が定まらなくなる。
【要求仕様書を書くとき守ってほしいこと】
- まず最小構成で考える。いま一番困っていることだけを解決し、欲張らない。
- 専門用語を避け、私（非エンジニア）が読める言葉で書く。
- 後の工程（設計・テスト）が、この要求仕様書だけを読んで進められるよう、
入力・出力・判定基準を具体的に書く。
- 入力データの様式を、テスト用のデータ（フィクスチャ）を作れる粒度まで具体的に書く。
実サンプルがあればその様式を基準にし、無ければセル／列の配置・ラベルの文字列・
レイアウトのパターン・数式の形まで決める。ここが曖昧だと、後でテストの入力データが作れず、
正常系（正しく動く場合）の検証ができなくなる。
- 前提にする技術・道具を書く。画面の作り方（例：ローカルのデスクトップ画面なら tkinter）、
入出力のファイルを扱うライブラリ（例：Excelの読み書き・グラフなら openpyxl）など、
要求（ローカル完結・既存スタックと揃える・入出力の形式）から事実上決まるものは、要求仕様書に明記する。
これが無いと、設計で技術選定を聞かれ、テスト設計でフィクスチャのライブラリや手動確認の画面の種類が定まらない。
- 「やること」を、大・中・小の3階層に整理し、それぞれにIDを振る。
・大項目＝この道具で何ができるか（例：測定値を正しく取り出す）
・中項目＝テストで1つの観点として確かめられる、1つのふるまい（例：2系統で照合して採否を決める）
・小項目＝具体的な分岐・動作（例：一致なら採用／不一致なら除外）
IDは「REQ-2」「REQ-2.2」「REQ-2.2.1」のように、大・中・小で桁を増やす。
中項目を決める基準は「これはテストで1観点として確かめられるか?」の一つだけ。
- 処理の流れを、上から下へのワークフロー図（簡単な箇条書きの流れでよい）にし、
各ステップに対応するIDを添える。この図を要求仕様書の中に置く。これが後の設計・テストの原図になる。
【要求仕様書の構成】
1. このツールは何か
2. 背景と困りごと
3. このツールがやること（大・中・小の3階層＋ID）
4. 入力と出力（入力データの様式まで：どこに何の値が入るか・ラベル／見出しの文字列・レイアウトのパターン・数式の形。テスト用データを作れる粒度で。実サンプルがあれば添付）
5. 処理の流れ（ワークフロー図＋各ステップのID）
6. やらないこと
7. なぜ既存ツールでは足りないか
8. 使う人に持たせる安心
9. 前提にする技術・道具（画面の作り方・入出力のライブラリ・制約など、要求から決まるもの）
10. ID辞書（全IDの一覧表：ID／階層（大中小）／実現すること）
【流れ】
1. まず、確認したいことを1〜2問ずつ聞いて、12項目を埋めていく。
2. 全項目がそろったら、私に一度内容を確認させる。
3. OKが出たら、「要求仕様書の構成」に沿って要求仕様書を出力する。
出力は .docx（Word）形式のファイルで行う。
あわせて、ID辞書と同じ内容を docs/spec_ids.json（後の整合チェックが読む機械可読なID一覧）
としても出力する。形式は [{"id":"REQ-2","level":"大","desc":"..."}, ...]。
（途中で、項目を【 】で埋めただけの中間プロンプトは作らない）仕上げ確認プロンプト
この要求仕様書に、後工程（設計・テスト）が必要とする定義の不足がないか確認してください。
前提：入力は正しく運用されたデータとする。正常な運用ならありえないデータは、穴として
挙げない（前提が破れたときに初めて問題になるものだけを挙げる）。
確認する観点は4つ。それぞれ「後工程が一意に決められるか」を見る：
- 入力：何がどこから取れるか（取得元・様式の見分け方）が決まっているか。
- 出力：何をどんな形で出すか（完成イメージから一意に決まるか）。
- 計算・判定：何を基準に、どんな値で決めるか（基準値・桁・丸め方など）。
- 不備：何を異常とし、それをどう扱うか。
報告：穴を「必須（決めないと実装が止まる）／推奨／軽微」で分類し、各項目に
推し（こう決めるとよい）と理由を1〜2文添える。ただし勝手に埋めず、決まっていないことを
挙げて私の判断を仰ぐ。推測で補った箇所は【推測】と明示する。問診で固まった要求
問診を進めると、要求仕様書ができあがります。全部を読まなくても中身が伝わるよう、要点だけ項目ごとに並べます。
- このツールは何か：
品質担当者が手元のPCだけで使う道具。1品目分（複数ロット）の検査成績書をまとめて読み込み、検査項目ごとの平均値の推移を表と散布図で見える化する。 - やること：
フォルダ内の全ロットを読み込む／2つの独立した経路で測定値を取り、照合して採否を決める／検査項目ごとに整理する／不備を検査して人の判断を仰ぐ／検査項目ごとに集約Excelを出力する。 - 入力と出力：
入力はフォルダ1つ（中に1品目・複数ロットのExcel）。様式は品目ごとに3パターン。出力は検査項目ごとに1ファイルで、サマリー・平均値の推移・データ台帳の3シート。 - やらないこと：
Cp・Cpkや分散の算出、合否判定、管理図、複数品目の横断集約、3様式以外への対応。これらはスコープ外とする。 - 前提にする技術・道具：
画面はtkinter、Excelの読み書きはopenpyxl。クラウドは使わず、手元のPCで完結する。
計算には一つ意図があります。平均値をそのまま出すのではなく、個々の測定値を一つも取りこぼさずに確保し、そこから平均を出し直す。これは、将来この台帳から分散や工程能力指数（Cp・Cpk）を計算するための土台を残しておく狙いです。だからこそ「やること」に測定値の照合を、「やらないこと」にCp・Cpk本体を置く、という線引きになります。欲張らず、いま一番困っていることだけを解く——これが最小構成の考え方です。
できあがった要求仕様書は、下のボタンから読めます。
様式を選ばず、測定値を読む仕組みを設計仕様書で決める
要求仕様書という「種」ができたら、次はそれをもとに設計仕様書を作ります。ここで決めるのは、このツールの心臓部——様式がばらばらな成績書から、どうやって測定値を取り違えずに読むか、です。設計の中身は、大きく2つの判断でできています。
数式の足跡を辿って、測定値を取る
様式が3つあれば、測定値が置かれるセルの位置はそれぞれ違います。様式ごとに位置を決め打ちすれば読み取れますが、それだけでは「決め打ちした場所が、本当に測定値かどうか」の保証がありません。新しいロットでレイアウトが少しずれていたら、まったく違うセルを測定値として読んでしまう余地が残ります。
そこで手がかりにしたのが、平均を出すために置かれているAVERAGE関数です。検査成績書を作った人は、平均を計算するときに「この範囲が測定値だ」と決めて数式を書いています。つまり数式が参照している範囲は、作成者が残した「測定値はここだ」という足跡です。この範囲を逆に辿れば、測定値が横に並んでいても、縦に並んでいても、項目ごとに積み上がっていても、同じ手順で測定値に届きます。これを1つ目の経路とします。
2つの独立した経路で照合し、取り違えを検出する
ただ、数式の足跡を辿れたとしても、その範囲が本当に正しいという保証は、まだどこにもありません。そこで、数式を一切見ない別の経路を用意します。様式ごとに決めた開始位置から、数値が続くかぎりセルをたどって測定値を集める。これを2つ目の経路とします。1つ目は範囲を数式が決め、2つ目は数値の並びが決める。出どころがまったく違うので、2つの経路は独立しています。
そして、両方の経路で取った測定値が点数も値も完全に一致し、平均も一致したときだけ採用する。独立した2つの経路が同じ答えに行き着くことを、正しさの根拠にする——これが設計の軸です。
逆に、2つの経路が食い違ったときは、取り違えの疑いがあるものとして不備に回します。たとえば数式が参照する範囲と、実際に数値が並んでいる範囲がずれていれば、取れる点数が変わります。下の図では、経路1が9点、経路2が10点を取り、点数が食い違っています。こうしたずれを、黙って通さずに捕まえる。
この照合をどこまで作り込むかは、Claudeとのやり取りの中で一度立ち止まりました。
Web Claude測定値に空やNAといった欠損が混じっていないかも照合すべきではないでしょうか？
Claudeは安全側に寄って、提案してきました。測定値の中に空やNAが一つでも混じっていたら、そのデータを疑えるように、という発想です。
これに対しては、前提を正しました。検査成績書は、正式に発行された品質記録です。測定値が欠けたまま発行される成績書は、そもそも存在しません。もしあるなら、それは集計ツールが照合で拾う以前の問題で、検査記録の作成段階で破綻しています。ツールが疑うべきは、データそのものではなく、ツール自身が様式を取り違えていないか。そこだけです。データが正しいという前提に立ち、照合は「測定値の一致」と「平均の一致」に絞りました。
AIに設計を任せると、安全装置を足し続ける方向に傾きがちです。現場の前提——成績書は正式な記録である——を人が伝えることで、設計は必要十分なところに収まります。判断するのは人、補強するのがClaude、という役割分担です。
このコアとUIの設計は、要求仕様書を渡して設計用のプロンプトで作りました。使ったプロンプトは下に畳んでおきます。
設計プロンプト
設計プロンプト
あなたは非エンジニアの開発相談相手です。
添付の「要求仕様書」と「設計の基礎」を読み、設計を1本の設計仕様書（.docx）にまとめてください。
設計の基礎の共通ルール（独立性・取り決めの物理表現・UIに判断を置かない・ファイル構成・
正常系以外・検証可能性・確定待ち）を、すべて守ります。
判断の根拠は、添付の文書とデータ（要求仕様書・入力サンプル・出力完成ファイル・設計の基礎）だけにし、会話の記憶を根拠にしない。添付された入力サンプル・完成ファイル（Excel など）は必ず実際に開いて中身を確かめ、要求の文言だけで判断しない（特に確定待ちのリスク見積もり＝基礎7）。
このプロンプトには、設計フェーズ固有のことだけを書きます。共通の原則は設計の基礎を見てください。
【このフェーズでやること】
- 計算・判定の中身（コア）と、画面（UI）を、同じ設計仕様書の中で節に分けて書く。
- 判定・計算の手順は、順を追った日本語で書く（実コードは書かない）。非エンジニアが設計だけ読んで
筋が分かるように。
- 各関数の取り決め（名前・引数と型・戻り値・物理表現）と、入力・出力データの形を、表で定義する。
- 各関数に設計ID（DES-）を振る（基礎9：モジュール大・関数中）。
- 要求仕様書の各IDを「要求ID → 設計ID（関数）→ 何をするか」の対応表にし、全IDに担当を割り当てる。
- 要求仕様書の「やらないこと」を超えない。最小構成。
【書き終えたら自己チェック】
- この設計仕様書だけで、テスト設計者が (1)入力を組み立て (2)関数を呼び (3)戻り値を読み
(4)期待値を計算 できるか。
- 設計の基礎の5〜7（正常系以外・検証可能性・確定待ち）を満たしているか。
【構成】
1. 全体像（何を受け取り何を返すか・画面の使い方・モジュール構成）
2. コア
2-1. 入力データの読み込み（どこから何を読むか）
2-2. 入力と出力のデータ（項目名・型の表）
2-3. 判定・計算の手順（日本語。順を追って）
2-4. 関数の取り決め一覧（設計ID／関数名／引数と型／戻り値／何をするか）
2-5. データ構造の物理表現（dataclass か dict か、フィールドの英語名・型、状態の文字列値、日付形式、丸め桁）
2-6. しきい値・設定値
2-7. 正常系以外のふるまい（基礎5の5カテゴリ）
3. UI
3-1. 画面構成 3-2. 操作の流れ 3-3. 結果の見せ方 3-4. 呼ぶコアの関数
4. 設計ID一覧（モジュール大・関数中：DES-C／U／M）
5. 要求ID → 設計ID（関数）→ 何をするか 対応表
6. 使う技術とやらないこと
7. 確定待ち（各項目にリスク〔影響度×発生頻度→大中小〕と対応の目安を添える。要求側の穴はその旨を明記）設計の基礎（設計プロンプトと一緒に渡してください）
# 設計の基礎（このプロジェクトの共通ルール）
設計・テスト設計・実装の全フェーズで守る、共通の原則。
各フェーズのプロンプトは、このファイルを一緒に渡して「設計の基礎に従う」として参照する。
## 1. 設計とテストは独立に作る（独立性）
- 各フェーズは、前フェーズの成果物（要求仕様書・設計仕様書などの文書）だけを唯一の入力とする。
会話の履歴・記憶を根拠にしない。穴・確定待ち・矛盾の判断も、渡された文書に書いてあるか・いないか
だけで決める。「前に会話でこう言った」を持ち出すと、確定済みの事項を曖昧と誤判定したり、
文書に無い穴を作り出したりする（幻の穴）。だから各フェーズは独立したチャットで行う。
- 設計仕様書には実装の中身（コード）を書かない。書くのは日本語の手順と、各関数の取り決めだけ。
- テストは、実コードを見ず・走らせず、設計の取り決めと要求仕様書の期待値から書く。
- テストとコードは、実装フェーズで初めて出会う（pytest 実行）。これで「動く」でなく「正しい」を確かめる。
- テストの期待値は、要求仕様書の計算例（人間が確認済みの正解）に紐づける。コードから逆算しない。
## 2. 取り決め（関数の入口と出口の約束）は物理表現まで定義する
各関数の取り決め（名前・受け取るもの・返すもの）には、テスト設計者がこれだけでテストを書ける粒度まで：
- 関数名・引数（名前と型）・戻り値
- 戻り値や受け渡すデータの物理表現：dataclass か dict か、フィールドの英語名と型
（例：LotResult は dataclass。属性 lot_no:str, mean:float, status:str）
- モジュール構成：ファイル名＝import名（例：コアは core.py ＝ import core）
- 値の決まり：日付の入力形式、丸めの桁、状態を表す文字列の値（"採用"／"除外" など）
取り決めが曖昧だと、テストを書く人と実装する人が別々の名前・戻り値を想定して噛み合わない。
中身（アルゴリズム）は書かず、表面の取り決め（何を受け取り何を返すか）は具体的に共有する。
## 3. UIに判断を置かない
- コア（計算・判定）とUI（画面）は役割を分ける。UIはコアを呼ぶだけ。
- 判断（中断する／警告する／弾く／続行する など）は、画面のボタンやイベントに紐づくものでも、
コア側の関数に切り出す。UIはそれを呼んで結果を表示するだけ。
- UIに残してよいのは、純粋な画面操作（要素の配置・表示・入力の受け渡し）だけ。
- 守らないと、判断がUIに埋もれて自動テストできず、「画面操作だから手動確認」で逃げてしまう。
## 4. ファイルは増やしすぎない
- 原則 models（データ構造）・core（読み込み・計算・判定・出力の全関数）・ui（画面）の3つに収める。
- 設定値（しきい値など）が多ければ config を足してよい。
- 「関心を関数で分ける」ことと「ファイルを分ける」ことは別もの。reader／validator／writer のように
機能ごとにファイルを増やさない。役割ごとの関数はコメントで区切って同じ core に並べる。
## 5. 正常系以外を必ず定義する
正常に動く場合だけでなく、次の5つを定義する（抜けると実装もテストも決められない）：
- 失敗・例外の経路：開けない・壊れている・権限がない・想定外の構造のとき、例外を投げるのか、
エラーを表す戻り値（status 等）に畳むのか。技術的な失敗（I/O・破損・ロック）も。
- 値の境界・特殊値：空・欠損・非数値・エラー値・ゼロ・極端な値のとき、どう扱うか。
- 状態とデータの整合：ある状態（不整合・除外など）のとき、保持するデータの中身は何か。
- 件数・重複の境界：0件・1件・重複のとき、どうふるまうか。キーが衝突したら誰がどう止めるか。
- 結果に影響する技術前提：ライブラリの動作モードで結果が変わる箇所は前提を明記
（例：Excel を数式の文字列で読むのか、計算済みの値で読むのか）。
## 6. 検証できる形になっているか
- 各要求を検証する情報が、関数の戻り値やデータ構造に乗っているか。乗っていなければ、
実装が何を入れても通ってしまう（＝検証不能）。例：「不整合のセル番地を報告する」要求なのに、
抽出関数が値しか返さず番地を持たないなら、その要求はどの戻り値からも確かめられない。
- 本文と、データ構造・対応表が、互いに矛盾していないか。
## 7. 確定待ち（勝手に埋めない・リスクで仕分ける）
- 決められない点は、勝手に仮定で埋めず「確定待ち」として、何を決めれば埋まるかと一緒に明記する。
- それが本来は要求仕様書にあるべき穴（様式・ふるまい）なら、要求側の穴である旨を明記する。
- 各確定待ちに、リスクの大きさを添える。リスクは「影響度 × 発生頻度」で見積もる。
・影響度：大＝間違った結果が正しく見えるまま出る（静かなデータ破損）／中＝目に見えて止まる
（気づける失敗）／小＝見た目が変わる程度。
・発生頻度：正しく運用されたデータで、どれくらい起きるか（よく／たまに／ほぼ起きない）。
頻度は要求の文言だけで決めず、添付された実データ（入力サンプル・完成ファイル）を実際に見て
見積もる。実データで起こりうるか確かめてから強度を決める（例：要求に「表記ゆれを正規化」とあっても、
添付サンプルにゆれが無ければ頻度は「ほぼ起きない」）。実データを見れば消えるリスクを文言だけで
過大計上しない。確かめる実データが無ければ【未検証】と明記する。
- リスク大→要求仕様書に戻って定義／リスク中→既定で進め次バージョンで検討と記録／
リスク小→既定のままでよい（要求に戻さない）。最終判断は人間。
- 全部を要求仕様書に戻さない。リスクと労力で線を引く。静かなデータ破損（影響度大）だけは、
頻度が低くても軽視しない。
## 8. 要求とのつながり
- 要求仕様書は仕上げ確認を通った確定版とみなす。要求で決まっていることは再確認しない。
- 要求IDごとに、それを実現する関数／確かめるテストを割り当て、全IDに担当があることを確認する。
## 9. ID体系（要求・設計・テストをつなぐ）
- 要求ID（REQ-x.x）：要求仕様書が幹。唯一の採番元。大・中・小の階層。
- 設計ID（DES-）：関数を一意に指す。モジュール大・関数中（core→DES-C01...／ui→DES-U01...／models→DES-M01...）。
- テストID（V-）：観点を主軸に振る（V-01...）。種類（単体／結合／手動）は観点の属性（列）にし、分類軸にしない
（1観点が単体と手動にまたがるため）。
- 3者は多対多（1関数が複数要求／1要求に複数関数）。番号一致では表せず、トレーサビリティマトリクスで結ぶ。
- コードに刻む：実装の関数は「@id: DES-Cxx ＋ @spec: REQ-x.x（一言）」、テストは「@id: V-xx ＋ @verify: REQ-x.x（一言）」。
タグは関数の本体の中の「# コメント行」に書く（docstring の中には書かない。整合チェックが拾えず未検証と誤判定される）。1行に1つのIDだけ（複数は行を分ける）。こうして固めた設計仕様書では、計算の中身（コア）と画面（UI）を節に分けて書いています。中身は下のボタンから読めます。
設計仕様書をもとに、Claude Codeで実装する
設計仕様書まで固まれば、実装はそれを土台にする作業です。Claude Codeに設計仕様書と実装用のプロンプトを渡し、設計の通りにコードを書かせます。仕様が決まっているので、ここで新しい判断はほとんど発生しません。使った実装プロンプトは下に畳んでおきます。
実装プロンプト
docs/ の要求仕様書と設計仕様書を読んでください。CLAUDE.md のルールに従います。
設計仕様書には実装の中身は無く、各関数の契約（名前・引数・戻り値）と日本語の手順があります。
あなたが、その契約と手順に従って中身を実装します。
【テストには触れない（最優先の境界）】
- テストコード（tests/ の test_*.py）は、別の担当（Web Claude）が契約と期待値から独立に書いて、
すでに配置されています。あなたは、これを書かない・置き直さない・書き換えない。走らせるだけ。
- import が通らないのをテスト側で直そうとしない。import は、あなたが実装側の名前を揃えれば通る。
直す向きは常に実装側。テストは正しさの基準なので動かさない。
【まず実装側の土台を置く（中身は書かない）】
- 設計仕様書の物理表現（2-5）の全データ構造（dataclass など）を、そのまま models 等に置く。
- 設計仕様書の全関数を、契約どおりの「空のシグネチャ」で置く（中身は実装せず、NotImplementedError
を投げるだけ）。この土台には @spec を付けない（まだ何も実現していないため）。
- これで、既に配置されているテストの import が通り、全テストが「赤（失敗）」で始まる。
ここが正しい出発点。配置するのは models と空シグネチャだけ。テストファイルは触らない。
【ここから中身を実装する（依存順・大項目の節目で報告）】
- 中項目（REQ-x.x）を、依存順で実装する（下位のロジックを先に、それを使う上位を後に）。
- 設計仕様書の関数の契約のとおりに中身を実装する（契約は変えない）。
- 実装した関数・分岐に「# @spec: REQ-x.x ＋ 何をするかの一言」を付ける。空シグネチャには付けない。
- 要求IDに対応しない土台の行には、3点ルール（いつ・どうする・無いと何が起きるか）のコメントを書く。
- 各中項目を実装したらその REQ のテストを走らせ「赤→緑」を確認しながら進む。
大項目（REQ-2／REQ-3 などの節目）まで実装したら一度止まり、テストが全部緑になったか、
psdd.py extract と psdd.py check の結果をまとめて報告する。
- ただし、契約どおりでもテストが赤のまま／仕様に無い判断が要る／テストか契約を変えるしかない、
と感じたら、節目を待たず止まって報告する（安全弁）。
仕様に書かれていない判断が必要なときは、勝手に決めず、止まって質問してください。要求仕様の項目が満たされたかを、テストとトレーサビリティで確認する
わざと取り違うデータで、不備として弾かれるかを確かめる
実装ができたら、その通りに動くかをテストで確かめます。テストの設計も、要求仕様書と設計仕様書をもとに、専用のプロンプトで作ります。ここで大事なのは、テストを設計するときに実装の中身（コード）を見ないことです。作ったものを、作った中身を見ずに、要求から確かめる。検査の世界で「作った本人が、自分の作ったものを合格にしない」のと同じ考え方です。
テスト設計プロンプト
テスト設計プロンプト
あなたは、非エンジニアの開発相談相手です。
添付の「要求仕様書」と「設計仕様書」を読み、作ったものが正しいかを確かめるテストを設計してください。
【前提：あなたは実コードを見ない・走らせない】
- 設計仕様書には、実装の中身（コード）は含まれない。あるのは各関数の契約
（名前・引数と型・戻り値の構造）と、日本語の手順だけ。
- テストは、その契約と、要求仕様書の計算例（人間が確認済みの期待値）から書く。
実コードは見ないし、復元もしない。この場でテストを実行もしない。
テストを実コードに対して走らせるのは、後の実装フェーズで Claude Code が行う。
- なぜか：実コードを見て・走らせて作ったテストは、コードがやっていることをなぞるだけになり、
コードの間違いを見つけられない。入力と期待出力だけで書くから、間違いを捕まえられる。
【守ってほしいこと】
- 「動く」だけでなく「正しい」を確かめる視点で設計する。判定の境目（しきい値ちょうど・月末・
不備データなど）を狙う。
- テスト観点は、要求仕様書のIDから起こす。中項目が観点の自然な単位になる。
- 各テストは「何を・どんな入力で・期待する出力・これで何が分かるか」を表で示す。
- 正常だけでなく、うまくいかない入力（不備データ・空ファイルなど）も入れる。
「わざと壊して、ちゃんと弾かれるか」を必ず観点に含める。
- テストコードは Python（pytest）。設計仕様書の関数の契約に沿って、入力を渡し戻り値を確かめる
形で書く。考え方を日本語で示してからコードを置く。
- テスト用の入力データ（フィクスチャ）は、要求仕様書の「入力データの様式」から作る。
Excelなどは、できあがったファイルを置かず、テストコードの中で openpyxl 等で組み立てる
（「どのセルに何を入れた入力か」が意図ごとコードに残り、独立性が保てる）。
- 要求仕様書に入力様式が無くてフィクスチャが作れないなら、それは要求仕様書の穴。そのIDは
「確定待ち」として、何の情報が足りないかと一緒に報告する（勝手に様式を仮定して埋めない）。
- 各テストに「# @verify: REQ-x.x ＋ 何を確かめるかの一言」を付ける。
- 最後に「要求ID → テスト」のカバレッジ表を付け、テストの無いID（穴）が無いか確認する。
手動確認にしてよいのは純粋な画面操作だけ。判断（中断・警告・弾く・続行など）はUIに紐づいていても
コア側の関数として自動テストする（手動確認に逃がさない）。
- 要求仕様書の「やらないこと」はテストしない。
- 完成したテスト設計仕様書は .docx で出力。テストコード（.py。フィクスチャ生成を含む）は
別ファイルで添える。tests/ に置く想定で、ファイル名は test_*.py とする。
【テスト設計仕様書の構成】
1. テストの狙い
2. テスト観点の一覧（表：観点／入力／期待する出力／これで分かること／検証ID）
3. 重点的に狙う境目（しきい値・月末・不備データなど）
4. テスト用入力データ（フィクスチャ）の作り方
5. テストコード（Python・pytest・@verify付き）
6. 要求ID → テスト カバレッジ表（自動／手動確認／確定待ちを区別）
7. テストしないこと設計の基礎（設計プロンプトと一緒に渡してください）
# 設計の基礎（このプロジェクトの共通ルール）
設計・テスト設計・実装の全フェーズで守る、共通の原則。
各フェーズのプロンプトは、このファイルを一緒に渡して「設計の基礎に従う」として参照する。
## 1. 設計とテストは独立に作る（独立性）
- 各フェーズは、前フェーズの成果物（要求仕様書・設計仕様書などの文書）だけを唯一の入力とする。
会話の履歴・記憶を根拠にしない。穴・確定待ち・矛盾の判断も、渡された文書に書いてあるか・いないか
だけで決める。「前に会話でこう言った」を持ち出すと、確定済みの事項を曖昧と誤判定したり、
文書に無い穴を作り出したりする（幻の穴）。だから各フェーズは独立したチャットで行う。
- 設計仕様書には実装の中身（コード）を書かない。書くのは日本語の手順と、各関数の取り決めだけ。
- テストは、実コードを見ず・走らせず、設計の取り決めと要求仕様書の期待値から書く。
- テストとコードは、実装フェーズで初めて出会う（pytest 実行）。これで「動く」でなく「正しい」を確かめる。
- テストの期待値は、要求仕様書の計算例（人間が確認済みの正解）に紐づける。コードから逆算しない。
## 2. 取り決め（関数の入口と出口の約束）は物理表現まで定義する
各関数の取り決め（名前・受け取るもの・返すもの）には、テスト設計者がこれだけでテストを書ける粒度まで：
- 関数名・引数（名前と型）・戻り値
- 戻り値や受け渡すデータの物理表現：dataclass か dict か、フィールドの英語名と型
（例：LotResult は dataclass。属性 lot_no:str, mean:float, status:str）
- モジュール構成：ファイル名＝import名（例：コアは core.py ＝ import core）
- 値の決まり：日付の入力形式、丸めの桁、状態を表す文字列の値（"採用"／"除外" など）
取り決めが曖昧だと、テストを書く人と実装する人が別々の名前・戻り値を想定して噛み合わない。
中身（アルゴリズム）は書かず、表面の取り決め（何を受け取り何を返すか）は具体的に共有する。
## 3. UIに判断を置かない
- コア（計算・判定）とUI（画面）は役割を分ける。UIはコアを呼ぶだけ。
- 判断（中断する／警告する／弾く／続行する など）は、画面のボタンやイベントに紐づくものでも、
コア側の関数に切り出す。UIはそれを呼んで結果を表示するだけ。
- UIに残してよいのは、純粋な画面操作（要素の配置・表示・入力の受け渡し）だけ。
- 守らないと、判断がUIに埋もれて自動テストできず、「画面操作だから手動確認」で逃げてしまう。
## 4. ファイルは増やしすぎない
- 原則 models（データ構造）・core（読み込み・計算・判定・出力の全関数）・ui（画面）の3つに収める。
- 設定値（しきい値など）が多ければ config を足してよい。
- 「関心を関数で分ける」ことと「ファイルを分ける」ことは別もの。reader／validator／writer のように
機能ごとにファイルを増やさない。役割ごとの関数はコメントで区切って同じ core に並べる。
## 5. 正常系以外を必ず定義する
正常に動く場合だけでなく、次の5つを定義する（抜けると実装もテストも決められない）：
- 失敗・例外の経路：開けない・壊れている・権限がない・想定外の構造のとき、例外を投げるのか、
エラーを表す戻り値（status 等）に畳むのか。技術的な失敗（I/O・破損・ロック）も。
- 値の境界・特殊値：空・欠損・非数値・エラー値・ゼロ・極端な値のとき、どう扱うか。
- 状態とデータの整合：ある状態（不整合・除外など）のとき、保持するデータの中身は何か。
- 件数・重複の境界：0件・1件・重複のとき、どうふるまうか。キーが衝突したら誰がどう止めるか。
- 結果に影響する技術前提：ライブラリの動作モードで結果が変わる箇所は前提を明記
（例：Excel を数式の文字列で読むのか、計算済みの値で読むのか）。
## 6. 検証できる形になっているか
- 各要求を検証する情報が、関数の戻り値やデータ構造に乗っているか。乗っていなければ、
実装が何を入れても通ってしまう（＝検証不能）。例：「不整合のセル番地を報告する」要求なのに、
抽出関数が値しか返さず番地を持たないなら、その要求はどの戻り値からも確かめられない。
- 本文と、データ構造・対応表が、互いに矛盾していないか。
## 7. 確定待ち（勝手に埋めない・リスクで仕分ける）
- 決められない点は、勝手に仮定で埋めず「確定待ち」として、何を決めれば埋まるかと一緒に明記する。
- それが本来は要求仕様書にあるべき穴（様式・ふるまい）なら、要求側の穴である旨を明記する。
- 各確定待ちに、リスクの大きさを添える。リスクは「影響度 × 発生頻度」で見積もる。
・影響度：大＝間違った結果が正しく見えるまま出る（静かなデータ破損）／中＝目に見えて止まる
（気づける失敗）／小＝見た目が変わる程度。
・発生頻度：正しく運用されたデータで、どれくらい起きるか（よく／たまに／ほぼ起きない）。
頻度は要求の文言だけで決めず、添付された実データ（入力サンプル・完成ファイル）を実際に見て
見積もる。実データで起こりうるか確かめてから強度を決める（例：要求に「表記ゆれを正規化」とあっても、
添付サンプルにゆれが無ければ頻度は「ほぼ起きない」）。実データを見れば消えるリスクを文言だけで
過大計上しない。確かめる実データが無ければ【未検証】と明記する。
- リスク大→要求仕様書に戻って定義／リスク中→既定で進め次バージョンで検討と記録／
リスク小→既定のままでよい（要求に戻さない）。最終判断は人間。
- 全部を要求仕様書に戻さない。リスクと労力で線を引く。静かなデータ破損（影響度大）だけは、
頻度が低くても軽視しない。
## 8. 要求とのつながり
- 要求仕様書は仕上げ確認を通った確定版とみなす。要求で決まっていることは再確認しない。
- 要求IDごとに、それを実現する関数／確かめるテストを割り当て、全IDに担当があることを確認する。
## 9. ID体系（要求・設計・テストをつなぐ）
- 要求ID（REQ-x.x）：要求仕様書が幹。唯一の採番元。大・中・小の階層。
- 設計ID（DES-）：関数を一意に指す。モジュール大・関数中（core→DES-C01...／ui→DES-U01...／models→DES-M01...）。
- テストID（V-）：観点を主軸に振る（V-01...）。種類（単体／結合／手動）は観点の属性（列）にし、分類軸にしない
（1観点が単体と手動にまたがるため）。
- 3者は多対多（1関数が複数要求／1要求に複数関数）。番号一致では表せず、トレーサビリティマトリクスで結ぶ。
- コードに刻む：実装の関数は「@id: DES-Cxx ＋ @spec: REQ-x.x（一言）」、テストは「@id: V-xx ＋ @verify: REQ-x.x（一言）」。
タグは関数の本体の中の「# コメント行」に書く（docstring の中には書かない。整合チェックが拾えず未検証と誤判定される）。1行に1つのIDだけ（複数は行を分ける）。確かめたことは2つです。1つは、3つの様式すべてで2つの経路が同じ測定値に届き、一致したこと。もう1つは、わざと様式をずらしたデータを入れたとき、照合が食い違い、不備として弾かれたことです。正常に通ることだけでなく、壊れたものがきちんと弾かれることまで確かめます。
テストはClaude Codeで実行します。下のプロンプトでテストを走らせた結果、30項目すべてが通りました（30件成功・0件失敗）。テスト項目の一覧や期待値の作り方は、テスト設計仕様書にまとめてあります。
テスト実行プロンプト
tests/ に、Web Claude が契約と期待値から書いたテストコード（test_*.py）が配置されています。
あなたはそれを書き換えず、実装した実コードに対して pytest で走らせてください。
- テストの期待値や assert を、通すために緩めない。テストもコードも甘くしない。
- 落ちたら、(a) 実装が契約や仕様を外したか、(b) テストの期待値が仕様を読み違えたか、を
切り分けて報告する。自分でどちらかを勝手に直さず、まず報告する。
- psdd.py check を実行し、@verify と @spec が spec_ids.json と合うか、未検証のIDが無いかを報告する。
テストを通すこと自体を目的にしない。目的は、実コードが仕様どおりかを確かめることです。トレーサビリティマトリクスで、要求の取りこぼしがないかを見る
トレーサビリティマトリクスは、聞き慣れない言葉ですが、中身は単純です。「どの要求が、どの関数で実現され、どのテストで確かめられたか」を、一行ずつ並べた表です。要求の一つひとつに、設計とテストの担当が割り当たっているかを、一覧で見渡せます。
これがあると、後から来た人でも「この機能はなぜあるのか」「どこで正しさを確かめたのか」を辿れます。作った本人がいなくなっても、表をたどれば追える。属人化を避ける仕組みです。
結果として、すべての要求に担当が割り当たり、取りこぼし（担当のない要求）はありませんでした。ただし、確かめ方は1種類ではありません。表の上では、次の3つに分けています。
- 自動で確かめた：
測定値の照合や平均の再計算など、計算と判定の中身。プログラムが機械的に確かめる。 - 手で確かめた：
フォルダを選ぶ画面操作など、人が実際に動かして確かめる部分。 - 確定待ちとして残した：
測定値の並びをどこで区切るかなど、要求の側で一言決めておくとよい宿題。
「すべて合格」で終わらせず、どこを自動で確かめ、どこが手作業や宿題として残っているかを、表の上で正直に分ける。手作業で確かめる部分は、次の章で実際にツールを動かして確認します。テスト設計仕様書とトレーサビリティマトリクスは、下のボタンから読めます。
仕様書通りに実装し、実際にツールを動かす
要求・設計・テストの仕様書がそろい、テストも通りました。ここからは、実際にツールを動かして、手作業がどう変わるかを見ます。
ツールの画面はこれだけです。集計したい品目のフォルダを選び、実行ボタンを押す。それで終わりです。
［画像：ツールのGUI画面（フォルダ選択と実行ボタン）］
今回は品目A（六角ナット）のフォルダを処理しました。この品目には検査項目が2つ（高さ・二面幅）あるので、出力も項目ごとに分かれ、「高さ」と「二面幅」の2つのExcelファイルができます。検査項目が増えれば、その数だけファイルが出ます。
1つのファイルは、3つのシートでできています。読み込んだロットの一覧を載せたサマリー、平均値の推移を見る表とグラフ、そして個々の測定値をすべて残したデータ台帳です。
まずは高さの集計結果を示します。
同じように二面幅についてもファイルが生成され同じ様式で出力されていることを確認しました。
一点、思いどおりにいかなかったところもあります。平均値の推移は、本来は点を打つだけの散布図にしたかったのですが、できあがったグラフは点を線でつないだ形になりました。グラフは散布図の表示ではあるのですが、点を線でつなぐ散布図の表示もあるようです。仕様書で意図を決めても、細かい表示までは一度で思いどおりにならないことがある——これも、実際に動かして初めて見える部分です。グラフの形は、後から指示し直して整えられます。
毎月、ファイルを1つずつ開いて転記していた集計が、フォルダを選んで実行するだけになりました。
テストで自動化できない部分を、実機で確かめる
トレーサビリティの表で「手で確かめる」「通しで確かめる」とした項目は、関数単位の自動テストでは確かめきれません。実際にツールを動かして、次の点を確認しました。
- フォルダの読み込み：
選んだフォルダ内の全ロットを順に読み込み、出力フォルダや一時ファイルを誤って拾わないか。 - 不備の一覧表示と判断：
全ロットを先にチェックし、不備ロットを一覧で示して、続行か中止かを人が選べるか。 - 除外の反映：
続行を選んだとき、不備ロットだけを除外し、正常ロットだけで集約Excelが作られるか。 - 出力ファイルの中身：
検査項目ごとにファイルが分かれ、3つのシートと表・グラフが想定どおりに書き出されるか。
特にテストで確認できなかった不備、除外の反映は異常系として実際のアプリで確認する価値はあります。
これらはトレーサビリティマトリクスに項目として並んでいるので、表をたどれば、どこを実機で確かめるべきかが分かります。自動テストと実機確認を分けて、両方をやり切って初めて、要求仕様書の項目が満たされたと言えるわけです。
このツールをどう発展させるか
修正は、リスクの大きさで進め方を変える
先ほどのグラフのように、動かしてみて初めて「ここを直したい」と気づくことがあります。このとき、毎回すべての仕様書を作り直していては、いつまでも終わりません。かといって、何でも実装を直接いじると、仕様書と中身がずれていきます。そこで、修正のリスクの大きさで、進め方を分けます。
判断の軸は、変えるのが「外側」か「内側」かです。グラフの形や軸の単位、画面の見た目といった外側の表示は、間違っても目で見てすぐ気づけます。一方、測定値の取り方や平均の計算といった内側のロジックは、間違っても結果がそれらしく出てしまい、気づけません。だから、この2つは直し方を変えます。
- 外側（表示・レイアウト）＝軽い修正：
グラフの形、軸の単位、画面の見た目など。間違ってもすぐ気づけるので、Claude Codeに直接指示して直す。直した内容は、後から差分として要求仕様書に書き戻しておく。 - 内側（計算・判定）＝重い修正：
測定値の取り方、照合の仕方、平均の計算など。間違っても静かに通ってしまうので、要求仕様書から見直し、設計・テストの仕様書も更新してから実装し直す。
今回のグラフの手直しは、表示だけの話で、測定値の取り方には一切影響しません。だから外側の軽い修正として、直接直して差分を仕様書に戻せば十分です。仕様書を土台に置く考え方は保ちつつ、軽い修正は速く回す。この使い分けが、現実的な開発の速さにつながります。
機能を足して、さらに使いやすくする
このツールには、まだ伸ばせる先があります。
- 複数品目の一括処理（バッチ処理）：
今は1品目のフォルダを都度選ぶ作りです。親フォルダを選べば、その配下にある複数品目のフォルダをまとめて処理する形にすれば、品目が多いほど手間が減ります。 - 他の様式への対応：
今回は代表3様式を扱いました。社内に別の書式があれば、その様式定義を足して対応範囲を広げられます。 - 統計機能の追加：
合否判定、Cp・Cpk、管理図。今回「やらないこと」に置いたものを、確保した測定値の台帳を土台に足していけます。
これらは内側のロジックに関わるので、思いつきで実装に足すのではなく、要求仕様書から見直して進めます。土台がある分、ゼロから作るより確実に、そして速く積み増せます。
まとめ
品目が多く、様式もばらつく検査成績書を、取り違えずに集計する。この課題を、プロンプト仕様駆動開発（PSDD）で、要求から実機まで通して解いてみました。
- 品目が多く一つずつ対応できないため、様式を選ばず処理できる仕組みを目指した
- 何を作るかは、問診形式のプロンプトで要求仕様書にまとめた
- 測定値は、数式の足跡と、様式の並びという2つの独立した経路で取り、一致を正しさの根拠にした
- 取り違えはデータを疑うのではなく、ツールが様式を取り違えていないかを確かめることで防いだ
- テストとトレーサビリティで、要求の取りこぼしがないかを確かめ、自動・手動・確定待ちを正直に区別した
- 修正は、表示などの外側は直接直し、計算などの内側は仕様書から——リスクの大きさで進め方を分ける
仕様書を土台に置くと、後から誰が見ても、なぜそう作ったのかを辿れます。動いたかどうかだけでなく、正しいと言える根拠が残る。これが、手作業や場当たりの自動化との違いです。今回はその一例でした。
※注意：この記事で扱ったデータ・品名・測定値は、すべて架空のものです。実在の企業・製品とは関係ありません。
コメント