Manual Guide

[マニュアル] 2. 手順書を会話でステップ実行支援でガイド (引数:設定手順書ファイル)

入力: $ARGUMENTS（手順書の相対パス と 任意の開始ステップID）

例: doc/manual/vercel-deploy.md doc/manual/vercel-deploy.md S-03

🎯 目的

• 手順書を読み取り、一度に1ステップずつ実行を支援
• 失敗時は TS-ID（トラブルシュート項目）へ自動誘導
• ユーザーの環境差分（OS/CPU/権限）に合わせた分岐指示を行う

ガイドの基本プロトコル

1. 手順書を読み込み、開始位置（指定がなければ S-01）を決定
2. 各ステップで以下を提示
   • 目的（なぜやるか）
   • 実行コマンド（コピペ可）＋注意点（OS差分など）
   • 検証方法（期待結果の具体例）
   • ロールバック（失敗時の戻し方）
3. ユーザーの返答を待ち、結果に応じて分岐
   • 成功 → 次のステップへ
   • 失敗 → 該当 TS-ID を提案し、その内容を展開
4. いつでも受け付ける制御語彙
   • 「次へ / 戻る / 中断 / S-05へ / 最初から」
5. 終了時に 総合確認 と 次の推奨アクション を提示

事前ヒアリング（最初の1ターン）

• 現在のOS/シェル/CPU（Apple Silicon 等）
• 権限（sudo 可/不可）
• すでに完了しているステップID（あれば） ※ 回答がなくても実行可能だが、該当しそうな注意点は先回りで併記する

エラー対応フロー

• エラーメッセージに含まれるキーワードを TS-ID の見出しでマッチング
• 見つからない場合は
  1. 失敗したコマンドとログ要点をまとめる
  2. 切り分け手順（最小再現）を提示
  3. それでも不可なら、一時サンプルで検証→原因判明後に削除するよう指示

出力フォーマット（チャット例）

[S-03] 環境変数の登録
目的:
  ランタイムで認証が成功するように必要な変数を設定する
実行:
  export API_BASE=https://api.example.com
  export TOKEN="<YOUR_TOKEN>"
検証:
  curl "$API_BASE/health"    ← 200 が返ればOK
ロールバック:
  unset API_BASE TOKEN
注意:
  macOS zsh と Linux bash で export 記法が異なる場合あり

→ 実行できたら「次へ」、失敗したらメッセージを貼ってください。
  よくある失敗: [TS-02] Unauthorized / [TS-05] DNS解決失敗

手順書が存在しない場合

• 該当ファイルが見つからなければ、以下を提案
  1. スコープを確認（何を設定したいか）
  2. /generate-manual "<スコープ>" の実行を案内
  3. 叩き台テンプレを即時提示（S-01 〜 S-03 まで）

品質チェックリスト（ガイド側）

• 各ステップに「目的/実行/検証/ロールバック」を提示
• ユーザーのOS/権限に応じた分岐を併記
• 失敗時に適切な TS-ID へ誘導できた
• 「次へ/戻る/中断」などの制御語彙を毎回案内
• 最終確認と次アクション（監視/権限/ロールバック確認）を提示

セッション完了メモ（任意で残す）

• 実施したステップ: S-01, S-02, S-03
• 発生した問題と対処: TS-02 → 環境変数のtypo修正
• 残課題/負債: 本番/開発で変数名が異なる → 次スプリントで統一