操作マニュアルの初稿をソースコードから生成する（設計編）

はじめに

こんにちは。くにきちです。

久しぶりの投稿です。いまもプロダクトの利用者向け操作マニュアルを作る仕事をしています。コードを書く仕事ではありません。

最近は Claude にマニュアルの生成を任せてみたり、タスク管理をさせて雑事を引き取ってもらったりと、試行錯誤しながら戯れています。今回はそのうち、ソースコードを分析してマニュアルの初稿を生成する仕組み（下図）を作った話です。

この記事は、マニュアルを書く仕事をしている方と、書き手のいるチームで仕組みを考える立場の方に向けて書きました。コードを書ける必要はありません。書き慣れている人でも、どのコードを見に行けばいいかを探す工程では止まるものだと思います。私が外したかったのは、そこでした。

注意点

• 紹介する仕組みは未公開です。 土台に使った OSS（tsumiki ）の公開版には、利用者向け操作マニュアルを生成する機能は入っていません。この記事を読んで公開版を入れても、マニュアルがそのまま生成されるわけではありません。お伝えしたいのは、そこに至るまでに何を決めたかのほうです。
• 題材は架空の蔵書管理アプリで、載せているコードや設定は説明のために書き起こした例です。
• Git とコマンドラインの基本操作が必要です。理由は最後に書きます。

なぜ作ろうと思ったか

背景

マニュアルには、画面にどの項目が並ぶのか、選択肢に何が入るのか、入力できる文字数はいくつか、どんなエラーが出るのかを、正確に書く必要があります。しかし、それらが記載された仕様書があるとは限りません。あったとしても、最新の状態が保たれているとは限りません。

結局のところ、一番正しいのは実装です。そのため、ソースコードを読んだり、実際に画面を操作したりしながら確認する必要がありました。

とはいえ、私はそのプロダクトの実装者ではありません。そのうえ、担当するプロダクトによって技術スタックも変わります。マニュアルを書くたびに、どこを見ればいいのかを手探りで探すところから始めていました。当然、時間がかかります。手探りである以上、見落としも起きます。書き終えたあとやレビューの段階で、選択肢やエラーの記述漏れに気づくこともありました。

社内 AI 活用推進の波に

ちょうどその頃、社内で AI 活用が推進されはじめ、私も Claude を使い始めました。最初は自分の書いた文章をチェックさせたり、ドキュメントの要約を考えてもらったりと、小さなことからです。試すうちに、ソースコードの確認にも使うようになりました。

そのうちに 「そうだ、AI にコードをまるっと分析させよう」 と思ったのが、はじまりでした。

まず AI に書かせてみた

やってみたのは、コードを読ませて操作マニュアルの初稿を書かせることです。このとき、書き方のテンプレートも一緒に渡していました。

出てきたものは、悪くありませんでした。ただ、2 本目、3 本目を作るうちに困ったことが出てきます。同じように頼んでいるのに、毎回書きっぷりが変わるのです。

• ページ冒頭の書き出しが変わる
• セクションの分け方が変わる
• 項目の説明が、あるページでは 1 文なのに、別のページでは 3 文になる

1 本ずつ読めば「どれも間違ってはいない」のですが、並べると記述が揃っていません。

これは、読者にじわじわと効いてきます。操作マニュアルは、1 ページだけ読んで終わるものではありません。画面を切り替えながら、何ページも続けて読むものです。ページごとに書きっぷりが変わると、読者はそのたびに読み方を切り替えなければなりません。この積み重ねが負担となり、結果として「読みにくいマニュアル」になってしまいます。

テンプレートを渡していたのに、なぜ揃わないのか。あとで分かったのは、渡していたテンプレートが「どういうセクションを置くか」までしか決めていなかったことでした。たとえば、次のようなことが決まっていませんでした。

• タイトルはどういう形式で書くか
• 操作の手順は何ステップで書くか
• ページ概要の語尾をどう揃えるか
• 画面のボタンやメニューをどの記号で囲むか
• 同じものを指す言葉が複数あるとき、どれを使うか

