/init — 项目初始化命令
Claude Code 斜杠命令系列 · 第 7.1 节
一、这个命令做什么？
/init 是 Claude Code 的项目引导命令。它在你项目的根目录下生成一个 CLAUDE.md 文件——相当于给 Claude Code 的"项目说明书"，让后续的每一次对话都自带完整的项目上下文，而不是每次都从零猜你的代码结构。
执行效果一句话概括：
扫描 → 理解 → 写入
CLAUDE.md→ 后续对话自动加载
二、基本用法
在 Claude Code 的交互式 REPL 中（即你已经 claude 进入了对话界面），直接在提示符处输入：
/init不需要额外参数。Claude Code 会以当前工作目录为项目根目录进行扫描。
三、/init 做了什么？
执行 /init 后，Claude Code 大致按以下流程工作：
| 步骤 | 行为 | 说明 |
|---|---|---|
| ① 目录扫描 | 遍历当前目录及子目录 | 读取文件树结构，识别源码、配置、文档等 |
| ② 内容解析 | 分析代码与配置文件 | 推断技术栈、目录约定、入口文件、依赖关系等 |
| ③ 生成知识摘要 | 提炼为结构化项目描述 | 写入 CLAUDE.md，作为持久化的项目记忆 |
| ④ 自动挂载上下文 | 后续对话隐式引用 | 你不用每次手动贴代码或解释项目结构 |
最终产物就是一个 CLAUDE.md 文件，出现在你的项目根目录中。
四、CLAUDE.md 是什么？怎么用？
4.1 本质
CLAUDE.md 是一个 Markdown 格式的指令/记忆文件，Claude Code 会在每次对话启动时自动读取它，当作系统上下文的一部分注入。
它通常包含（由 /init 自动生成 + 你手动补充）：
- 项目用途与架构概述
- 技术栈与关键依赖
- 目录结构说明
- 构建/运行方式
- 编码规范或特殊约定
4.2 你可以（而且应该）手动编辑它
/init 给的是起点，不是终点。建议你打开 CLAUDE.md 做补充：
## 项目概述
这是一个 xxx 服务，负责……
## 技术栈
- Runtime: Node.js 20 + TypeScript
- Framework: Express / Hono / Next.js（按实际情况）
- DB: PostgreSQL + Prisma
- 测试: Vitest
## 目录速览
/src
/routes # API 路由
/services # 业务逻辑
/db # 数据访问层
## 开发命令
- dev: `npm run dev`
- build: `npm run build`
- test: `npm test`
## 约定
- 所有 API 返回统一信封 { code, data, message }
- 不允许在 route 层写业务逻辑这条文件的价值 = 你往里面填的有用信息 × 被 Claude Code 自动引用的次数
4.3 要不要提交到 Git？
| 策略 | 适合场景 |
|---|---|
| 提交到仓库 | 团队共用 Claude Code，CLAUDE.md 描述的是项目客观事实（结构、命令、规约） |
放进 .gitignore |
里面有个人偏好、路径、本地环境信息，或你希望每个人各自维护自己的 |
折中方案：提交一个 CLAUDE.md.example（模板），个人的 CLAUDE.md 忽略。
五、什么时候用 /init？
典型场景
场景 1：第一次在一个项目里用 Claude Code
cd your-project/
claude # 进入 REPL
/init # 让 Claude Code 认识这个项目之后你问它"帮我给 /api/users 加一个删除接口"，它已经知道你的路由在哪、你的 DB 层怎么写、你的返回格式长什么样。
场景 2：项目结构发生了较大变化
/init重新跑一次，CLAUDE.md 会被刷新（ 注意下面说的覆盖问题）。
六、注意事项 & 坑位提醒
| 注意点 | 说明 |
|---|---|
/init 主要产出只有 CLAUDE.md |
它不会帮你改代码、建文件、装依赖——只是写"说明书" |
| 大型项目扫描耗时 | monorepo / node_modules 没配好忽略规则的话会很慢且噪音多。建议先用 .gitignore 或告诉 Claude Code 忽略哪些目录 |
重新 /init 可能覆盖手工编辑 |
如果你已经在 CLAUDE.md 里写了一堆宝贵注释，重跑 /init 前建议先备份：cp CLAUDE.md CLAUDE.md.bak |
| 不是魔法 | /init 生成的初稿质量取决于项目本身是否"自描述"（有没有 package.json、README、清晰的目录名）。越规范的仓库效果越好 |
.gitignore 里的文件不会被关注 |
这和 git 的忽略规则通常是一致的，但如果有特殊目录不想让它看，留意一下 |
七、推荐工作流（最佳实践）
# 1. 进入项目
cd my-project
# 2. 首次初始化
claude
/init
# 3. 打开 CLAUDE.md，手补一段"人话"——
# 项目是干嘛的、核心约定是什么、哪些目录千万别乱动
vim CLAUDE.md # 或用 VS Code 打开编辑
# 4. 清掉初始化过程中的闲聊历史（可选），正式开工
/clear之后日常开发：
你：「帮我在 src/services/payment.ts 里加一个 refund() 方法，
复用现有的 prisma 实例和日志工具」Claude Code 已经知道 prisma 在哪、logger 怎么用、错误该怎么返回——因为这些都在 CLAUDE.md 里。
八、常与 /init 搭配的命令
| 命令 | 用途 |
|---|---|
/clear |
清空当前对话历史，保留 CLAUDE.md 上下文——适合 init 完想"重新开始" |
/memory |
直接编辑 CLAUDE.md（有些版本支持此快捷入口） |
/context |
查看当前上下文占用情况 |
/model |
如果 init 过程中发现需要用更大上下文窗口的模型 |
一句话总结：
/init的意义不是"初始化项目"（项目早就在那了），而是初始化 Claude Code 对这个项目的认知。CLAUDE.md就是这个认知的物化载体——自动生成打底，人工精修加码，才是正确打开方式。
如果你愿意，把你项目的 目录树（tree -L 2 -I 'node_modules|.git|dist' 的输出）或者现有的 CLAUDE.md 贴出来，我可以帮你进一步精炼成一份高质量的项目记忆文件，让它对 Claude Code 的指导效果最大化。
