CLAUDE.md Nutzungsanleitung

CLAUDE.mdEs ist die wichtigste Konfigurationsdatei in Claude Code, mit der Claude projektweite persistente Anweisungen übergeben werden. Jedes Mal, wenn eine Claude-Code-Sitzung gestartet wird, liest und lädt es automatisch die Inhalte dieser Datei und bindet sie als Kontext auf Systemebene in jede Konversation ein.

Einfach ausgedrückt,CLAUDE.mdes ist ein Arbeitshandbuch, das du für Claude im Projekt schreibst — es sagt ihm, was das Projekt ist, welche Standards befolgt werden müssen und worauf zu achten ist, damit es jedes Mal so arbeiten kann, dass es die Projektanforderungen erfüllt, anstatt in jeder Konversation erneut erklärt werden zu müssen.


Die Rolle von CLAUDE.md

OhneCLAUDE.mdes beginnt Claude, dein Projekt jedes Mal von Grund auf zu verstehen, und du musst ihm wiederholt sagen: welchen Paketmanager es verwenden soll, wie der Codestil ist, wie Tests ausgeführt werden, welche Dateien nicht angefasst werden dürfen... MitCLAUDE.mdmüssen diese Informationen nur einmal geschrieben werden, und Claude wird sich jedes Mal daran halten.

Konkret,CLAUDE.mdes kann dir helfen, Folgendes zu erreichen:

  • Teamverhalten vereinheitlichen: Die Datei in git committen, und alle Teammitglieder folgen denselben Standards bei der Verwendung von Claude Code
  • Wiederholte Kommunikation reduzieren: Projektkonventionen, Architekturregeln und verbotene Elemente werden nur einmal geschrieben und bleiben dauerhaft wirksam
  • Verringern Sie die Wahrscheinlichkeit von Fehlern: Informieren Sie Claude klar darüber, welche Operationen riskant sind, und verhindern Sie so, dass es falsche Entscheidungen trifft
  • KI-Verständnis beschleunigen: Helfen Sie Claude, wichtige Dateien schnell zu finden und die Projektstruktur zu verstehen, wodurch unnötige Dateierkundung reduziert wird

Dateiablageort

Claude Code lädt von mehreren OrtenCLAUDE.md, und Dateien an verschiedenen Orten haben unterschiedliche Geltungsbereiche:

Ort Pfad Geltungsbereich In git committen?
Projekt-Stammverzeichnis {项目根目录}/CLAUDE.md Alle Sitzungen des aktuellen Projekts ✅ Empfohlen zum Committen, vom Team gemeinsam genutzt
Projektlokal {项目根目录}/.claude/CLAUDE.md Alle Sitzungen des aktuellen Projekts ❌ Zu .gitignore hinzufügen, nur für den persönlichen Gebrauch
Unterverzeichnis {任意子目录}/CLAUDE.md Automatisch geladen, wenn Claude Dateien in diesem Verzeichnis öffnet ✅ Geeignet für Multi-Modul-Repositories
Global auf Benutzerebene ~/.claude/CLAUDE.md Alle Projekte des aktuellen Benutzers ❌ Persönliche Konfiguration, nicht committen

Wenn mehrere Speicherorte vorhanden sindCLAUDE.md, wird Claude Codealle von ihnen laden und zusammenführen, wobei die Priorität von hoch nach niedrig wie folgt ist:

Project local → Project root directory → Subdirectory → Global user level

Das Stammverzeichnis des ProjektsCLAUDE.mdEs wird empfohlen, in git zu committen, damit das gesamte Team denselben Satz an KI-Arbeitsstandards verwendet.

Persönliche Präferenzen (wie z. B. die Abneigung gegen Semikolons) sollten in.claude/CLAUDE.mdund hinzugefügt zu.gitignore, ohne andere zu beeinträchtigen.


CLAUDE.md schnell erstellen

Der einfachste Weg ist, Claude Code automatisch eine erste Version generieren zu lassen. Nachdem Sie Claude Code im Projektverzeichnis gestartet haben, führen Sie aus:

/init

Claude Code analysiert Ihre Projektstruktur, Ihren Code-Stil und vorhandene Konfigurationsdateien (wie z. B.package.json、pyproject.toml、.eslintrcusw.) und generiert automatisch eine Version, die der tatsächlichen Projektsituation entsprichtCLAUDE.md, und anschließend können Sie darauf aufbauend ergänzen und Anpassungen vornehmen.

