k2works/operating-script

運用スクリプト作成

環境構築やデプロイ、プロビジョニングなどの運用タスクを自動化する Gulp スクリプトを作成する。スクリプトはプロジェクトの運用効率を左右するため、ネーミング・構造・実装スタイルの一貫性が重要になる。

Instructions

1. 参照ガイド

@docs/reference/運用スクリプト作成ガイド.md に定義されたルールに従う。このガイドがネーミング規則・ディレクトリ構成・コーディング規約の正とする。

2. ファイル命名規則

{カテゴリ}_{環境}.js の形式で命名する。

| カテゴリ | 説明 | 例 | |---------|------|-----| | develop | アプリケーション開発タスク | develop.js | | deploy | デプロイスクリプト | deploy_dev.js, deploy_stg.js | | provision | IaC プロビジョニング | provision_stg.js | | ssh | SSH・踏み台操作 | ssh_stg.js |

環境サフィックス: _dev（開発）、_stg（ステージング）、_prd（本番）、_local（ローカル）、なし（環境非依存）

3. Gulp タスク命名規則

{カテゴリ}:{環境}:{アクション} の形式で命名する。

deploy:dev:build          # 開発環境: ビルド
provision:stg:vpc         # ステージング: VPC プロビジョニング
dev:db:start              # アプリ開発: DB 起動
tdd:backend               # TDD モード: バックエンド

4. スクリプトの基本構造

すべてのスクリプトは以下のセクション構成に従う。

'use strict';

import path from 'path';
import { execSync } from 'child_process';
import { cleanDockerEnv } from './shared.js';

// ============================================
// 設定
// ============================================

const PREFIX = 'DEV'; // 環境変数プレフィックス

/** サービス定義 */
const SERVICES = [
  { name: 'backend', port: 8080, label: 'バックエンド' },
];

// ============================================
// ヘルパー関数
// ============================================

/**
 * JSDoc コメントで関数の目的・引数・戻り値を記述
 * @param {string} param - パラメータの説明
 * @returns {string}
 */
function helperFunction(param) {
  // 実装
}

// ============================================
// Gulp タスク
// ============================================

export default function(gulp) {
  gulp.task('category:action', (done) => {
    // タスク実装
    done();
  });

  // ヘルプタスク（必須）
  gulp.task('category:help', (done) => {
    console.log(`...`);
    done();
  });
}

5. 実装ルール

• ESM: import / export を使用。require は使わない
• strict mode: ファイル先頭に 'use strict';
• JSDoc: すべての関数に JSDoc コメント
• DOCKER_HOST 対応: Docker 操作は cleanDockerEnv() を使用
• ヘルプタスク: 各カテゴリに {category}:help タスクを必ず作成
• 共通関数: shared.js と ssh.js の既存関数を活用

6. 環境変数

.env で管理し、環境プレフィックス（DEV_, STG_, PRD_）で名前空間を分離する。新しい環境変数を追加した場合は .env.example も更新する。

7. 作成手順

1. カテゴリと環境からファイル名を決定
2. 基本構造テンプレートに従って実装
3. shared.js / ssh.js の既存関数を活用
4. ヘルプタスクを作成
5. gulpfile.js にインポートとタスク登録を追加
6. npx gulp {category}:help で動作確認
7. .env.example に必要な環境変数を追記

8. gulpfile.js への登録

import newTasks from './ops/scripts/{new_file}.js';
newTasks(gulp);

9. 対応する環境とスクリプト

| 環境 | スクリプト | 関連スキル | |------|----------|----------| | アプリケーション開発 | develop.js | operating-setup | | 開発環境サーバー | deploy_dev.js | operating-deploy | | ステージング AWS | deploy_stg.js, provision_stg.js, ssh_stg.js | operating-deploy, operating-provision | | 本番 AWS | deploy_prd.js, provision_prd.js, ssh_prd.js | operating-deploy, operating-provision |

10. 注意事項

• 運用スクリプト作成ガイド（@docs/reference/運用スクリプト作成ガイド.md）を正として従う
• Docker 操作では cleanDockerEnv() を必ず使う（DOCKER_HOST 環境変数による接続エラーを防ぐため）
• 既存スクリプト（shared.js, ssh.js, develop.js 等）のパターンを踏襲する
• 新しいスクリプト作成時は .env.example とドキュメントも同時に更新する

関連スキル

• operating-setup — 環境構築（スクリプト作成のトリガー）
• operating-deploy — デプロイ・ロールバック
• operating-provision — IaC プロビジョニング
• operating-cicd — CI/CD パイプライン構築
• orchestrating-operation — 運用フェーズ全体のワークフロー