決めていない部分は、AI がその場で判断します。そして、毎回同じ判断をするとは限りません。揃わなかったのは AI のせいではなく、私が決めていなかったからでした。

決めたことをファイルに書き出した

そこで、決めていなかったことを 1 つずつ書き出しました。テンプレートに「このセクションはこう書く」という指示を足し、用語や記号のルールは別ファイルにまとめました。当時担当していたプロダクト向けに作ったのが最初です。仕組みというより、テンプレートとルールのファイル一式です。呼び出すと、AI がそれを読んでからマニュアルを書きます。

やってみると、たしかに揃うようになりました。同時に、書き出す量がかなり多いことも分かりました。操作の種類ごとにテンプレートが必要になるからです。検索する画面、何かを登録する画面、状態を変える画面では、書く型がそれぞれ違います。

このとき私は、自分がふだん何を考えて書いていたのかを、はじめて文章にしました。どういう情報をどういう順番で見せるか。エラーの説明には何を書けば、読者が復帰できるか。「なんとなくそうしている」と思っていたことにも、書いてみると理由がありました。時間はかかりましたが、ここがいちばん効いた作業です。

すでに分析機能を持つ OSS に載せた

ファイル一式はできましたが、コードを読む部分は、AI にその場で任せたままでした。そこを毎回うまく頼むのも大変です。

調べてみると、コードを読んで文書を出す機能を持った OSS がありました。tsumiki です。AI 駆動開発を支援するフレームワークで、Claude Code のプラグインとして配布されています。備わっているのは、プロジェクトの技術スタックや構造の分析、ソースコードからの画面仕様の生成、既存コードからの設計文書やテスト仕様書の逆生成といった機能です。

つまり「コードを読ませて文書を出す」という筋道は、もともとフレームワーク側にありました。そこで、私が書き出したテンプレートやルールを、その上に載せることにしました。ゼロから設計したのではなく、同じ筋道の上に、マニュアルを出すための手順を足したことになります。

この土台はよそのチームも使います。そのため、土台側のもとの動きは変えないことも決めました。私が足したのは、マニュアルを生成するための手順と、オンにしたときだけ効くオプション設定です。公開版が文書として出せるのは、先に挙げたとおり開発者向けのものだけで、利用者向けマニュアルの生成は手元の開発・検証用リポジトリにしかありません。品質が固まってから載せるつもりで、いまは見送っています。

載せるときに 3 つに分けた

載せる作業をしていて、書き出したファイルがそのプロダクト専用になっていることに気づきました。別のプロダクトでは、そのまま使えません。そこで中身を見直し、3 つに分けました。

• プロダクトが変わっても同じもの … コードの読み方、書き方の既定
• プロダクトごとに変わるもの … どのコードを見に行くか、そのプロダクト向けの書き方
• 機械に任せられるもの … 用語や語尾が揃っているかの検査

これが 3 層になりました。人の確認は層に入れず、3 層を通したあとに置いています。

右の 2 列が要点です。プロダクトごとに新しく書くものの大半を第 2 層に寄せ、生成したマニュアルも含めてプロダクト側のリポジトリに置きました。第 1 層は、プロダクトが増えても触りません。

もう少し細かく示すと、次のようになります。左上のソースコードを起点に、下へ読んでください。

なお、第 2 層で使う書き方の既定は第 1 層側が持っているため、図では第 1 層の中に入れています。

第 1 層 コードの読み方

分ける作業をしていて、ひとつ気づいたことがあります。技術スタックは変わっても、「何を探しているか」は変わっていませんでした。一覧画面のフィルタ条件を洗い出す。入力欄の必須・任意と文字数上限を拾う。実際に発生し得るエラーを抽出する。言語もフレームワークもディレクトリ構成も違うのに、やっていることは毎回同じでした。変わっていたのは、その情報がどこに書いてあるかだけです。

つまり、毎回ゼロから手探りしていた作業は、「読み方」と「当たり先」に分けられます。そして、読み方は使い回せます。これが第 1 層と第 2 層を分けた理由です。

「読み方」に何を書いたか

読み方とは、マニュアルに書ける確かさになるまで調べる手順です。

