Structure des répertoires du projet Claude Code
Voici une structure type de répertoires d'un projet Claude Code :
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 -- Instructions essentielles du projet
CLAUDE.md
C'est le moment où Claude entre dans le projetle premier fichier de lecture, équivalent au manuel d'accueil du projet.
CLAUDE.md est placé dans le répertoire racine du projet et partagé par tous les membres de l'équipe. Il indique à Claude : ce qu'est ce projet, comment l'exécuter et quelles conventions existent.
Contenu typique :
# 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/ # 数据模型层
💡 Astuce :Claude lira automatiquement et de manière récursive les fichiers CLAUDE.md dans les répertoires parents. Dans un monorepo, vous pouvez placer un autre CLAUDE.md dans un sous-package, et Claude fusionnera et comprendra les instructions des deux niveaux.
CLAUDE.local.md
Couche de dérogation personnelle exclusive, superposée à CLAUDE.md.
CLAUDE.local.md stocke des préférences ou des instructions temporaires qui ne concernent que vous et ne doivent pas être partagées avec l'équipe.
Contenu typique :
# 我的本地覆盖 本地数据库地址:localhost:5433(非默认端口) 调试时请优先输出详细日志。 ## 临时规则(本次任务用) 目前专注于重构 auth/ 模块,其他模块暂时不要改动。
.claude/settings.json-- Centre des permissions et de la configuration
settings.json
Fichier de configuration partagé par l'équipe qui contrôle les opérations que Claudeautorise ou interditd'exécuter, servant de socle de sécurité pour l'équipe.
{
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(pytest:*)",
"Bash(git diff:*)",
"Bash(git log:*)"
],
"deny": [
"Bash(rm -rf *)",
"Bash(curl * | bash)"
]
}
}settings.local.json
Dérogation de permissions locale et personnelle, assouplissant ou renforçant temporairement certaines permissions sans affecter les autres membres de l'équipe.
{
"permissions": {
"allow": [
"Bash(rm ./tmp/*)"
]
}
}
.claude/commands/-- Commandes Slash personnalisées
Chacun dans le répertoire.mdle fichier est automatiquement mappé à un/project:文件名commande.
.claude/commands/est l'approche de l'équipe pour transformer des tâches répétitivesen un mécanisme central standardisé.
| Nom du fichier | commande correspondante |
|---|---|
review.md |
/project:review |
fix-issue.md |
/project:fix-issue |
deploy.md |
/project:deploy |
Exemple :commands/review.md
# Code Review 请对当前修改执行完整的代码审查: 1. 检查是否有安全漏洞(SQL 注入、XSS 等) 2. 验证错误处理是否完整 3. 确认测试覆盖率是否达标 4. 检查是否符合代码风格规范 5. 评估性能影响 用中文输出结构化审查报告,按严重程度排列问题。
Exemple :commands/fix-issue.md(avec paramètres)
# Fix GitHub Issue 给定 Issue 编号 $ARGUMENTS,请: 1. 读取并理解 Issue 描述 2. 定位相关代码文件 3. 实现最小化修复方案 4. 编写对应的单元测试 5. 更新 CHANGELOG.md 调用方式:/project:fix-issue 123
💡 Passage de paramètres :Dans le fichier de commande, vous pouvez utiliser
$ARGUMENTSdes espaces réservés pour recevoir les paramètres transmis lors de l'invocation.
.claude/rules/-- Règles comportementales modulaires
Divisez les règles dans CLAUDE.mden stockage modulaire. Claude s'y conforme toujours pendant toute la session. Convient pour stocker des conventions comportementales stables à long terme, en évitant un CLAUDE.md trop volumineux.
Exemple :rules/code-style.md
# Code Style Rules - TypeScript 严格模式,禁用 any 类型 - 函数长度不超过 40 行,超出则拆分 - 优先使用 const,避免使用 let - 导入顺序:标准库 → 三方包 → 本地模块 - 所有 export 的函数/类型需要 JSDoc 注释 - 禁止使用 console.log,使用项目 logger
Exemple :rules/testing.md
# Code Style Rules - TypeScript 严格模式,禁用 any 类型 - 函数长度不超过 40 行,超出则拆分 - 优先使用 const,避免使用 let - 导入顺序:标准库 → 三方包 → 本地模块 - 所有 export 的函数/类型需要 JSDoc 注释 - 禁止使用 console.log,使用项目 logger
Exemple :rules/api-conventions.md
# API Conventions
- RESTful 风格,资源名使用复数形式
- 统一响应格式:{ data, error, meta }
- 错误码遵循 HTTP 标准语义
- 所有接口需要在 OpenAPI 文档中声明
- 分页参数统一使用 page / page_size
.claude/skills/-- Flux de travail invoqués automatiquement
Les Skills sont des flux de travail compositesplus avancés. Lorsque Claude détermine qu'une tâche convient à un skill, il lit et exécute automatiquement le SKILL.md correspondant,aucune invocation manuelle nécessaire.。
Chaque compétence est un sous-répertoire, contenantSKILL.md。
Exemple :skills/security-review/SKILL.md
# Security Review Skill ## 触发条件 当用户请求代码审查、代码涉及认证/授权/加密/用户输入处理时自动触发。 ## 执行步骤 1. 扫描 SQL 注入风险(检查所有数据库查询) 2. 检查 XSS 防护(验证输出转义) 3. 审计权限边界(确认最小权限原则) 4. 检查敏感数据处理(日志、错误信息中是否泄露) 5. 输出 OWASP Top 10 对照检查表 ## 输出格式 按 CVSS 评分排列,高危问题优先展示。
⚡ Différence entre les compétences et les commandes :
- CommandesNécessite que l'utilisateur saisisse activement une commande slash pour déclencher ; c'est une "boîte à outils"
- CompétencesClaude détermine automatiquement s'il faut l'invoquer en fonction du contexte ; c'est un "instinct intelligent"
.claude/agents/-- Rôles des sous-agents
Définit ce qui peut être dispatché par l'instance principale de ClaudeSous-agents professionnels dispatchés. Dans les tâches complexes, l'agent principal délègue les sous-tâches aux rôles experts correspondants, ce qui permet unecollaboration multi-agents. Les sous-agents s'exécutent dans des contextes isolés et disposent de périmètres d'autorisation indépendants.
Exemple :agents/code-reviewer.md
--- name: code-reviewer description: 资深代码审查员,专注代码质量与可维护性 --- # 代码审查员 ## 角色定位 你是一名拥有 10 年经验的资深工程师,专注于代码可读性、性能优化和最佳实践。 ## 审查重点 - 命名是否清晰表达意图 - 函数/类的单一职责原则 - 边界条件和错误处理 - 性能瓶颈(N+1 查询、不必要的循环等) ## 权限 只读访问,不直接修改文件。 ## 输出格式 使用 Markdown 表格输出,包含:问题位置、严重程度、建议方案。
Exemple :agents/security-auditor.md
--- name: security-auditor description: 安全审计专家,专注漏洞扫描与合规审计 --- # 安全审计员 ## 角色定位 你是一名安全工程师,熟悉 OWASP、CVE 数据库和常见攻击向量。 ## 审计范围 - 认证与授权逻辑 - 输入验证与输出转义 - 依赖包已知漏洞(结合 npm audit / pip audit) - 敏感信息泄露风险 ## 权限 只读访问 + 可运行安全扫描工具。 ## 输出格式 按 CVSS 3.1 评分排列,包含:漏洞描述、影响范围、修复建议、参考链接。
Aide-mémoire
| Fichier / Répertoire | Commit dans Git | Méthode de déclenchement | Objectif principal |
|---|---|---|---|
CLAUDE.md |
✅ Oui | Automatique (au démarrage) | Instructions et conventions de base du projet |
CLAUDE.local.md |
❌ Non | Automatique (au démarrage) | Remplacements personnels, instructions temporaires |
.claude/settings.json |
✅ Oui | Automatique (au démarrage) | Autorisations de base de l'équipe |
.claude/settings.local.json |
❌ Non | Automatique (au démarrage) | Remplacements personnels des autorisations |
.claude/commands/*.md |
✅ Oui | Manuel (/project:xxx) |
Flux de travail standardisés réutilisables |
.claude/rules/*.md |
✅ Oui | Automatique (applicable globalement) | Lignes directrices comportementales modulaires |
.claude/skills/*/SKILL.md |
✅ Oui | Automatique (évalué par Claude) | Flux de travail composites intelligents |
.claude/agents/*.md |
✅ Oui | Automatique (distribué par l'agent principal) | Définitions des rôles des sous-agents professionnels |

Recommandations de bonnes pratiques
Commencez par une configuration minimale viable :
your-project/
├── CLAUDE.md # 先从这里开始
└── .claude/
└── settings.json # 配置基本权限
À mesure que le projet grandit, introduisez progressivement :
commands/— Lorsque vous vous surprenez à saisir plusieurs fois les mêmes instructionsrules/— Lorsque CLAUDE.md dépasse 100 lignes, scindez-le en modulesskills/— Lorsqu'il existe des workflows complexes à plusieurs étapes qui nécessitent d'être standardisésagents/— Lorsque les tâches sont suffisamment complexes pour nécessiter plusieurs perspectives professionnelles en parallèle
Autres extensionsPrincipe :"Assez bon" vaut mieux que "parfait". Ne construisez pas un système multi-agents complexe dès le départ ; ne l'introduisez que lorsqu'il est vraiment nécessaire.