AIで書いた仕様書をクライアント向けの仕様書に変換するスキルを作成しました

仕様書にも色々ある

業務系の受託開発をやっていると、「仕様書」と言っても読み手に合わせて様々な形式のものが必要になります。

• エンジニア向けの仕様書: 実装の指針、データ構造、エッジケース、テスト観点まで含めたもの
• クライアント向けの仕様書: 「何ができるのか」をビジネス用語だけで書いたもの

最近はAIコーディングが主流になってきました。自分は実装前に仕様書を書くワークフローを採用しているのですが、せっかくならこの仕様書をクライアント向けの仕様書にも流用したいと思い、変換用のスキルを作ってみました。

全体像

ワークフローはこうなっています。

1. エンジニア向け仕様書（specs）は、スキルsuperpowers:brainstorming^[1]で作成
2. クライアント向け仕様書は、自作のスキルがspecsを読んで、専用テンプレートに沿った Markdownファイルを生成
3. MarkdownファイルをpandocでWordファイルに変換

という流れです。

自作スキルの中身

自作スキルでは上記の2,3のフローを自動化しています。
下記が中身です。

---
name: create-spec-review
description: 仕様書（specs）をもとにクライアント向けの仕様書（docx）を作成するスキル。
---

# 仕様書作成スキル

## ステップ1: 入力を確認する
ユーザーが指定した仕様書ファイルのパスを確認する。
指定がなければ `docs/superpowers/specs/` 配下の最新ファイルを候補として提示し確認する。

## ステップ2: 仕様書とテンプレートを読む
1. 仕様書ファイル（ユーザー指定のもの）
2. テンプレート（`docs/templates/機能仕様書.md`）

## ステップ3: 仕様書Markdownを作成する

### 執筆の方針
対象読者はシステムに明るくないビジネス担当者。以下を徹底する：
- ファイル名・関数名・コンポーネント名などの技術用語は一切使わない
- 「何が"できるようになるか"」を中心に書く
- 専門的な処理は平易な言葉で説明する
- 箇条書きを活用し、読みやすく簡潔にまとめる

## ステップ4: docxを生成する
bash docs/scripts/convert-to-docx.sh {MDファイルパス} "{タスク名}" {YYYYMMDD}

ポイントは3つです。

「技術用語禁止」を明文化する

クライアント向け仕様書では、読み手のコンテキストに合わせて技術的な専門用語を使わないように指示しています。
これはスキル内で「ファイル名・関数名・コンポーネント名などの技術用語は一切使わない」と明示的に禁止事項として書くとかなり防げます。

それに加えて、「何が『できるようになるか』を中心に書く」というポジティブな指針もセットで入れています。禁止事項だけを指示するのではなく、代替手段も合わせて書くことで出力のブレが少なくなるようにしています。

テンプレートを別ファイルに切り出す

クライアント向け仕様書の章立ては固定にしたかったので、テンプレートのMarkdownファイルとして用意し、スキルにはそれを読ませる形にしています。

## 背景・目的
## 対応内容
## 画面仕様
## 影響範囲
## 今回の対応に含まれないこと
## 備考

「今回の対応に含まれないこと」は重要で、これを明示しておくと実装機能の範囲を明確に示せて、認識齟齬が少なくなります。

Wordファイルへの変換はpandocに投げる

Markdown → Wordファイルの変換はpandocというオープンソースのドキュメント変換ツールを使っています。スキルの中で次のようにシェルスクリプトを呼ぶ形にしています。

bash docs/scripts/convert-to-docx.sh {MDファイルパス} "{タスク名}" {YYYYMMDD}

スクリプトの中身はpandocにオプションを指定して叩いているだけです。特別なことはしていませんが、1点だけ工夫しているのは、--reference-docオプションを指定して、別途用意したテンプレートファイルを参照し、出力スタイルを固定している点です。

使ってみてどうか

良かった点：

• 言い換えの揺れが減る: 同じ機能を別の場所で別の言葉で説明していたのが、specs → クライアント向け仕様書という一方向の流れになるので、表現がブレない
• 引き継ぎや非エンジニア向けの説明資料としても使える: 仕様書がそのまま社内共有資料として使える

逆に気をつけている点：

• 生成されたドキュメントは必ず人間がレビューする： 特に「今回の対応に含まれないこと」は、AIが書きすぎる傾向があるので削る方向で見直しています。また要件によって出力内容にも多少ばらつきが出てしまうので、肉付けも含めて最終的にはかなり手直しをしています（この点はスキルの修正余地あり）。
• specs側に書いてない決定事項は、クライアント向け仕様書にも出てこない：当たり前ですが、specsが薄いとクライアント向け仕様書も薄くなります。逆に言うと「specsを書く段階で意思決定を済ませる」ことが強制されるので、これは結果的にプラスに働くかもしれません。

まとめ

• AI駆動開発で書いたspecsを一次成果物として、スキルでクライアント向け仕様書に変換する仕組みを作った
• スキルには「技術用語禁止」「『できるようになるか』を中心に書く」など、執筆方針を明文化しておくと安定する
• Wordファイル変換は「pandoc+テンプレートファイル」で出力スタイルを揃える

脚注

1. SuperpowersはClaudeCode向けのオープンソースのスキル。brainstormingはその中の1つで、対話を通じて要件を詰めてspecsを出力してくれます。