Claude Code的設定，您是否隨意使用呢？

Hooks、Skills、CLAUDE.md、settings.json、MCP、權限管理…… 2026年的Claude Code功能爆炸性增長。但正確設定這些功能的工程師不到1%。

本文提供了涵蓋所有功能的「可用於生產的設定檔一套」。複製貼上即可立即使用。

立即使用的讀者： 我們已經公開一個將所有設定打包的資料庫，可以用一個命令在任何項目中進行配置。

curl -fsSL https://raw.githubusercontent.com/babushkai/claude-code-config/main/setup.sh

GitHub: https://github.com/babushkai/claude-code-config

總結來說

Claude Code的設定由7個層次組成：

1. CLAUDE.md - 給Claude的指示文件（團隊共享 / 個人用）
2. 自動記憶體 - Claude自動學習的記錄
3. .claude/rules/ - 模組化的規則檔
4. settings.json - 權限、許可工具、環境設定
5. Hooks - 生命周期事件自動化（17個事件）
6. Skills - 自訂斜線命令
7. MCP - 外部工具整合（GitHub、DB、Sentry等）

只有正確設定這些內容，才能真正稱之為「生產運用」。

目錄結構總覽

首先，讓我們看看完成的目錄結構：

your-project/
├── CLAUDE.md                    # 項目指示文件（git管理）
├── CLAUDE.local.md              # 個人指示文件（gitignore）
├── .mcp.json                    # 團隊共享MCP設定（git管理）
├── .claude/
│   ├── CLAUDE.md                # 別名配置OK（與CLAUDE.md相同）
│   ├── settings.json            # 共享設定（git管理）
│   ├── settings.local.json      # 個人設定（gitignore）
│   ├── rules/                   # 模組化規則
│   │   ├── code-style.md
│   │   ├── testing.md
│   │   ├── security.md
│   │   └── frontend/
│   │       ├── react.md
│   │       └── styles.md
│   ├── skills/                  # 自訂技能
│   │   ├── deploy/
│   │   │   └── SKILL.md
│   │   ├── review-pr/
│   │   │   └── SKILL.md
│   │   └── fix-issue/
│   │       └── SKILL.md
│   ├── agents/                  # 自訂子代理
│   │   └── security-reviewer/
│   │       └── AGENT.md
│   └── hooks/                   # Hook腳本
│       ├── lint-on-save.sh
│       ├── block-secrets.sh
│       └── notify-slack.sh
│
├── ~/.claude/                   # 使用者全域設定
│   ├── CLAUDE.md                # 全項目通用的個人指示
│   ├── settings.json            # 全域設定
│   ├── settings.local.json      # 僅限本地
│   ├── rules/                   # 個人規則
│   │   └── preferences.md
│   └── skills/                  # 個人技能
│       └── explain-code/
│           └── SKILL.md

1. CLAUDE.md - 給Claude的指示文件

CLAUDE.md是安裝到Claude腦中的項目DNA。

記憶層次（優先級順序）

CLAUDE.md的黃金法則：「人類唯一知道的事情」才該寫

最常見的錯誤：將可以從源代碼獲取的資訊寫入CLAUDE.md。

Claude可以通過閱讀package.json了解構建命令，透過tsconfig.json獲得TypeScript的設定，探索目錄可以解釋架構，而.eslintrc中的資料則能獲知編碼規範。

將這些寫入CLAUDE.md是浪費token。

CLAUDE.md應只記錄那些Claude無法透過閱讀源代碼獲得的資訊：

生產用的CLAUDE.md範本

# 項目的決策過程

## 為什麼會選擇這種結構
- 採用單一代碼庫的原因：前端和後端之間的型別共享，將錯誤數量從每週3個減少至0
- 選擇Hono的原因：Cloudflare Workers中的冷啟動時間低於50ms
- 使用PlanetScale的原因：安全地在生產數據庫中進行模式變更

## 絕對不能做的事情
- `packages/shared/src/legacy/` 是舊API的兼容層。雖然會想重構，但請勿改動（有3家客戶依賴，計畫於2026年Q3淘汰）
- Stripe的webhook處理器一旦破壞冪等性將導致重複收費，過去曾發生過$12,000的事故
- `users`表的`email`欄位沒有UNIQUE約束。歷史原因下存在重複，應在應用層進行驗證

## 部署與環境
- staging: Cloudflare Workers（`wrangler deploy --env staging`）
- production: 生產部署僅限GitHub Actions。禁止手動部署
- DB遷移: 必須先在staging上執行`pnpm db:migrate`並確認

## 團隊工作流程
- PR必須經過至少一人的審核
- `feat/`分支使用squash merge，`fix/`分支使用正常merge
- 每週五15時後禁止進行生產部署（以避免周末的應對）