コードを最初から全部読むわけではありません。tsumiki には画面仕様を作る機能（dev-screen-spec）があるので、まずそれを走らせます。出力に入るのは、画面の名前、並んでいる要素、入力項目です。ここまでは公開版だけでできます。

ただ、マニュアルに書くには足りません。入力できる文字数の実際の値、読者が実際に目にするエラーの文言、その操作を誰ができるか。これらは出力に入らないので、コードから取りに行きます。

そしてもうひとつ。dev-screen-spec の出力は、項目ごとに「コードから確かめたもの」と「推測で埋めたもの」を区別してくれます。私が足した側では、推測のほうはマニュアルに持ち込まず、コードで取り直す ようにしました。AI が出したものを次の AI に渡すため、どこまで確かなのかを一緒に引き継がないと、推測がそのままマニュアルの文章になってしまいます。

コードから取りに行く手順は、次のとおりです。入力欄の文字数上限なら、要点だけ挙げるとこうなります。

1. その画面を実際に描いているファイルを確定する
2. そこから入力欄を拾い、画面側とサーバ側の両方の入力チェックまで辿る
3. 上限が定数名で書かれていたら、定数の中身まで見に行って実際の数値にする
4. 画面側とサーバ側で値が違ったら、読者が実際にぶつかるほうを採る
5. 確定しなかったものは空欄にせず、「調べたが無い」のか「調べたが決まらない」のかを書き分ける

手順 1 は、はじめは入れていませんでした。名前が似ているだけのファイルや、もう使われていない古いファイルが残っていることがあります。そこを読むと、実在しない項目を書いてしまったり、逆に実在する項目が抜けたりします。画面のアドレスから辿って、本当に表示されているファイルはどれかを先に決める。この一手間を入れるまで、原因の分からない食い違いが出ていました。

手順 3 も地味に大事でした。マニュアルに「BOOK_TITLE_MAX 文字以内で入力してください」と書いても、読者には通じません。定数の中身まで見に行って「100 文字以内」にする、というところまで手順にしておかないと、そこで手が止まります。

手順 4 は、どちらかを固定で正とするものではありません。画面側で先に弾かれるならその値が読者の目に入りますし、画面側をすり抜けてサーバ側で弾かれるなら、そちらが目に入ります。読者が実際に見る値はどれか、で決めます。

そして、いちばん強く決めたのが手順 5 の推測で埋めないことです。「調べたが無い」と「調べたが決まらない」は意味が違うので、同じ空欄にはしません。決まらないものは、その場で決めずに人へ返します。ここを曖昧にすると、検査に通っても中身が信用できなくなります。

探すものごとに、この形で手順を書いてあります。書き先は Claude Code のスキルです。スキルとは、Claude Code に「こういう手順で作業してください」と書いておくファイルで、呼び出すとそのとおりに動きます。

決めた原則はひとつです。コードの読み方は汎用の側に置く。プロダクトごとに変わるのは、どのコードを見に行くかと、どう書くかだけにする。

第 2 層 どこを読むか

第 1 層が「読み方」なら、第 2 層は「どこを読むか」です。プロダクトごとに新しく書くものは、ほぼここに集まります。

最初に作ったときは、この層を 2 つに分けていました。当たり先と用語集を書く設定と、テンプレートや校正ルールを書く場所です。どちらも自分で用意する前提でした。

これで失敗しました。次のプロダクトを担当したとき、当たり先はすぐ書けたのに、テンプレートの前で止まったのです。前のプロダクトのものを持ってくるにも、どこがそのプロダクト固有でどこが汎用なのか、自分で書いたはずなのに分かりません。結局、また白紙から書き起こすことになりました。分けたはずなのに、いちばん重い作業だけが毎回そのまま残っていたわけです。

そこで、汎用にできる部分を第 1 層側に既定として引き上げ、3 段構えにしました。

ねらいは、何も書かなくても動く状態から始められるようにすることです。

1. 既定（書き方は決めなくても動く）

