Claude Code Projektverzeichnisstruktur

Eine typische Claude Code Projektverzeichnisstruktur sieht wie folgt aus:

your-project/
├── CLAUDE.md                    ← 团队共享指令,提交到 git
├── CLAUDE.local.md              ← 个人覆盖,被 git 忽略
└── .claude/
    ├── settings.json            ← 权限 + 配置,提交到 git
    ├── settings.local.json      ← 个人权限,被 git 忽略
    ├── commands/                ← 自定义斜杠命令
    │   ├── review.md            →  /project:review
    │   ├── fix-issue.md         →  /project:fix-issue
    │   └── deploy.md            →  /project:deploy
    ├── rules/                   ← 模块化指令文件(全局生效)
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    ├── skills/                  ← 自动调用的工作流
    │   ├── security-review/
    │   │   └── SKILL.md
    │   └── deploy/
    │       └── SKILL.md
    └── agents/                  ← 子代理角色定义
        ├── code-reviewer.md
        └── security-auditor.md


CLAUDE.md -- Projekt-Kernanweisungen

CLAUDE.md 

Dies ist die Datei, die Claude beim Eintritt ins Projektzuerst liest, gleichbedeutend mit dem Willkommenshandbuch des Projekts.

CLAUDE.md befindet sich im Projektstammverzeichnis und wird von allen Teammitgliedern geteilt. Es teilt Claude mit: was dieses Projekt ist, wie es ausgeführt wird und welche Konventionen gelten.

Typischer Inhalt:

# My Project

一句话描述项目用途。

## Tech Stack
- Backend: Python / FastAPI
- Frontend: React + TypeScript
- Database: PostgreSQL