Sie können sie auch manuell im Projektverzeichnis erstellen:

touch CLAUDE.md

Struktur des Dateiinhalts

CLAUDE.mdEs handelt sich um eine gewöhnliche Markdown-Datei ohne verbindliche Formatanforderungen, aber eine gute Struktur kann Claude dabei helfen, wichtige Informationen schneller zu finden. Im Folgenden wird die empfohlene Inhaltsstruktur beschrieben:

# 项目名称

一句话说明这个项目是什么,方便 Claude 快速定位项目性质。

## 技术栈
- 语言:Python 3.11
- 框架:FastAPI 0.110
- 数据库:PostgreSQL 15 + SQLAlchemy ORM
- 测试:pytest

## 常用命令

### 开发
```bash
uv run uvicorn main:app --reload   # 启动开发服务器
uv run pytest                       # 运行所有测试
uv run pytest -k "test_auth"        # 运行指定测试
```

### 代码检查
```bash
uv run ruff check .                 # 代码检查
uv run ruff format .                # 代码格式化
```

## 项目结构
- `src/api/` — API 路由和请求处理
- `src/models/` — 数据库模型定义
- `src/services/` — 业务逻辑层
- `tests/` — 测试文件,与 src/ 目录结构镜像对应

## 编码规范
- 使用 `uv` 管理依赖,不使用 pip 直接安装
- 所有函数必须有类型注解
- 字符串一律使用双引号
- 新增 API 路由必须同步添加测试

## 注意事项
- 不要修改 `migrations/` 目录下的已有文件,只能新增迁移文件
- `config/secrets.py` 包含敏感配置,禁止输出其内容到日志或终端
- 数据库操作必须通过 Service 层,不要在路由层直接操作 ORM

Ausführliche Erläuterung der Kerninhaltsmodule

1. Häufige Befehle

Dies istCLAUDE.mdMediumder am häufigsten referenzierteTeil. Wenn Claude Aufgaben wie Tests, Builds und Code-Linting ausführt, sucht es zuerst nach den hier definierten Befehlen, um zu vermeiden, Befehle zu erraten oder falsche Befehle zu verwenden:

## 常用命令

### 安装依赖
```bash
npm ci                    # 安装依赖(CI 环境使用,严格按 lock 文件安装)
```

### 开发
```bash
npm run dev               # 启动开发服务器(端口 3000)
npm run build             # 构建生产版本
npm run preview           # 预览生产构建
```

### 测试
```bash
npm test                  # 运行所有测试
npm test -- --watch       # 监听模式
npm test -- --coverage    # 生成覆盖率报告
```

### 代码质量
```bash
npm run lint              # ESLint 检查
npm run lint:fix          # 自动修复可修复的问题
npm run typecheck         # TypeScript 类型检查
```

2. Beschreibung der Projektstruktur

Hilft Claude, Dateien schnell zu finden und unnötige Verzeichnis-Scans zu reduzieren, besonders effektiv in großen Projekten:

## 项目结构

```
src/
├── app/                  # Next.js App Router 页面
│   ├── (auth)/           # 需要登录才能访问的页面组
│   └── api/              # API 路由
├── components/           # 可复用 UI 组件
│   ├── ui/               # 基础 UI 组件(Button、Input 等)
│   └── features/         # 业务组件(按功能模块组织)
├── lib/                  # 工具函数和配置
│   ├── db/               # 数据库客户端和查询
│   └── auth/             # 认证相关逻辑
└── types/                # TypeScript 类型定义
```

关键文件:
- `src/lib/db/client.ts` — 数据库连接配置
- `src/middleware.ts` — 认证中间件,处理路由保护
- `env.example` — 所有必要的环境变量示例

3. Programmierstandards

Informiert Claude über den Code-Stil und die Konventionen des Projekts und stellt sicher, dass der generierte Code mit dem Stil der bestehenden Codebasis übereinstimmt:

## 编码规范

### 通用
- 文件名使用 kebab-case(如 `user-profile.ts`),类名使用 PascalCase
- 优先使用具名导出(named export),避免默认导出(default export)
- 异步函数一律使用 async/await,禁止使用 .then() 链式调用

### 组件规范
- 组件文件与其测试文件放在同一目录(如 `Button.tsx` 和 `Button.test.tsx`)
- Props 类型使用 interface 定义,命名格式为 `${组件名}Props`
- 不要将业务逻辑写在组件中,提取为自定义 Hook 或 Service