1 段目は、最初にプロダクト専用で書き出したものを、汎用の形に直して第 1 層側に持たせたものです。設定で何も指定がなければ、これがそのまま使われます。操作の種別や権限ロールにも既定があり、初期化のときの回答に応じて、そのプロダクトに合ったものが入ります。

イメージが湧きにくいと思うので、架空の蔵書管理アプリで操作ページの例を挙げます。説明のために書き起こしたもので、実際の既定と一致するものではありません。

# 蔵書を検索する

蔵書を条件で絞り込んで一覧表示する方法を説明します。

## 操作する前に

- この操作は館長、司書、来館者が実行できます。

## 操作方法

1. サイドメニューの [蔵書管理] ＞ [蔵書検索] をクリックします。
2. 検索条件を入力します。
3. [検索] ボタンをクリックします。

## 検索条件

| 項目名 | 説明 |
|---|---|
| タイトル | 部分一致で検索します。100 文字以内で入力してください。 |
| 著者名 | 部分一致で検索します。50 文字以内で入力してください。 |
| 貸出状態 | すべて／貸出可／貸出中 から選択します。初期値は「すべて」です。 |

## エラーが発生した場合

| エラーメッセージ | 対処方法 |
|---|---|
| タイトルは 100 文字以内で入力してください | 入力内容を 100 文字以内に修正してください。 |

さきほど「決めていなかった」と書いたものが、ここでは決まっています。概要の語尾、手順のステップ数、項目の表の列、ボタンの書き方です。だから、1 本目からある程度揃った形で出てきます。

白紙から始めるのと、動くものを直していくのとでは、着手のしやすさがまったく違います。最初に私が味わったのは前者でした。

2. 設定（初期化で雛形ができる）

前の段で「何も決めなくてよい」と書いたのは、書き方の話だけです。この段の設定ファイルは必須で、これがないと生成が始まりません。

とはいえ、形式を自分で考える必要はありません。初期化のスキルを 1 回実行すると、対話形式で聞かれるので答えていくだけで、プロダクト側のリポジトリに設定ファイルと用語集の雛形ができます。設定の中身は、だいたい次のくらいの細かさです。

# 説明用に書き起こした例です。実際の設定ファイルの形式ではありません。
# 値は架空の蔵書管理アプリのものです。
sources:
  - label: 画面まわり          # 画面の項目・選択肢・入力制限が確定する場所
    dir: src/pages/books/
  - label: サーバまわり        # バリデーションとエラー文言が確定する場所
    dir: api/handlers/books/

用語集も、雛形ができたあと専用のスキルで既存の文書やコードから集めて育てられます。

3. 上書き（書き方を自分の流儀にする）

3 段目は、テンプレートと校正ルールを差し替えるところです。章立ては設定ファイルに直接、各セクションの書き方と校正ルールは別ファイルに書いて置き場所を指定します。効き方の規則は同じで、指定があればそれ、無ければ既定です。

置き場所はそのプロダクトのリポジトリにして、コードと同じように変更履歴を追えるようにしました。テンプレートが出すのは、特定の出力ツールに依存しないプレーンな Markdown です。

ここが、最初に私が手で書き出したものと同じ役割です。違うのは、既定を土台に始められる点だけです。

当たり先は、自分で書けるのか

ここまで読んで、こう思った方がいるかもしれません。「どのコードを見ればいいか分からないことが問題だったのに、その当たり先を自分で書けるなら苦労していないのでは」。

もっともな疑問です。私も最初にそう思いました。実際に書いてみると、必要なのは「画面まわりのコードはこのあたり」「サーバ側はこのあたり」というディレクトリ単位の粗さで足りました。その中から探すのは AI の担当です。機能のキーワードを渡すと、指定されたディレクトリを検索して、該当しそうなコンポーネント・バリデーション定義・エラー定義を見つけに行きます。私がやっていた「手探りで探す」工程は、ここに移りました。書いていない範囲も汎用の手順で探しに行くので、最初から詳しく書けている必要はありません。

そして、いちばん大きかったのはここです。1 本目で「探しにくかった」と分かったら、それを設定に書き足す。次からは、そこを見に行く。

