主题
2.6 配置模板速查 — 拿来即用的最佳实践
学习目标：拿到一套可以直接复制粘贴的 Claude Code 配置模板，包括项目记忆（CLAUDE.md）、MCP 服务器配置、Hook 脚本和自定义 Agent 定义；知道每个模板文件放在哪里、怎么改成自己的。
为什么需要这篇速查
前面几节课我们分别讲了记忆系统、MCP、Hooks、子智能体。你可能学完后心想：道理都懂了，但真要从零配一套，还是得翻回去找格式。
这篇就是你的"抄作业专用页"。每个模板都经过实践验证，复制过去改几个字就能用。不用记格式，不用担心写错字段名——打开这篇，照抄就行。
一、CLAUDE.md 项目记忆模板
记忆文件是 Claude Code 每次启动时自动读取的"上下文备忘录"。放对位置，AI 就能记住你的项目规矩。
放在哪里：项目根目录的 .claude/CLAUDE.md（团队共享）或 ~/.claude/CLAUDE.md（个人全局）。
通用版 — 适合任何项目
markdown
# 项目信息
## 技术栈
- 语言：[填你的语言，如 TypeScript / Python / Go]
- 框架：[填框架名，如 Express / Django / Gin]
- 包管理器：[npm / pnpm / pip / go mod]
- 数据库：[SQLite / PostgreSQL / MongoDB]
## 常用命令
- 启动开发：[你的启动命令]
- 运行测试：[你的测试命令]
- 构建打包：[你的构建命令]
- 代码检查：[你的 lint 命令]
## 编码规范
- 缩进：[2 空格 / 4 空格 / Tab]
- 命名风格：[camelCase / snake_case / PascalCase]
- 错误处理：所有异步操作必须有错误处理
- 注释语言：中文
## 目录结构
- src/ — 源代码
- tests/ — 测试文件
- docs/ — 文档
- scripts/ — 脚本工具
## 注意事项
- [写上你项目里容易踩的坑]
- [写上 AI 操作时需要避开的目录或文件]前端项目版 — React / Vue / Next.js
markdown
# 前端项目信息
## 技术栈
- 框架：Next.js 14（App Router）
- 语言：TypeScript（strict 模式）
- 样式方案：Tailwind CSS
- UI 组件库：shadcn/ui
- 状态管理：Zustand
- 包管理器：pnpm
## 常用命令
- 启动开发服务器：pnpm dev
- 运行测试：pnpm test
- 构建生产版本：pnpm build
- 代码检查：pnpm lint
- 类型检查：pnpm type-check
## 编码规范
- 组件文件：PascalCase（如 UserProfile.tsx）
- 工具函数文件：camelCase（如 formatDate.ts）
- 组件用默认导出，工具函数用命名导出
- CSS 类名用 Tailwind，不写自定义 CSS（除非万不得已）
- 所有 API 请求统一走 src/lib/api.ts
## 目录结构
- src/app/ — 页面路由（Next.js App Router）
- src/components/ — 可复用组件
- src/components/ui/ — shadcn/ui 基础组件（不要手动修改）
- src/lib/ — 工具函数、API 封装、配置
- src/hooks/ — 自定义 React Hooks
- src/types/ — TypeScript 类型定义
- src/stores/ — Zustand 状态管理
- public/ — 静态资源
## 注意事项
- 不要修改 src/components/ui/ 下的 shadcn 组件源码
- 新页面必须在 src/app/ 下创建对应目录和 page.tsx
- 环境变量放在 .env.local，不要硬编码后端项目版 — Node.js / Python / Go
markdown
# 后端项目信息
## 技术栈
- 语言：Python 3.12
- 框架：FastAPI
- ORM：SQLAlchemy 2.0
- 数据库：PostgreSQL 16
- 缓存：Redis
- 包管理器：uv
## 常用命令
- 启动开发服务器：uv run uvicorn app.main:app --reload
- 运行测试：uv run pytest -v
- 运行测试（带覆盖率）：uv run pytest --cov=app --cov-report=term-missing
- 数据库迁移：uv run alembic upgrade head
- 生成迁移文件：uv run alembic revision --autogenerate -m "描述"
- 代码检查：uv run ruff check .
- 代码格式化：uv run ruff format .
## 编码规范
- 命名风格：snake_case（函数和变量）、PascalCase（类）
- 所有函数必须有 type hints
- API 路由统一返回 { code, data, message } 格式
- 业务异常用自定义 HTTPException
- 数据库操作统一走 Repository 模式
## 目录结构
- app/main.py — 应用入口
- app/api/ — 路由定义
- app/models/ — SQLAlchemy 模型
- app/schemas/ — Pydantic 请求/响应模型
- app/services/ — 业务逻辑层
- app/repositories/ — 数据库访问层
- app/core/ — 配置、安全、依赖注入
- tests/ — 测试文件
- alembic/ — 数据库迁移
## 注意事项
- 不要直接在路由层写业务逻辑，统一放 services/
- 数据库连接用依赖注入，不要在函数里直接创建 session
- 敏感配置走环境变量，参考 app/core/config.py
- 修改模型后必须生成 Alembic 迁移文件怎么用：选一个最接近你项目的版本，复制到 .claude/CLAUDE.md，把方括号里的占位符改成你项目的实际信息。5 分钟搞定，之后每次开 Claude Code 都省 5 分钟的重复解释。
二、MCP 服务器配置模板
MCP 配置文件在 ~/.claude.json（用户级别，所有项目共用）或项目目录下的 .claude.json（仅当前项目）。
下面是三个最常用的 MCP 服务配置，可以按需组合。
GitHub MCP — 管理仓库、Issue、PR
json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-github"],
"env": {
"GITHUB_TOKEN": "ghp_你的PersonalAccessToken"
}
}
}
}安装前提：需要先在 GitHub Settings > Developer settings > Personal access tokens 生成一个 Token，勾选 repo 权限。
命令行安装（更简单）：
bash
claude mcp add github -s user -- -y @anthropic-ai/mcp-github文件系统 MCP — 跨目录操作文件
json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@anthropic-ai/mcp-filesystem",
"/Users/你的用户名/Documents",
"/Users/你的用户名/Downloads",
"/Users/你的用户名/Desktop"
]
}
}
}注意：args 最后面的路径是你允许 AI 访问的目录。想让它操作哪些目录就加哪些，不加的目录 AI 碰不到。这是安全机制。
命令行安装：
bash
claude mcp add filesystem -s user -- -y @anthropic-ai/mcp-filesystem ~/Documents ~/Downloads ~/Desktop数据库 MCP — 直接查数据
以 PostgreSQL 为例：
json
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-postgres"],
"env": {
"DATABASE_URL": "postgresql://用户名:密码@localhost:5432/数据库名"
}
}
}
}安全提示：数据库密码不要直接写在配置文件里提交到 Git。在本地开发环境用没问题，但如果 .claude.json 要提交到仓库，务必把它加入 .gitignore。
组合配置 — 三个一起装
实际使用时你可以把多个 MCP 写在同一个 ~/.claude.json 里：
json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-github"],
"env": {
"GITHUB_TOKEN": "ghp_你的Token"
}
},
"filesystem": {
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-filesystem", "/Users/你的用户名/Documents"]
},
"puppeteer": {
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-puppeteer"]
}
}
}怎么用：复制到 ~/.claude.json，把 Token 和路径改成你自己的，重启 Claude Code 就生效。
三、Hook 脚本模板
Hook 配置在 ~/.claude/settings.json 中。下面三个是最实用的组合。
自动格式化 — 写完文件自动美化代码
json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"command": "prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
}
]
}
}用 Python 项目的话，把 prettier 换成 ruff：
json
{
"command": "ruff format \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
}用 Go 项目的话：
json
{
"command": "gofmt -w \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
}核心思路：2>/dev/null || true 确保即使格式化工具报错也不会打断 AI 的工作流。
提交前检查 — 拦截硬编码密钥
json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit",
"command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -qiE '(api_key|secret_key|password|token)\\s*[:=]\\s*[\"'\\'''][A-Za-z0-9+/=]{16,}' && echo 'BLOCKED: 检测到疑似硬编码密钥' && exit 1 || exit 0"
}
]
}
}效果：如果 AI 试图写入包含硬编码密钥的代码，会被直接拦截。AI 会自动修正为使用环境变量的写法。
桌面通知 — 任务完成提醒
macOS 版：
json
{
"hooks": {
"Stop": [
{
"matcher": "",
"command": "osascript -e 'display notification \"任务已完成，来看看结果吧\" with title \"Claude Code\" sound name \"Glass\"'"
}
]
}
}Linux 版：
json
{
"hooks": {
"Stop": [
{
"matcher": "",
"command": "notify-send 'Claude Code' '任务已完成，来看看结果吧'"
}
]
}
}三合一配置 — 复制即用
把三个 Hook 组合到一起，直接放入 ~/.claude/settings.json：
json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit",
"command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -qiE '(api_key|secret_key|password|token)\\s*[:=]\\s*[\"'\\'''][A-Za-z0-9+/=]{16,}' && echo 'BLOCKED: 检测到疑似硬编码密钥' && exit 1 || exit 0"
}
],
"PostToolUse": [
{
"matcher": "Write|Edit",
"command": "prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
}
],
"Stop": [
{
"matcher": "",
"command": "osascript -e 'display notification \"任务已完成\" with title \"Claude Code\" sound name \"Glass\"'"
}
]
}
}怎么用：复制到 ~/.claude/settings.json，根据你的技术栈把 prettier 换成对应的格式化工具。如果是 Linux 系统，把 osascript 那行换成 notify-send。
四、自定义 Agent 定义模板
自定义 Agent（子智能体）放在 ~/.claude/agents/ 目录下，一个 .md 文件就是一个 Agent。Claude Code 需要时会自动调用。
通用模板 — 照这个格式写就行
markdown
# [Agent 名称]
## Role
你是一个专注于 [领域] 的 [角色描述]。
## When to Use
- [触发场景 1]
- [触发场景 2]
## Checklist
每次执行必须检查以下项目：
- [ ] [检查项 1]
- [ ] [检查项 2]
- [ ] [检查项 3]
## Output Format
[描述输出的格式和分级标准]安全审查 Agent — security-reviewer.md
markdown
# Security Reviewer
## Role
你是一个专注于安全审查的代码审查员。你的职责是发现代码中的安全漏洞，而不是评判代码风格。
## Checklist
每次审查必须逐项检查：
- [ ] 无硬编码的密钥、密码、Token
- [ ] 所有用户输入已做验证和转义
- [ ] SQL 查询使用参数化方式，无拼接
- [ ] API 端点有认证和授权检查
- [ ] 敏感数据（密码、Token）不出现在日志中
- [ ] 错误信息不泄露内部实现细节
- [ ] 文件上传有类型和大小限制
- [ ] CORS 配置合理，未使用 * 通配符
## Output Format
按严重程度分级报告：
- CRITICAL: 必须立即修复，存在被攻击的直接风险
- HIGH: 强烈建议修复，存在潜在安全隐患
- MEDIUM: 建议改进，可降低攻击面
- LOW: 最佳实践建议TDD 引导 Agent — tdd-guide.md
markdown
# TDD Guide
## Role
你是一个严格遵循测试驱动开发的教练。你的原则是：先写测试，再写实现，最后重构。
## Workflow
1. 根据需求拆分出最小可测试单元
2. 为每个单元编写失败的测试用例（RED）
3. 编写最少代码让测试通过（GREEN）
4. 重构代码保持整洁（REFACTOR）
5. 检查测试覆盖率是否达到 80%
## Rules
- 永远不要跳过写测试直接写实现
- 每次只关注一个测试用例
- 测试命名要描述行为，不要描述实现
- Mock 外部依赖，不 Mock 被测模块的内部逻辑
## Output Format
每个步骤输出：
1. 要测试的行为描述
2. 测试代码
3. 实现代码
4. 重构说明（如有）代码审查 Agent — code-reviewer.md
markdown
# Code Reviewer
## Role
你是一个经验丰富的高级工程师，负责对代码改动进行全面审查。
## Review Dimensions
1. 逻辑正确性：代码是否完整实现了需求
2. 边界情况：是否处理了空值、异常输入、并发场景
3. 性能：是否有 N+1 查询、不必要的循环、内存泄漏风险
4. 可读性：命名是否清晰、结构是否合理、注释是否充分
5. 一致性：是否与项目现有代码风格保持统一
## Output Format
- CRITICAL: 必须修复，存在 Bug 或数据丢失风险
- HIGH: 强烈建议修复
- MEDIUM: 建议改进
- LOW: 可以优化但不紧急
- PASSED: 检查通过的项目（也要列出来，让人放心）怎么用：在 ~/.claude/agents/ 目录下创建对应的 .md 文件。比如安全审查 Agent 就保存为 ~/.claude/agents/security-reviewer.md。创建完不需要重启，Claude Code 会在需要时自动发现和调用。
创建目录的命令：
bash
mkdir -p ~/.claude/agents配置文件位置速查表
怕搞混？这张表帮你一秒定位每个配置文件该放在哪：
| 配置类型 | 文件路径 | 作用范围 |
|---|---|---|
| 项目记忆 | 项目根/.claude/CLAUDE.md | 当前项目，可提交 Git |
| 个人记忆 | ~/.claude/CLAUDE.md | 你的所有项目 |
| MCP 配置（用户级） | ~/.claude.json | 你的所有项目 |
| MCP 配置（项目级） | 项目根/.claude.json | 当前项目 |
| Hook 配置 | ~/.claude/settings.json | 你的所有项目 |
| 自定义 Agent | ~/.claude/agents/xxx.md | 你的所有项目 |
小结
- 本篇提供了四大类配置模板：CLAUDE.md 记忆文件（通用/前端/后端三个版本）、MCP 服务器配置（GitHub/文件系统/数据库）、Hook 脚本（自动格式化/密钥检查/桌面通知）、自定义 Agent 定义（安全审查/TDD/代码审查）。
- 所有模板都是复制即用的，改几个占位符就能匹配你的项目。
- 记住关键路径：记忆放
.claude/CLAUDE.md，MCP 放.claude.json，Hook 放settings.json，Agent 放~/.claude/agents/。 - 建议现在就花 10 分钟，把这篇里最适合你的模板复制过去配上。配一次，受益整个项目周期。