配置文件模板

配置文件模板

这一篇把 Claude Code 会用到的配置文件都摆出来，每个模板带注释、可整段复制。把这一页当「种子仓库」——clone 下来改几个字就能用。

字段含义以官方 docs.claude.com 的 settings、memory、hooks、mcp 页为准。

CLAUDE.md（项目级）

放在仓库根目录，每次会话自动全量加载。写「每次都要遵守的规矩」，写长了费 token，长内容拆成 Skill。

# 项目：电商后台 API

## 技术栈
- 语言：TypeScript（严格模式）
- 框架：NestJS
- ORM：Prisma
- 测试：Vitest
- 包管理：pnpm（禁止用 npm / yarn）

## 命令
- 装 deps：`pnpm install`
- 跑开发：`pnpm dev`
- 跑测试：`pnpm test`
- 单个文件：`pnpm test path/to/file.test.ts`
- lint：`pnpm lint`
- 类型检查：`pnpm tsc --noEmit`

## 代码风格
- 用 ESM import，不用 require
- 错误抛自定义业务异常（src/exceptions/），不用原生 Error
- 命名：文件 kebab-case，类 PascalCase，函数/变量 camelCase
- 所有 async 函数必须有 try/catch 或交由全局过滤器处理

## 目录约定
- src/modules/<domain>/ 按业务域组织
- 每个 module 含 controller / service / repository / dto
- 共享工具放 src/common/
- 不要在 module 之间直接 import，走 service 接口

## 测试
- 新功能必须带测试，覆盖率门禁 80%
- 测试文件 *.spec.ts，放被测文件同目录
- 不要 mock 整个 Prisma，用 testcontainers 起真库

## Git
- 提交信息用 Conventional Commits（中文描述）
- 分支命名：feat/xxx、fix/xxx、refactor/xxx
- 禁止直接 push main，必须走 PR

注释：项目级 CLAUDE.md 进 git，团队共享。只放「每次都要提醒」的规矩，场景化能力写 Skill。

~/.claude/CLAUDE.md（用户级）

跨项目生效，写你的个人偏好。

# 个人偏好

## 模型
- 默认用 sonnet，复杂架构用 opus，简单查询用 haiku

## 输出
- 用简体中文回答
- 解释代码时配一个最小可运行示例
- 不要在回答里加过多 emoji

## 习惯
- 改代码前先跑一遍现有测试，确认绿
- 提交前自动跑 lint 和 test
- 改完一处就提交一次，别攒大改动

## 全局工具
- 包管理用 pnpm
- 编辑器用 VS Code，格式化用 Prettier

注释：用户级 CLAUDE.md 放个人习惯，优先级低于项目级——项目说用 npm，你就用 npm。

.claude/settings.json（项目级）

项目级配置，进 git 团队共享。集成权限、env、hooks、sandbox、statusLine。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "permissions": {
    "allow": [
      "Bash(pnpm:*)",
      "Bash(npm test:*)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Read(./src/**)",
      "Read(./tests/**)"
    ],
    "deny": [
      "Bash(git push --force:*)",
      "Bash(git push -f:*)",
      "Bash(rm -rf:*)",
      "Edit(./.env)",
      "Edit(./.env.production)",
      "Read(./.env.production)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(git commit:*)"
    ]
  },
  "env": {
    "GITHUB_TOKEN": "${GITHUB_TOKEN}",
    "DATABASE_URL": "${DATABASE_URL}"
  },
  "sandbox": {
    "enabled": false,
    "network": "allow"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm exec prettier --write $CLAUDE_FILE_PATHS 2>/dev/null || true"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo $CLAUDE_TOOL_INPUT | grep -q 'git commit'; then pnpm lint && pnpm tsc --noEmit; fi"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude 任务完成\" with title \"Claude Code\" sound name \"Glass\"' 2>/dev/null || true"
          }
        ]
      }
    ]
  },
  "statusLine": {
    "type": "command",
    "command": "echo \"model: $CLAUDE_MODEL | branch: $(git branch --show-current 2>/dev/null) | cost: $CLAUDE_SESSION_COST\""
  },
  "enabledPlugins": {
    "code-review-workflow": true
  }
}

注释逐块：

• $schema 提供 JSON 补全。
• model 默认模型。
• permissions.allow 安全操作放行；deny 危险操作封死；ask 重要操作每次问。
• env 注入环境变量，${VAR} 从 shell 取值，不写死密钥。
• sandbox 关闭（开发期）；探索陌生代码时再开。
• hooks.PostToolUse 编辑后自动格式化。
• hooks.PreToolUse commit 前跑 lint + 类型检查。
• hooks.Stop 任务完成系统通知。
• statusLine 状态栏显示模型、分支、成本。

.claude/settings.local.json（本地级）

不进 git，放私有配置和密钥。

{
  "permissions": {
    "allow": [
      "Bash(docker:*)",
      "Bash(psql:*)"
    ]
  },
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxxxxxxxxxxx",
    "LOCAL_DATABASE_URL": "postgresql://localhost:5432/mydb_dev"
  },
  "model": "opus"
}

注释：本地级优先级最低，但放密钥最安全——它在 .gitignore 里，不会泄露。model: opus 是你本地想用贵模型，不影响团队。

managed-settings.json（企业级）

IT 推送到系统路径，员工改不了，最高优先级。路径因平台而异（macOS 在 /Library/Application Support/ClaudeCode/，Linux 在 /etc/claude-code/，Windows 在 C:\ProgramData\ClaudeCode\）。

