很多开发者装好Claude Code后的第一件事，就是丢一段需求进去看看效果。结果往往是：简单的能跑，复杂一点的就开始"自由发挥"——代码风格不统一，文件放错位置，甚至数据库表名都是编的。
原因很简单：AI不了解你的项目。就像一个能力很强但刚入职的同事，不了解项目规范，写出来的代码也很难直接用。
AI编程的第一课，不是急着写代码，而是先教会AI认识你的项目。本文通过一个完整的实战案例，演示从项目配置到功能开发的标准流程。
一、项目结构与配置
一个典型的项目结构
在开始任何AI编程之前，先来看一下一个配置好的项目目录长什么样：
my-project/
├── .claude/ # Claude Code 配置目录
│ ├── agents/ # 自定义Agent定义
│ ├── commands/ # 自定义斜杠命令
│ ├── rules/ # 自定义规则
│ ├── skills/ # 自定义技能
│ └── settings.json # 权限、环境变量等配置
├── backend/ # 后端工程
│ └── my-project-code/ # Gradle多模块项目
│ ├── my-project-common/ # 公共模块
│ ├── my-project-service/ # 业务服务模块
│ ├── build.gradle
│ ├── CLAUDE.md # 后端模块级配置
│ └── settings.gradle
├── frontend/ # 前端工程
├── docs/ # 项目文档
├── openspec/ # OpenSpec框架生成文件（后续文章详解）
├── rules/ # 项目规则定义
├── CLAUDE.md # 项目根级配置（最重要）
└── README.md
这个结构中有几个关键点值得注意。
CLAUDE.md：AI的项目说明书
CLAUDE.md是整个AI编程配置中最核心的文件。你可以把它理解为写给AI的项目说明书——它告诉AI这个项目用了什么技术栈、代码该怎么写、有哪些需要注意的坑。
Claude Code会按层级加载CLAUDE.md文件：
graph TD
A["~/.claude/CLAUDE.md<br/>全局配置"] --> B["项目根目录/CLAUDE.md<br/>项目级配置"]
B --> C["frontend/CLAUDE.md<br/>前端模块配置"]
B --> D["backend/CLAUDE.md<br/>后端模块配置"]
style A fill:#1a4040,stroke:#1A9090,color:#fff
style B fill:#1a5050,stroke:#1A9090,color:#fff
style C fill:#1a6060,stroke:#1A9090,color:#fff
style D fill:#1a6060,stroke:#1A9090,color:#fff
这种层级结构的好处是：根目录的CLAUDE.md定义全局规则，子目录的CLAUDE.md定义局部规则。当AI在某个子目录下工作时，会同时读取从根目录到当前目录路径上的所有CLAUDE.md，自动合并成完整的上下文。
不要急着引入"最佳实践"
你可能已经注意到项目结构中有 agents、commands、rules、skills 等目录。
网上有很多关于Claude Code的配置模板，但我的建议是：先不要急着填充这些目录。
原因很简单：这些高级配置是为了解决特定场景下的问题而设计的。如果你还没遇到那些问题，提前引入只会增加理解负担，甚至可能和你的项目产生冲突。
先从写好CLAUDE.md开始。等你在实际开发中发现了具体的痛点，再有针对性地引入对应的工具。这样每一个配置都是"因为需要才加的"，而不是"别人用了所以我也加"。
CLAUDE.md的生成和编写要点
最快的起步方式是在项目根目录运行 /init 命令，Claude Code会自动分析你的项目结构，生成一份初始的CLAUDE.md。但自动生成的内容往往比较泛，需要你根据实际情况优化。
以一个Java Spring Boot + Vue的前后端分离项目为例，一份好的CLAUDE.md大致包含以下内容：
# 项目名称
## 技术栈
- 前端：Vue 3 + TypeScript + Element Plus
- 后端：Spring Boot 3 + MyBatis Plus + Gradle
- 数据库：MySQL 8.0
## 项目结构
- backend/my-project-code/：后端Gradle多模块工程
- my-project-common：公共模块（实体类、工具类、通用配置）
- my-project-service：业务服务模块（Controller、Service、Mapper）
- frontend/：前端Vue工程
## 常用命令
- 后端构建：`cd backend/my-project-code && ./gradlew build`
- 后端启动：`./gradlew bootRun`
- 运行测试：`./gradlew test`
- 前端启动：`cd frontend && npm run dev`
## 代码规范
- Controller层不写业务逻辑，全部下沉到Service层
- Service接口定义在 api 包下，实现在 impl 包下
- 数据库表名使用下划线命名，如 customer_info
- Mapper接口继承BaseMapper，复杂查询使用Wrapper方式
- 前端组件使用 Composition API + <script setup> 语法
## 注意事项
- 数据库连接配置在 application-dev.yml，不要修改生产配置
- 前端路由配置在 src/router/index.ts，新增页面需要手动注册
- 新增依赖加在对应子模块的 build.gradle 中，不要加在根 build.gradle
编写CLAUDE.md时有一个判断标准：对于每一行内容，问自己"如果删掉这行，AI会不会犯错？" 如果答案是"不会"，那就删掉它。CLAUDE.md应该精练有力，而不是事无巨细的文档。
关于项目结构中的openspec目录，这里先提一句：它是OpenSpec开发框架的生成文件目录，用于存放结构化的需求规格说明，是AI编程中一个很有用的实践。内容较多，我们在后续文章中专门讨论。
二、实战——为"客户查询"增加查询条件
配置做好了，该动手写代码了。我们以一个真实场景为例：在现有的"客户查询"功能菜单中，新增一个查询条件——客户年龄。
这是一个很小的需求，但麻雀虽小五脏俱全，它涵盖了AI编程的完整流程。
1. 了解现有实现
拿到需求后，不要直接告诉AI"给客户查询加一个年龄条件"。正确的做法是先让AI了解现有代码是怎么实现的。
这里要用到Claude Code的Plan Mode。Plan Mode是一个只读模式，在这个模式下，AI只能读取文件、搜索代码、提出问题，但不能修改任何文件。它的作用就是强制AI先"看懂"再"动手"。
激活Plan Mode的方式很简单：在输入框中按两次 Shift+Tab，或者使用 /plan 命令。
进入Plan Mode后，你可以这样提问：
请分析"客户查询"功能的现有实现，包括：
1. 前端查询表单在哪个文件
2. 查询接口调用链路
3. 后端SQL查询逻辑
4. 现有的查询条件有哪些
AI会开始阅读相关文件，然后给出一份分析报告。这时候你需要做的是仔细审查AI的分析结果：
- 它找到的文件对不对？
- 调用链路有没有遗漏？
- 对现有查询条件的理解是否准确？
sequenceDiagram
participant 你
participant AI
participant 代码库
你->>AI: 进入Plan Mode<br/>分析客户查询功能
AI->>代码库: 搜索相关文件
AI->>代码库: 读取组件代码
AI->>代码库: 读取API接口
AI->>代码库: 读取后端逻辑
AI->>你: 返回分析报告
你->>你: 审查分析结果<br/>确认是否准确
alt 分析有误
你->>AI: 指出错误，补充信息
AI->>代码库: 重新分析
end
如果发现AI理解有偏差，及时纠正。比如AI可能把一个通用的查询组件误认为是客户查询专用的，或者遗漏了某个中间层的封装。这些纠正不仅帮助当前任务，也为后续优化CLAUDE.md提供了素材。
2. 设计方案
确认AI已经正确理解了现有实现后，接下来提出你的需求：
在客户查询功能中，新增一个查询条件：客户年龄。
请给出设计方案，包括需要修改哪些文件、每个文件的具体改动。
AI会给出一个设计方案。这时候你需要关注几个方面：
风格一致性——AI提议的代码风格是否和现有代码一致？比如现有的查询条件用的是下拉框还是输入框？年龄条件应该是一个范围选择器还是精确值输入？
规范符合性——是否符合项目的编码规范？比如API参数命名是驼峰还是下划线？数据库字段类型选择是否合理？
改动范围——AI是否过度修改了不该动的地方？有时候AI会"顺手"重构一些它认为不太好的代码，这不是当前需求要求的。
flowchart LR
A[AI给出方案] --> B{审查方案}
B -->|风格不一致| C[指出具体问题<br/>要求调整]
B -->|不符合规范| C
B -->|改动范围过大| C
B -->|方案合理| D[确认方案]
C --> A
D --> E[将方案写入.md文件]
classDef default fill:#1a4040,stroke:#1A9090,color:#fff
classDef check fill:#1a5050,stroke:#1A9090,color:#fff
classDef action fill:#0d6666,stroke:#1A9090,color:#fff
class B check
class D,E action
经过交互调整后，确认方案没有问题了，让AI把设计方案写入一个.md文件保存下来。这样做有两个好处：一是留下记录方便后续参考，二是当AI在实现过程中偏离方案时，你可以引导它回到方案上来。
3. 代码实现
方案确定后，退出Plan Mode，让AI根据设计方案实现具体的功能代码：
请按照设计方案，逐步实现客户年龄查询条件的功能。
每修改完一个文件后，说明改动内容。
在实现阶段，有几个实践建议：
逐步实现，不要一次性全做。让AI先改前端表单，确认没问题后再改API调用，再改后端逻辑。这样每一步都可以验证，出了问题也容易定位。
及时验证。每一步改完后运行项目，确认功能正常。不要等全部改完再测试，那样出了问题排查起来很痛苦。
保持关注。AI写代码时可能会做一些你没要求的改动。如果发现AI在"自作主张"，及时叫停并要求它回到方案上来。
4. 总结和调整
功能实现并验证通过后，先别急着收工。这一步才是AI编程的精髓——从实战中反哺配置。
4.1 代码读取索引
回顾整个过程，当你让AI了解"客户查询"功能时，它是怎么找到相关代码的？是通过文件名搜索、关键字匹配，还是你手动告诉它的？
如果AI找得很费劲，说明项目缺少有效的"入口索引"。你可以在CLAUDE.md中补充这类信息：
## 功能模块索引
- 客户管理：前端入口 src/pages/customer/，后端 server/controllers/CustomerController
- 订单管理：前端入口 src/pages/order/，后端 server/controllers/OrderController
- 查询条件组件：统一使用 src/components/SearchForm 封装
这样下次AI遇到类似需求时，能更快地定位到正确的代码位置，减少搜索时间和出错概率。
你也可以在告诉AI需求时，直接提供入口信息：
客户查询功能在 src/pages/customer/CustomerList.vue 中，
请分析这个功能的完整实现链路。
给AI一个明确的起点，比让它大海捞针要高效得多。
4.2 从功能开发中完善配置
在开发过程中，AI暴露出来的问题就是优化配置的线索：
-
如果AI的代码风格和项目不一致——在CLAUDE.md的代码规范部分补充具体规则。比如AI用了Options API但项目用的是Composition API，就加一条明确说明。
-
如果AI引入了不该用的依赖——在CLAUDE.md中注明项目已有的工具库。比如"日期处理使用dayjs，不要引入moment"。
-
如果AI把文件放错了位置——在CLAUDE.md中明确目录结构的组织规则。比如"新增API接口文件放在 src/services/ 对应模块下"。
-
如果AI的SQL写法不符合规范——在子目录的CLAUDE.md中补充数据库相关规范。比如在 server/CLAUDE.md 中注明"查询必须使用MyBatis Plus的Wrapper方式，不要写原生SQL"。
这种"遇到问题就更新配置"的模式，会让你的CLAUDE.md越来越完善，AI在项目中的表现也会越来越好。这就是配置与开发相互驱动的良性循环。
graph LR
A[初始配置] --> B[功能开发]
B --> C[发现问题]
C --> D[更新配置]
D --> B
classDef default fill:#1a4040,stroke:#1A9090,color:#fff
classDef highlight fill:#0d6666,stroke:#1A9090,color:#fff,stroke-width:2px
class D highlight
三、总结
这是一个很简单的示例——给查询页面加一个字段，绝大多数开发者闭着眼睛都能写。但重点不在于这个功能本身，而在于通过这个过程，你掌握了AI编程的基本模式：
- 配置先行：先写好CLAUDE.md，让AI了解你的项目。
- 先看后写：用Plan Mode让AI先理解现有代码，审查分析结果，确认无误后再动手。
- 方案驱动：让AI给出设计方案，经过审查调整后再实现，而不是直接让AI自由发挥。
- 持续迭代：从每次开发中发现配置的不足，及时更新CLAUDE.md，让AI越来越懂你的项目。
AI编程不是"把需求丢给AI然后等结果"，而是你和AI之间的一次协作。你负责把控方向和质量，AI负责执行和加速。配置是这种协作的基础，CLAUDE.md写得越好，协作效率越高。
如果你是第一次尝试AI编程，建议从一个小功能开始，走完这套流程。不要一上来就让AI写复杂系统，先用简单任务磨合，找到适合你和你项目的协作模式。等你的CLAUDE.md经过几轮迭代变得足够完善，AI的表现会超出你的预期。