以前は、手探りの結果が私の頭の中にしか残らず、次のマニュアルでまたゼロから探していました。同じプロダクトの 2 本目でも、探し方を思い出すところから始めていたのです。いまは、探した結果が設定として積み上がります。

「どこに何が書いてあるか分からない」は、一度で解消するものではなく、育てて解消するものでした。設定ファイルは、その育ちを置いておく場所です。

なお、まったく手がかりがない場合は、下調べを先に機械にやらせる手もあります。技術スタックや構造を分析する dev-context と、画面仕様の文書を生成する dev-screen-spec です。この 2 つは公開版の tsumiki に入っているので、今日から試せます。

第 3 層 品質判定

テンプレートと校正ルールを渡しても、まだ揺れが残ります。用語の揺れ、語尾、ボタンの書き方、禁止表現、見出しの形。読めば分かるものですが、読む人によって判定が変わります。そして何より、レビューのたびに「これは指摘すべきか」を考えるのが、重い作業でした。

そこでこの層は生成から切り離し、機械に検査させることにしました。判定は 1 件ごとに「通る／通らない」で出ます。主観が入らないので、担当者が変わっても指摘が揺れません。

中身は textlint と markdownlint に用語辞書を組み合わせたもので、さらにプロダクト固有の構造ルールを足しています。用語辞書のもとは、第 2 層で育てた用語集です。ただ、用語集をそのまま検査に使うことはできませんでした。用語集には、読者に見せる説明や読みと、検査に使う「この書き方は誤り、正しくはこちら」の対応が同じファイルに並んでいます。検査に要るのは後者だけで、全部かけるとそのプロダクトでは使わない語まで拾ってしまいます。そこで、用語集を正本と決めて、検査側にはそこから選んだものを置きました。

通すと、次のような形で出ます。これは、形式を説明するために書き起こした例です。

manual-samples/book-search.md
  12:8   表記ゆれ: 「検索ボタン」→「[検索] ボタン」
  34:1   語尾が規約と不一致
  58:22  禁止表現: 「〜することができます」

検出したものは、判定を止めるものと、警告として出すだけのものに分かれます。どちらに置くかは、ルールごとに決めてあります。警告を直すかは書き手が決めますが、何が検出されるかはいつも同じです。揺らしたくないのは、検出のほうだからです。

第 2 層でも語尾や記号のルールを書きましたが、あちらは書く側に渡す指示です。第 3 層は、揃っているかを確かめるためのものです。役割の違いがはっきり出た場面もありました。生成 AI 側の文章チェックが「指摘なし」と返した原稿から、機械の検査が違反を拾ったのです。片方だけでは足りませんでした。

そこで、こう割り切りました。

書く側は、頼み方をどれだけ工夫しても完全には揃わない。だから、揃っているかを確かめる側は機械にする。

機械の検査は、同じものを何回かけても同じ判定が出ます。「ちゃんと揃えてくださいね」とお願いして祈るのではなく、揃っていなければ止まる。この形にしてから、生成のたびに出力を読み比べる作業がなくなりました。

人が見るところ（3 層の外）

自動化した範囲と同じくらい、していない範囲をはっきりさせることが大事でした。人に残したのは 3 つです。

実装との突合について補足します。生成された記述の結論が正しくても、参照したコードが間違っていることがあります。たとえば、使われていない古い処理が残っていて、そちらを読んで判断してしまうケースです。第 1 層の手順 1 で減らす手は打っていますが、それでも残ります。そして、この種の誤りは、出てきた文章だけを読んでも気づけません。

突合を人がやるなら、前と変わらないのでは

ここも当然の疑問だと思います。結論から言うと、やること自体は残りましたが、やる範囲が変わりました。

この表の 3 行は、どれも仕組み側に持たせたものです。

根拠を残す。 生成時のコード分析の結果を、マニュアル本文と 1 対 1 で対応する形で残しました。レビューでは本文と根拠を並べて見るので、「この記述はどこから来たのか」を自分で探し直す必要がありません。