{
  "permissions": {
    "deny": [
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Bash(git push --force:*)",
      "Bash(rm -rf:*)",
      "Read(./.env.production)",
      "Edit(./.env.production)"
    ],
    "ask": [
      "Bash(git push:*)"
    ]
  },
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.corp.internal",
    "ANTHROPIC_API_KEY": "${CORP_LLM_KEY}"
  },
  "sandbox": {
    "enabled": true,
    "network": "allow"
  }
}

注释：企业级锁死外发请求（禁 curl/wget）、禁 force push、强走内部 LLM 网关、强制沙箱。员工的项目级 settings 改不动这些。

.mcp.json（MCP 配置）

仓库根目录，团队共享 MCP 服务器清单。

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/mydb"
      ]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/me/code",
        "/Users/me/docs"
      ]
    },
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

注释：mcpServers 是顶层键，每个 key 是 MCP 名。env 里用 ${VAR} 引环境变量，密钥不写死。filesystem 的 args 限定可访问目录。详见 MCP 服务器清单。

.claude/hooks/ 目录结构

复杂 hook 脚本建议单独放文件，settings.json 里 command 指向脚本路径。

.claude/
├── settings.json
├── hooks/
│   ├── format.sh          # PostToolUse：保存后格式化
│   ├── pre-commit.sh      # PreToolUse：commit 前 lint+test
│   ├── block-dangerous.sh # PreToolUse：拦危险命令
│   ├── notify.sh          # Stop：完成通知
│   └── log.sh             # PostToolUse：记录工具调用
├── agents/                # 子代理（见 subagent-templates）
│   ├── code-reviewer.md
│   └── security-reviewer.md
├── skills/                # 技能（见 skill-templates）
│   └── commit-messages/
│       └── SKILL.md
└── commands/              # 自定义命令
    └── ship.md

format.sh 示例：

#!/usr/bin/env bash
# PostToolUse hook：保存后跑 Prettier
set -e
for f in $CLAUDE_FILE_PATHS; do
  case "$f" in
    *.ts|*.tsx|*.js|*.jsx|*.json|*.md)
      pnpm exec prettier --write "$f" 2>/dev/null || true
      ;;
  esac
done
exit 0

block-dangerous.sh 示例：

#!/usr/bin/env bash
# PreToolUse hook：拦下危险命令
input="$CLAUDE_TOOL_INPUT"
if echo "$input" | grep -qE 'rm -rf /|:(){:|:&};:|curl.*\| sh'; then
  echo "危险命令，已拦截" >&2
  exit 2
fi
exit 0

注释：脚本要 chmod +x。exit 2 拦截并把 stderr 反馈给 Claude，exit 0 放行。

settings.json 里这样引用：

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": ".claude/hooks/format.sh" }] }
    ],
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": ".claude/hooks/block-dangerous.sh" }] }
    ]
  }
}

.devcontainer/（Devcontainer 模板）

把 Claude Code 装进容器，隔离环境，团队一致。探索陌生代码、跑 AI 生成脚本时尤其推荐。

.devcontainer/devcontainer.json

{
  "name": "Claude Code Dev",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "features": {
    "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {}
  },
  "postCreateCommand": "npm install -g @anthropic-ai/claude-code && pnpm install",
  "customizations": {
    "vscode": {
      "extensions": ["anthropic.claude-code"],
      "settings": {
        "terminal.integrated.defaultProfile.linux": "bash"
      }
    }
  },
  "remoteEnv": {
    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}",
    "GITHUB_TOKEN": "${localEnv:GITHUB_TOKEN}"
  },
  "mounts": [
    "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached"
  ],
  "workspaceFolder": "/workspace"
}

配套 .devcontainer/Dockerfile（需要自定义时）：

FROM mcr.microsoft.com/devcontainers/typescript-node:20

RUN apt-get update && apt-get install -y \
    git \
    ripgrep \
    fzf \
    && rm -rf /var/lib/apt/lists/*

RUN npm install -g @anthropic-ai/claude-code

# 非 root 用户
USER node
WORKDIR /workspace

注释：

• postCreateCommand 容器建好后装 Claude Code 和项目依赖。
• remoteEnv 从本地传环境变量进容器，密钥不进镜像。
• docker-outside-of-docker 让容器里能用宿主 Docker（跑 testcontainers 等）。
• VS Code 扩展自动装 Claude Code 插件。

.gitignore 模板

# Claude Code 本地配置，不进 git
.claude/settings.local.json

# 会话与历史
.claude/tool.log
.claude/sessions/

# 个人 agents / skills（按需）
# .claude/agents/personal-*.md
# .claude/skills/personal-*/

注释：.claude/settings.json、.claude/agents/、.claude/skills/、.mcp.json、CLAUDE.md 都要进 git——这些是团队共享的资产。只把 settings.local.json 和会话日志排掉。

一份起步清单

新项目接入 Claude Code，按这个顺序做：

1. 根目录建 CLAUDE.md，写技术栈和命令。
2. .claude/settings.json 配 permissions + hooks + statusLine。
3. .claude/settings.local.json 放你的密钥，加进 .gitignore。
4. .mcp.json 加团队要用的 MCP。
5. .claude/agents/ 放审查类子代理。
6. .claude/skills/ 沉淀团队规范。
7. 进 git，团队 clone 即用。

---

模板是种子，不是成品：抄一份改几个字，跑起来再调。配置的每个字段含义看 Settings，子代理模板看 Subagent 模板库，技能模板看 Skill 模板库。🚀