[マニュアル] 1. 設定手順書の生成 (引数:作成したい設定手順書)

[マニュアル] 1. 設定手順書の生成 (引数:作成したい設定手順書)

入力: $ARGUMENTS（トピック/対象サービス名 または 主要ディレクトリ）

例: "Vercelデプロイ手順" backend/​auth infra/​terraform

---

🎯 目的

• プロジェクトの設定/デプロイ手順を doc/​manual/ に体系化し、再現性とオンボーディング速度を向上
• SSOT（doc/​input/​rdd.md, doc/​Architecture.md, doc/​input/​design/​*）と整合し、ブラックボックス化を回避
• コマンドはコピペで実行可能・ロールバック可能・検証可能にする

---

参照ルール（SSOT）

• 必須参照: doc/​input/​rdd.md, doc/​Architecture.md
• デザイン参照: doc/​input/​design/​design_context.json, doc/​input/​design/​html/
  • 存在しない/空なら デザイン参照はスキップ（UI前提の手順は出力しない）

---

更新ポリシー（既存手順書がある場合）

手順書は「育つ」前提で、全消し上書きはしない。差分更新して、人間の追記を守る。

1) 既存ファイルの有無で分岐

• 出力先（doc/​manual/​{slug}.md）が存在しない → 新規作成
• 存在する → 既存内容をSSOTとして扱い、以下のルールで最小差分更新

2) 更新ルール（ハイブリッド）

• 見出し構造（章立て）をできるだけ維持する
• もし手順書内にステップID（例: [S-01]）がある場合:
  • 変更が必要な箇所は 該当ステップIDの中だけを更新する
• ステップIDが無い/対応するIDが見つからない場合:
  • 関連する章（例: 「前提条件」「詳細手順」「トラブルシューティング」）を対象に追記・修正する
• 既存のプロジェクト固有メモ（運用メモ/注意書き/既知の罠）がある場合は削除しない

3) 変更履歴（必須）

• ## 変更履歴 が無い場合は手順書の先頭付近に追加する
• 更新時は必ず1行追記する
  • 例: - 2026-01-01: [S-03] 環境変数の章を更新（理由: 仕様変更に追従）

---

生成方針

1. 対象の特定: $ARGUMENTS から手順のスコープを定義（例: 環境構築/​CI/​CD/デプロイ/認証設定）
2. 前提の抽出: OS/​CPU/権限/必要ツール/バージョン/​Secretsの所在（.env など）
3. 手順の分解: ステップは最小粒度で [S-01] 形式の連番を付与
4. 検証の明記: 各ステップに「確認コマンド/期待結果」を付ける
5. ロールバック: 主要操作に「巻き戻し手順」を付ける
6. トラブルシューティング: 代表的なエラーと対処（[TS-01] 等のID付け）
7. 再実行性: すべてのコマンドはコピー&ペーストで動くこと
8. セキュリティ: 秘密情報は直接書かず プレースホルダ にする（例: <GITHUB_TOKEN>）

---

出力先

doc/​manual/​{slug}.md
例: doc/​manual/​vercel-deploy.md

---

手順書テンプレ（自動整形）

# {タイトル}
最終更新: {YYYY-MM-DD} / 対象: {環境やサービス名} / 想定読者: {role}

## 1. 概要
- 目的: …
- 成果物: …
- 失敗時の影響: …

## 2. 前提条件
- OS/シェル: …
- 必要ツール: node@XX / pnpm@YY / docker@ZZ …
- 権限: …
- 参照: doc/​input/​rdd.md §…, doc/​Architecture.md §…

## 3. 詳細手順
### [S-01] {手順名}
- 目的: …
- 実行コマンド:
    （複数ある場合は順に記載。**そのままコピペ可能**）
    例:
        pnpm install
        pnpm run build
- 検証:
    実行:
        pnpm test
    期待結果:
        すべてのテストが PASS
- ロールバック:
    例:
        git restore -SW :/
- 注意:
    例: ARM/​Mac の場合は X を実行

### [S-02] …

## 4. 確認方法（総合）
- ヘルスチェックURL: …
- 期待レスポンス例:
    {json例をここに}
- 監視/ログ確認: …

## 5. トラブルシューティング
- [TS-01] エラー: EADDRINUSE → 対処: ポート変更 …
- [TS-02] Docker build が失敗 → キャッシュクリア …

## 6. 完了後の効果
- デプロイ時間が X% 短縮 / 再現性が担保 etc.

## 7. 付録（環境差分/変数一覧）
- 環境変数: KEY/説明/例（**値は書かない**、例のみ）
- OS差分: macOS / Linux の差異

---

品質チェックリスト

• SSOT（rdd/​architecture）と整合
• デザインが無い/空の場合、UI依存手順を出していない
• 各ステップに「目的/コマンド/検証/ロールバック」がある
• コマンドはコピペで実行可能（変数は明示）
• 代表エラーに TS-ID が付与されている
• Secrets は直接記載していない
• 依存ツールとバージョンが明記されている

---

自己評価

成功自信度 (1-10) ＋ 一言理由