← 返回 Blog
UseAIAPIAI API2min

别再碎片化搜教程了——Claude Code 个人开发者一站式配置清单（含.claude/目录模板）

很多 Claude Code 的入门教程都止步于两步：安装软件、编写一个 CLAUDE.md 文件，然后就告诉你可以开始使用了。但实际经验告诉我们，仅仅依靠这两步，大概率无法应对真实项目中的复杂任务，很快就会遇到各种摩擦和问题。

ClaudeClaude Code从零配置 Claude Code

从零配置 Claude Code：打造有纪律的 AI 开发伙伴

很多 Claude Code 的入门教程都止步于两步：安装软件、编写一个 CLAUDE.md 文件，然后就告诉你可以开始使用了。但实际经验告诉我们，仅仅依靠这两步，大概率无法应对真实项目中的复杂任务，很快就会遇到各种摩擦和问题。

今天我们不谈 "把所有功能都装上"，而是帮你养成一种科学的配置习惯：每一个文件的存在都必须有明确的理由，每一行配置都必须能产生实际的效果。

一、认识.claude/ 目录：Claude Code 的 "命令总线"

从 2025 到 2026 年的现行体系来看，Claude Code 的配置是围绕项目根目录的.claude/和全局的~/.claude/组织的，而不是散落在系统的各个角落：

  • ~/.claude/：个人全局配置，适用于你所有的项目
  • 项目里的.claude/：团队级配置，提交到 Git 仓库即可实现团队共享
  • 少数文件也可以放在项目根目录（如 CLAUDE.md、.mcp.json、.worktreeinclude），方便直接查看

以下是已投产项目中最常见的目录结构（已修正原文中因格式问题导致的错误目录名）：

plaintext

your-project/
├── CLAUDE.md              # ✅ 项目主"说明书"（提交到Git）
├── CLAUDE.local.md        # 🔒 个人私人偏好（添加到.gitignore，不提交）
├── .mcp.json              # MCP外部工具注册（按需使用）
└── .claude/
    ├── settings.json      # ✅ 权限、钩子、环境变量、模型默认配置（提交到Git）
    ├── settings.local.json # 🔒 本地覆盖配置（自动被Git忽略）
    ├── rules/             # 按主题拆分的可加载规则（可选）
    │   ├── code-style.md
    │   ├── security.md
    │   └── frontend/react.md
    ├── hooks/             # 脚本文件：PreToolUse防火墙、PostEdit质量门（可选）
    ├── skills/            # 可复用工作流、斜杠命令（可选）
    └── agents/            # 专用子代理定义（可选）

需要特别注意的是，原文中提到的.code/目录是错误的，正确的目录名是.claude/（一个点加 claude），钩子脚本通常放在.claude/hooks/目录下，而不是所谓的books/目录。

settings.json文件管理着 Claude Code 的行为边界：哪些文件可以读取、哪些命令可以执行、按照什么规则行事。你不需要在第一天就填满所有文件，先搞清楚每个文件 "为什么存在"，比盲目堆砌文件重要得多。

二、CLAUDE.md：不是想到什么就写什么

最常见的新手错误是把 README 中的技术栈介绍，甚至一整篇技术笔记直接复制粘贴到 CLAUDE.md 中。

官方和社区已经形成了一致的共识：CLAUDE.md 文件最好控制在约 200 行以内。太长的文件不会 "不加载"，但会稀释有效信息，导致 Claude 的遵循度反而下降。

编写 CLAUDE.md 有一个非常实用的判断标准：

如果把这一行删掉，Claude 会不会做出错误的行为？

—— 如果不会，就删掉。

因此，CLAUDE.md 应该只包含那些 Claude 无法自行猜测的内容：

表格

✅ 应该写入的内容❌ 不应该写入的内容
团队约定的 Bash 命令固定用法（如必须使用 pnpm，禁止 npm install）编程语言本身的标准语法（模型已经掌握）
与默认风格不一致的编码约定（命名规则、导出方式、目录边界）一周内就会过期的版本号和临时开关
架构决策和环境特殊配置（为什么用 A 不用 B、哪类改动容易出问题）详细的 API 文档（这是专门文档的职责）

以下是一个有效的示例：

markdown

## 包管理
- 只能使用pnpm作为包管理器，禁止直接运行npm install
- 锁文件pnpm-lock.yaml必须提交到Git仓库

CLAUDE.md 还支持引用机制，可以把 "只在特定场景才需要" 的内容拆分出去，例如只在处理 React 组件目录时才加载前端规则，确保上下文窗口始终保持干净。

