Estructura de directorios del proyecto Claude Code
Una estructura de directorios típica de un proyecto Claude Code es la siguiente:
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 -- Instrucciones principales del proyecto
CLAUDE.md
Este es el archivoque Claude lee primeroal entrar al proyecto; equivale al manual de bienvenida del proyecto.
CLAUDE.md se coloca en el directorio raíz del proyecto y es compartido por todos los miembros del equipo. Le indica a Claude: qué es este proyecto, cómo ejecutarlo y qué convenciones existen.
Contenido típico:
# 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/ # 数据模型层
💡 Consejo:Claude lee automáticamente de forma recursiva el CLAUDE.md en los directorios padre. En un monorepo, se puede colocar otro CLAUDE.md dentro del subpaquete, y Claude combinará y entenderá ambas capas de instrucciones.
CLAUDE.local.md
Capa de anulación personal, superpuesta encima de CLAUDE.md.
CLAUDE.local.md almacena preferencias o instrucciones temporales que solo te conciernen a ti; no debe compartirse con el equipo.
Contenido típico:
# 我的本地覆盖 本地数据库地址:localhost:5433(非默认端口) 调试时请优先输出详细日志。 ## 临时规则(本次任务用) 目前专注于重构 auth/ 模块,其他模块暂时不要改动。
.claude/settings.json-- Centro de permisos y configuración
settings.json
Archivo de configuración compartido por el equipo que controlaqué operaciones están permitidas o prohibidaspara Claude, como línea base de seguridad del equipo.
{
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(pytest:*)",
"Bash(git diff:*)",
"Bash(git log:*)"
],
"deny": [
"Bash(rm -rf *)",
"Bash(curl * | bash)"
]
}
}settings.local.json
Anulación local de permisos personal; permite ampliar o restringir temporalmente ciertos permisos sin afectar a otros miembros del equipo.
{
"permissions": {
"allow": [
"Bash(rm ./tmp/*)"
]
}
}
.claude/commands/-- Comandos de barra personalizados
Cada.mdarchivo del directorio se asigna automáticamente a un/project:文件名comando.
.claude/commands/Es el mecanismo central del equipo paraestandarizartareas repetitivas.
| Nombre de archivo | comando correspondiente |
|---|---|
review.md |
/project:review |
fix-issue.md |
/project:fix-issue |
deploy.md |
/project:deploy |
Ejemplo:commands/review.md
# Code Review 请对当前修改执行完整的代码审查: 1. 检查是否有安全漏洞(SQL 注入、XSS 等) 2. 验证错误处理是否完整 3. 确认测试覆盖率是否达标 4. 检查是否符合代码风格规范 5. 评估性能影响 用中文输出结构化审查报告,按严重程度排列问题。
Ejemplo:commands/fix-issue.md(con parámetros)
# Fix GitHub Issue 给定 Issue 编号 $ARGUMENTS,请: 1. 读取并理解 Issue 描述 2. 定位相关代码文件 3. 实现最小化修复方案 4. 编写对应的单元测试 5. 更新 CHANGELOG.md 调用方式:/project:fix-issue 123
💡 Paso de parámetros:En los archivos de comandos se pueden usar
$ARGUMENTSmarcadores de posición para recibir los parámetros pasados al invocarlos.
.claude/rules/-- Reglas de comportamiento modular
Las reglas de CLAUDE.md sedividen en módulosy se almacenan; Claude las cumple durante toda la sesión. Son adecuadas para convenciones de comportamiento estables a largo plazo, evitando que CLAUDE.md sea demasiado extenso.
Ejemplo:rules/code-style.md
# Code Style Rules - TypeScript 严格模式,禁用 any 类型 - 函数长度不超过 40 行,超出则拆分 - 优先使用 const,避免使用 let - 导入顺序:标准库 → 三方包 → 本地模块 - 所有 export 的函数/类型需要 JSDoc 注释 - 禁止使用 console.log,使用项目 logger
Ejemplo:rules/testing.md
# Code Style Rules - TypeScript 严格模式,禁用 any 类型 - 函数长度不超过 40 行,超出则拆分 - 优先使用 const,避免使用 let - 导入顺序:标准库 → 三方包 → 本地模块 - 所有 export 的函数/类型需要 JSDoc 注释 - 禁止使用 console.log,使用项目 logger
Ejemplo:rules/api-conventions.md
# API Conventions
- RESTful 风格,资源名使用复数形式
- 统一响应格式:{ data, error, meta }
- 错误码遵循 HTTP 标准语义
- 所有接口需要在 OpenAPI 文档中声明
- 分页参数统一使用 page / page_size
.claude/skills/-- Flujos de trabajo de invocación automática
Skills sonflujos de trabajo compuestosmás avanzados. Cuando Claude determina que una tarea se adapta a una skill, lee y ejecuta automáticamente el SKILL.md correspondiente,sin necesidad de invocación manual.。
Cada skill es un subdirectorio que contieneSKILL.md。
Ejemplo:skills/security-review/SKILL.md
# Security Review Skill ## 触发条件 当用户请求代码审查、代码涉及认证/授权/加密/用户输入处理时自动触发。 ## 执行步骤 1. 扫描 SQL 注入风险(检查所有数据库查询) 2. 检查 XSS 防护(验证输出转义) 3. 审计权限边界(确认最小权限原则) 4. 检查敏感数据处理(日志、错误信息中是否泄露) 5. 输出 OWASP Top 10 对照检查表 ## 输出格式 按 CVSS 评分排列,高危问题优先展示。
⚡ Diferencia entre Skills y Commands:
- CommandsRequiere que el usuario introduzca activamente un comando de barra para activarlo; es una "caja de herramientas".
- SkillsClaude decide automáticamente según el contexto si debe invocarlo; es un "instinto inteligente".
.claude/agents/-- Roles de subagentes
Define subagentes especializados quepueden ser enviados por la instancia principal de Claude.En tareas complejas, el agente principal delega subtareas a los roles expertos correspondientes, lograndocolaboración multiagente.Los subagentes se ejecutan en contextos aislados y tienen alcances de permisos independientes.
Ejemplo:agents/code-reviewer.md
--- name: code-reviewer description: 资深代码审查员,专注代码质量与可维护性 --- # 代码审查员 ## 角色定位 你是一名拥有 10 年经验的资深工程师,专注于代码可读性、性能优化和最佳实践。 ## 审查重点 - 命名是否清晰表达意图 - 函数/类的单一职责原则 - 边界条件和错误处理 - 性能瓶颈(N+1 查询、不必要的循环等) ## 权限 只读访问,不直接修改文件。 ## 输出格式 使用 Markdown 表格输出,包含:问题位置、严重程度、建议方案。
Ejemplo:agents/security-auditor.md
--- name: security-auditor description: 安全审计专家,专注漏洞扫描与合规审计 --- # 安全审计员 ## 角色定位 你是一名安全工程师,熟悉 OWASP、CVE 数据库和常见攻击向量。 ## 审计范围 - 认证与授权逻辑 - 输入验证与输出转义 - 依赖包已知漏洞(结合 npm audit / pip audit) - 敏感信息泄露风险 ## 权限 只读访问 + 可运行安全扫描工具。 ## 输出格式 按 CVSS 3.1 评分排列,包含:漏洞描述、影响范围、修复建议、参考链接。
Hoja de referencia rápida
| Archivo / Directorio | Commit en Git | Método de activación | Uso principal |
|---|---|---|---|
CLAUDE.md |
✅ Sí | Automático (al inicio) | Instrucciones y convenciones básicas del proyecto |
CLAUDE.local.md |
❌ No | Automático (al inicio) | Anulaciones personales, instrucciones temporales |
.claude/settings.json |
✅ Sí | Automático (al inicio) | Línea base de permisos del equipo |
.claude/settings.local.json |
❌ No | Automático (al inicio) | Anulación de permisos personal |
.claude/commands/*.md |
✅ Sí | Manual (/project:xxx) |
procesos estandarizados reutilizables) |
.claude/rules/*.md |
✅ Sí | Automático (efecto global) | Normas de comportamiento modular |
.claude/skills/*/SKILL.md |
✅ Sí | Automático (lo determina Claude) | Flujos de trabajo compuestos inteligentes |
.claude/agents/*.md |
✅ Sí | Automático (enviado por el agente principal) | Definiciones de roles de subagentes especializados |

Recomendaciones de mejores prácticas
Comienza con una configuración mínima viable:
your-project/
├── CLAUDE.md # 先从这里开始
└── .claude/
└── settings.json # 配置基本权限
A medida que el proyecto crezca, introduce gradualmente:
commands/— Cuando notes que repites las mismas instrucciones una y otra vezrules/— Cuando CLAUDE.md supere las 100 líneas, divide los módulosskills/— Cuando haya flujos de trabajo complejos de varios pasos que necesiten estandarizaciónagents/— Cuando las tareas sean tan complejas que requieran múltiples perspectivas especializadas en paralelo
Otras extensionesPrincipio:"Suficiente" es mejor que "perfecto". No construyas sistemas multiagente complejos desde el principio; introdúcelos solo cuando realmente los necesites.