让 Claude 理解你的项目

┌─────────────────────────────────────────────────────────────┐
│                     Agentic Loop                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   用户提问                                                  │
│      │                                                      │
│      ▼                                                      │
│   ┌──────────────┐    ┌──────────────┐    ┌─────────────┐  │
│   │  Gather      │───▶│  Take        │───▶│  Verify     │  │
│   │  Context     │    │  Action      │    │  Results    │  │
│   │  (收集上下文) │    │  (执行操作)   │    │  (验证结果)  │  │
│   └──────────────┘    └──────────────┘    └─────────────┘  │
│          │                   │                   │          │
│          └───────────────────┴───────────────────┘          │
│                        (循环直到完成)                        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

# 典型的 Web 项目结构
src/
  ├── components/     ← 识别为 UI 组件目录
  ├── pages/          ← 识别为路由页面（Next.js/Nuxt 模式）
  ├── api/            ← 识别为 API 路由
  ├── utils/          ← 工具函数
  └── types/          ← 类型定义

# 典型的后端项目结构
app/
  ├── models/         ← 数据库模型
  ├── routes/         ← 路由处理器
  ├── services/       ← 业务逻辑
  └── core/           ← 核心配置

claude> 检查 src/auth.ts 中的登录逻辑
# Claude 直接读取 src/auth.ts

claude> 用户认证是怎么实现的？
# Claude 会搜索包含 "auth"、"login"、"session" 的文件名和内容

claude> 解释这个项目的整体架构
# Claude 读取 package.json、主入口文件、路由配置等

claude> 我最近的改动有什么问题？
# Claude 读取 git diff 中涉及的文件

claude> 这个函数应该怎么用？
# Claude 可能读取对应的 .test.ts 文件看用法示例

claude> 分析这个项目的技术栈。列出：1) 主要编程语言和框架 2) 构建工具 3) 测试框架 4) 数据库/ORM 5) 部署方式

基于对项目文件的分析，技术栈如下：

1. 主要编程语言和框架：
   - TypeScript（主语言）
   - Next.js 15（React 框架，App Router）
   - React 19（UI 库）

2. 构建工具：
   - Vite 6（开发服务器和构建）
   - pnpm（包管理器）

3. 测试框架：
   - Vitest（单元测试）
   - Playwright（E2E 测试）

4. 数据库/ORM：
   - PostgreSQL（数据库）
   - Drizzle ORM（类型安全的数据库操作）

5. 部署方式：
   - Docker（容器化）
   - 从 Dockerfile 推断可能使用 AWS ECS 或类似平台

claude> 分析 package.json 中的关键依赖。哪些是直接依赖？哪些是开发依赖？有没有已知的安全风险或过时包？

claude> 解释这个项目的目录结构。每个主要目录的作用是什么？遵循什么设计模式？

项目采用 Next.js App Router 的标准结构，遵循功能模块组织原则：

src/
├── app/                    # Next.js App Router 路由
│   ├── (marketing)/        # 路由组：营销页面（无共享布局）
│   ├── dashboard/          # 仪表盘路由
│   ├── api/                # API 路由端点
│   └── layout.tsx          # 根布局
├── components/
│   ├── ui/                 # 基础 UI 组件（Button, Input 等）
│   └── features/           # 功能组件（与业务逻辑耦合）
├── lib/
│   ├── db/                 # 数据库相关（schema, queries）
│   ├── auth/               # 认证工具
│   └── utils/              # 通用工具函数
├── types/                  # 全局 TypeScript 类型
└── hooks/                  # 自定义 React Hooks

设计模式：
- 使用 Barrel exports（index.ts）简化导入
- UI 组件与功能组件分离，便于复用
- API 路由与页面路由共存，全栈开发

claude> 列出这个项目中最重要的 10 个文件，并说明每个文件的作用

claude> 找出这个项目的所有入口点：1) 应用程序入口 2) 库/包的导出入口 3) 测试入口 4) CLI 入口（如果有）

入口点分析：

1. 应用程序入口：
   - 前端：src/app/layout.tsx（Next.js 根布局）
   - 后端 API：src/app/api/[[...route]]/route.ts（API 路由聚合）

2. 库/包导出：
   - src/index.ts（主包导出）
   - src/components/ui/index.ts（UI 组件桶文件）

3. 测试入口：
   - vitest.config.ts 中定义的入口
   - src/**/*.test.ts 模式匹配

4. CLI 入口：
   - bin/cli.js（如果项目包含 CLI 工具）

claude> 找到处理用户登录逻辑的文件
# Claude 自动搜索包含 login、auth、signin 等关键词的文件

claude> 看看 @src/auth.ts 里的登录函数有什么问题
# @ 触发文件路径自动补全，直接读取指定文件

claude> 搜索所有包含 "JWT" 这个词的文件，并显示上下文
# Claude 使用 Grep 工具执行正则搜索

claude> 列出所有以 .service.ts 结尾的文件
# Claude 使用 Glob 工具匹配文件模式

claude> 找到 `validateUser` 函数的定义，以及所有调用它的地方

