現場向け操作マニュアル作成

feature 開発の一部として、現場ユーザー向けの操作マニュアルを Markdown で作成し、 最終的に PDF 化する。現場向けマニュアルなので、開発用語・物理名・Issue 番号等は 原則含めない。

起動条件

• ユーザーから「マニュアル作って」「マニュアル化して」等の指示
• feature PR を出した後、または出す直前
• 対応 Issue 番号が確定している (PR 本文と紐付くため)

進め方

Step 1. 範囲確認 (必ず最初に行う)

このマニュアルで扱う範囲・扱わない範囲をユーザーに確認する。明示的指示がない場合は PR の Closes #XXXX の Issue を読んで、現場が触る画面・操作を抽出する。

Step 2. 既存マニュアルのスタイル確認

docs/business/manuals/ 配下の既存 .md を 1〜2 件読んで、以下を踏襲する:

• 章立ての粒度
• 表で項目整理する書式
• スクショ参照パスの慣例 (例: ../../images/issue-XXXX/name.png?raw=true)
• 注意ボックスの書式 (> **基本コンセプト**)
• メニュー導線の書き方
• 「よくある質問」の有無

既存スタイルがない場合は templates/operation-manual.md をベースに作成。

Step 3. 骨格作成

templates/operation-manual.md をベースに以下の項目を埋める:

1. タイトル + 1〜2 行の用途説明
2. このマニュアルが扱う範囲 / 扱わない範囲 (青コールアウト)
3. 基本コンセプト (任意、ただし業務概念で説明)
4. いつ使う機能か (シナリオベース)
5. メニュー導線 (PC とスマホで節を分ける、権限・操作場所表)
6. 第 1 章, 第 2 章, ... (操作手順、各章にスクショ 1 枚以上)
7. 印刷物がある場合: ラベル/帳票の印字項目を「上段/中段/下段」で表記
8. 在庫の流れ等のセクション (任意、業務全体把握用)
9. よくある質問 (現場が抱きそうな疑問を 5〜7 件)

Step 4. 用語チェック (重要)

骨格を書き終えたら、TERMINOLOGY.md の「チェック方法 (grep)」セクションに ある 4 種類すべて を実行する:

1. 固定 NG ワード grep (DB スキーマ / コード由来 / Issue 参照)
2. 「業務語（英名）」の括弧併記 grep — [ぁ-んァ-ヶ一-龯]+（[A-Z][A-Za-z]+）
3. プロジェクトの UI コンポーネント / Model クラス名動的抽出 grep — フレームワークごとのコンポーネント基底クラスを継承するクラスを抽出 （Laravel + Livewire なら app/Contexts / app/Models から extends Component / extends Model を抽出する例が TERMINOLOGY.md に あるので、自プロジェクトに合わせて書き換える）
4. ファイル名・パスの混入 grep — .blade.php / .tsx / .vue 等の 拡張子や app/Contexts/ のようなコード配置パス

すべてヒット 0 件であること。ヒットがあれば論理名に書き換える。

重要: 1 だけでは不十分。実運用で「業務語に擬態した短い英名」 （例: Fill、Pick のような単語）が固定 NG リストに無く、括弧併記の形で マニュアルに混入する事故が起きた。4 種類すべて実行する こと。

詳細・コマンドは TERMINOLOGY.md 参照。

Step 5. スクショ撮影

SCREENSHOT_GUIDE.md の手順に従う:

1. テストデータ準備 (本物の DB データを優先、無ければ最小限を一時作成)
2. ブラウザログインのため Playwright 起動 → 認証
3. 画面ごとに撮影 (PC: 1400x900, スマホ: 428x926)
4. 印刷物がある場合は実際の印刷画面を撮影
5. 一時データは必ず削除
6. ファイル名は docs/images/issue-XXXX/<purpose>.png で保存

Step 6. レビュー

REVIEW_CHECKLIST.md のチェックリストを上から順に確認する。 ユーザーに「マニュアルレビューして」と聞かれた場合も同じチェックリストで進める。

Step 6.5. 実装との整合スポットチェック (必須)

