Configuración de desarrollo de Claude Code
¿Alguna vez te has encontrado con estas situaciones?
- Cada vez que abres una nueva sesión, vuelves a tener que explicarle a Claude las convenciones de nomenclatura de nuestro proyecto.
- Claude, de repente, ejecuta un comando peligroso, como borrar archivos.
- Le pides a Claude que haga una revisión de código, y termina metiendo todo el proyecto en el contexto, algo lento y costoso.
- Has afinado cuidadosamente una serie de prácticas con Claude, y los nuevos compañeros no tienen idea de cómo reutilizarlas.
Todos estos problemas se pueden resolver con una estructura llamada Agent Development Kit (ADK, kit de desarrollo de agentes).
Su núcleo son 5 carpetas. Con estas 5 carpetas podemos convertir Claude Code en un equipo de desarrollo automatizado que tiene memoria, conoce las reglas, sabe dividir el trabajo y se puede replicar.
Estructura general:
你的项目/ ├── CLAUDE.md/ ← 第一层：记忆 ├── skills/ ← 第二层：知识 ├── hooks/ ← 第三层：护栏 ├── subagents/ ← 第四层：分工 └── plugins/ ← 第五层：复制
| Capa | Directorio / Archivo | Función | Significado clave | Analogía |
|---|---|---|---|---|
| Capa 1 | CLAUDE.md/ |
Centro de reglas globales y memoria del agente | Define las normas de comportamiento de la IA, el contexto del proyecto y las restricciones de desarrollo. | Manual de operación del proyecto de IA |
architecture.rules |
Definición de reglas de arquitectura | Establece la estructura del código, las convenciones de nomenclatura y el diseño de directorios. | Estándares de codificación del equipo técnico | |
global.md |
Memoria compartida global | Reglas a largo plazo que aplican a todos los proyectos | Memoria a largo plazo de la IA | |
project.md |
Memoria exclusiva del proyecto actual | Contexto de negocio y requisitos especiales del repositorio actual. | Versión mejorada del README del proyecto | |
| Capa 2 | skills/ |
Directorio de módulos de habilidades | Inyecta capacidades profesionales a la IA | Biblioteca de habilidades de la IA |
SKILL.md |
Archivo de descripción de habilidades | Indica a la IA cuándo debe invocar esa habilidad | Especificación de la habilidad | |
scripts/ |
Directorio de scripts de habilidades | Almacena scripts y plantillas de automatización | Caja de herramientas | |
context.md |
Contexto de la habilidad | Proporciona el conocimiento de fondo necesario para la ejecución de la habilidad | Base de conocimiento especializado | |
| Capa 3 | hooks/ |
Sistema de Hooks (ganchos) | Inserta automáticamente lógica de verificación antes y después de la ejecución. | Auditoría de seguridad automática |
PreToolUse.sh |
Hook previo a la ejecución de la herramienta | Valida antes de ejecutar el comando | "Confirmador de operaciones peligrosas" | |
PostToolUse.sh |
Hook posterior a la ejecución de la herramienta | Procesa automáticamente después de la ejecución | Formateo automático, notificaciones | |
SessionStart.sh |
Hook de inicio de sesión | Inicializa el entorno de desarrollo | Script de inicio de IDE | |
| Capa 4 | subagents/ |
Directorio de subagentes | Divide diferentes agentes especializados | Sistema de colaboración en equipo de IA |
code-reviewer.md |
Agente de revisión de código | Especializado en code review | Ingeniero reviewer | |
test-runner.md |
Agente de pruebas | Ejecuta pruebas automáticamente | Ingeniero de pruebas QA | |
explorer.md |
Agente de exploración | Analiza la estructura de la base de código | Investigador técnico | |
| Capa 5 | plugins/ |
Sistema de plugins | Distribuye capacidades de forma modular | Mercado de aplicaciones de IA |
manifest.json |
Manifiesto de configuración del plugin | Define los metadatos del plugin | npm package.json | |
marketplace.url |
Dirección del mercado de plugins | Punto de entrada para descargar y compartir plugins | Tienda de aplicaciones | |
team.install |
Script de instalación para el equipo | Sincroniza el entorno del equipo con un clic | Script de inicialización DevOps |
Cada capa resuelve un problema específico. A continuación, lo desglosamos una por una.
Capa 1:CLAUDE.md— Dale a Claude una memoria a largo plazo
¿Cuál es el problema?
Claude no tiene memoria entre sesiones. Hoy le dices que los nombres de componentes usan UpperCamelCase, y mañana, cuando abres una nueva sesión, lo ha olvidado.
Solución
En el proyecto, coloca unCLAUDE.mdarchivo y escribe en él todo lo que no quieras repetir. Al comienzo de cada sesión, Claude lo lee automáticamente.
Dos archivos, dos alcances:
| Ubicación del archivo | Alcance |
|---|---|
~/.claude/CLAUDE.md |
En tu computadoraTodos los proyectosquedan cubiertos |
Raíz del proyecto.claude/CLAUDE.md |
Solo paraeste repositorioes válido |
¿Qué escribir en él? Piensa en lo que más repites a Claude:
# 项目：我的电商平台 ## 技术栈 - 前端：Next.js 14（App Router） - 样式：Tailwind CSS - 数据库：PostgreSQL + Prisma ## 命名规范 - 组件文件：大驼峰，如 `UserCard.tsx` - 工具函数：小驼峰，如 `formatPrice.ts` - API 路由：短横线，如 `/api/user-profile` ## 注意事项 - 禁止使用 `any` 类型 - 所有异步函数必须有 try/catch - 提交代码前必须通过 ESLint 检查 - 不要直接操作 `main` 分支 ## 代码风格 - 缩进：2 个空格 - 引号：单引号 - 函数优先用箭头函数
Efecto:Ya no volverás a pegar un gran párrafo de contexto al inicio de cada conversación.
Capa 2:skills/— Guarda tu experiencia
¿Cuál es el problema?
Cada vez que pides a Claude que escriba un componente nuevo, puede que lo haga de una manera diferente: a veces añade pruebas, a veces no; a veces incluye tipos de TypeScript, a veces no.
Solución
Convierte las prácticas estándar en archivos de habilidades y colócalos en elskills/directorio. Claude, según la descripción de tu tarea,hará coincidir automáticamente e invocarála habilidad correspondiente. No necesitas escribir ningún comando.
Estructura del directorio:
skills/ ├── SKILL.md ← 技能索引（描述 + 触发条件） ├── create-component.md ← 创建 React 组件的标准流程 ├── write-api.md ← 写接口的标准流程 └── fix-bug.md ← 排查 Bug 的标准流程
¿Cómo se ve un archivo de habilidad?
---
name: create-react-component
description: >
当用户说"创建组件"、"新建页面"、"写一个 UI"时，
自动调用此技能。
---
# 创建 React 组件的标准流程
## 步骤
1. 检查 `src/components/` 下是否已存在同名组件
2. 用大驼峰命名新建 `.tsx` 文件
3. 必须定义 TypeScript interface，不允许 any
4. 同步在 `src/stories/` 下新建对应的 Storybook 故事
5. 在 `__tests__/` 下新建单元测试文件
## 代码模板
\`\`\`tsx
interface Props {
// 在这里定义 props
}
export const ComponentName: React.FC<Props> = ({ }) => {
return <div>{/* 内容 */}</div>;
};
\`\`\`
Efecto:Si dices 'ayúdame a crear un componente de tarjeta de usuario', Claude sigue automáticamente el flujo estándar de tu equipo, sin omitir pruebas, tipos ni documentación.
💡 En términos sencillos:Es como escribir un 'manual de operaciones' para un empleado nuevo; él sigue el manual y no necesita que lo estés vigilando cada vez.
Capa 3:hooks/— Establece una protección que no se puede evadir
¿Cuál es el problema?
A veces la IA realiza operaciones que absolutamente no deseas, como borrar la base de datos directamente en producción o ejecutar unrm -rfcomando. Para estas cosas no es fiable confiar en poner en el prompt que no lo haga.
Solución
Los Hooks sonscripts de Shell que se ejecutan automáticamente antes y después de cada llamada a herramientas de Claude. Son lógica de código pura, de ejecución determinista, que la IA no puede evitar.
Tres archivos principales:
hooks/ ├── PreToolUse.sh ← 工具调用「之前」运行 ├── PostToolUse.sh ← 工具调用「之后」运行 └── SessionStart.sh ← 会话「开始时」运行
Ejemplo de PreToolUse.sh: interceptar comandos peligrosos:
#!/bin/bash # 检查 Claude 准备执行的命令 TOOL_INPUT="$2" # 禁止执行 rm -rf / if echo "$TOOL_INPUT" | grep -qE "rm\s+-rf\s+/"; then echo "已拦截：禁止执行破坏性删除命令" >&2 exit 1 fi # 禁止在没有确认的情况下操作生产数据库 if echo "$TOOL_INPUT" | grep -q "prod_db" && echo "$TOOL_INPUT" | grep -qE "DROP|DELETE"; then echo "已拦截：生产数据库的破坏性操作需要人工确认" >&2 exit 1 fi exit 0
Ejemplo de PostToolUse.sh: formatear automáticamente después de guardar el archivo:
#!/bin/bash
# 每次 Claude 写完文件，自动跑 lint 和格式化
TOOL_NAME="$1"
FILE_PATH="$2"
if [ "$TOOL_NAME" = "write_file" ]; then
case "$FILE_PATH" in
*.ts|*.tsx|*.js|*.jsx)
npx eslint --fix "$FILE_PATH"
npx prettier --write "$FILE_PATH"
echo "已自动格式化：$FILE_PATH"
;;
esac
fi
Efecto:
- Claude ejecuta automáticamente el lint después de escribir código; no necesitas ejecutarlo manualmente.
- Los comandos peligrosos se bloquean antes de ejecutarse; ni siquiera tienes que mirarlos.
- Cuando el script de despliegue termina, envía automáticamente una notificación de Slack al equipo.
💡 En términos sencillos:Es como el control de calidad en una línea de producción. Antes de salir de fábrica, el producto pasa obligatoriamente por una inspección; los que no cumplen las especificaciones se rechazan directamente, sin depender del criterio personal del trabajador.
Capa 4:subagents/— Asigna cada tarea al especialista adecuado
¿Cuál es el problema?
Si Claude hace 'revisión de código + ejecutar pruebas + escribir documentación' a la vez en una sesión, el contexto es cada vez más grande y lento, y las tareas interfieren entre sí.
Solución
Divide las diferentes tareas y asígnalas asubagentes independientes. Cada subagente tiene su propia ventana de contexto independiente y permisos de herramientas exclusivos; solo hace una cosa y, cuando termina, informa del resultado.
Estructura del directorio:
subagents/ ├── code-reviewer.md ← 专门做代码审查 ├── test-runner.md ← 专门跑测试 └── doc-writer.md ← 专门写文档
Ejemplo de code-reviewer.md:
--- name: code-reviewer description: PR 需要代码审查时调用此代理 tools: - read_file # 只允许读文件 permissions: - read_only # 只读权限，绝对不会误操作 --- # 代码审查专用代理 你是一名资深代码审查员。你只会收到 git diff，不需要了解整个项目。 你没有写入权限，只能阅读和分析。 ## 审查清单 - [ ] 有没有硬编码的密钥或密码？ - [ ] 新函数有没有对应的单元测试？ - [ ] TypeScript 类型是否明确，有没有 any？ - [ ] 异步操作有没有错误处理？ - [ ] 有没有遗留的 console.log？ ## 输出格式 1. **总体评价**：一句话说清楚 2. **必须修改**：阻塞合并的问题 3. **建议优化**：非阻塞的改进项 4. **结论**：可以合并 / 需要修改
Flujo de funcionamiento general:
你说："帮我审查这个 PR 并运行测试"
│
├──→ 调用 code-reviewer 子代理
│ 独立上下文，只看 diff，只读权限
│ 返回：结构化审查报告
│
├──→ 调用 test-runner 子代理
│ 独立上下文，有执行测试的权限
│ 返回：测试通过/失败摘要
│
└──→ 主会话汇总结果，上下文始终保持干净
💡 En términos sencillos:Es como un capataz de obra. Él no escribe código, pero tiene a su cargo electricistas, albañiles y carpinteros especializados. Cada uno hace su trabajo, sin interferencias, y al final el capataz informa del avance de forma unificada.
Capa 5:plugins/— Comparte con todo el equipo con un clic
¿Cuál es el problema?
Pasaste varios días dejando bien afinadas las cuatro capas anteriores, pero cuando un nuevo compañero se incorpora, ¿cómo conoce esta configuración? ¿Acaso tiene que volver a configurarla?
Solución
Empaqueta todo el sistema como un plugin. Un nuevo miembro ejecuta un comando y al instante tiene un entorno de trabajo de Claude Code idéntico al tuyo.
Estructura de directorios:
plugins/ ├── manifest.json ← 描述插件包含什么 ├── marketplace.url ← 分享链接 └── team.install ← 一键安装脚本
Ejemplo de team.install:
#!/bin/bash echo "🚀 正在安装团队 ADK 配置..." # 安装项目级 CLAUDE.md cp ./CLAUDE.md/project.md ./.claude/CLAUDE.md # 安装所有技能 mkdir -p ./.claude/skills && cp -r ./skills/* ./.claude/skills/ # 安装钩子（记得加执行权限） mkdir -p ./.claude/hooks && cp -r ./hooks/* ./.claude/hooks/ chmod +x ./.claude/hooks/*.sh # 安装子代理 mkdir -p ./.claude/subagents && cp -r ./subagents/* ./.claude/subagents/ echo "安装完成！Claude Code 已配置为团队模式。"
El primer día de trabajo del nuevo compañero:
bash plugins/team.install
Listo. Usa exactamente el mismo Claude Code que tú.
💡 Comprensión sencilla:Es como el "paquete de configuración de computadora para nuevos empleados" de la empresa. El departamento de TI crea una imagen, el nuevo empleado la instala con un clic, y el entorno es idéntico al de los empleados antiguos, sin necesidad de configurar manualmente uno por uno.
Diagrama de flujo completo: cómo colaboran las 5 capas
开发者输入任务
│
▼
CLAUDE.md → 加载项目规范和背景知识
│
▼
skills/ → 匹配任务类型，调用对应工作流
│
▼
hooks/PreToolUse → 执行前检查，拦截危险操作
│
▼
subagents/ → 复杂任务拆分给专属子代理执行
│
▼
hooks/PostToolUse→ 执行后处理，自动格式化/通知
│
▼
plugins/ → 整套配置一键同步给所有团队成员
Resumen de los problemas que resuelve cada una de las 5 capas
| Nivel | Carpeta | Qué problema resuelve | Analogía |
|---|---|---|---|
| Primera capa | CLAUDE.md/ |
Claude siempre olvida las normas del proyecto | Manual del empleado |
| Segunda capa | skills/ |
Las tareas del mismo tipo se realizan de forma inconsistente cada vez | Manual de operaciones |
| Tercera capa | hooks/ |
Las operaciones peligrosas no se pueden prevenir | Control de calidad en la línea de producción |
| Cuarta capa | subagents/ |
Expansión del contexto en tareas complejas | División especializada del trabajo |
| Quinta capa | plugins/ |
La configuración no se puede reutilizar en el equipo | Paquete de incorporación para nuevos empleados |
Inicio rápido: 3 cosas que puedes hacer hoy
Si crees que configurarlo todo de una vez es demasiado complicado, puedes empezar por lo que ofrece el mayor retorno:
Paso 1 (5 minutos):Crea unCLAUDE.md, y escribe en él los antecedentes del proyecto que más repites a Claude.
Paso 2 (10 minutos):Crea unhooks/PreToolUse.sh, y añade algunas reglas de bloqueo para los comandos peligrosos que menos quieres que Claude ejecute.
Paso 3 (30 minutos):Escribe el tipo de tarea que más realizas (por ejemplo, "crear componentes") como el primerskills/archivo, y acumula los estándares de tu equipo.
Las capas restantes se pueden ir completando sobre la marcha, no es necesario hacerlo todo de una vez.
Otras extensionesEste sistema se llamaAgent Development Kit（ADK）. Estructura de cinco capas, un stack.
No necesitas más herramientas, solo 5 carpetas.