@k2works/claude-code-booster 1.12.0 → 2.0.0

package/lib/assets/docs/reference//351/201/213/347/224/250/343/202/271/343/202/257/343/203/252/343/203/227/343/203/210/344/275/234/346/210/220/343/202/254/343/202/244/343/203/211.md

@@ -0,0 +1,421 @@
+# 運用スクリプト作成ガイド
+
+## 概要
+
+本ガイドは `ops/scripts/` 配下に配置する運用スクリプトのネーミングルール、ディレクトリ構成、実装スタイルを定義します。Gulp タスクランナーと連携し、環境構築・デプロイ・プロビジョニング・運用タスクを自動化します。
+
+## ディレクトリ構成
+
+```text
+ops/
+├── scripts/
+│   ├── shared.js              # 共通ユーティリティ
+│   ├── ssh.js                 # SSH/SCP ヘルパー
+│   ├── deploy_dev.js          # 開発環境デプロイ
+│   ├── deploy_stg.js          # ステージング環境デプロイ
+│   ├── deploy_prd.js          # 本番環境デプロイ
+│   ├── provision_stg.js       # ステージング環境プロビジョニング
+│   ├── provision_prd.js       # 本番環境プロビジョニング
+│   ├── develop.js             # アプリケーション開発タスク
+│   ├── release.js             # リリースワークフロー
+│   ├── journal.js             # 開発ジャーナル生成
+│   ├── mkdocs.js              # ドキュメントビルド
+│   ├── vault.js               # シークレット管理
+│   ├── ssh_stg.js             # ステージング SSH・踏み台
+│   ├── ssh_prd.js             # 本番 SSH・踏み台
+│   ├── sonar_local.js         # SonarQube ローカル環境
+│   └── sonar_aws.js           # SonarQube AWS 環境
+├── terraform/                  # IaC（Terraform）
+├── docker/                     # Docker 関連設定
+└── nix/                        # Nix 開発環境（任意）
+```
+
+## ネーミングルール
+
+### ファイル名
+
+`{カテゴリ}_{環境}.js` の形式で命名する。
+
+| カテゴリ | 説明 | 例 |
+|---------|------|-----|
+| `deploy` | デプロイスクリプト | `deploy_dev.js`, `deploy_stg.js`, `deploy_prd.js` |
+| `provision` | IaC プロビジョニング | `provision_stg.js`, `provision_prd.js` |
+| `ssh` | SSH・踏み台操作 | `ssh.js`（共通）, `ssh_stg.js`, `ssh_prd.js` |
+| `develop` | アプリケーション開発タスク | `develop.js` |
+| `release` | リリースワークフロー | `release.js` |
+| `journal` | 開発ジャーナル | `journal.js` |
+| `mkdocs` | ドキュメント | `mkdocs.js` |
+| `sonar` | コード品質分析 | `sonar_local.js`, `sonar_aws.js` |
+| `shared` | 共通ユーティリティ | `shared.js` |
+| `vault` | シークレット管理 | `vault.js` |
+
+**環境サフィックス**:
+
+| サフィックス | 環境 | 例 |
+|-------------|------|-----|
+| `_dev` | 開発環境 | `deploy_dev.js` |
+| `_stg` | ステージング環境 | `deploy_stg.js`, `provision_stg.js` |
+| `_prd` | 本番環境 | `deploy_prd.js`, `provision_prd.js` |
+| `_local` | ローカル環境 | `sonar_local.js` |
+| `_aws` | AWS 環境 | `sonar_aws.js` |
+| なし | 環境非依存 / 共通 | `shared.js`, `ssh.js`, `release.js` |
+
+### Gulp タスク名
+
+`{カテゴリ}:{環境}:{アクション}` の形式で命名する。
+
+```
+deploy:dev:build          # 開発環境: ビルド
+deploy:dev:push           # 開発環境: Registry プッシュ
+deploy:dev                # 開発環境: デプロイ実行
+deploy:dev:status         # 開発環境: ステータス確認
+deploy:dev:logs           # 開発環境: ログ取得
+deploy:dev:clean          # 開発環境: クリーンアップ
+deploy:dev:setup          # 開発環境: 初回セットアップ
+deploy:dev:help           # 開発環境: ヘルプ
+
+provision:stg:plan        # ステージング: Terraform plan
+provision:stg:vpc         # ステージング: VPC プロビジョニング
+provision:stg:rds         # ステージング: RDS プロビジョニング
+provision:stg:ecs         # ステージング: ECS プロビジョニング
+provision:stg             # ステージング: 全リソース一括
+provision:stg:destroy     # ステージング: 全リソース廃棄
+provision:stg:help        # ステージング: ヘルプ
+
+ssh:stg:login             # ステージング: 踏み台ログイン
+ssh:stg:tunnel            # ステージング: SSH トンネル
+ssh:stg:backup            # ステージング: DB バックアップ
+ssh:stg:restore           # ステージング: DB リストア
+
+dev:sms                   # SMS 開発サーバー起動
+dev:sms:product           # SMS product プロファイル起動
+tdd:sms                   # SMS TDD モード
+```
+
+## 実装スタイル
+
+### 基本構造
+
+すべてのスクリプトは以下の構造に従う。
+
+```javascript
+'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, container: 'app-backend', label: 'Backend' },
+  { name: 'frontend', port: 3000, container: 'app-frontend', label: 'Frontend' },
+];
+
+// ============================================
+// ヘルパー関数
+// ============================================
+
+/**
+ * JSDoc コメントで関数の目的・引数・戻り値を記述
+ * @param {string} param - パラメータの説明
+ * @returns {string}
+ */
+function helperFunction(param) {
+  // 実装
+}
+
+// ============================================
+// Gulp タスク
+// ============================================
+
+export default function(gulp) {
+  // タスク登録
+  gulp.task('deploy:dev:build', (done) => {
+    // タスク実装
+    done();
+  });
+}
+```
+
+### コーディング規約
+
+#### 1. strict mode
+
+すべてのファイルの先頭に `'use strict';` を記述する。
+
+#### 2. ESM（ES Modules）
+
+`import` / `export` 構文を使用する。`require` は使用しない。
+
+```javascript
+// Good
+import path from 'path';
+import { execSync } from 'child_process';
+import { cleanDockerEnv } from './shared.js';
+
+// Bad
+const path = require('path');
+```
+
+#### 3. セクション区切り
+
+コード内のセクションは以下のコメントで区切る。
+
+```javascript
+// ============================================
+// 設定
+// ============================================
+
+// ============================================
+// ヘルパー関数
+// ============================================
+
+// ============================================
+// Gulp タスク
+// ============================================
+```
+
+#### 4. JSDoc コメント
+
+すべての関数に JSDoc コメントを記述する。
+
+```javascript
+/**
+ * docker build に渡すオプションを組み立てる
+ * @returns {string} ビルドオプション文字列
+ */
+function dockerBuildOptions() {
+  // ...
+}
+```
+
+#### 5. 環境変数の管理
+
+環境変数は `.env` ファイルで管理し、環境プレフィックス（`DEV_`, `STG_`, `PRD_`）で名前空間を分離する。
+
+```javascript
+// 環境変数プレフィックスで名前空間を分離
+const PREFIX = 'STG';
+const awsProfile = () => process.env.STG_AWS_PROFILE || '';
+const sshHost = () => process.env[`${PREFIX}_SSH_HOST`];
+```
+
+**環境変数の命名規則**:
+
+| プレフィックス | 環境 | 例 |
+|-------------|------|-----|
+| `DEV_` | 開発環境 | `DEV_SSH_HOST`, `DEV_SSH_USER` |
+| `STG_` | ステージング環境 | `STG_AWS_PROFILE`, `STG_DB_USERNAME` |
+| `PRD_` | 本番環境 | `PRD_AWS_PROFILE`, `PRD_DB_USERNAME` |
+| `GHCR_` | GitHub Container Registry | `GHCR_USER`, `GHCR_TOKEN` |
+| `DOCKER_` | Docker 関連 | `DOCKER_BUILD_NETWORK`, `DOCKER_BUILD_DNS` |
+
+#### 6. サービス定義
+
+複数サービスを扱うスクリプトでは、サービスを配列で定義する。
+
+```javascript
+const SERVICES = [
+  { name: 'sms', port: 8080, container: 'app-sms', label: 'SMS（販売管理）' },
+  { name: 'fas', port: 8081, container: 'app-fas', label: 'FAS（財務会計）' },
+];
+```
+
+サービス定義を基に、個別タスクと一括タスクを動的に生成する。
+
+```javascript
+// 個別タスク: deploy:dev:build:sms, deploy:dev:build:fas
+SERVICES.forEach((svc) => {
+  gulp.task(`deploy:dev:build:${svc.name}`, (done) => {
+    buildImage(svc);
+    done();
+  });
+});
+
+// 一括タスク: deploy:dev:build（全サービス）
+gulp.task('deploy:dev:build', gulp.series(
+  ...SERVICES.map((svc) => `deploy:dev:build:${svc.name}`)
+));
+```
+
+#### 7. エラーハンドリング
+
+`execSync` のエラーは適切にキャッチし、ユーザーにわかりやすいメッセージを表示する。
+
+```javascript
+try {
+  execSync(command, { stdio: 'inherit', env: cleanDockerEnv() });
+} catch (err) {
+  console.error(`エラー: ${err.message}`);
+  process.exit(1);
+}
+```
+
+#### 8. ヘルプタスク
+
+各カテゴリにヘルプタスクを提供する。
+
+```javascript
+gulp.task('deploy:dev:help', (done) => {
+  console.log(`
+=== 開発環境デプロイコマンド ===
+
+  deploy:dev:build          全サービスをローカルビルド
+  deploy:dev:push           全イメージを Registry にプッシュ
+  deploy:dev                全サービスをデプロイ
+  deploy:dev:status         コンテナ状態を確認
+  deploy:dev:logs           コンテナログを表示
+  deploy:dev:clean          開発環境を完全削除
+  deploy:dev:setup          初回セットアップ
+  deploy:dev:help           このヘルプを表示
+  `);
+  done();
+});
+```
+
+## 共通ユーティリティ（shared.js）
+
+環境をまたいで共通的に使用するユーティリティ関数を `shared.js` に集約する。
+
+```javascript
+'use strict';
+
+/**
+ * DOCKER_HOST を除外した環境変数を返す
+ * Docker Desktop 使用時に DOCKER_HOST が設定されていると接続エラーが発生するため除外する
+ * @returns {Object} DOCKER_HOST を除外した環境変数
+ */
+export function cleanDockerEnv() {
+  const env = { ...process.env };
+  delete env.DOCKER_HOST;
+  return env;
+}
+```
+
+## SSH ヘルパー（ssh.js）
+
+SSH/SCP 操作を共通化する。環境プレフィックスで接続先を切り替える。
+
+```javascript
+/**
+ * SSH 接続パラメータを取得
+ * @param {string} [prefix='DEV'] 環境変数プレフィックス
+ * @returns {{ host: string, user: string, port: string, keyFile: string | undefined }}
+ */
+export function getSSHConfig(prefix = 'DEV') {
+  const host = process.env[`${prefix}_SSH_HOST`];
+  const user = process.env[`${prefix}_SSH_USER`];
+  const port = process.env[`${prefix}_SSH_PORT`] || '22';
+  const keyFile = process.env[`${prefix}_SSH_KEY`];
+
+  if (!host || !user) {
+    throw new Error(`${prefix}_SSH_HOST と ${prefix}_SSH_USER を .env に設定してください`);
+  }
+
+  return { host, user, port, keyFile };
+}
+
+/**
+ * SSH でリモートコマンドを実行
+ * @param {string} command 実行するコマンド
+ * @param {object} [options] オプション
+ * @param {boolean} [options.ignoreError] エラーを無視するか
+ * @param {boolean} [options.capture] 出力を文字列で返すか
+ * @param {string} [options.prefix] 環境変数プレフィックス
+ * @returns {string} 標準出力
+ */
+export function sshExec(command, options = {}) {
+  // 実装
+}
+
+/**
+ * SCP でローカルファイル/ディレクトリをリモートに転送
+ * @param {string} localPath ローカルパス
+ * @param {string} remotePath リモートパス
+ * @param {object} [options] オプション
+ * @param {boolean} [options.recursive] ディレクトリを再帰的に転送
+ * @param {string} [options.prefix] 環境変数プレフィックス
+ */
+export function scpUpload(localPath, remotePath, options = {}) {
+  // 実装
+}
+```
+
+## AWS 連携パターン
+
+### aws-vault ラッパー
+
+AWS 操作では `aws-vault exec` 経由で認証情報を自動取得する。
+
+```javascript
+/**
+ * aws-vault ラッパーを組み立てる
+ * @returns {string} コマンドプレフィックス
+ */
+function awsExecPrefix() {
+  const profile = process.env.STG_AWS_PROFILE || '';
+  if (!profile) return '';
+  return `aws-vault exec ${profile} -- `;
+}
+```
+
+### Terraform 操作
+
+```javascript
+/**
+ * Terraform コマンドを実行
+ * @param {string} subcommand - Terraform サブコマンド
+ * @param {object} options - オプション
+ */
+function terraform(subcommand, options = {}) {
+  const prefix = awsExecPrefix();
+  const cmd = `${prefix}terraform ${subcommand}`;
+  execSync(cmd, { cwd: options.cwd, stdio: 'inherit' });
+}
+```
+
+## Gulp タスク登録パターン
+
+### gulpfile.js
+
+```javascript
+import gulp from 'gulp';
+import deployDev from './ops/scripts/deploy_dev.js';
+import deployStg from './ops/scripts/deploy_stg.js';
+import provisionStg from './ops/scripts/provision_stg.js';
+
+// 各モジュールのタスクを登録
+deployDev(gulp);
+deployStg(gulp);
+provisionStg(gulp);
+```
+
+### package.json のスクリプト
+
+```json
+{
+  "scripts": {
+    "deploy:dev": "npx gulp deploy:dev",
+    "deploy:stg": "npx gulp deploy:stg",
+    "provision:stg": "npx gulp provision:stg"
+  }
+}
+```
+
+## スクリプト作成の手順
+
+新しい運用スクリプトを作成する際は以下の手順に従う。
+
+1. **ネーミング**: `{カテゴリ}_{環境}.js` でファイル名を決定
+2. **テンプレート**: 基本構造（設定→ヘルパー関数→Gulp タスク）に従って実装
+3. **共通関数**: `shared.js` と `ssh.js` の既存関数を活用
+4. **環境変数**: `.env.example` に必要な環境変数を追記
+5. **ヘルプ**: `{カテゴリ}:{環境}:help` タスクを作成
+6. **gulpfile.js**: タスクを登録
+7. **ドキュメント**: コマンドリファレンスを作成・更新

