設計書は、Claude が資料をもとに Markdown で書き、スクリプトで Excel に変換して提出します。正本は GitLab に置いた Markdown だけで、Excel は Markdown からいつでも作り直せる写しとして扱います。
-
入力資料を集める
仕様書、業務の流れ、既存の Excel、議事録を Claude に読ませます。決まった書式で用意する必要はありません。Claude は確定している情報だけを拾い、決まっていないことは未決事項の表に回します。 -
Claude で Markdown の設計書を作る
Claude は、スキル（AI への作業指示）とテンプレートに沿って、要件定義書・基本設計書・詳細設計書を書きます。詳細設計書は画面ごとに1ファイルです。3つの文書は REQ-001 や SCR-001 のような ID でつながっているので、要件から画面までたどれます。文章の言い回しと判断は人が直し、GitLab の MR（レビュー依頼）で確認してから取り込みます。 -
スクリプトで Excel に変換する
変換は design-doc-sync という変換ルールに沿ってスクリプトが行います。AI が書き直すわけではないため、変換の途中で内容が変わることはありません。Excel の表紙には、元にした Markdown の版を入れます。できあがった Excel は SharePoint に置き、提出に使います。 -
指摘を Markdown に戻す
先方が Excel に吹き出しを付けたり直接直したりした場合は、まず変更点を Claude に一覧にさせます。それを人が確認してから Markdown に反映し、Excel を作り直します。Excel を正本にしない理由は、2つのファイルを並行して直すと、どちらが新しいか分からなくなるからです。
Excel 側での修正を「指摘」として受け取るこの運用は、まだチームで合意していない提案です。以前決めた「Excel・Markdown のどちらからでも直せる（案A）」と食い違うので、ここだけ先に決めておく必要があります。
文章は natural-japanese のルールに沿って書きました。手元の環境では付属の自動チェックが動かなかったため、手動チェックリストで確認しています。
設計書作成の流れとディレクトリー配置
設計書は、Claude が資料をもとに Markdown で書き、スクリプトで Excel に変換して提出します。正本は GitLab に置いた Markdown だけで、Excel は Markdown からいつでも作り直せる写しとして扱います。
1. 作成の流れ
1.1 入力資料を集める
仕様書、業務の流れ、既存の Excel、議事録を Claude に読ませます。決まった書式で用意する必要はありません。Claude は確定している情報だけを拾い、決まっていないことは未決事項の表に回します。
1.2 Claude で Markdown の設計書を作る
Claude は、スキル（AI への作業指示）とテンプレートに沿って、要件定義書・基本設計書・詳細設計書を書きます。詳細設計書は画面ごとに1ファイルです。3つの文書は REQ-001 や SCR-001 のような ID でつながっているので、要件から画面までたどれます。
文章の言い回しと判断は人が直し、GitLab の MR（レビュー依頼）で確認してから取り込みます。
1.3 スクリプトで Excel に変換する
変換は design-doc-sync という変換ルールに沿ってスクリプトが行います。AI が書き直すわけではないため、変換の途中で内容が変わることはありません。Excel の表紙には、元にした Markdown の版を入れます。できあがった Excel は SharePoint に置き、提出に使います。
1.4 指摘を Markdown に戻す
先方が Excel に吹き出しを付けたり直接直したりした場合は、まず変更点を Claude に一覧にさせます。それを人が確認してから Markdown に反映し、Excel を作り直します。Excel を正本にしない理由は、2つのファイルを並行して直すと、どちらが新しいか分からなくなるからです。
要合意 Excel 側での修正を「指摘」として受け取るこの運用は、まだチームで合意していない提案（松本）です。以前決めた「Excel・Markdown のどちらからでも直せる（案A）」と食い違うので、ここだけ先に決めておく必要があります。
2. ディレクトリー配置
設計書のファイルは、GitLab のリポジトリ1つにまとめます。AI への指示（スキル）と設計書本体を同じ場所に置くと、Claude が毎回同じ手順とテンプレートで書けます。
（リポジトリ）/
├── CLAUDE.md … 「@AGENTS.md」の1行だけ
├── AGENTS.md … 案件の目次。AI が最初に読む
├── README.md
├── docs/ … 設計書の正本（Markdown）
│ ├── 01_要件定義/
│ │ └── 要件定義書.md
│ ├── 02_基本設計/
│ │ └── 基本設計書.md
│ ├── 03_詳細設計/
│ │ └── 詳細設計書_SCR-001_備品申請登録.md … 画面ごとに1ファイル
│ └── coding-standard.md
├── .claude/
│ ├── skills/ … 書き方の手順とテンプレート
│ │ ├── write-requirements/ SKILL.md・template.md
│ │ ├── write-basic-design/ SKILL.md・template.md
│ │ ├── write-detailed-design/ SKILL.md・template.md
│ │ └── design-doc-sync/ SKILL.md・templates/（MD と Excel のひな形） ※案
│ └── agents/ … 役割を分けた AI
│ ├── req-analyst.md
│ ├── design-reviewer.md
│ └── doc-researcher.md
└── tools/ … MD ⇔ Excel の変換スクリプト ※案
├── md2excel.py
└── excel2md.py
Excel は GitLab には置かず、SharePoint に置きます。Markdown からいつでも作り直せるので、Git で版を管理する必要がないからです。
※案 の2か所は、今はサンプルとは別の zip（設計書フォーマット、MD と Excel の往復の実証）に入っています。実際の案件では、上のようにまとめてリポジトリに入れることを提案します。
AGENTS.md は短く保つ
ここに書くのは、資料の場所、ID の付け方、AI への約束ごとの3つだけです。詳しい内容は docs/ に書き、AI は ID で検索して必要な部分だけを読みます。全文を毎回読ませないことで、トークンの消費を抑えます。
| ID の種類 | 形式 | 例 |
|---|---|---|
| 要件 | REQ-連番3桁／非機能 NFR-連番3桁 | REQ-001, NFR-004 |
| 機能 | FUNC-連番3桁 | FUNC-001 |
| 画面 | SCR-連番3桁 | SCR-001 |
| テーブル | TBL-連番3桁 | TBL-001 |
| メッセージ | MSG-種類1文字＋連番3桁（I:情報 W:確認 E:エラー） | MSG-E001 |
| 未決事項 | Q-連番3桁 | Q-001 |
| 単体テスト | UT-連番3桁 | UT-001 |
3. 使用しているスキル
スキルは4つです。3つが設計書を書くためのもので、1つが Excel に変換するためのものです。
| スキル | 使う場面 | 主な手順 |
|---|---|---|
| write-requirements | 議事録やヒアリングメモから要件定義書を作る・直す | 資料を「困っていること・やりたいこと・決まったこと・決まっていないこと」に分け、要件に REQ-xxx を振る |
| write-basic-design | 要件定義書から基本設計書を作る | REQ を1つずつ機能（FUNC-xxx）に割り当て、どの機能にも対応しない要件を残さない。画面一覧と画面遷移図も作る |
| write-detailed-design | 画面1つ分の詳細設計書を作る | 基本設計書からその画面に関係する部分だけを ID で読み、クラス構成・入力チェック・SQL・単体テストの観点を書く |
| design-doc-sync | Markdown と Excel を変換する | 章はシート、表の列はそのまま、Mermaid の図は Excel の図形に対応させる。ID の振り直しや推測での穴埋めはしない |
どのスキルにも共通する決まりが1つあります。分からないことは推測で埋めず、未決事項（Q-xxx）の表に書くことです。
4. スキルと一緒に使うエージェント
スキルが「書き方」なのに対し、エージェントは「誰がやるか」を決めます。役割ごとに使える道具を絞っています。
| エージェント | 役割 | できること |
|---|---|---|
| req-analyst | 要件定義の担当 | 資料を読み、要件定義書を書く |
| design-reviewer | レビューの担当 | REQ → FUNC → SCR → TBL のつながりと漏れを確認する。ファイルは変更しない |
| doc-researcher | 調べ物の担当 | 「SCR-001 の入力チェックは？」のような質問に、根拠の場所を付けて5行以内で答える |
design-reviewer がファイルを変更できないようにしているのは、書く役と確かめる役を分けるためです。AI のレビュー結果は指摘の一覧として受け取り、直すかどうかは人が決めます。
5. 決めること
- 正本を Markdown だけにするか（案A との食い違いの解消）
- design-doc-sync と変換スクリプトをリポジトリのどこに置くか（上の ※案）
- Excel を置く SharePoint のフォルダー