### 错误处理
- API 路由使用统一的错误响应格式:`{ error: string, code: string }`
- 客户端错误通过 Error Boundary 捕获,不要在每个组件里单独 try/catch

4. Architektureinschränkungen und verbotene Punkte

Dies ist der entscheidende Teil, um zu verhindern, dass Claude "clevere, aber falsche" Entscheidungen trifft. Für besondere Situationen, die Sie verstehen, die Claude aber nicht kennt, müssen Sie sie klar aufschreiben:

## 架构约束

- 所有数据库查询必须通过 `src/lib/db/queries/` 中的函数执行,不要在路由或组件中直接写 SQL
- 状态管理使用 Zustand,不要引入 Redux 或其他状态管理库
- 样式使用 Tailwind CSS utility class,不要新增 CSS 文件或使用 CSS Modules

## 注意事项(重要)

- `legacy/` 目录下的代码是遗留代码,**禁止修改**,只能读取
- `.env.local` 和 `.env.production` 包含真实密钥,**禁止输出文件内容**
- `prisma/migrations/` 中已有的迁移文件**禁止修改**,数据库变更只能新增迁移
- 修改 `src/middleware.ts` 前必须先告知我,该文件影响所有路由的认证逻辑

5. Beschreibung der Entwicklungsumgebung

Hilft Claude, die Laufzeitumgebung des Projekts zu verstehen und Fehler bei der Befehlsausführung aufgrund von Umgebungsunterschieden zu vermeiden:

## 开发环境

- Node.js:需要 v20 或以上版本(通过 `.nvmrc` 指定)
- 包管理器:pnpm(禁止使用 npm 或 yarn 安装依赖)
- 本地数据库:Docker Compose 启动(`docker compose up -d`)
- 端口:前端 3000,API 3001,数据库 5432

### 环境变量
参考 `.env.example` 文件配置本地环境变量,复制为 `.env.local` 后填入实际值。
必填项:`DATABASE_URL`、`NEXTAUTH_SECRET`、`NEXTAUTH_URL`

Konfiguration für Multi-Modul-Repository (Monorepo)

In einem Monorepo können Sie eine globale Konfiguration im Stammverzeichnis des Repositorys platzierenCLAUDE.md, und die jeweilige in jedem Unterpaket-Verzeichnis platzieren.CLAUDE.mdWenn Claude eine Datei in einem Unterpaket öffnet, lädt es sowohl die Dateien des Stammverzeichnisses als auch die Dateien des Unterpaket-Verzeichnisses:

my-monorepo/
├── CLAUDE.md                  ← 全局规范:共用命令、整体架构、通用约定
├── packages/
│   ├── web/
│   │   └── CLAUDE.md          ← 前端专属:React 规范、样式约定、构建流程
│   ├── api/
│   │   └── CLAUDE.md          ← 后端专属:API 设计规范、数据库约定
│   └── shared/
│       └── CLAUDE.md          ← 共享包:导出规则、版本管理约定
└── tools/
    └── CLAUDE.md              ← 工具脚本:特殊说明和使用限制
<!-- 根目录 CLAUDE.md(全局规范) -->
# My Monorepo

使用 pnpm workspace 管理的前后端一体化项目。

## 全局命令
```bash
pnpm install          # 安装所有包的依赖
pnpm -r build         # 构建所有包
pnpm -r test          # 运行所有包的测试
pnpm --filter web dev # 只启动 web 包的开发服务器
```

## 包之间的依赖关系
- `web` 和 `api` 都依赖 `shared`
- 禁止 `shared` 依赖 `web` 或 `api`(防止循环依赖)
- 跨包引用使用包名(如 `@my-app/shared`),不要使用相对路径

Referenzieren externer Dateien mit der @-Syntax

Wenn das Projekt bereits Spezifikationsdokumente enthält (wie API-Designspezifikationen, Datenbank-Design-Dokumente usw.), ist es nicht nötig, den Inhalt zu kopieren inCLAUDE.mdVerwenden Sie stattdessen direkt@file pathum sie zu referenzieren.

Wenn Claude liestCLAUDE.mdlädt er automatisch die Inhalte der referenzierten Datei:

## 规范文档

详细的 API 设计规范请参考:
@docs/api-design-guide.md

数据库设计约定:
@docs/database-conventions.md

组件库使用说明:
@docs/component-guidelines.md