## 業務背景
- 企業客戶對於SLA要求在200ms內的響應時間
- 必須遵循GDPR。用戶數據必須進行邏輯刪除（禁止物理刪除）
- 每月1日深夜進行的月報生成由cron執行。這一天的DB負載較高

此範本的要點

• 沒有寫pnpm install或pnpm test → Claude可以通過閱讀package.json得知
• 沒有寫目錄結構 → Claude可以通過ls得知
• 相反地，記錄「為什麼」、禁止的事項和過去的事故 → 這些是代碼中未提及的

以import引用外部檔案

可以從CLAUDE.md引用其他檔案：

有關項目的概要請參見 @README.md。
可以使用的命令請查閱 @package.json。
Git運作規則依循 @docs/git-workflow.md 。

# 個人設定
- @~/.claude/my-project-instructions.md

import的注意事項

• 相對路徑是從CLAUDE.md所在的目錄為基準解決
• 最多可進行5層的遞歸import
• 代碼區塊中的@不被解釋為import
• 首次import會彈出授權對話框

.claude/rules/ - 條件性規則

可以為特定的檔案模式編寫適用的規則：

# .claude/rules/api-rules.md
---
paths:
  - "packages/backend/src/routes/**/*.ts"
---
# API開發規則
- 所有端點均需加入zod驗證
- 錯誤響應須按照RFC 7807格式
- 響應中需包含分頁資訊
- 回傳速率限制標頭

# .claude/rules/react-rules.md
---
paths:
  - "packages/frontend/src/**/*.{tsx,ts}"
---
# React開發規則
- 預設使用Server Components
- "use client"應盡量減少使用
- 使用Suspense管理加載狀態
- key屬性不能使用index

2. settings.json - 權限和設定

設定檔的優先順序

管理政策（最高）
  ↓
CLI標記（--disallowedTools等）
  ↓
.claude/settings.local.json（項目本地）
  ↓
.claude/settings.json（項目共享）
  ↓
~/.claude/settings.local.json（使用者本地）
  ↓
~/.claude/settings.json（使用者共享・最低）

生產用 .claude/settings.json（團隊共享）

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(pnpm run *)",
      "Bash(pnpm test *)",
      "Bash(pnpm build *)",
      "Bash(pnpm lint *)",
      "Bash(pnpm typecheck)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git branch *)",
      "Bash(git checkout *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(gh pr *)",
      "Bash(gh issue *)",
      "Bash(npx prisma *)",
      "Bash(* --version)",
      "Bash(* --help)",
      "Edit(/packages/**)",
      "Write(/packages/**)"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Read(.env*)",
      "Read(**/*.pem)",
      "Read(**/*secret*)",
      "Edit(.env*)",
      "Edit(/.github/workflows/**)"
    ]
  },
  "env": {
    "MAX_MCP_OUTPUT_TOKENS": "50000"
  }
}

個人用 .claude/settings.local.json

{
  "permissions": {
    "allow": [
      "Bash(docker *)",
      "Bash(docker-compose *)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/lint-on-save.sh\""
          }
        ]
      }
    ]
  }
}

控制提交・PR的歸屬顯示（attribution）

Claude Code會預設在提交訊息中添加Co-Authored-By: Claude。若不需要，可透過attribution設定來隱藏：

{
  "attribution": {
    "commit": "",
    "pr": ""
  }
}

可以用空字串""完全隱藏，亦可設定自訂訊息：

{
  "attribution": {
    "commit": "Generated with Claude Code"
  }
}

若置入~/.claude/settings.json中則對所有項目生效。

權限模式的詳細參考

*重要：``前面的空格會改變行為**

• Bash(ls *) → 匹配ls -la，不匹配lsof（有單字邊界）
• Bash(ls*) → 同時匹配ls -la和lsof（無單字邊界）

3. Hooks - 17個生命周期事件

Hooks與CLAUDE.md的「請求」不同，確保實際執行。

所有事件列表

四種Handler

command  → 執行Shell腳本
http     → 發送HTTP POST請求
prompt   → 將判斷留給LLM（是/否）
agent    → 使用子代理進行驗證

生產Hooks設定範例

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/block-secrets.sh\"",
            "statusMessage": "進行安全檢查中..."
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/lint-on-save.sh\"",
            "timeout": 30
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/notify-slack.sh\"",
            "async": true
          }
        ]
      }
    ]
  }
}

實用的Hook腳本集

危險命令阻止（PreToolUse）：

#!/bin/bash
# .claude/hooks/block-secrets.sh
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# 阻止包含秘密資訊的命令
if echo "$COMMAND" | grep -qE '(password|secret|token|api.?key)'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "含有秘密資訊的命令被阻止"
    }
  }'
  exit 0
