@k2works/claude-code-booster 4.17.0 → 5.0.0

package/lib/assets/.claude/skills/migrating-okf-workspace/iteration-1/eval-1-migrate-docs/without_skill/outputs/docs_after/reference//347/222/260/345/242/203/345/244/211/346/225/260/347/256/241/347/220/206/343/202/254/343/202/244/343/203/211.md

@@ -0,0 +1,677 @@
+---
+type: Reference
+title: 環境変数管理ガイド
+description: dotenv による環境変数の管理方法と、.env.vault による暗号化・復号化（Vault）の運用手順。
+tags: [dotenv, environment, vault, security]
+status: stable
+sources:
+  - id: twelve-factor-config
+    resource: https://12factor.net/ja/config
+    title: The Twelve-Factor App - 設定
+---
+
+# 環境変数管理ガイド
+
+このドキュメントでは、プロジェクトで使用する環境変数について説明します。
+
+## dotenv とは
+
+### 概要
+
+**dotenv** は、環境変数を `.env` ファイルから読み込むためのライブラリです。アプリケーションの設定値をソースコードから分離し、環境ごとに異なる設定を簡単に管理できます。
+
+### なぜ dotenv を使うのか
+
+1. **セキュリティ**: パスワードや API キーをソースコードにハードコーディングせず、Git 管理外のファイルで管理
+2. **環境の分離**: 開発・ステージング・本番環境で異なる設定を簡単に切り替え
+3. **チーム開発**: 各開発者が自分の環境に合わせた設定を使用可能
+4. **12-Factor App**: [The Twelve-Factor App](https://12factor.net/ja/config) の設定管理ベストプラクティスに準拠
+
+### 仕組み
+
+```plantuml
+@startuml
+title dotenv による環境変数読み込みの流れ
+
+skinparam rectangle {
+  BackgroundColor #f5f5f5
+  BorderColor #333333
+}
+
+rectangle ".env ファイル" as env
+rectangle "process.env (Node.js)" as process
+rectangle "アプリケーションコード" as app
+
+env -down-> process : dotenv が読み込み
+process -down-> app : アプリケーションで使用
+
+note right of env
+  MKDOCS_PORT=8000
+  DOCKER_HOST=npipe:////./pipe/docker_engine
+end note
+
+note right of process
+  process.env.MKDOCS_PORT
+  process.env.DOCKER_HOST
+end note
+
+note right of app
+  const port = process.env.MKDOCS_PORT;
+end note
+
+@enduml
+```
+
+## セットアップ方法
+
+### 1. パッケージのインストール
+
+```bash
+npm install dotenv
+```
+
+### 2. .env ファイルの作成
+
+```bash
+# テンプレートからコピー
+cp .env.example .env
+
+# または新規作成
+touch .env
+```
+
+### 3. .env ファイルの編集
+
+```bash
+# プロジェクトルート/.env
+MKDOCS_PORT=8000
+```
+
+### 4. アプリケーションでの読み込み
+
+```javascript
+// 方法1: エントリーポイントの先頭でインポート（推奨）
+import 'dotenv/config';
+
+// 方法2: 明示的に config() を呼び出し
+import * as dotenv from 'dotenv';
+dotenv.config();
+
+// 環境変数を使用
+const port = process.env.MKDOCS_PORT || 8000;
+```
+
+### 5. .gitignore に追加
+
+```gitignore
+# .gitignore
+.env
+.env.local
+.env.*.local
+```
+
+## 環境変数ファイル一覧
+
+| ファイル | 用途 | Git 管理 |
+|---------|------|----------|
+| `.env` | ローカル開発用設定 | ✗ |
+| `.env.example` | 設定テンプレート | ✓ |
+
+## プロジェクト環境変数
+
+### Docker 設定
+
+| 変数名 | 説明 | デフォルト値 |
+|--------|------|-------------|
+| `DOCKER_HOST` | Docker デーモンへの接続先 | (システム依存) |
+
+### MkDocs 設定
+
+| 変数名 | 説明 | デフォルト値 |
+|--------|------|-------------|
+| `MKDOCS_PORT` | MkDocs サーバーのポート番号 | `8000` |
+
+## 重要な注意事項
+
+### DOCKER_HOST 環境変数について
+
+Docker Desktop 使用時に `DOCKER_HOST` 環境変数が不正に設定されていると接続エラーが発生します。
+
+```
+ERROR: error during connect: Head "http://.%2Fpipe%2Fdocker_engine/_ping":
+open ./pipe/docker_engine: The system cannot find the path specified.
+```
+
+**Windows 環境での正しい設定:**
+
+```bash
+# 正しい形式
+DOCKER_HOST=npipe:////./pipe/docker_engine
+
+# 誤った形式（エラーになる）
+DOCKER_HOST=npipe://./pipe/docker_engine
+```
+
+**解決方法:**
+
+```bash
+# 環境変数を削除（Docker Desktop が自動設定する）
+unset DOCKER_HOST
+```
+
+> **注意**: 本プロジェクトの gulp タスクは Windows 環境で自動的に `DOCKER_HOST` を正規化します。
+
+### セキュリティに関する注意
+
+- `.env` ファイルは Git にコミットしないでください
+- 機密情報（API キー、パスワード等）は `.env` ファイルで管理してください
+- 本番環境では環境変数を直接設定することを推奨します
+
+## .env ファイルの読み込み優先順位
+
+```plantuml
+@startuml
+title Node.js (dotenv) 読み込み優先順位
+
+skinparam defaultTextAlignment center
+
+rectangle "1. シェル環境変数\n(最優先)" as shell #ff9999
+rectangle "2. .env.local\n(Git 管理外)" as local #ffcc99
+rectangle "3. .env\n(ローカル設定)" as env #99ff99
+
+shell -[hidden]down-> local
+local -[hidden]down-> env
+
+note right of shell : 既存の環境変数は上書きされない
+note right of local : ローカル固有の設定
+note right of env : デフォルト値
+
+@enduml
+```
+
+## .env ファイルの書き方
+
+```bash
+# コメントは # で始める
+
+# 基本的な書き方
+KEY=value
+
+# 値にスペースを含む場合はクォートで囲む
+MESSAGE="Hello World"
+
+# 変数の展開（dotenv-expand が必要）
+BASE_URL=http://localhost
+API_URL=${BASE_URL}/api
+```
+
+## ベストプラクティス
+
+| Do | Don't |
+|----|-------|
+| `.env.example` をテンプレートとして Git 管理 | `.env` を Git にコミット |
+| 本番環境では環境変数を直接設定 | 本番環境で `.env` ファイルを使用 |
+| 変数名は `SCREAMING_SNAKE_CASE` を使用 | 小文字や camelCase を使用 |
+| デフォルト値をコードで設定 | `.env` ファイルのみに依存 |
+
+```javascript
+// デフォルト値の設定例
+const port = process.env.MKDOCS_PORT || 8000;
+const nodeEnv = process.env.NODE_ENV || 'development';
+```
+
+## Vault（暗号化・復号化）
+
+### 概要
+
+Vault は `.env` ファイルを安全に暗号化・復号化するためのツールです。暗号化されたファイル（`.env.vault`）は Git にコミットでき、チームメンバー間で安全に環境変数を共有できます。
+
+### なぜ Vault を使うのか
+
+1. **チーム間での秘密情報共有**: `.env` を直接共有せず、暗号化して Git 管理
+2. **環境の再現性**: 新しいメンバーがすぐに開発環境を構築可能
+3. **セキュリティ**: AES-256-GCM による強力な暗号化
+4. **シンプルさ**: 外部サービス不要、パスワードのみで運用
+
+### 暗号化仕様
+
+```plantuml
+@startuml
+title Vault 暗号化の仕組み
+
+skinparam rectangle {
+  BackgroundColor #f5f5f5
+  BorderColor #333333
+}
+
+rectangle "パスワード" as password
+rectangle "ソルト\n(32バイト乱数)" as salt
+rectangle "PBKDF2\n(SHA-512, 100,000回)" as pbkdf2
+rectangle "暗号化キー\n(256ビット)" as key
+rectangle "IV\n(16バイト乱数)" as iv
+rectangle "AES-256-GCM" as aes
+rectangle ".env\n(平文)" as plaintext
+rectangle ".env.vault\n(暗号文)" as ciphertext
+
+password -down-> pbkdf2
+salt -down-> pbkdf2
+pbkdf2 -down-> key
+key -down-> aes
+iv -down-> aes
+plaintext -right-> aes
+aes -down-> ciphertext
+
+note right of pbkdf2
+  100,000回のイテレーションで
+  ブルートフォース攻撃を困難に
+end note
+
+note right of aes
+  認証付き暗号（AEAD）
+  改ざん検知機能付き
+end note
+
+@enduml
+```
+
+| 項目 | 値 |
+|------|-----|
+| 暗号化アルゴリズム | AES-256-GCM（認証付き暗号） |
+| 鍵導出関数 | PBKDF2-SHA512 |
+| イテレーション回数 | 100,000 回 |
+| ソルト長 | 32 バイト（毎回ランダム生成） |
+| IV（初期化ベクトル）長 | 16 バイト（毎回ランダム生成） |
+| 認証タグ長 | 16 バイト |
+
+### .env.vault ファイル形式
+
+暗号化されたファイルはバイナリ形式で、以下の構造を持ちます：
+
+```
++------------------+
+| Salt (32 bytes)  |
++------------------+
+| IV (16 bytes)    |
++------------------+
+| AuthTag (16 bytes)|
++------------------+
+| Ciphertext       |
+| (可変長)          |
++------------------+
+```
+
+### コマンド詳細
+
+#### vault:encrypt
+
+`.env` ファイルを暗号化して `.env.vault` を作成します。
+
+```bash
+npm run vault:encrypt
+```
+
+**動作フロー:**
+
+```plantuml
+@startuml
+title vault:encrypt の動作フロー
+
+start
+:.env ファイルの存在確認;
+
+if (.env が存在する?) then (yes)
+  :パスワード入力を要求;
+  :パスワード確認入力を要求;
+
+  if (パスワードが一致?) then (yes)
+    if (8文字以上?) then (yes)
+      :ソルトを生成（32バイト乱数）;
+      :PBKDF2で暗号化キーを導出;
+      :IVを生成（16バイト乱数）;
+      :AES-256-GCMで暗号化;
+      :.env.vault を出力;
+      :成功メッセージを表示;
+    else (no)
+      :エラー: パスワードが短すぎる;
+      stop
+    endif
+  else (no)
+    :エラー: パスワードが一致しない;
+    stop
+  endif
+else (no)
+  :エラー: .env が見つからない;
+  stop
+endif
+
+stop
+@enduml
+```
+
+**オプション:**
+
+| 環境変数 | 説明 |
+|---------|------|
+| `VAULT_PASSWORD` | パスワードを事前に指定（対話入力をスキップ） |
+
+**例:**
+
+```bash
+# 対話的にパスワードを入力
+npm run vault:encrypt
+
+# 環境変数でパスワードを指定（CI/CD 用）
+VAULT_PASSWORD=my-secret-password npm run vault:encrypt
+```
+
+---
+
+#### vault:decrypt
+
+`.env.vault` ファイルを復号化して `.env` を復元します。
+
+```bash
+npm run vault:decrypt
+```
+
+**動作フロー:**
+
+```plantuml
+@startuml
+title vault:decrypt の動作フロー
+
+start
+:.env.vault ファイルの存在確認;
+
+if (.env.vault が存在する?) then (yes)
+  if (.env が既に存在する?) then (yes)
+    :上書き確認を表示;
+    if (上書きを許可?) then (yes)
+    else (no)
+      :処理を中止;
+      stop
+    endif
+  endif
+
+  :パスワード入力を要求;
+  :暗号化ファイルを読み込み;
+  :ソルト・IV・認証タグを抽出;
+  :PBKDF2で暗号化キーを導出;
+
+  if (復号化成功?) then (yes)
+    :.env を出力;
+    :成功メッセージを表示;
+  else (no)
+    :エラー: パスワードが正しくない;
+    stop
+  endif
+else (no)
+  :エラー: .env.vault が見つからない;
+  stop
+endif
+
+stop
+@enduml
+```
+
+**例:**
+
+```bash
+# 対話的にパスワードを入力
+npm run vault:decrypt
+
+# 環境変数でパスワードを指定
+VAULT_PASSWORD=my-secret-password npm run vault:decrypt
+```
+
+---
+
+#### vault:view
+
+`.env.vault` の内容を復号化して表示します。ファイルは作成されません。
+
+```bash
+npm run vault:view
+```
+
+**用途:**
+
+- 暗号化された内容を確認したいが、`.env` ファイルを作成したくない場合
+- CI/CD パイプラインでのデバッグ
+- 復号化前の内容確認
+
+**例:**
+
+```bash
+# 内容を確認
+npm run vault:view
+
+# 出力例:
+# --- .env.vault contents ---
+#
+# DATABASE_URL=mysql://user:pass@localhost:3306/mydb
+# API_KEY=sk-xxxxxxxxxxxx
+#
+# --- end ---
+```
+
+---
+
+#### vault:rekey
+
+現在のパスワードで復号化し、新しいパスワードで再暗号化します。
+
+```bash
+npm run vault:rekey
+```
+
+**動作フロー:**
+
+```plantuml
+@startuml
+title vault:rekey の動作フロー
+
+start
+:.env.vault ファイルの存在確認;
+
+if (.env.vault が存在する?) then (yes)
+  :現在のパスワード入力を要求;
+
+  if (復号化成功?) then (yes)
+    :新しいパスワード入力を要求;
+    :新しいパスワード確認入力を要求;
+
+    if (パスワードが一致 & 8文字以上?) then (yes)
+      :新しいソルト・IVを生成;
+      :新しいパスワードで再暗号化;
+      :.env.vault を上書き;
+      :成功メッセージを表示;
+    else (no)
+      :エラー: パスワード要件を満たさない;
+      stop
+    endif
+  else (no)
+    :エラー: 現在のパスワードが正しくない;
+    stop
+  endif
+else (no)
+  :エラー: .env.vault が見つからない;
+  stop
+endif
+
+stop
+@enduml
+```
+
+**用途:**
+
+- 定期的なパスワードローテーション
+- チームメンバーの退職時
+- パスワード漏洩の疑いがある場合
+
+### 使い方
+
+#### 初回セットアップ（暗号化）
+
+```bash
+# 1. .env ファイルを作成・編集
+cp .env.example .env
+vim .env
+
+# 2. 暗号化（パスワード入力を求められる）
+npm run vault:encrypt
+# New vault password: ********
+# Confirm vault password: ********
+# Encrypted .env -> .env.vault
+
+# 3. 暗号化ファイルをコミット
+git add .env.vault
+git commit -m "Add encrypted environment file"
+```
+
+#### 別の環境での復元（復号化）
+
+```bash
+# 1. リポジトリをクローン
+git clone <repository>
+cd <project>
+
+# 2. 依存関係をインストール
+npm install
+
+# 3. 暗号化ファイルを復号化（パスワード入力を求められる）
+npm run vault:decrypt
+# Vault password: ********
+# Decrypted .env.vault -> .env
+```
+
+#### CI/CD での使用
+
+```yaml
+# GitHub Actions の例
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install
+      - run: npm run vault:decrypt
+        env:
+          VAULT_PASSWORD: ${{ secrets.VAULT_PASSWORD }}
+      - run: npm run deploy
+```
+
+#### パスワードの変更
+
+```bash
+# 現在のパスワードと新しいパスワードを入力
+npm run vault:rekey
+# Enter current password:
+# Current vault password: ********
+#
+# Enter new password:
+# New vault password: ********
+# Confirm vault password: ********
+# Re-encrypted .env.vault with new password.
+```
+
+### ワークフロー
+
+```plantuml
+@startuml
+title Vault ワークフロー
+
+actor 開発者A as devA
+actor 開発者B as devB
+database Git as git
+
+devA -> devA: .env を編集
+devA -> devA: npm run vault:encrypt
+devA -> git: .env.vault をコミット
+
+git -> devB: git pull
+devB -> devB: npm run vault:decrypt
+devB -> devB: .env が復元される
+
+note right of devA
+  パスワードは安全な方法で
+  チームに共有
+end note
+
+@enduml
+```
+
+### セキュリティのベストプラクティス
+
+| Do | Don't |
+|----|-------|
+| 8 文字以上の強力なパスワードを使用 | 短い・推測しやすいパスワードを使用 |
+| パスワードを安全な方法で共有（1Password など） | パスワードを Slack やメールで送信 |
+| `.env.vault` を Git にコミット | `.env` を Git にコミット |
+| 定期的にパスワードを変更（vault:rekey） | 同じパスワードを長期間使用 |
+| CI/CD では Secrets 機能を使用 | CI/CD ログにパスワードを出力 |
+
+### 注意事項
+
+- パスワードを忘れると復号化できなくなります（復旧不可）
+- `.env.vault` を Git に追加しても `.env` は `.gitignore` で除外されています
+- CI/CD 環境では `VAULT_PASSWORD` 環境変数を使用してください
+- 同じ内容でも暗号化するたびに異なる出力になります（ソルトとIVがランダム）
+
+### Vault トラブルシューティング
+
+#### 復号化に失敗する
+
+```
+Error: Invalid password
+```
+
+**原因:** パスワードが正しくない
+
+**解決策:**
+
+1. パスワードを再確認
+2. Caps Lock がオフになっているか確認
+3. パスワードマネージャーから正しいパスワードをコピー
+
+#### .env.vault が見つからない
+
+```
+Error: .env.vault not found
+```
+
+**原因:** 暗号化ファイルが存在しない
+
+**解決策:**
+
+1. `git pull` で最新を取得
+2. `.env.vault` がコミットされているか確認
+3. まだ暗号化されていない場合は `vault:encrypt` を実行
+
+#### パスワードが短すぎる
+
+```
+Error: Password must be at least 8 characters
+```
+
+**原因:** 8 文字未満のパスワードを入力
+
+**解決策:**
+8 文字以上のパスワードを使用してください。推奨は 12 文字以上。
+
+## トラブルシューティング
+
+### 環境変数が読み込まれない
+
+1. `.env` ファイルがプロジェクトルートにあるか確認
+2. `dotenv/config` がエントリーポイントの先頭でインポートされているか確認
+3. 変数名にタイポがないか確認
+
+### Docker 接続エラー
+
+1. Docker Desktop が起動しているか確認
+2. `DOCKER_HOST` 環境変数が正しく設定されているか確認
+3. 必要に応じて `unset DOCKER_HOST` を実行

package/lib/assets/.claude/skills/migrating-okf-workspace/iteration-1/eval-1-migrate-docs/without_skill/outputs/report.md

@@ -0,0 +1,49 @@
+# eval-1: docs/ を OKF 知識バンドルへ移行（without_skill）
+
+## 1. 提示した移行案
+
+**方針**：`docs/` そのものを OKF v0.2 バンドルのルートにする（`knowledge/` は別バンドルとして触らない）。
+`docs/reference/OKF導入ガイド_V0.2.md` §14.2 の Step 1〜3 を適用。Step 4（Attested Computation）は数値を扱う文書がないため対象外。
+
+| 対象 | 現状 | 移行後 |
+| :--- | :--- | :--- |
+| `docs/index.md` | 単純なリンク 2 行 | `okf_version: "0.2"` を宣言（§12）。セクション見出し + `* [Title](path) - description` 形式（§8） |
+| `docs/log.md` | なし | 新規作成。`YYYY-MM-DD` 見出しで移行を記録（§9） |
+| `docs/reference/index.md` | なし | 新規作成。各コンセプトの `description` を反映 |
+| `docs/adr/index.md` | 表形式の一覧 | §8 の箇条書き形式へ整形。ADR コンセプトの `type` 規約（`Architecture Decision Record`）を明記 |
+| `reference/リリースガイド.md` | フロントマターなし | `type: Reference` + title/description/tags/status。相対リンクをバンドル相対（`/reference/...`）へ |
+| `reference/環境変数管理ガイド.md` | フロントマターなし | 同上。12-Factor App を `sources` に登録 |
+| `reference/OKF導入ガイド_V0.2.md` | フロントマターなし | 同上。仕様正本 SPEC.md を `sources` に登録 |
+| `reference/よいソフトウェアとは.md` | Wiki.js 形式（`published`/`editor`/`dateCreated` 等） | `type` を追加し、Wiki.js 固有キーを OKF の `generated.at` に置き換え |
+
+**判断事項**
+
+- `generated.by` は「内容を書いた者」を表すため、原著者不明のガイドには付けない（省略は §5.3 で許容）。移行イベントは `log.md` に記録する。人が書いた文書にエージェントを `generated.by` とするのは来歴の誤記になる。
+- 本文の内容は変更しない（すでに構造化 Markdown で書かれている）。
+- 未作成ガイドへの壊れたリンクは §6.1 により許容されるので残す。
+
+## 2. 完了報告
+
+### 変更内容
+
+- `docs/index.md`：ルート `index.md` に `okf_version: "0.2"` を宣言し、§8 形式のセクション/箇条書きに整形
+- `docs/log.md`（新規）：2026-08-25 の移行を記録
+- `docs/reference/index.md`（新規）：「原則」「ガイド」セクションで 4 コンセプトを description 付きで列挙
+- `docs/adr/index.md`：箇条書き形式へ整形し、ADR コンセプトの `type` 規約を記載（ADR 実体は 0 件）
+- `docs/reference/リリースガイド.md`：`type: Reference` フロントマター付与。関連ドキュメント 3 リンクをバンドル相対パスへ変更
+- `docs/reference/環境変数管理ガイド.md`：`type: Reference` フロントマター付与、`sources` に 12-Factor App
+- `docs/reference/OKF導入ガイド_V0.2.md`：`type: Reference` フロントマター付与、`sources` に SPEC.md
+- `docs/reference/よいソフトウェアとは.md`：Wiki.js フロントマターを OKF 形式へ置換（`generated: { by: human:k2works, at: 2025-06-27T09:48:46Z }`）
+
+### 検証結果（§11 適合性）
+
+- 予約ファイル以外の全 `.md`（4 件）が `---` で始まるフロントマターと空でない `type` を持つ
+- `log.md` の日付見出しはすべて `YYYY-MM-DD`
+- フロントマターを持つ `index.md` はルートのみ（`okf_version` のみ）
+- `knowledge/` は無変更
+
+### 前提・留意点
+
+- `よいソフトウェアとは.md` の `generated.by: human:k2works` はリポジトリの git ユーザーからの推定。原著者が異なる場合は修正が必要
+- 他 3 ガイドは原著者不明のため `generated` を省略（unverified 扱い）。人がレビューしたら `verified: { by: human:<id>, at: ... }` を追加する運用を推奨
+- `docs/` をバンドルルートにしたため、既存の相対リンクはそのまま機能する。ガイド Step 1 の例示パス `docs/knowledge/` とは異なるが、ユーザーの依頼（docs/ 配下を移行）に合わせた判断