Der referenzierte Dateipfad ist relativ zuCLAUDE.mddem Verzeichnis, in dem sich die Datei befindet. Der Inhalt der referenzierten Datei belegt Platz im Kontextfenster, daher sollten zu große Dateien vermieden werden (es wird empfohlen, dass eine einzelne referenzierte Datei 500 Zeilen nicht überschreitet).


Empfehlungen zur Verwendung der globalen CLAUDE.md

Benutzerebene~/.claude/CLAUDE.mdeignet sich zum Speichern persönlicher Vorlieben und Gewohnheiten, die projektübergreifend üblich sind; diese Inhalte gelten für alle Projekte:

<!-- 文件路径:~/.claude/CLAUDE.md -->
# 个人全局配置

## 回答偏好
- 回复使用中文
- 代码修改前先简要说明修改思路,不要直接给出代码
- 遇到有多种实现方案时,列出选项让我选择,而不是直接选一种

## 通用约定
- 提交信息使用英文,格式:`type(scope): description`
- 新文件开头不加版权注释
- 优先使用原生 API,避免引入不必要的依赖

## 安全习惯
- 修改认证相关代码前主动提示我注意安全影响
- 不要在代码注释或日志中输出任何密钥或 token

Wartungshinweise für CLAUDE.md

1. Prägnant halten

CLAUDE.mdDer Inhalt belegt in jeder Sitzung Platz im Kontextfenster. Zu viel Inhalt komprimiert den tatsächlich für Claude verfügbaren Kontextraum und verringert die Effizienz. Es wird empfohlen, diese Grundsätze zu befolgen:

  • Schreibe jede Regel nur einmal; wiederhole nicht dieselbe Bedeutung.
  • Füge keine Hintergrundinformationen ein, die nicht mit Code zusammenhängen (wie Unternehmensvorstellungen, Produktpläne).
  • Informationen, die durch den Code selbst vermittelt werden können (z. B. eine eslint-Konfiguration, die bereits den Codestil definiert), müssen nichtCLAUDE.mderneut in der Datei deklariert werden.
  • Es wird empfohlen, die Gesamtwortzahl auf 500 Wörter zu begrenzen; wenn sie 1000 Wörter überschreitet, sollte über eine Vereinfachung nachgedacht werden.

2. Kontinuierlich aktualisieren

Während sich das Projekt weiterentwickelt,CLAUDE.mdmuss es auch synchron aktualisiert werden. Die folgenden Anlässe sollten Aktualisierungen auslösen:

  • Paketmanager oder Build-Tool geändert
  • Wichtige Abhängigkeitsbibliotheken hinzugefügt oder entfernt
  • Neue Coding-Konventionen etabliert
  • Entdeckt, dass Claude wiederholt denselben Fehlertyp macht (was darauf hindeutet, dass diesCLAUDE.mdin der Datei ergänzt werden muss)
  • Eine bestimmte Datei oder ein bestimmtes Modul lässt sich nicht mehr beliebig ändern (fügen Sie es den Vorsichtsmaßnahmen hinzu)

3. Imperative Sprache verwenden

Je klarer die Anweisung, desto höher die Wahrscheinlichkeit, dass Claude sie befolgt. Vermeiden Sie vage Beschreibungen und verwenden Sie direkte Anweisungen:

❌ Vage Beschreibung ✅ Klare Anweisung
Code sollte relativ sauber sein Funktionen sollten 50 Zeilen nicht überschreiten; wenn doch, müssen sie aufgeteilt werden.
Versuchen Sie, Tests zu schreiben Jede neue Funktion muss einen entsprechenden Unit-Test haben
Auf Sicherheit achten Benutzereingaben müssen durchsanitize()Funktionsverarbeitung laufen, bevor sie in Datenbankabfragen übergeben werden
Das Legacy-Verzeichnis ist nicht sehr wichtig Es ist verboten,legacy/irgendwelche Dateien im Verzeichnis zu ändern
Die Verwendung von pnpm ist besser Zur Abhängigkeitsverwaltung ausschließlich pnpm verwenden; npm und yarn sind verboten.

Vollständiges Beispiel

Das Folgende ist das vollständige Beispiel eines Node.js + TypeScript Full-Stack-Projekts,CLAUDE.mddas als Referenzvorlage für Ihr Projekt dienen kann:

Beispiel

# MyApp — E-Commerce-Admin-Dashboard

Basierend auf Next.js 14 App Router + Prisma +E-Commerce-Managementsystem mit PostgreSQL.