package/lib/assets/docs/reference//351/226/213/347/231/272/343/202/254/343/202/244/343/203/211.md

@@ -2,7 +2,7 @@
 
 ## 開発ライフサイクル
 
-分析では、アプリケーションの機能や性能、品質、セキュリティ、運用、保守などの要件をまとめる活動を行います。
+分析では、情報システム戦略立案、アプリケーションの機能や性能、品質、セキュリティ、運用、保守などの要件をまとめる活動を行います。
 開発では要件を満たすための設計、実装、テストなどの活動を行います。
 運用では、アプリケーションの運用、保守、改善などの活動を行います。
 構築では、アプリケーションの環境設定を行います。
@@ -39,8 +39,11 @@ state 配置 #lightblue
 
 ```plantuml
 @startuml "Phase 1"
-|要件定義|
+|戦略|
 start
+:ビジネスアーキテクチャ;
+:インセプションデッキ;
+|要件定義|
 :要件定義;
 :ユースケース;
 :ユーザーストーリー;
@@ -65,6 +68,11 @@ stop
 
 @enduml
 ```
+### 戦略
+
+#### ビジネスアーキテクチャ
+
+ビジネスアーキテクチャの詳細は [ビジネスアーキテクチャ分析ガイド](ビジネスアーキテクチャ分析ガイド.md) を参照
 
 ### 要件定義
 
