Claude code 系列（三）：Claude Code 全链路配置与 AI 驱动开发
很多开发者刚上手 Claude Code（或其他基于 Claude 的 AI 编程工具）时，都会遇到一个痛点：AI 总是记不住我的项目规范，每次都要重新解释一遍。
其实，这并不是 AI 变笨了，而是你没有建立正确的配置与上下文体系。一套成熟的 Claude Code 项目配置，本质上是给 AI 建立一套“长期记忆”和“行为准则”。
我们先来看一张完整的全景树状图。
一、 核心配置全景图
在终端中，配置主要分为两大地盘：一个是属于你电脑的“全局层”，另一个是属于具体代码库的“项目层”。
一个完整的 Claude Code 项目配置结构：
# 📁 你的电脑主目录 (Home Directory) ~/.claude/ 👉 【全局层】AI 的系统设置 ├── config.json # 全局参数：默认模型、终端行为、自动确认权限 ├── auth.json # 你的登录凭证 (切勿泄露) └── mcp.json # 全局扩展：跨项目的通用工具 (如接通本地 SQLite)# 📁 你的代码仓库 (Project Directory) /my-awesome-project/ 👉 【项目层】AI 的业务说明书 ├── .gitignore # AI 会自动读取它，忽略里面的敏感文件 ├── CLAUDE.md # 核心总纲：项目技术栈、核心指令 (进 Git) ├── CLAUDE.local.md # 个人覆盖：你的本地私有配置 (不进 Git) │ ├── .claude/ ├── settings.json # ⚙️ 项目设置（团队共享） ├── settings.local.json # 👤 个人项目设置（gitignore） ├── CLAUDE.md # 📋 等效于根目录 CLAUDE.md ├── rules/ # 📏 模块化规则文件 │ ├── code-style.md # 代码风格 │ ├── testing.md # 测试规范 │ └── security.md # 安全要求 ├── agents/ # 🤖 自定义子代理 │ ├── code-reviewer.md │ └── debugger.md ├── skills/ # ⚡ 自定义技能 │ └── fix-issue/ │ └── SKILL.md └── worktrees/ # 🌳 Git Worktree 目录（加入 .gitignore）二、 逐层扒开：每个配置到底干啥的？
我们从外到内，看看这套体系是怎么运作的。
1. 全局层 (~/.claude/)：管好 AI 的“出厂设置”
- 概念： 这里的配置对你电脑上的所有项目都生效。它不管你写的是 Python 还是前端，它只管“AI 怎么和你交互”。
- 痛点场景： 每次让 AI 跑脚本，它都要停下来问你
Allow this command? (y/n)。 - 解决方案 (config.json)：
你可以通过修改配置来调整权限和习惯。
{"theme":"dark", "primaryModel":"claude-3-7-sonnet", // 默认调用的模型 "autoExecute": false, // 是否允许 AI 未经确认直接跑命令 (新手建议 false)"commands":{"allowList":["npm run lint", "git status"] // 白名单：这些命令不用问我，直接跑 }}2. 项目总纲 (CLAUDE.md)：消灭 AI “幻觉”的神器
- 概念： 只要你在项目根目录建了这个文件，Claude 启动时就会强制全文阅读。这是整个团队共享的“开发公约”。
- 痛点场景： 你让 AI 写个组件，它给你用原生 CSS 写了一堆样式，但你们团队其实规定了只能用 Tailwind CSS。
- 如何写好 CLAUDE.md： 不要长篇大论，要指令化和约束化。
CLAUDE.md 优质模板：
# 项目背景 这是一个基于 Next.js 15 的后台管理系统。 核心技术栈 & 规范 UI 框架: Tailwind CSS + Shadcn UI（严禁手写 CSS）。 状态管理: Zustand（不要用 Redux）。 数据获取: 必须在 Server Components 中获取数据，客户端组件只负责交互。 常用终端指令 (当用户要求执行任务时，使用这些命令) 运行开发: npm run dev 代码格式化: npm run format 运行特定测试: npm run test -- <filename> 进阶指引 如果遇到复杂的业务流程，请查阅 .claude/skills/ 目录下的相关文件。 技巧揭秘：最后一句非常关键，它告诉了 AI 去哪里寻找更详细的“外挂大脑”。
3. 本地覆盖 (CLAUDE.local.md)：留给自己的“后门”
概念： 团队的 CLAUDE.md 提交到了 Git，但你本地的数据库密码或者特定的测试端口不想公开，怎么办？写在这里。
机制： AI 读取时，如果 local 和主文档冲突，以 local 为准。记住在 .gitignore 中忽略它。
三、 高阶实战：让 AI 掌握特定 Skills (技能包)
初级用户只用 CLAUDE.md，而高级用户会建立 .claude/skills/ 目录。
为什么要分出 Skills 目录？
因为 CLAUDE.md 有长度限制（Context 也是要钱的/消耗算力的），把所有细节都塞进去会导致 AI 抓不住重点。通过分化成独立的 Markdown 文件，AI 可以在需要时按需读取。
场景演示：教 AI “如何写测试”
假设你对单元测试有严格要求。你可以在 .claude/skills/write-unit-test.md 中写下 SOP：
# 技能说明：编写 React 单元测试 触发条件：当用户要求“编写测试”、“补充测试用例”时。 ## 执行步骤：1. **定位位置**：在原文件同级目录下创建 `__tests__` 文件夹，文件命名为 `[name].test.tsx`。 2. **基础依赖**：必须引入 `@testing-library/react` 和 `vitest`。 3. **结构要求**： - 必须包含 1 个快照测试 (Snapshot)。 - 必须包含至少 2 个异常边界测试。 4. **验证**：编写完成后，自动在终端运行 `npx vitest run [当前测试文件路径]`，如果报错则自动修复。 结果： 下次你只要对 Claude 说一句：“帮我给 Header 组件加个测试”，它就会精准执行这 4 步，一气呵成。
四、 运行机制：Claude 是如何读取配置的？（优先级说明）
在博客里一定要讲清楚“优先级（Precedence）”，因为排错通常都在这里。当指令发生冲突时，Claude 听谁的？
最高优先级： 你当前输入的 Prompt。（你说“这次用 CSS 写”，它就会忽略所有规范听你的）。
第二优先级： CLAUDE.local.md。（你的本地私有环境）。
第三优先级： .claude/rules/ & .claude/skills/。（具体任务的强制规定）。
第四优先级： CLAUDE.md。（项目的全局兜底规范）。
最低优先级： ~/.claude/config.json。（工具的底层偏好）。
五、 给开发者的避坑总结
不要把机密写进 CLAUDE.md：因为它是要进 Git 仓库的，Token 和 Key 请放在 CLAUDE.local.md 或系统的环境变量里。
善用 .gitignore：Claude 会聪明地读取它。如果不想让 AI 扫描你本地巨大的 Log 文件夹，确保它在 .gitignore 里。
渐进式添加（从简入繁）：新手一开始只需要建一个 CLAUDE.md。当你发现 AI 第二次犯同一个错误（比如总是拼错某个特定的内部 API）时，再把它加进 .claude/rules/ 里。
推荐关注
笔者是AI行业算法资深从业者，日常分享AI算法和技术实践、趋势，干货多多，欢迎关注 wechat 公众号 Jae.Log