マニュアルの 「具体的な記述」を実装で裏取りする。grep では捕捉できない 事実誤認 (動線間違い・ボタンラベル違い等) を防ぐ。Plan / Explore エージェント 等の subagent に実装ファイルを読ませて突合せをすると効率的。

subagent には read-only での突合せを指示すること。git checkout / git switch / gh pr checkout 等で作業ツリーや HEAD を変更させない (subagent は isolation 指定が無いと親と作業ツリーを共有する。dotfiles を symlink で配布している環境では、共有ツリーでのブランチ切替が稼働中の設定を 壊しうる)。ブランチ切替を伴う検証が必要なら isolation: "worktree" で spawn して親ツリーから隔離する。

確認観点（フレームワーク依存の部分は自プロジェクトに読み替え）:

• メニュー導線: 大カテゴリ名・サブメニュー名がナビゲーション実装 （Laravel なら navigation.blade.php、React なら Navigation.tsx 等）の ルート定義と i18n キーに一致するか
• ボタン / リンク名: テンプレートに書かれたボタンラベル / i18n キー / wire:click / onClick 属性と完全一致するか
• 画面遷移の動線: 「○○ボタンを押すと△△画面が開く」が実装の ディスパッチ / ルーティングと一致するか。特に類似ボタン (例: 「出荷」「在庫予約」など) が 別モーダル / 別画面を開く ケースは 混同しやすいので必ず実装を見て確認する
• チェックボックス / トグルの ON/OFF 挙動: 双方向バインディング （wire:model / v-model / React state 等）で連動する UI 要素 （条件付き表示など）が記述と一致するか
• バリデーション制限: 文字数・数値範囲・必須/任意の判定が フォームバリデーション実装と一致するか
• 保存ロジック: 「○○のとき NULL 保存」「○○のとき正規化される」等の 記述がコンポーネント / コントローラー側の正規化メソッドと一致するか
• 印字物の項目: ラベル / 帳票の各項目がテンプレートの条件分岐と 一致するか (特に条件付き印字)
• 状態判定: 「○○のとき表示される」「○○のとき抑制される」等の 条件がテンプレートの条件式と一致するか

ヒットしたら、実装と一致するようマニュアルを直す (または挙動が想定外なら 実装側を直す)。

Step 7. PDF 化

/pdf スキルを呼び出す:

cd docs/business/manuals && PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome \
  npx --yes md-to-pdf <file>.md \
  --basedir <repo-root> \
  --stylesheet ~/.claude/skills/pdf/assets/manual-style.css \
  --pdf-options '{"format":"A4","printBackground":true,"preferCSSPageSize":true}' \
  --launch-options '{"executablePath":"/usr/bin/google-chrome","args":["--no-sandbox","--disable-dev-shm-usage"]}'

PUPPETEER_EXECUTABLE_PATH を指定しないと WSL2 環境で Chrome 起動タイムアウトになる ことがあるので、明示する。

PDF は .gitignore に docs/**/*.pdf がある場合がほとんどなので、コミットせず ローカル生成物として扱う (運用に応じてユーザーに確認)。

Step 8. コミット

Markdown + スクショを docs/business/manuals/ と docs/images/issue-XXXX/ に配置。 PR ブランチにコミット & push。

出力先

関連スキル

• /pdf — PDF 化を担当 (本スキルから呼び出す)
• /create-pr — マニュアルを含む PR 作成
• /create-issue — Issue 作成 (本スキルの前段)

重要な原則

1. 現場が読む ことが目的。開発者向けではない
2. メニュー導線は実装と必ず一致させる (ナビゲーション実装ファイルを必ず確認)
3. 物理名禁止 (テーブル名・カラム名・フラグ値・ID・パス)
4. Issue/ADR/PR 番号禁止 (本 PR では, (要件N), Closes #XXXX は現場には不要)
5. ログ確認手順は「システム担当に依頼」 に統一 (現場が grep する想定はしない)
6. スクショは現物 / または現物に近いシナリオ で撮る (DEMO データ作成時は後始末必須)