@@ -153,6 +161,8 @@ UI設計の詳細は [UI設計ガイド](UI設計ガイド.md) を参照
 
 ユースケース・ユーザーストーリーの詳細は[ユースケース作成ガイド](ユースケース作成ガイド.md)を参照
 
+## 開発
+
 ### リリース計画
 
 ```plantuml
@@ -171,8 +181,8 @@ state イテレーション {
   満足条件2: （ユーザーストーリー、予算、スケジュール)
   満足条件2 --> イテレーションプランニング
   イテレーションプランニング --> 満足条件2
-  イテレーションプランニング --> 開発
-  開発 --> フィーチャが追加された状態
+  イテレーションプランニング --> コーディングとテスト
+  コーディングとテスト --> フィーチャが追加された状態
   フィーチャが追加された状態 --> 満足条件2 : フィードバック
   フィーチャが追加された状態 --> 満足条件1 : フィードバック
 }
@@ -184,8 +194,9 @@ state イテレーション {
 
 計画づくりの詳細は [リリース・イテレーション計画ガイド](リリース・イテレーション計画ガイド.md)	 を参照。
 
+リリースの詳細は [リリースガイド](リリースガイド.md) を参照
 
-## 開発
+### コーディングとテスト
 
 ```plantuml
 @startuml