## Common Commands
\`npm run dev\`    # 启动开发服务器
\`pytest tests/\`  # 运行测试
\`npm run build\`  # 构建生产版本

## Code Conventions
- 使用 snake_case 命名变量
- 所有 API 需要写单元测试
- PR 合并前必须通过 CI

## Architecture Overview
src/
├── api/        # FastAPI 路由层
├── services/   # 业务逻辑层
└── models/     # 数据模型层

💡 Tipp:Claude liest CLAUDE.md in übergeordneten Verzeichnissen automatisch rekursiv ein. In einem Monorepo kannst du eine weitere CLAUDE.md in einem Unterpaket platzieren, und Claude fügt beide Anweisungsebenen zusammen und versteht sie.

CLAUDE.local.md

Persönliche exklusive Überschreibungsebene, die über CLAUDE.md gelegt wird.

CLAUDE.local.md speichert Präferenzen oder temporäre Anweisungen, die nur für dich relevant sind und nicht mit dem Team geteilt werden sollten.

Typischer Inhalt:

# 我的本地覆盖

本地数据库地址:localhost:5433(非默认端口)

调试时请优先输出详细日志。

## 临时规则(本次任务用)
目前专注于重构 auth/ 模块,其他模块暂时不要改动。


.claude/settings.json-- Berechtigungen und Konfigurationszentrale

settings.json

Von Team gemeinsam genutzte Konfigurationsdatei, die steuert, welche Operationen Claudeerlauben oder verbietendarf, und als Sicherheitsbasislinie des Teams dient.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(pytest:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl * | bash)"
    ]
  }
}

settings.local.json

Persönliche lokale Berechtigungsüberschreibung, die bestimmte Berechtigungen vorübergehend lockert oder verschärft, ohne andere Teammitglieder zu beeinflussen.

{
  "permissions": {
    "allow": [
      "Bash(rm ./tmp/*)"
    ]
  }
}


.claude/commands/-- Benutzerdefinierte Slash-Befehle

Jede im Verzeichnis.mdDatei wird automatisch einem/project:文件名Befehl.

.claude/commands/ist der Ansatz des Teams, wiederkehrende Aufgabenin einen standardisiertenKernmechanismus umzuwandeln.

Dateiname entsprechenden Befehl
review.md /project:review
fix-issue.md /project:fix-issue
deploy.md /project:deploy

Beispiel:commands/review.md

# Code Review

请对当前修改执行完整的代码审查:

1. 检查是否有安全漏洞(SQL 注入、XSS 等)
2. 验证错误处理是否完整
3. 确认测试覆盖率是否达标
4. 检查是否符合代码风格规范
5. 评估性能影响

用中文输出结构化审查报告,按严重程度排列问题。

Beispiel:commands/fix-issue.md(mit Parametern)

# Fix GitHub Issue

给定 Issue 编号 $ARGUMENTS,请:

1. 读取并理解 Issue 描述
2. 定位相关代码文件
3. 实现最小化修复方案
4. 编写对应的单元测试
5. 更新 CHANGELOG.md

调用方式:/project:fix-issue 123

💡 Parameterübergabe:In der Befehlsdatei können Sie$ARGUMENTSPlatzhalter verwenden, um beim Aufruf übergebene Parameter zu empfangen.


.claude/rules/-- Modulare Verhaltensregeln

Teilen Sie die Regeln in CLAUDE.mdin modulareSpeicherung auf. Claude hält sie während der gesamten Sitzung stets ein. Geeignet zum Speichern langfristig stabiler Verhaltenskonventionen, wobei eine übermäßig aufgeblähte CLAUDE.md vermieden wird.

Beispiel:rules/code-style.md

# Code Style Rules

- TypeScript 严格模式,禁用 any 类型
- 函数长度不超过 40 行,超出则拆分
- 优先使用 const,避免使用 let
- 导入顺序:标准库 → 三方包 → 本地模块
- 所有 export 的函数/类型需要 JSDoc 注释
- 禁止使用 console.log,使用项目 logger

Beispiel:rules/testing.md

# Code Style Rules

- TypeScript 严格模式,禁用 any 类型
- 函数长度不超过 40 行,超出则拆分
- 优先使用 const,避免使用 let
- 导入顺序:标准库 → 三方包 → 本地模块
- 所有 export 的函数/类型需要 JSDoc 注释
- 禁止使用 console.log,使用项目 logger

Beispiel:rules/api-conventions.md

# API Conventions

- RESTful 风格,资源名使用复数形式
- 统一响应格式:{ data, error, meta }
- 错误码遵循 HTTP 标准语义
- 所有接口需要在 OpenAPI 文档中声明
- 分页参数统一使用 page / page_size


.claude/skills/-- Automatisch aufgerufene Workflows

Skills sind fortgeschrittenerezusammengesetzte Workflows. Wenn Claude feststellt, dass eine Aufgabe für einen Skill geeignet ist, liest und führt es automatisch die entsprechende SKILL.md aus,kein manueller Aufruf erforderlich。

Jeder Skill ist ein Unterverzeichnis und enthältSKILL.md。

Beispiel:skills/security-review/SKILL.md

# Security Review Skill

## 触发条件
当用户请求代码审查、代码涉及认证/授权/加密/用户输入处理时自动触发。

## 执行步骤
1. 扫描 SQL 注入风险(检查所有数据库查询)
2. 检查 XSS 防护(验证输出转义)
3. 审计权限边界(确认最小权限原则)
4. 检查敏感数据处理(日志、错误信息中是否泄露)
5. 输出 OWASP Top 10 对照检查表

## 输出格式
按 CVSS 评分排列,高危问题优先展示。

⚡ Unterschied zwischen Skills und Befehlen:

  • BefehleErfordert, dass der Benutzer aktiv einen Slash-Befehl eingibt, um ausgelöst zu werden; es ist eine "Toolbox"
  • SkillsClaude entscheidet automatisch anhand des Kontexts, ob sie aufgerufen werden; es ist "intelligenter Instinkt"


.claude/agents/-- Subagent-Rollen

Definiert Rollen, die von der Haupt-Claude-Instanz entsandt werden könnenEntsandte professionelle Subagenten. In komplexen Aufgaben delegiert der Hauptagent Teilaufgaben an entsprechende Expertenrollen und erreicht dadurchMulti-Agenten-Zusammenarbeit. Subagenten laufen in isolierten Kontexten und haben unabhängige Berechtigungsumfänge.

Beispiel:agents/code-reviewer.md

---
name: code-reviewer
description: 资深代码审查员,专注代码质量与可维护性
---

# 代码审查员

## 角色定位
你是一名拥有 10 年经验的资深工程师,专注于代码可读性、性能优化和最佳实践。

## 审查重点
- 命名是否清晰表达意图
- 函数/类的单一职责原则
- 边界条件和错误处理
- 性能瓶颈(N+1 查询、不必要的循环等)

## 权限
只读访问,不直接修改文件。

## 输出格式
使用 Markdown 表格输出,包含:问题位置、严重程度、建议方案。

Beispiel:agents/security-auditor.md

---
name: security-auditor
description: 安全审计专家,专注漏洞扫描与合规审计
---

# 安全审计员

## 角色定位
你是一名安全工程师,熟悉 OWASP、CVE 数据库和常见攻击向量。

## 审计范围
- 认证与授权逻辑
- 输入验证与输出转义
- 依赖包已知漏洞(结合 npm audit / pip audit)
- 敏感信息泄露风险

## 权限
只读访问 + 可运行安全扫描工具。

## 输出格式
按 CVSS 3.1 评分排列,包含:漏洞描述、影响范围、修复建议、参考链接。


Spickzettel

Datei / Verzeichnis Commit zu Git Auslösemethode Kernzweck
CLAUDE.md ✅ Ja Automatisch (beim Start) Grundlegende Projektanweisungen und Konventionen
CLAUDE.local.md ❌ Nein Automatisch (beim Start) Persönliche Überschreibungen, temporäre Anweisungen
.claude/settings.json ✅ Ja Automatisch (beim Start) Team-Berechtigungsbasis
.claude/settings.local.json ❌ Nein Automatisch (beim Start) Persönliche Berechtigungsüberschreibungen
.claude/commands/*.md ✅ Ja Manuell (/project:xxx) Wiederverwendbare standardisierte Workflows
.claude/rules/*.md ✅ Ja Automatisch (global wirksam) Modulare Verhaltensrichtlinien
.claude/skills/*/SKILL.md ✅ Ja Automatisch (von Claude beurteilt) Intelligente zusammengesetzte Workflows
.claude/agents/*.md ✅ Ja Automatisch (vom Hauptagenten ausgelöst) Professionelle Rollendefinitionen für Sub-Agenten


Best-Practice-Empfehlungen

Beginnen Sie mit einer minimalen lebensfähigen Konfiguration:

your-project/
├── CLAUDE.md        # 先从这里开始
└── .claude/
    └── settings.json    # 配置基本权限

Wenn das Projekt wächst, führen Sie nach und nach ein:

  1. commands/— Wenn Sie feststellen, dass Sie wiederholt dieselben Anweisungen eingeben
  2. rules/— Wenn CLAUDE.md 100 Zeilen überschreitet, teilen Sie es in Module auf
  3. skills/— Wenn es komplexe mehrstufige Workflows gibt, die standardisiert werden müssen
  4. agents/— Wenn Aufgaben so komplex sind, dass sie mehrere professionelle Perspektiven parallel erfordern

Prinzip:"Gut genug" schlägt "perfekt." Bauen Sie nicht von Anfang an ein komplexes Multi-Agenten-System auf; führen Sie es erst ein, wenn es wirklich benötigt wird.

Weitere Erweiterungen