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:

  1. commands/— Cuando notes que repites las mismas instrucciones una y otra vez
  2. rules/— Cuando CLAUDE.md supere las 100 líneas, divide los módulos
  3. skills/— Cuando haya flujos de trabajo complejos de varios pasos que necesiten estandarización
  4. agents/— Cuando las tareas sean tan complejas que requieran múltiples perspectivas especializadas en paralelo

Principio:"Suficiente" es mejor que "perfecto". No construyas sistemas multiagente complejos desde el principio; introdúcelos solo cuando realmente los necesites.

Otras extensiones