fi

# 阻止rm -rf命令
if echo "$COMMAND" | grep -qE 'rm\s+-rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "rm -rf 被禁止"
    }
  }'
  exit 0
fi

exit 0

保存檔案後自動校正（PostToolUse）：

#!/bin/bash
# .claude/hooks/lint-on-save.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_result.filePath // empty')

if [ -z "$FILE_PATH" ]; then
  exit 0
fi

# 只針對TypeScript檔案進行校正
if [[ "$FILE_PATH" == *.ts || "$FILE_PATH" == *.tsx ]]; then
  RESULT=$(npx eslint --fix "$FILE_PATH" 2>&1)
  if [ $? -ne 0 ]; then
    jq -n --arg msg "$RESULT" '{
      hookSpecificOutput: {
        hookEventName: "PostToolUse"
      },
      transcript: ("ESLint錯誤:\n" + $msg)
    }'
  fi
fi

exit 0

Slack通知（Stop - 非同步）：

#!/bin/bash
# .claude/hooks/notify-slack.sh
INPUT=$(cat)
STOP_REASON=$(echo "$INPUT" | jq -r '.stop_reason // "unknown"')

if [ "$STOP_REASON" = "end_turn" ]; then
  curl -s -X POST "$SLACK_WEBHOOK_URL" \
    -H 'Content-Type: application/json' \
    -d "{\"text\": \"Claude Code的任務已完成\"}" > /dev/null 2>&1
fi

Prompt Hook（LLM判斷型）

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "請判斷以下Bash命令是否會影響生產環境。命令: $ARGUMENTS。如果包含對生產DB的連接、向生產伺服器的部署、或環境變數的更改，請回答no。",
            "timeout": 15
          }
        ]
      }
    ]
  }
}

4. Skills - 自訂斜線命令

Skill的前端元資料所有字段

實用Skills範例

PR審核技能：

# .claude/skills/review-pr/SKILL.md
---
name: review-pr
description: 審核PR並提供改進的建議
context: fork
agent: Explore
allowed-tools: Bash(gh *)
argument-hint: "[PR編號]"
disable-model-invocation: true
---

## PR上下文
- PR差異: !`gh pr diff $ARGUMENTS`
- PR評論: !`gh pr view $ARGUMENTS --comments`
- 更改文件: !`gh pr diff $ARGUMENTS --name-only`

## 審核步驟
1. 理解變更的意圖
2. 檢查代碼的質量（型別安全性、錯誤處理）
3. 確認是否有安全隱患
4. 評估對性能的影響
5. 檢查測試覆蓋範圍

將審核結果總結為要點，並標註重要性（關鍵/主要/次要）。

Issue修正技能：

# .claude/skills/fix-issue/SKILL.md
---
name: fix-issue
description: 修復GitHub Issue
disable-model-invocation: true
argument-hint: "[issue編號]"
---

修復GitHub issue #$ARGUMENTS。

1. 使用`gh issue view $ARGUMENTS`查看Issue內容
2. 確認相關代碼
3. 實施修正
4. 添加測試
5. 使用`git commit -m "fix: 修正 #$ARGUMENTS"`

部署技能（執行子代理）：

# .claude/skills/deploy/SKILL.md
---
name: deploy
description: 部署至測試環境
disable-model-invocation: true
context: fork
allowed-tools: Bash(pnpm *), Bash(git *), Bash(gh *)
---

將$ARGUMENTS部署至測試環境：

1. 執行測試套件
2. 執行構建
3. 執行部署命令
4. 確認部署成功
5. 通知Slack

動態上下文注入

