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:
commands/— Wenn Sie feststellen, dass Sie wiederholt dieselben Anweisungen eingebenrules/— Wenn CLAUDE.md 100 Zeilen überschreitet, teilen Sie es in Module aufskills/— Wenn es komplexe mehrstufige Workflows gibt, die standardisiert werden müssenagents/— Wenn Aufgaben so komplex sind, dass sie mehrere professionelle Perspektiven parallel erfordern
Weitere ErweiterungenPrinzip:"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.