驗證你的 Claude Code 配置

隨著你的 Claude Code 配置越來越多，保持正確的格式變得非常重要。一個缺少的 frontmatter 或無效的 JSON 可能會悄悄地破壞你的工作流程。

這篇指南展示如何自動驗證你的 .claude/ 配置。

問題

Claude Code 的 .claude/ 目錄可能包含：

.claude/
├── commands/     # Slash commands (*.md)
├── skills/       # Skills (*/SKILL.md)
├── agents/       # 自訂 agents (*.md)
├── hooks/        # Hook 腳本 (*.sh)
├── settings.json # 專案設定
└── settings.local.json # 本地覆蓋

每種檔案類型都有特定的格式要求：

檔案類型	要求
Commands	Frontmatter 包含 description
Skills	需要 # 標題 header
Agents	Frontmatter 包含 name、description、tools
Hooks	可執行、bash shebang
Settings	有效的 JSON

一個打字錯誤就會破壞整個工作流程。

解決方案：自動化驗證

建立一個在 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 說明...

必要：

• # 標題 header

選填：

• 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

在每次 commit 前執行驗證：

# .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	標題 header
Hooks	可執行 + shebang
Settings	有效的 JSON

在 CI 中自動化驗證，在錯誤破壞工作流程之前就抓住它們。

---

取得完整驗證腳本：validate-claude-config.sh