Claude Code 設定の検証

Claude Code の設定が増えるにつれて、正しい形式を維持することが重要になります。frontmatter の欠落や無効な JSON は、ワークフローを静かに壊す可能性があります。

このガイドでは、.claude/ 設定を自動的に検証する方法を紹介します。

問題

Claude Code の .claude/ ディレクトリには以下が含まれます：

.claude/
├── commands/     # スラッシュコマンド (*.md)
├── skills/       # Skills (*/SKILL.md)
├── agents/       # カスタム agents (*.md)
├── hooks/        # Hook スクリプト (*.sh)
├── settings.json # プロジェクト設定
└── settings.local.json # ローカルオーバーライド

各ファイルタイプには特定の形式要件があります：

ファイルタイプ	要件
Commands	description を含む frontmatter
Skills	# タイトル ヘッダーが必要
Agents	name、description、tools を含む frontmatter
Hooks	実行可能、bash shebang
Settings	有効な JSON

1つのタイプミスでワークフロー全体が壊れます。

解決策：自動検証

CI で実行する検証スクリプトを作成：

#!/bin/bash
# scripts/validate-claude-config.sh

ERRORS=0

# Commands を検証
for file in .claude/commands/*.md; do
    [ -f "$file" ] || continue

    # frontmatter の存在を確認
    if ! head -1 "$file" | grep -q "^---$"; then
        echo "❌ $file: frontmatter がありません"
        ((ERRORS++))
    fi

    # description フィールドを確認
    if ! grep -q "^description:" "$file"; then
        echo "⚠️ $file: description がありません"
    fi
done

# Agents を検証
for file in .claude/agents/*.md; do
    [ -f "$file" ] || continue

    if ! head -1 "$file" | grep -q "^---$"; then
        echo "❌ $file: frontmatter がありません"
        ((ERRORS++))
    fi

    for field in name description tools; do
        if ! grep -q "^$field:" "$file"; then
            echo "❌ $file: '$field' がありません"
            ((ERRORS++))
        fi
    done
done

# Skills を検証
for file in .claude/skills/*/SKILL.md; do
    [ -f "$file" ] || continue

    if ! grep -q "^# " "$file"; then
        echo "❌ $file: タイトルがありません"
        ((ERRORS++))
    fi
done

# Hooks を検証
for file in .claude/hooks/*.sh; do
    [ -f "$file" ] || continue

    if [ ! -x "$file" ]; then
        echo "❌ $file: 実行できません"
        ((ERRORS++))
    fi
done

# JSON 設定を検証
for json in .claude/settings.json .claude/settings.local.json; do
    [ -f "$json" ] || continue

    if ! python3 -c "import json; json.load(open('$json'))" 2>/dev/null; then
        echo "❌ $json: 無効な JSON"
        ((ERRORS++))
    fi
done

exit $ERRORS

GitHub Actions 統合

CI パイプラインに追加：

# .github/workflows/validate.yml
name: Validate Claude Config

on:
  push:
    paths:
      - '.claude/**'
  pull_request:
    paths:
      - '.claude/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate Claude Config
        run: ./scripts/validate-claude-config.sh

これで .claude/ を変更するすべての PR が自動的に検証されます。

ファイル形式リファレンス

Commands (.claude/commands/*.md)

---
description: コマンドの簡単な説明
---

# コマンド名

コマンドの説明...

必須：

• Frontmatter ブロック (---)
• description フィールド

Agents (.claude/agents/*.md)

---
name: agent-name
description: この agent が何をするか
tools: [Read, Write, Bash]
model: sonnet
---

# Agent システムプロンプト

agent への指示...

必須：

• name：Agent 識別子
• description：何をするか
• tools：許可されたツールの配列

オプション：

• model：haiku、sonnet、opus

Skills (.claude/skills/*/SKILL.md)

---
description: この skill が何をするか
user-invocable: true
context: fork
agent: Explore
---

# Skill 名

Skill の説明...

必須：

• # タイトル ヘッダー

オプション：

• description：自動検出トリガー
• user-invocable：/skillname で呼び出し可能
• context：main（デフォルト）または fork
• agent：どの agent が実行するか

Hooks (.claude/hooks/*.sh)

#!/bin/bash
# Hook ロジック

必須：

• 実行権限 (chmod +x)
• Bash shebang (#!/bin/bash)

Settings (.claude/settings.json)

{
  "permissions": {
    "allow": ["Read", "Write"],
    "deny": ["Bash(*rm -rf*)"]
  },
  "hooks": {
    "PreToolUse": [...]
  }
}

必須：

• 有効な JSON 構文

よくある間違い

1. Frontmatter 区切りの欠落

<!-- ❌ 間違い -->
description: 私のコマンド

# コマンド

<!-- ✅ 正解 -->
---
description: 私のコマンド
---

# コマンド

2. Hook の権限問題

# ❌ スクリプトが実行できない
$ ./scripts/my-hook.sh
bash: permission denied

# ✅ 修正
$ chmod +x ./scripts/my-hook.sh

3. JSON の末尾カンマ

// ❌ 無効な JSON
{
  "allow": ["Read", "Write",]
}

// ✅ 有効な JSON
{
  "allow": ["Read", "Write"]
}

4. 間違った Frontmatter フィールド名

<!-- ❌ 間違ったフィールド名 -->
---
desc: 私の agent
---

<!-- ✅ 正しいフィールド名 -->
---
description: 私の agent
---

Pre-commit Hook

すべてのコミット前に検証を実行：

# .git/hooks/pre-commit
#!/bin/bash
./scripts/validate-claude-config.sh

または pre-commit フレームワークを使用：

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: validate-claude-config
        name: Validate Claude Config
        entry: ./scripts/validate-claude-config.sh
        language: script
        files: ^\.claude/

まとめ

チェック項目	検証内容
Commands	Frontmatter + description
Agents	Frontmatter + name + description + tools
Skills	タイトルヘッダー
Hooks	実行可能 + shebang
Settings	有効な JSON

CI で検証を自動化して、ワークフローを壊す前にエラーをキャッチしましょう。

---

完全な検証スクリプトを入手：validate-claude-config.sh