@@ -221,6 +232,7 @@ state イテレーション {
 |構築|
 start
 :環境構築;
+:プロビジョニング;
 :CI/CD構築;
 
 |配置|
@@ -233,3 +245,55 @@ stop
 
 @enduml
 ```
+
+```plantuml
+@startuml
+
+[*] --> 環境構築
+
+state 環境構築 {
+  アプリケーション開発環境セットアップ --> 開発環境セットアップ
+  開発環境セットアップ --> ステージング環境セットアップ
+  ステージング環境セットアップ --> 本番環境セットアップ 
+}
+
+環境構築 --> プロビジョニング
+
+state プロビジョニング {
+  インフラプロビジョニング --> インフラコード管理
+  インフラコード管理 --> インフラプロビジョニング
+}
+
+プロビジョニング --> CICD構築
+
+state CICD構築 {
+  CICDパイプライン設計 --> CICDパイプライン実装
+  CICDパイプライン実装 --> CICDパイプライン設計
+}
+
+CICD構築 --> デプロイ設定
+
+state デプロイ設定 {
+  デプロイ戦略設計 --> デプロイ戦略実装
+  デプロイ戦略実装 --> デプロイ戦略設計
+}
+
+
+環境構築 --> ドキュメント更新
+プロビジョニング --> ドキュメント更新
+CICD構築  --> ドキュメント更新
+デプロイ設定 --> ドキュメント更新
+
+アプリケーション開発環境セットアップ --> 運用スクリプト作成
+開発環境セットアップ --> 運用スクリプト作成
+ステージング環境セットアップ --> 運用スクリプト作成
+本番環境セットアップ --> 運用スクリプト作成
+インフラコード管理 --> 運用スクリプト作成
+CICDパイプライン実装 --> 運用スクリプト作成
+デプロイ戦略実装 --> 運用スクリプト作成
+運用スクリプト作成 --> ドキュメント更新
+  
+ドキュメント更新 --> [*]
+@enduml
+```
+