`validateUser` 函数定义在 src/lib/auth.ts:45：

```typescript
export async function validateUser(
  email: string,
  password: string
): Promise<User | null> {
  // ... 实现
}

**提问模板 7：类型追踪**

```bash
claude> `User` 类型在哪里定义？哪些文件使用了这个类型？

claude> 分析 src/services/ 目录下各模块的依赖关系。哪个模块被最多其他模块引用？有没有循环依赖？

claude> 追踪一个用户注册请求从 API 入口到数据库的完整数据流。列出涉及的所有文件和函数调用链。

用户注册数据流：

1. API 入口
   src/app/api/auth/register/route.ts
   └── POST handler (line 15)

2. 输入验证
   └── validateRegistrationInput()
       src/lib/validation/auth.ts:23

3. 业务逻辑
   └── authService.register()
       src/services/auth.ts:45
       ├── checkExistingUser() — src/services/user.ts:12
       ├── hashPassword() — src/lib/crypto.ts:8
       └── createUser() — src/services/user.ts:34

4. 数据库操作
   └── db.insert(users).values(...)
       src/lib/db/queries/user.ts:56
       └── 使用 Drizzle ORM 的 schema
           src/lib/db/schema.ts:23 (users 表定义)

5. 响应构造
   └── 返回 { success: true, user: {...} }
       src/app/api/auth/register/route.ts:42

涉及文件：6 个
函数调用深度：4 层

claude> 使用 subagent 并行探索：1) 认证模块的代码结构 2) 支付模块的代码结构 3) 通知模块的代码结构。每个 subagent 返回该模块的关键文件列表和职责说明。

claude> 使用 explore subagent 查找所有与 WebSocket 相关的代码。返回文件路径、关键代码片段和整体架构说明。

claude> /context

Context usage: 68% (142,000 / 200,000 tokens)

Breakdown:
- System prompt + CLAUDE.md: 12,000 tokens (8%)
- Conversation history: 45,000 tokens (32%)
- File reads: 62,000 tokens (44%)
- Command outputs: 18,000 tokens (13%)
- Tool definitions: 5,000 tokens (4%)

Optimization suggestions:
- Run /compact to free up ~20,000 tokens
- 5 files in context haven't been referenced in 10+ turns
- Consider starting a new session for a different task

claude> /compact 保留关于认证模块重构的决策

<!-- CLAUDE.md 示例 -->
# 项目上下文

## 项目概述
这是一个基于 Next.js 15 的全栈 SaaS 应用，使用 TypeScript 和 Tailwind CSS。

## 关键目录
- `src/app/` — App Router 页面和 API 路由
- `src/components/ui/` — 基础 UI 组件（shadcn/ui）
- `src/components/features/` — 业务功能组件
- `src/lib/db/` — 数据库 schema 和查询
- `src/lib/auth/` — 认证相关工具
- `src/services/` — 业务逻辑层

## 技术栈
- Next.js 15 + React 19
- TypeScript 5.7
- Tailwind CSS 4
- Drizzle ORM + PostgreSQL
- NextAuth.js v5
- Vitest + Playwright

## 代码规范
- 所有函数必须有类型注解
- 使用 async/await，避免回调
- 错误处理使用 Result 模式，不抛异常
- UI 组件使用 cn() 工具合并 Tailwind 类名

## 常用命令
```bash
pnpm dev          # 启动开发服务器
pnpm test         # 运行单元测试
pnpm test:e2e     # 运行 E2E 测试
pnpm db:generate  # 生成 Drizzle 迁移
pnpm db:migrate   # 执行迁移

**最佳实践 2：使用 `/init` 自动生成 CLAUDE.md**

Claude Code 提供了 `/init` 命令，可以自动分析项目并生成初始的 `CLAUDE.md`[^7]：

```bash
claude> /init

~/.claude/CLAUDE.md          # 全局：个人偏好、通用标准
./CLAUDE.md                  # 项目根：架构、技术栈
./packages/api/CLAUDE.md     # 子包：API 层的特定约定
./packages/web/CLAUDE.md     # 子包：前端层的特定约定

claude> 这个项目有点问题，帮我看看
# Claude 不知道从哪里开始，可能读取大量无关文件

claude> 登录功能有问题，帮我检查一下
# Claude 会搜索 auth 相关文件，但仍需探索

claude> 在 src/app/api/auth/login/route.ts 中，POST 处理函数（约第 15 行）没有验证请求体。添加 Zod schema 验证，确保 email 是有效邮箱格式，password 至少 8 位。参考 src/lib/validation/user.ts 中的现有验证模式。
# Claude 直接定位到具体文件，理解约束条件，参考现有模式

[具体位置] + [当前行为] + [期望行为] + [约束/参考]

claude> 我需要给通知系统添加 Slack 渠道支持。先不要写代码，先探索 /src/notifications/ 目录，了解：1) 文件结构 2) 渠道基类接口 3) 现有渠道（Email、SMS）是如何注册的。只读模式，不要修改任何文件。

claude> 基于刚才的探索，制定一个详细的实施计划。需要：1) 创建哪些文件 2) 修改哪些文件 3) 遵循什么模式 4) 测试策略是什么。列出每一步的具体操作。