三、settings.json：行为边界，不是装饰品

如果说 CLAUDE.md 是给 Claude"装脑子"，那么 settings.json 就是给 Claude"戴上手套和手铐"，明确规定它能做什么、不能做什么。

1. 养成使用规划模式的习惯

在开始任何复杂任务之前，使用Shift+Tab切换到规划模式（Plan Mode），让 Claude 先输出详细的实施方案，再开始执行。规划的成本很低，但返工的成本很高。

2. 权限配置：硬规则的底线

settings.json 中的权限规则评估顺序非常关键：deny（拒绝）→ ask（询问）→ allow（允许），第一个匹配的规则就会生效，因此deny规则具有最高优先级。

以下是一个最小可用的项目级权限配置示例：

json

{
  "permissions": {
    "allow": [
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(pnpm:*)",
      "Bash(npm test:*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force:*)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

配置要点：

  • Bash(...)规则是前缀匹配，不是正则匹配
  • Read(./.env)这类拒绝规则还能从 "文件发现和读取" 层面直接挡住敏感文件

3. 钩子系统：把 "建议" 升级为 "确定性护栏"

官方钩子体系的核心思想是：CLAUDE.md 是建议，可能会被遗忘；而钩子是执行层的强制规则，不满足条件就会被拦截或报错。

常见的钩子配置结构是在 settings.json 中声明事件和脚本路径，脚本文件放在.claude/hooks/目录下：

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/pre-bash-firewall.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/post-edit-quality.sh" }
        ]
      }
    ]
  }
}

钩子脚本通过标准输入接收包含工具名称、工具输入等信息的 JSON 数据，然后通过退出码来传达指令：

表格

退出码含义
0放行，执行成功
2阻断，标准错误输出的内容会被返回给 Claude 作为反馈
其他非阻断错误，通常会被记录和提示，但动作继续执行

典型的pre-bash-firewall.sh脚本逻辑是：读取标准输入→解析命令→命中危险模式就将原因输出到标准错误并以退出码 2 终止，否则以退出码 0 放行。

特别提醒：不要忘记给脚本授予执行权限（chmod +x .claude/hooks/*.sh），否则会出现 "钩子配置了但无法运行" 的隐蔽问题。

四、三层上下文：用对层级才是高手

Claude Code 的上下文加载机制容易被误解为 "合并覆盖"，但更准确的说法是多层同时生效，且各有不同的加载时机：

  1. ~/.claude/CLAUDE.md：个人全局偏好，优先级最低，但在所有项目中都生效
  2. 项目根目录的CLAUDE.md（或.claude/CLAUDE.md）：项目通用规范，提交到 Git 实现团队共享
  3. CLAUDE.local.md：个人对当前项目的私人偏好，不提交到 Git

在 monorepo（多包仓库）场景下，还有一个非常重要的细节：子目录中的 CLAUDE.md 只有在 Claude 读取或进入该目录范围时才会生效，并不是 "把子包规则无脑塞进根目录一起加载"。

因此，更好的实践是：

  • 根目录只保留全局约定和最常用的构建、测试、代码检查命令
  • 领域相关的规则放到.claude/rules/目录中，并使用路径匹配机制让它只在处理相关文件或目录时才加载，避免上下文窗口被 "永远在线但无关的规则" 占满

结语：让 AI 成为可靠的开发伙伴

配置 Claude Code 的本质从来不是 "堆砌功能"，而是把你脑子里那些不需要每次都解释的规矩，外化成文件系统中的规则：

  • CLAUDE.md = "你希望它永远记得的规范"
  • settings.json 和权限配置 = "它绝对不能越过的红线"
  • 钩子系统 = "你不相信它的记忆，所以用脚本兜底的质量门"

当你下次运行复杂任务时，Claude 不再重蹈你曾经踩过的坑 —— 那才是这套配置真正生效的那一刻。

对于需要大规模使用 AI 大模型的开发者和企业来说，UseAIAPI提供了一站式的接入解决方案。平台支持包括 Claude、Gemini、ChatGPT、DeepSeek 在内的全球主流 AI 大模型，提供稳定可靠的企业级定制化服务，让用户无需复杂配置即可直接接入使用。在价格方面，平台推出了极具竞争力的优惠政策，最低可享官方价格 5 折，大幅降低了高强度内容生成和开发过程中的成本压力，让更多开发者和企业能够轻松享受到先进 AI 技术带来的效率提升。