# Claude Code Settings Setup Guide

**目的**: `.claude/settings.local.json` の自動初期化問題を解決し、ユーザー固有の設定を永続化する

**最終更新**: 2025-10-29

---

## 📋 背景

`.claude/settings.local.json` は `build_slash_commands.py` スクリプトで自動生成されるファイルです。以前は実行するたびに `deny` と `ask` 権限が初期化（リセット）されていました。

**この問題の原因:**
- スクリプトが YAML から生成した `allow` 権限のみを出力
- 手動で追加した `deny` / `ask` 権限が保持されていなかった
- ファイル全体が上書きされてしまっていた

**解決方法:**
- `global_permissions` を `config/slash_commands.yaml` に統合
- `build_slash_commands.py` を修正して YAML から deny/ask を読み込む
- `.claude/settings.local.json` を `.gitignore` に追加（ユーザー固有設定）

---

## 🚀 初回セットアップ

### Step 1: テンプレートをコピー

```bash
cd /path/to/noveler
cp .claude/settings.local.json.template .claude/settings.local.json
```

### Step 2: スクリプトで権限を生成・マージ

```bash
python scripts/setup/build_slash_commands.py
```

このコマンドが実行されると：

1. `config/slash_commands.yaml` を読み込み
2. `global_permissions` セクションから deny/ask を抽出
3. コマンド定義から allow 権限を抽出
4. `.claude/settings.local.json` に統合

**結果:**
```json
{
  "permissions": {
    "allow": [
      "Bash(bin/test:*)",
      "Bash(git add:*)",
      ...
    ],
    "deny": [
      "Bash(sudo:*)",
      "Bash(rm:*)",
      "Bash(rm -rf:*)",
      ...
    ],
    "ask": []
  }
}
```

---

## 📁 ファイル構成

### `config/slash_commands.yaml`

**新規セクション**: `global_permissions`

```yaml
version: 1.0.0
last_updated: '2025-10-29'

# グローバル権限ルール（全スクリプト共通）
# これらはスクリプト再実行時に自動的に保持される
global_permissions:
  deny:
    - "Bash(sudo:*)"
    - "Bash(rm:*)"
    - "Bash(rm -rf:*)"
    # ... その他のセキュリティ制限
  ask: []

commands:
  - name: /test
    script: bin/test
    # ... コマンド定義
```

**重要**: deny/ask の変更は YAML で行う（JSON では直接編集しない）

### `.claude/settings.local.json.template`

初回セットアップ用のテンプレートです。実際の設定ファイルではなく、参考用です。

### `.claude/settings.local.json`

生成される実ファイルです。`.gitignore` に登録されているため、Git には追跡されません。

---

## 🔄 ワークフロー

### パターン1: deny/ask 権限を追加したい場合

**推奨方法**: `config/slash_commands.yaml` の `global_permissions.deny` に追加

```yaml
global_permissions:
  deny:
    - "Bash(sudo:*)"
    - "Bash(rm:*)"
    - "Bash(custom_dangerous_cmd:*)"  # ← 新しい制限を追加
  ask: []
```

その後、スクリプトを実行：

```bash
python scripts/setup/build_slash_commands.py
```

**理由:**
- YAML が唯一の truth source
- git で変更を追跡可能
- チームメンバー全体で同期

### パターン2: スクリプト実行時に allow 権限を失った場合

スクリプトが別のコマンドを削除した場合、そのコマンドの allow 権限も自動的に削除されます。これは予期された動作です。

**復旧方法:**
```bash
python scripts/setup/build_slash_commands.py
```

削除されたコマンドのみが影響を受けます。deny/ask は YAML から復元されます。

### パターン3: CI/CD で自動生成したい場合

GitHub Actions または pre-commit hook で以下を実行：

```bash
python scripts/setup/build_slash_commands.py
```

.gitignore に登録されているため、生成ファイルは tracked されません。

---

## 📊 権限の管理ポイント

| 権限の種類 | 保管場所 | 編集方法 | 用途 |
|-----------|--------|--------|------|
| **allow** | YAML/コマンド定義 | スクリプト自動生成 | 実行許可 |
| **deny** | YAML global_permissions | 手動編集（YAML） | セキュリティ制限 |
| **ask** | YAML global_permissions | 手動編集（YAML） | インタラクティブ確認 |

---

## 🛡️ セキュリティ考慮

### `.gitignore` に登録された理由

1. **ユーザー固有の設定**
   - マシンによって必要な権限が異なる可能性
   - 開発環境と本番環境で異なるパスを参照
   - ローカルマシン特有のツール

2. **生成ファイル**
   - `build_slash_commands.py` で自動生成可能
   - `config/slash_commands.yaml` から再構築可能
   - 手動編集は非推奨

### 本番環境での取り扱い

```bash
# CI/CD で設定ファイルを生成
python scripts/setup/build_slash_commands.py

# .gitignore に登録されているため、自動的に上書きされない
# テンプレートから初期化が必要な場合
cp .claude/settings.local.json.template .claude/settings.local.json
python scripts/setup/build_slash_commands.py
```

---

## 🔧 トラブルシューティング

### Q: `build_slash_commands.py` 実行後、deny 権限が消えた

**A**: 現在のバージョンではこは起こりません。YAML の `global_permissions.deny` から自動的に復元されます。

確認方法：
```bash
grep -A 30 "global_permissions:" config/slash_commands.yaml
```

### Q: テンプレートと実ファイルが異なる

**A**: これは正常です。テンプレートは参考用で、実ファイルはスクリプトで自動生成されます。

確認：
```bash
python scripts/setup/build_slash_commands.py --dry-run
```

### Q: 新しいコマンド権限を追加したが反映されない

**A**: スクリプトを実行してください：

```bash
python scripts/setup/build_slash_commands.py
```

YAML の `commands[].permissions` に追加した権限が自動的に反映されます。

---

## 📚 関連ドキュメント

- [config/slash_commands.yaml](../config/slash_commands.yaml) - コマンド定義
- [scripts/setup/build_slash_commands.py](../scripts/setup/build_slash_commands.py) - 生成スクリプト
- [Claude Code Settings](https://docs.claude.com/en/docs/claude-code/claude_code_settings) - 公式ドキュメント

---

## ✅ チェックリスト

初回セットアップ後の確認：

- [ ] `.claude/settings.local.json` が存在する
- [ ] `git status` で `.claude/settings.local.json` が ignored として表示される
- [ ] `build_slash_commands.py` の実行後も `deny` / `ask` が保持されている
- [ ] `config/slash_commands.yaml` に `global_permissions` が存在する

---

**Generated with [Claude Code](https://claude.com/claude-code)**

Co-Authored-By: Claude <noreply@anthropic.com>
