这是一篇面向开发者的 Claude Code 项目初始化教程，完整讲清如何从项目根目录启动、用 /init 生成 CLAUDE.md、整理 README 与依赖信息、让 AI 只读分析代码库、验证上下文是否正确，并建立安全的项目规则。
摘要：先让 AI 读懂代码库，再让它改代码
很多人第一次用 Claude Code，习惯直接把需求丢给它：“帮我修这个 bug”“帮我加一个功能”。这类用法在小项目里偶尔能跑通，但在真实代码库里很容易出问题：AI 不知道入口文件在哪里，不清楚测试命令，不知道哪些目录不能动，也不知道项目的命名规范、架构边界和发布流程。结果就是改动范围变大、误读上下文、生成不符合项目习惯的代码。
更稳的做法是先做项目初始化：从正确的项目根目录启动 Claude Code，先让它只读扫描代码库，再用 /init 生成或改进 CLAUDE.md，把构建命令、测试命令、目录说明、禁止事项和协作规则写清楚。初始化不是形式主义，而是给 AI 建立项目地图，之后每一次修 bug、重构、补测试都会更可控。
如果你还没完成安装，可以先看站内 Claude Code Mac 安装教程：终端、权限、项目目录完整设置 或 Claude Code Windows 安装教程：WSL、Git Bash、Node 环境完整配置。如果想在编辑器里配合使用，可以继续看 Claude Code VS Code 插件教程：让 AI 直接在编辑器里改代码。
为什么项目初始化这么重要
AI 不会天然理解你的项目约定
Claude Code 可以读取代码、分析结构、运行命令，但它不会自动知道你团队的所有隐含规则。例如：哪些模块禁止改动、测试必须怎么跑、接口错误格式是什么、提交前要不要更新文档、配置文件是否能修改。这些内容如果不写出来，AI 只能根据文件内容猜。
初始化能减少重复解释
如果你每次都要重复说“这个项目用 pnpm”“不要改 .env”“API 在 src/server/routes 里”“改完要跑 npm test”，说明这些信息应该进入项目规则。Claude Code 官方文档也把 CLAUDE.md 定位为项目持久说明文件，用来保存编码标准、工作流、项目架构和常用命令。
初始化能降低误改风险
没有初始化时，AI 可能从错误目录开始阅读，可能把生成文件当源码，可能忽略已有测试，也可能修改你不希望动的配置。初始化流程能让它先理解边界，再进入修改阶段。
第一步：从正确的项目根目录启动
什么是项目根目录
项目根目录通常是包含 Git 仓库、README、依赖文件和源码目录的位置。常见标志包括：
.git或能执行git statusREADME.mdpackage.json、pyproject.toml、go.mod、pom.xml等依赖文件src、app、tests、docs等目录
不要从桌面、下载目录、父级大文件夹或整个工作盘启动 Claude Code。目录太大不仅浪费上下文，还会把无关文件带入分析。
启动前先做三项检查
进入你认为的项目目录后，先执行：
pwd
git status
lspwd 用来确认当前路径，git status 用来确认仓库状态，ls 用来确认根目录文件。如果 git status 提示不是 Git 仓库，就要确认是否进错了目录。
工作区有未提交改动怎么办
如果 git status 显示已有改动，先确认这些改动是谁做的、是否要保留。不要在一堆未知改动上直接让 AI 大范围修改。更稳的做法是先保存当前状态，或者把任务限定到明确文件。
第二步：先让 Claude Code 只读盘点项目
第一次不要直接要求修改文件
刚进入一个项目时，第一条任务建议只读分析：
请先只读分析当前代码库，不要修改任何文件，也不要运行会改变文件的命令。
请输出：
1. 项目类型和主要技术栈
2. 入口文件和核心目录
3. 本地启动命令
4. 测试命令和构建命令
5. 配置文件和敏感文件位置
6. 你建议写入 CLAUDE.md 的项目规则这条提示的目的不是让 AI 给你最终答案，而是检查它是否能正确理解项目结构。如果它连项目类型、入口文件、测试命令都说不清楚，就不应该进入修改阶段。
让它解释依据
为了避免 AI 凭经验猜测，可以追加要求：
请在每个结论后说明你是根据哪些文件判断的，例如 README.md、package.json、src 目录或测试配置。这样你能快速判断它是真的读了项目，还是把通用模板套进来。
建立项目地图
让 Claude Code 输出一份项目地图：
请生成一份项目地图，按目录列出每个主要模块的职责、关键文件、常见修改入口和不要随意改动的区域。项目地图适合后续写入 CLAUDE.md 或团队文档。对大型代码库来说，它比“帮我看一下项目”这种笼统请求更实用。
第三步：使用 /init 生成 CLAUDE.md
/init 的作用
Claude Code 官方文档说明，运行 /init 可以让 Claude 分析代码库，并生成起始 CLAUDE.md，其中通常包含构建命令、测试说明和它发现的项目约定。如果项目已经存在 CLAUDE.md，/init 会建议改进，而不是直接覆盖。
在 Claude Code 会话中执行：
/initCLAUDE.md 应该放在哪里
项目级说明通常放在项目根目录的 CLAUDE.md，或 .claude/CLAUDE.md。团队共享规则建议提交到版本控制；个人偏好、私有路径、测试账号和本地端口等内容不要写进共享文件，可以放到 CLAUDE.local.md 并加入 .gitignore。
不要把 CLAUDE.md 写成小说
官方文档建议 CLAUDE.md 保持具体、简洁、结构化。它会进入上下文，过长会占用上下文窗口，也会降低规则命中率。优先写可验证规则，例如“运行 npm test”比“确保质量”更有用。
CLAUDE.md 推荐模板
基础模板
# Project Rules
## Project Overview
- 这是一个 Node.js Web 项目。
- 前端入口在 src/app。
- API 代码在 src/server。
- 测试目录在 tests。
## Commands
- 安装依赖：npm install
- 本地开发：npm run dev
- 单元测试：npm test
- 代码检查：npm run lint
- 构建：npm run build
## Coding Rules
- 优先复用现有工具函数，不要重复造轮子。
- 保持当前代码风格，不做无关重构。
- 修改公共 API 前先说明兼容性影响。
## Safety Rules
- 不要读取、打印或提交 .env、密钥、账号密码。
- 不要执行删除数据库、清空线上数据或直接发布生产环境的命令。
- 大范围重构前必须先给计划，确认后再修改。
## Verification
- 修改后优先运行相关测试。
- 提交前 review git diff，检查误改配置、遗漏测试和敏感信息。根据项目类型补充规则
不同项目要补不同规则。前端项目可以写组件目录、样式规范、路由约定；后端项目可以写鉴权、中间件、数据库迁移规则；WordPress 项目可以写不要修改主题核心文件、不要直接发布线上文章、密钥必须从环境变量读取等。
引用已有文档
官方文档支持在 CLAUDE.md 中用 @path/to/file 导入其他文件。例如：
See @README.md for project overview.
See @package.json for npm scripts.
See @docs/deployment.md for deployment workflow.导入能减少重复维护，但不要把大量无关文档都塞进去。每个导入都应该有明确用途。
第四步：把规则拆到 .claude/rules
什么时候需要拆分
如果项目很大，单个 CLAUDE.md 容易变得臃肿。官方文档建议可以使用 .claude/rules/ 管理更细的规则文件，例如 testing.md、api-design.md、frontend-style.md。
路径级规则示例
对于只影响某类文件的规则，可以使用路径匹配，让规则只在相关文件被处理时生效：
---
paths:
- "src/api/**/*.ts"
---
# API Rules
- 所有接口必须做输入校验。
- 错误响应使用统一格式。
- 修改鉴权逻辑必须补充测试。大型项目的实践建议
共享且稳定的项目规则放进 CLAUDE.md；模块级规则放进 .claude/rules/；个人偏好放进 CLAUDE.local.md；真正需要硬性拦截的高风险操作，不要只靠文字说明，应结合权限设置或工具钩子。
第五步：验证 AI 是否真的读懂了项目
用问题反向检查上下文
初始化后，不要马上进入开发。先让 Claude Code 回答几类验证问题：
请根据当前项目文件回答：
1. 如果我要修改登录逻辑，应该先看哪些文件？
2. 如果我要新增一个 API，应该参考哪个已有接口？
3. 当前项目的测试命令是什么？
4. 哪些文件或目录你不应该随意修改？
5. CLAUDE.md 中哪些规则对本次任务最相关？如果回答明显不对，就要让它重新阅读关键文件，或修正 CLAUDE.md。
让它输出风险清单
在第一次真实修改前，让 Claude Code 输出风险清单：
请在修改前列出本任务的风险点，包括可能影响的模块、需要补充的测试、不能触碰的文件，以及验证失败时的回滚方式。让它先写计划再改代码
初始化完成后，推荐的修改流程是：
- 先只读分析任务相关文件
- 输出修改计划
- 确认后再改代码
- 运行验证命令
- 提交前 review diff
初始化后的标准工作流
只读分析
每次新任务先让 Claude 只读分析相关文件。示例：
请只读分析和这个 bug 相关的文件，不要修改。请说明调用链、可能原因、需要验证的假设。计划审查
要求它先给计划：
请先给出修改计划，列出要改的文件、每个文件的改动点、验证命令和风险。等我确认后再修改。小步修改
一次只处理一个清晰任务。不要把重构、修 bug、加功能、升级依赖和改 UI 混成一个请求。任务越清楚，Claude Code 越容易做出可审查的 diff。
验证与复盘
修改后运行测试、lint 或构建。提交前让 Claude review diff：
请 review 当前 git diff，重点检查 bug、遗漏测试、误改配置、敏感信息泄露和无关重构。如果你想看更多实际场景，可以阅读站内 Claude Code 最适合做什么？10 个真实开发场景完整演示。
常见错误
错误一：从错误目录启动
如果你从父目录、下载目录或桌面启动，Claude Code 可能看到大量无关文件，反而抓不住项目重点。始终从项目根目录启动。
错误二：CLAUDE.md 写得太空
“写高质量代码”“保持简洁”“注意安全”这类规则太抽象。改成可执行规则：“修改后运行 npm test”“不要读取 .env”“API 错误使用 errorResponse()”。
错误三：把私人配置提交进仓库
本地端口、测试账号、个人 token、临时路径不要放进共享 CLAUDE.md。可以写进 CLAUDE.local.md，并加入 .gitignore。
错误四：初始化后不验证
生成 CLAUDE.md 不代表 AI 已经理解正确。一定要用项目问题反向检查它的理解，必要时修正规则。
错误五：让 AI 一步到位大改
即使初始化做得好，也不建议一开始就让 Claude Code 重构整个项目。先小步修改，逐步建立信任和验证闭环。
FAQ
Claude Code 项目初始化必须运行 /init 吗？
不必须，但强烈建议。你也可以手写 CLAUDE.md，但 /init 能快速扫描项目并生成起始版本，再由你人工修正。
/init 会覆盖我已有的 CLAUDE.md 吗？
官方文档说明，如果已经存在 CLAUDE.md，/init 会建议改进，而不是直接覆盖。实际操作前仍建议先查看 Git 状态，保留可回退状态。
CLAUDE.md 应该提交到 Git 吗？
项目级、团队共享的规则建议提交到 Git。个人偏好、本地路径、测试账号和临时配置应放在 CLAUDE.local.md，并加入 .gitignore。
AGENTS.md 和 CLAUDE.md 有什么关系？
Claude Code 读取 CLAUDE.md。如果项目已有 AGENTS.md，可以在 CLAUDE.md 中用 @AGENTS.md 导入，再补充 Claude Code 专属规则。
大型 monorepo 怎么初始化？
先从你负责的子项目目录启动，再用 CLAUDE.md 写共享规则，用 .claude/rules/ 写路径级规则。不要一次让 AI 扫整个超大仓库。
初始化后还需要每次解释需求吗？
需要。初始化提供项目背景，不替代具体需求。每次任务仍要说明目标、范围、验收标准和禁止事项。
如何判断 AI 已经读懂代码库？
让它说明项目入口、核心目录、测试命令、关键调用链和风险点，并要求它指出依据文件。如果回答能对应真实代码，说明上下文基本建立。
参考来源
本文关于 /init、CLAUDE.md、CLAUDE.local.md、.claude/rules/ 和项目记忆加载方式的说明，参考 Claude Code 官方文档：How Claude remembers your project、Quickstart、Settings。由于产品功能会更新，正式操作前建议以官方文档为准。
环境配置与 Docker 工作流
适合阅读安装部署、本地配置、服务器搭建和自动化流程类文章后继续转化。