断定できないものは断定させない。 第 1 層で決めた「推測で埋めない」が効くのは、ここです。たとえば、日付検索の境界がタイムゾーンの扱いに依存する場合など、コードを読んでも確定できないことがあります。こうした箇所は本文で言い切らせず、「実機で確認したほうがよい箇所」として印を出します。印が付くのは根拠の記録の側で、マニュアル本文には入りません。全部を疑うのと、印のついた数箇所を見るのとでは、負担がまったく違います。

前回からの差分だけを見る。 生成したマニュアルには、参照したコミットを記録してあります。次の更新で見るのは、そのコミットからの差分だけです。実装が変わっていなければ「変更なし」で終わります。

つまり、人がやる工程を減らしたのではなく、人が見るべき範囲を機械に絞り込ませました。ここを自動化しきる方向には進めていません。マニュアルの正しさは、最後は実装との一致で決まります。そこを見ない仕組みにはしたくないからです。

いまの到達点

まだ道半ばです。現時点を正直に書いておきます。

できるようになったこと

• 「どのあたりのコードを見に行けばいいのか」を、毎回ゼロから手探りしなくてよくなった
• 初稿の生成を、呼び出し 1 行で始められる（そこから仕上がりまでが一続きではなく、途中で判断を挟む場面があります）
• 品質判定が「通る／通らない」で決まり、担当者が変わっても指摘が揺れない
• 書き方の判断がファイルとして読める形になり、他の人に引き継げるようになった
• 新しいプロダクトの立ち上げが、白紙からではなく「既定で動かして、対話で埋めて、必要なら上書きする」になった

まだ手が届いていないこと

• 実装との突合、画面文言の確認、読者視点の確認は、人が見る
• 差し替え用のテンプレートは初期化の対象外で、いまも白紙のファイルを作ることになる。やりたいのは「既定を少しだけ直す」なのに、その土台が手元に出てきません
• 第 1 層の適用範囲は狭いまま。複数のプロダクトで共有できる形にはしてありますが、同時に動かした実績はまだありません

そして、いちばん解けていないのが「漏れ」

「この選択肢が載っていない」「このエラーに触れていない」。こういう抜けは、この仕組みのどこでも見つけられません。

第 1 層が拾い漏らせば、その選択肢やエラーが存在すること自体が下流に伝わりません。第 3 層は書かれた文章を検査するので、書かれていないものは対象外です。つまり、記事の冒頭で「見落としも起きます」と書いた問題は、そのまま残っています。

揃えることと、漏らさないことは別の課題でした。 揃える側は、決めてファイルに書けば機械に渡せます。漏らさない側は、そもそも何を探すべきかを知らないと始まりません。ここは、いまも人が実装と画面を見て確かめています。

なお、外せたのは「どのコードを読めばいいかを自分で探す」ことです。生成への指示は自然言語で書けるので、プログラミングの知識も要りません。一方で Git とコマンドラインが残ったのは、マニュアルをプロダクトのリポジトリに置き、コードと同じ場所で変更履歴を追えるようにしたからです。これはマニュアルをどこに置くかの話なので、生成の仕組み側で解決するものではないと考えています。

まとめ

いちばん効いたと感じたのは、決めていなかったことを決めたことでした。書きっぷりが揺れた原因は AI ではなく、セクションの中をどう書くかを私が決めていなかったことです。それを 1 つずつファイルに書き出し、すでにコード分析の機能を持つ tsumiki に載せました。載せるときに コードの読み方（汎用）・どこを読むか（固有）・品質判定（機械） の 3 層に分けて、人の確認はその外に置きました。

決めるときの手がかりは、意外と自分の中にありました。「この工程は苦手だ」「ここは経験があるから迷わない」という感覚が、そのまま「どこを機械に渡すか」の目印だったのです。

そして、解けなかったものもはっきりしました。漏れは仕組みの外に残ったままです。次に手を入れるのはそこだと思っています。

仕組みがなくても始められることが 2 つあります。ひとつは、自分が書くときに無意識で決めている書き方を、書き出してみることです。もうひとつは、公開版の tsumiki に入っている dev-context と dev-screen-spec で、担当プロダクトの構造と画面仕様を機械に下調べさせてみることです。どちらもコードを書く必要はありません。

ではまた。