项目初始化与结构管理

前两章我们完成了 Claude Code 的安装，学会了基本的交互操作。但要让 Claude Code 真正理解你的项目——知道项目的技术栈、目录结构、构建命令——需要做项目初始化配置。这一章我们详细拆解 /init 命令和 Claude Code 的项目管理体系。

/init 命令：项目初始化

进入项目目录后，启动 Claude Code 并执行 /init：

cd /path/to/your/project
claude
> /init

/init 会做以下几件事：

扫描项目结构：读取 package.json、tsconfig.json、Dockerfile 等关键配置文件
分析技术栈：根据依赖推断使用的框架和库
生成 CLAUDE.md：在项目根目录创建配置文件
建立索引：记录项目的目录结构和关键文件位置

执行完成后，控制台会输出类似这样的信息：

Initializing project at /Users/me/projects/my-app
Detected: Next.js 14, TypeScript, Tailwind CSS, ESLint
Created CLAUDE.md with project context.
Indexed 127 files across 23 directories.

自动生成的内容

/init 自动生成的 CLAUDE.md 包含以下信息：

# my-app

## 项目概述
基于 Next.js 14 的全栈 Web 应用。

## 技术栈
- 框架: Next.js 14 (App Router)
- 语言: TypeScript 5.x
- 样式: Tailwind CSS 3.x
- 包管理: npm

## 目录结构
- app/ - 应用页面和路由
- components/ - 可复用 UI 组件
- lib/ - 工具函数和公共逻辑
- public/ - 静态资源

## 常用命令
- dev: npm run dev
- build: npm run build
- test: npm run test
- lint: npm run lint

注意：自动生成的内容不完美。比如它可能漏掉自定义的构建流程、特殊的目录约定等。你需要在生成后手动编辑，补充项目特有的信息。

.claude/ 目录详解

执行 /init 后，Claude Code 会在项目根目录创建 .claude/ 目录，这是它的配置存储位置：

.claude/
├── settings.json        # 会话配置和权限设置
├── sessions/            # 历史会话记录
│   └── 20250526T...     # 按时间命名的会话文件
└── cache/               # 缓存文件
    └── index.json       # 文件索引缓存

settings.json

这是最核心的配置文件，控制着 Claude Code 在项目中的行为：

{
  "permissions": {
    "allow": ["npm", "git", "cat", "ls"],
    "deny": ["rm -rf", "sudo"]
  },
  "model": {
    "preferred": "claude-sonnet-4-20250514"
  },
  "context": {
    "maxTokens": 32000,
    "autoCompact": true
  }
}

各字段说明：

字段	说明	默认值
`permissions.allow`	允许自动执行的命令模式列表	`[]`
`permissions.deny`	禁止执行的命令模式列表	`["sudo", "rm -rf"]`
`model.preferred`	首选的 Claude 模型	用户默认
`context.maxTokens`	上下文窗口最大 token 数	32000
`context.autoCompact`	是否自动压缩上下文	`true`

sessions/ 目录

每次与 Claude Code 的对话都会保存为一个会话文件。这些文件包含：

完整的对话历史
文件操作记录
命令执行记录

会话文件的用途：

恢复上次工作：用 claude --resume 回到上次的状态
审计追踪：查看 Claude Code 在项目中做了什么操作
调试：如果出现问题，可以查看具体哪一步出了错

会话文件是 JSON 格式，可以手动查看，但不建议直接编辑。

cache/ 目录

cache/index.json 保存了项目文件的索引信息，包括文件路径、大小、修改时间等。这帮助 Claude Code 在启动时快速了解项目结构，无需重新扫描。

如果项目文件有大量变动，你可以手动删除缓存：

rm -rf .claude/cache/

下次启动时会自动重建索引。

多个工作目录管理

大多数项目都在一个目录中，但有时你需要 Claude Code 同时理解多个代码库。比如你有一个前端项目和一个后端项目，它们之间有 API 契约需要对照。

/add-dir 命令用于将额外目录纳入工作范围：

claude
> /add-dir ../backend-api

执行后，Claude Code 会：

读取指定目录的 CLAUDE.md（如果有）
索引目录中的文件
将目录信息合并到当前上下文中

你可以随时查看当前所有工作目录：

> /status

输出示例：

Working directories:
  1. /Users/me/projects/frontend (current)
  2. /Users/me/projects/backend-api

Files indexed: 127 + 89 = 216
Context usage: 45%

注意：每添加一个目录，上下文占用会增加。如果你的项目非常大，建议只添加必要的子目录，而不是整个 monorepo。

实战：初始化一个 Next.js 项目

让我们完整走一遍流程，从新建 Next.js 项目到配置好 Claude Code。

第一步：创建项目

npx create-next-app@latest my-blog --typescript --tailwind --eslint
cd my-blog

第二步：启动 Claude Code 并初始化

claude
> /init

第三步：手动增强 CLAUDE.md

自动生成的内容比较基础。手动补充项目特有信息：

# my-blog

## 项目概述
技术博客，支持 Markdown 文章、标签分类和 RSS 订阅。

## 技术栈
- 框架: Next.js 14 (App Router)
- 语言: TypeScript 5.x
- 样式: Tailwind CSS 3.x
- 内容: MDX (contentlayer)
- 数据库: PostgreSQL + Prisma
- 包管理: npm

## 目录约定
- content/posts/ - 博客文章 Markdown 文件
- app/blog/[slug]/ - 文章页面路由
- components/mdx/ - MDX 自定义组件
- lib/prisma.ts - 数据库客户端单例

## 常用命令
- dev: npm run dev
- build: npm run build
- lint: npm run lint
- db:push: npx prisma db push
- db:studio: npx prisma studio
- type-check: npx tsc --noEmit

## 编码规范
- 使用 named export 而非 default export
- 页面组件放在 app/ 目录下，UI 组件放在 components/ 下
- API 路由统一返回 `{ success: boolean, data?: T, error?: string }` 格式
- 数据库查询放在 lib/queries/ 下，不直接写在页面组件中

第四步：验证配置

退出 Claude Code 并重新启动，确认配置生效：

claude
> /status

如果配置正确，Claude 应该能准确描述你的项目技术栈和目录结构。你可以问一个测试问题：

> 这个项目用了什么数据库 ORM？对应的配置文件在哪？

Claude 应该能从 CLAUDE.md 中读取信息并回答 "Prisma，配置文件在 prisma/schema.prisma"。

至此，项目初始化完成。下一章我们深入学习 CLAUDE.md 的完整配置语法，包括上下文窗口管理和高级配置技巧。