## Tech-Stack
-Frontend: Next.js 14(App Router), TypeScript, Tailwind CSS, shadcn/ui
-Backend: Next.js API-Routen, Prisma ORM
-Datenbank: PostgreSQL15
-Authentifizierung: NextAuth.js v5
-Paketmanager: pnpm

## Häufige Befehle

```bash
pnpm dev # Entwicklungsserver starten (Port3000)
pnpm build &&pnpm start # Produktionsserver bauen und starten
pnpm test # Alle Tests ausführen
pnpm test:e2e # End-to-End-Tests ausführen (erfordert vorheriges Starten des Entwicklungsservers)
pnpm db:migrate # Datenbankmigrationen ausführen
pnpm db:studio # Prisma Studio öffnen (Datenbank-Visualisierungstool)
pnpm lint &&pnpm typecheck # Code- und Typüberprüfung
```

## Projektstruktur

- `src/app/` — App-Router-Seiten und API-Routen
- `src/app/(dashboard)/` — Admin-Seiten, die eine Anmeldung erfordern
- `src/app/api/` — API-Routen (RESTful-Stil)
- `src/components/` — Wiederverwendbare Komponenten
- `src/lib/` — Hilfsfunktionen, Datenbank-Client, Auth-Konfiguration
- `prisma/schema.prisma` — Datenbankschema-Definitionen

## Programmierstandards

-Verwende nur benannte Exporte (namedexport), Standard-Exporte sind verbotendefault export(außer für Next.jsSeitendateien)
-Server-Komponenten sind standardmäßig asynchron; Client-Komponenten fügen ` am Anfang der Datei hinzu"use client"`
-API-Routen verwenden ein einheitliches Antwortformat: Erfolg `{ data: T }`, Fehler `{ error: string, Code: string }`
-Datenbankabfragen sind im Verzeichnis `src/lib/db/` gekapselt; verwenden Sie den `prisma`-Client nicht direkt an anderer Stelle

## Hinweise

- `prisma/migrations/Vorhandene Dateien in `**dürfen nicht geändert werden**; Datenbankänderungen können nur durch Ausführen von `pnpm db:migrate`, um neue Migrationen hinzuzufügen
- `.env.local` enthält echte Geheimnisse,**Inhalte der Datei nicht lesen oder ausgeben**
- `src/lib/auth.ts` ist die zentrale Auth-Datei,**Sie müssen mich informieren, bevor Sie sie ändern**
-Nach dem Ändern von `prisma/schema.prisma`, müssen Sie `pnpm db:migrate` ausführen und die Migrationsdateien committen

Häufig gestellte Fragen

F: Was ist, wenn Claude die Regeln in CLAUDE.md nicht befolgt?

Prüfen Sie zunächst, ob die Regel klar genug formuliert ist (siehe den obigen Vorschlag „imperative Sprache verwenden“). Wenn sie bereits klar ist, aber trotzdem nicht befolgt wird, können Sie sie im konkreten Gespräch erneut betonen oder die Regel an eine frühere Position in der Datei verschieben – Claude schenkt dem Inhalt in der ersten Hälfte der Datei mehr Aufmerksamkeit.

F: Ist eine längere CLAUDE.md besser?

Nein. Zu viel Inhalt hat zwei Nachteile: Erstens beansprucht er Platz im Kontextfenster und reduziert den Raum, den Claude für die Bearbeitung tatsächlicher Aufgaben hat; zweitens gehen wichtige Regeln in großen Textmengen unter und werden weniger wahrscheinlich befolgt. Es wird empfohlen, regelmäßig zu überprüfen und Einträge zu entfernen, die nicht mehr anwendbar oder von geringem Wert sind.

F: Wann wird die CLAUDE.md in einem Unterverzeichnis geladen?

Wenn Claude eine Datei in diesem Unterverzeichnis öffnet oder bearbeitet, wird die des UnterverzeichnissesCLAUDE.mdautomatisch geladen. Sie müssen Claude nicht manuell sagen, dass er sie lesen soll; der gesamte Vorgang ist automatisch.

F: Kann ich in CLAUDE.md auf eine andere CLAUDE.md verweisen?

Sie können nicht direkt darauf verweisen, aber Sie können@file pathSyntax verwenden, um auf den Inhalt jeder Markdown-Datei zu verweisen. Wenn es Konventionen gibt, die modulübergreifend geteilt werden, wird empfohlen, sie in eine separate Dokumentdatei auszulagern und dann in jederCLAUDE.mdVerwenden Sie@darauf zu verweisen.

Weitere Erweiterungen