claude> 按照计划实施。先创建 SlackChannel 类，然后注册到通知路由器，最后写测试。每完成一步告诉我结果。

claude> 用一段话概括这个项目是做什么的。它的核心功能是什么？目标用户是谁？

这是一个开源的在线协作白板应用，核心功能包括：

1. 实时多人协作：基于 WebSocket 的同步编辑
2. 丰富的绘图工具：便签、连线、图形、手绘
3. 导出功能：支持 PNG、SVG、PDF 导出
4. 自托管支持：提供 Docker 部署方案

目标用户是需要远程协作进行头脑风暴、流程图绘制、UI 原型设计的团队。

技术亮点：
- 使用 CRDT 算法处理并发编辑冲突
- Canvas 渲染引擎支持万级元素流畅操作
- 端到端加密选项保护敏感内容

claude> 详细分析这个项目的技术栈。包括：前端、后端、数据库、基础设施、开发工具。对每个主要技术选择，说明它的作用。

claude> 用树状图展示项目的目录结构（只显示到 2 级深度），然后解释每个主要目录的设计意图和包含的内容类型。

claude> 找到用户密码重置功能的完整实现。包括：1) 触发重置的 API 端点 2) 生成重置 token 的逻辑 3) 发送邮件的代码 4) 验证 token 并重置密码的逻辑 5) 对应的测试文件。列出每个文件的绝对路径和关键函数名。

claude> 解释 src/services/payment.ts 中的 `processRefund` 函数。包括：1) 输入参数和返回值 2) 核心逻辑步骤 3) 错误处理策略 4) 调用的外部服务 5) 可能的边界情况。

claude> 追踪"创建订单"这个业务操作的完整调用链。从前端提交表单开始，到数据写入数据库结束。列出每个步骤涉及的文件、函数和数据转换。

claude> 找出项目中所有使用 `useAuth` hook 的地方。对每个使用点，说明：1) 文件路径 2) 使用方式（读取了哪些返回值）3) 使用场景（在哪个组件中，做什么用）。

claude> 基于代码库生成一份架构文档，包含：1) 系统架构图（用 Mermaid 语法）2) 核心模块说明 3) 数据模型关系 4) API 端点列表 5) 部署架构。保存为 docs/architecture.md。

claude> 我需要给通知系统添加 Slack 渠道。在写任何代码之前，先探索 /src/notifications/。告诉我：1) 文件结构 2) 渠道基类接口 3) 现有渠道（Email、SMS）是如何注册的。只读，不修改。

claude> 现在实现 Slack 通知渠道。严格按照 EmailChannel 在 /src/notifications/channels/email.ts 中的模式。在 /src/notifications/channels/slack.ts 创建新文件。使用 /src/lib/slack.ts 中的 SlackWebhookClient 发送消息。

claude> 先读取整个 src/ 目录了解项目结构，然后修复这个 bug
# 消耗大量上下文在探索上

claude> 修复 src/auth.ts 中第 45 行的类型错误
# 只读取一个文件，如果需要更多 Claude 会请求

claude> 我们在 packages/api 中工作。入口点是 packages/api/src/index.ts。相关类型在 packages/shared/src/types/ 中，但只读取需要的类型文件，不要探索整个 shared 包。

## 包依赖关系
- `packages/api` 依赖 `packages/shared` 和 `packages/db`
- `packages/web` 依赖 `packages/shared` 和 `packages/ui`
- 无其他跨包依赖

claude> 总结一下我们目前完成了什么、什么还在进行中、还有什么待做。保存到 /tmp/progress.md。

# 新会话
claude> 问题：用户随机被登出。已尝试：1) 检查 token 过期逻辑（无果）2) 检查 cookie 设置（无果）。怀疑：session 刷新中间件有竞态条件。请检查 /src/middleware/session-refresh.ts 找出根本原因。

# .claudeignore
node_modules/
dist/
build/
.coverage/
*.min.js
*.min.css
public/assets/
test/fixtures/

cd ecommerce-platform
claude

# 如果项目没有 CLAUDE.md，先运行 /init
claude> /init

claude> 分析这个项目的技术栈和架构。用 3 句话概括它是做什么的，然后列出主要技术选择和目录结构。

claude> 这个电商平台有哪些核心领域模块？（如商品、订单、用户、支付等）每个领域的主要文件在哪里？

claude> 追踪"用户下单"的完整业务流程。从点击"购买"按钮开始，到订单创建成功结束。列出涉及的所有文件、API 端点、数据库表和外部服务调用。

claude> 列出所有数据库表（或模型），并说明它们之间的关系。用 Mermaid ER 图语法表示。

claude> 这个项目使用了哪些设计模式？代码中有哪些反复出现的约定？（如错误处理、API 响应格式、认证检查等）

claude> 基于以上分析，生成一份我个人的 onboarding 速查文档，保存为 ONBOARDING.md。包含：1) 项目一句话描述 2) 技术栈 3) 关键文件速查表 4) 常见任务的操作指南 5) 需要注意的坑。