可以使用!command`語法將Shell命令的結果注入到Skill中：

---
name: status
description: 專案狀態摘要
context: fork
agent: Explore
---

## 當前狀態
- 分支: !`git branch --show-current`
- 未提交: !`git status --short`
- 最新提交: !`git log --oneline -5`
- 測試結果: !`pnpm test --silent 2>&1 | tail -5`
- 型別檢查: !`pnpm typecheck 2>&1 | tail -3`

根據上述資訊總結專案狀態。

5. MCP - 外部工具整合

添加MCP伺服器

# HTTP（推薦）
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# SSE（不推薦）
claude mcp add --transport sse sentry https://mcp.sentry.dev/sse

# stdio（本地執行）
claude mcp add --transport stdio --env AIRTABLE_API_KEY=$KEY airtable \
  -- npx -y airtable-mcp-server

MCP的範疇

團隊共享的MCP設定（.mcp.json）

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DB_DSN}"],
      "env": {
        "DB_DSN": "${DB_DSN:-postgresql://readonly:pass@localhost:5432/dev}"
      }
    }
  }
}

MCP工具搜索

如果MCP工具過多影響上下文，自動Tool Search將會被啟用：

# 將閾值改為5%
ENABLE_TOOL_SEARCH=auto:5 claude

# 始終啟用
ENABLE_TOOL_SEARCH=true claude

# 禁用
ENABLE_TOOL_SEARCH=false claude

6. 自動記憶體 - Claude的自動學習

機制

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 索引（前200行被載入）
├── debugging.md       # 調試模式
├── api-conventions.md # API設計的決策
└── ...                # Claude自動生成

MEMORY.md僅載入最多200行。
超過的資訊需分為按主題的檔案，並從MEMORY.md鏈接。Claude將根據需要載入主題檔案。

明確記憶的內容

> 請記住不使用npm，而使用pnpm。
> 請將API測試需要本地Redis的資訊保存到記憶體中。

控制方法

// .claude/settings.json 中按專案禁用
{
  "autoMemoryEnabled": false
}

# 環境變數強制控制（settings.json優先）
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude  # 強制關閉
CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 claude  # 強制開啟

7. 生產運用檢查清單

確保一切已正確設置：

安全性

• 將.env*文件的Read/Edit設置為deny
• 在PreToolUse Hook中阻止rm -rf
• 將git push --force設置為deny
• 阻止讀取秘密金鑰（*.pem）
• 將curl/wget設置為deny，限制為WebFetch
• 阻止CI/CD工作流程的修改

開發效率

• 設置常用的構建/測試命令為allow
• 配置自動化校正於PostToolUse
• 創建PR審核的Skill
• 創建Issue修正的Skill
• 通過MCP設置與GitHub的整合

團隊標準化

• 使用git管理.claude/settings.json
• 使用git管理.mcp.json
• 透過.claude/rules/管理編碼規範
• 在CLAUDE.md中記錄「人類唯一知道的內容」
• 在.gitignore中添加以下內容：

CLAUDE.local.md
.claude/settings.local.json

常見錯誤及其對策

錯誤1：權限過於寬鬆

// 錯誤: 危險
{
  "permissions": {
    "allow": [
      "Bash"
    ]
  }
}

// 正確: 僅允許必要的命令
{
  "permissions": {
    "allow": [
      "Bash(pnpm *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ]
  }
}

錯誤2：在CLAUDE.md中寫下能從源代碼讀取的資訊

<!-- 錯誤: Claude可通過package.json和目錄結構獲取這些 -->
# 專案概要
TypeScript + React + Node.js的SaaS應用。
packages/frontend: Next.js 15
packages/backend: Hono

## 命令
- `pnpm install` - 安裝依賴
- `pnpm build` - 構建
- `pnpm test` - 執行測試

<!-- 正確: 寫出只有人類知道的『為什麼』和『不該這樣做』 -->
# 決策及限制
- legacy/預定於2026年Q3淘汰。請勿觸動
- 若打破Stripe webhook的冪等性，將導致重複收費（過去有$12K事故）
- 週五15時後禁止進行生產部署

錯誤3：Hook未設定timeout

// 錯誤: 無timeout（預設600秒）
{
  "type": "command",
  "command": "npm run lint"
}

// 正確: 設定適當的timeout
{
  "type": "command",
  "command": "npm run lint",
  "timeout": 30
}

錯誤4：Skill中忘記disable-model-invocation

# 錯誤: Claude有可能自動執行部署技能
---
name: deploy
description: Deploy to production
---

# 正確: 僅允許手動執行
---
name: deploy
description: Deploy to production
disable-model-invocation: true
---

總結

整合了Claude Code生產運用所需的所有設定：

• CLAUDE.md → 撰寫「人類唯一知道的事情」。 不要記錄構建命令或目錄結構，應記錄決策原因、禁止項目及業務限制
• settings.json → 權限使用最小權限原則。以deny第一的方式進行設計
• Hooks → 利用17個事件。安全檢查及自動校正為必要項
• Skills → 將常用工作流程斜線命令化。對於有副作用的要使用disable-model-invocation: true
• MCP → 團隊共享管理為.mcp.json。認證資訊使用環境變數
• 自動記憶體 → 注意200行限制。按主題分割
• 歸屬 → 透過attribution.commit與attribution.pr來控制歸屬顯示

只有在這一切均設定完畢後，Claude Code才能從「玩具」轉變為「生產工具」。

如果本文對您有所幫助，請給予讚與收藏！
有任何問題：您在Claude Code設定中最注重的是什麼？

原文出處：https://qiita.com/emi_ndk/items/56b2fc8bf4e7ed5ba7f3