Guía Definitiva de Configuración de Claude Code: Ganchos, Habilidades y Acciones

Claude Code convierte un repositorio de código ordinario en un miembro del equipo que puede leer, escribir, refactorizar e incluso gestionar tickets. Ya sea que seas un desarrollador independiente o parte de un equipo grande, este tutorial te ofrece una configuración práctica completa que cubre: * Memoria del proyecto a través de CLAUDE.md * Ganchos de ejecución, variables de entorno y restricciones de comandos * “Habilidades” reutilizables para patrones, pruebas y arquitectura * Servidores MCP para JIRA, GitHub, Slack … * Integración LSP para diagnósticos en tiempo real * Agentes personalizados y comandos slash * Acciones de GitHub para revisiones de PR, controles de calidad y tareas programadas

1. ¿Por qué Claude Code?

Los asistentes LLM tradicionales suelen leer el código como texto plano. Claude Code cambia eso al:

Con estos elementos, Claude se convierte en un compañero de confianza en lugar de una simple herramienta de generación de código.

2. Visión General de la Estructura del Proyecto

your‑project/
├── .claude/
│   ├── agents/          # Agentes AI personalizados
│   ├── commands/        # Comandos slash
│   ├── hooks/           # Scripts y reglas de ganchos
│   ├── skills/          # Conocimiento específico del dominio
│   ├── settings.json    # Ganchos globales y variables de entorno
│   └── settings.md      # Documentación legible
├── .mcp.json            # Configuración del servidor MCP (JIRA, GitHub, etc.)
├── .github/workflows/   # GitHub Actions
├── CLAUDE.md            # Memoria del proyecto – nivel superior
└── README.md

Tip: Almacena cualquier anulación específica del usuario en .claude/settings.local.json o un CLAUDE.local.md personal – estos archivos deben ignorarse por Git.

3. Inicio Rápido: Crea el Boilerplate

mkdir -p .claude/{agents,commands,hooks,skills}

# CLAUDE.md básica – edita según tu stack
cat <<'EOF' > CLAUDE.md
# Mi Proyecto Increíble

## Stack
- React
- TypeScript
- Node.js

## Directorios Clave
- src/components/  # UI
- src/api/         # Capa API
- tests/           # Pruebas Jest

## Estilo de Código
- Modo estricto de TypeScript
- Preferir interfaces sobre tipos
- Sin `any` – usar `unknown`
EOF

# settings.json básica con un ganchos PreToolUse simple
cat <<'EOF' > .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "[ \"$(git branch --show-current)\" != \"main\" ] || { echo '{\"block\": true, \"message\": \"Cannot edit on main branch\"}' >&2; exit 2; }",
            "timeout": 5
          }
        ]
      }
    ]
  }
}
EOF

Ejecuta git add -A && git commit -m "Initial Claude Code configuration" para guardar el esqueleto.

4. Memoria del Proyecto: CLAUDE.md

CLAUDE.md es la memoria persistente de Claude que se carga en cada sesión. Manténla concisa pero completa:

• Stack y arquitectura – Vista rápida del stack.
• Comandos clave – npm run test, npm run lint, npm run build.
• Directrices de estilo de código – Reglas de linting, estrictez de tipos.
• Directorios críticos – Dónde están los componentes, utilidades o pruebas.
• Restricciones especiales – Por ejemplo, no editar en la rama main.

Claude lee este archivo primero, así que coloca tu información más importante al principio.

5. Ganchos y Entorno: .claude/settings.json

Los ganchos te permiten interceptar llamadas a herramientas o indicaciones del usuario. Una configuración típica incluirá:

Ejemplo: Bloquear ediciones en main

"PreToolUse": [
  {"matcher": "Edit|Write", "hooks": ["if [ \"$(git branch --show-current)\" != \"main\" ]; then echo 'Allowed'; else echo 'Blocked'; fi"]}
]

También puedes añadir variables de entorno para secretos (tokens de API de JIRA, etc.). El archivo se commitea porque los secretos se referencian vía ${VAR} que se cargan en tiempo de ejecución.

6. Habilidades: Conocimiento Domain Reutilizable

Las habilidades son archivos Markdown que enseñan a Claude cómo escribir código en tu estilo. Cada habilidad vive bajo .claude/skills/{skill-name}/SKILL.md.

Ejemplo de Frontmatter de Habilidad

---
name: testing-patterns
description: Patrones de pruebas Jest para este proyecto. Usar al escribir pruebas, crear mocks o seguir la metodología TDD.
---

El campo description es crucial – Claude lo usa para decidir cuándo activar la habilidad. Incluye palabras clave en lenguaje natural (por ejemplo, test, jest, mock).

Contenido de Habilidad de Ejemplo

# Patrones de Pruebas

## Arrange-Act-Assert

```ts
// Arrange
const mockUser = getMockUser();

// Act
const result = login(mockUser);

// Assert
expect(result).toBeTruthy();

Mocking

Prefiere funciones factory sobre mocks globales para mantener las pruebas deterministas.

Añadir una Nueva Habilidad

1. Crea .claude/skills/{skill-name}/SKILL.md.
2. Escribe una descripción breve.
3. Implementa ejemplos de código.
4. Actualiza skill-rules.json si es necesario para mapear disparadores.
5. Añade el directorio de la habilidad a Git y commitea.

7. Ganchos de Evaluación de Habilidades

Cuando un usuario envía una indicación, el gancho UserPromptSubmit ejecuta un motor pequeño que busca:

• Palabras clave – por ejemplo, write test.
• Patrones de ruta – por ejemplo, src/components/*.
• Patrones de intención – expresiones regulares que capturan peticiones comunes.
• Mapeo de directorios – enlaza rutas de archivo con nombres de habilidad.

El gancho devuelve JSON especificando qué habilidades activar, por ejemplo:

{"activate": ["testing-patterns", "react-ui-patterns"]}

Tip: Mantén skill-rules.json ligero – agrega nuevas reglas conforme surjan patrones.

8. Servidores MCP: Conecta Herramientas Externas

Los servidores MCP (Model Context Protocol) brindan a Claude acceso directo a servicios como JIRA, GitHub, Slack, Sentry o Postgres. Configúralos en .mcp.json.

Ejemplo: JIRA y GitHub

{
  "mcpServers": {
    "jira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-jira"],
      "env": {"JIRA_HOST": "${JIRA_HOST}", "JIRA_EMAIL": "${JIRA_EMAIL}", "JIRA_API_TOKEN": "${JIRA_API_TOKEN}"}
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-github"],
      "env": {"GITHUB_TOKEN": "${GITHUB_TOKEN}"}
    }
  }
}

Almacena los tokens reales en variables de entorno o en un archivo .env que no se commitee.

El Comando /ticket

Un comando slash /ticket puede leer un issue de JIRA, generar una rama, implementar la funcionalidad solicitada y cerrar el ticket automáticamente. Instrucciones detalladas están disponibles en .claude/commands/ticket.md.

9. Soporte LSP

Añade plugins del Protocolo de Servidor de Lenguaje para darle a Claude diagnósticos en tiempo real:

// .claude/settings.json
"enabledPlugins": {
  "typescript-lsp@claude-plugins-official": true,
  "pyright-lsp@claude-plugins-official": true
}

Asegúrate de que los binarios LSP estén instalados (por ejemplo, npm i -g typescript-language-server). LSP le da a Claude:

• Diagnósticos – errores de tipo al editar.
• Intellisense – firmas de funciones e información de tipos.
• Navegación – saltar a definiciones.
• Autocompleciones – sugerencias contextuales.

10. Agentes y Comandos

Agentes

Los agentes son asistentes enfocados. Un agente code-reviewer podría ejecutar automáticamente una lista de verificación y comentar en pull requests.

---
name: code-reviewer
description: Revisa código TypeScript por estilo, seguridad y pruebas.
model: opus
---

Comandos

Los comandos slash ejecutan flujos de trabajo personalizados. Por ejemplo, /pr-review expande un PR, revisa los cambios y deja un comentario.

---
description: Revisa el PR actual usando una lista de verificación estándar.
allowed-tools: Bash(git:*), Read, Grep
---

Crea el archivo Markdown bajo .claude/commands/ y referencia en tus GitHub Actions.

11. Automatización con GitHub Actions

Automatiza puertas de calidad, sincronía de documentación y auditorías de dependencias con flujos de trabajo en .github/workflows/. Ejemplos típicos:

• Revisión automática de PR – dispara en eventos PR y ejecuta code-reviewer de Claude.
• Sincronía de Docs programada – programa mensual para asegurar que la documentación refleje el código más reciente.
• Calidad de Código semanal – análisis aleatorios de directorios con autocorrección.
• Auditoría de Dependencias quincenal – actualizaciones seguras con verificación de pruebas.

Un flujo de trabajo minimalista para revisión de PR:

name: PR - Claude Review
on:
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: anthropics/claude-code-action@beta
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          model: claude-opus-4-5-20251101
          prompt: |
            Review this PR using .claude/agents/code-reviewer.md standards.
            Run `git diff origin/main...HEAD` to see changes.

Añade ANTHROPIC_API_KEY a Secreto de Repositorio para el acceso a la API.

12. Mejores Prácticas

1. Comienza con CLAUDE.md – mantenlo breve pero completo.
2. Construye habilidades de forma incremental – enfócate en patrones de alto impacto.
3. Usa ganchos para tareas repetitivas – evita lint manual o fallos de prueba.
4. Crea agentes para flujos complejos – por ejemplo, triage de bugs, resumidores de PR.
5. Automatiza con GitHub Actions – programa controles de calidad y sincronías de documentación.
6. Versiona tu configuración – commitea todos los archivos excepto las anulaciones personales.
7. Protege datos sensibles – usa variables de entorno y no commitees secretos.
8. Mide costos – ejecuta una tabla de estimación de costos para mantener el uso predecible.

13. Resumen

Con esta configuración, tu repositorio es ahora:

• Autoconsciente – Claude entiende la stack, el estilo y las convenciones.
• Automatizado – el formateo, pruebas y puertas de calidad corren automáticamente.
• Conectado – tickets, PRs y chats se integran directamente con el flujo de trabajo de Claude.
• Extensible – agrega nuevas habilidades, agentes y comandos en minutos.

Comienza clonando el repositorio, personaliza los fragmentos para tu propio stack, y deja que Claude sea el compañero de equipo que nunca supiste que necesitabas.

¡Feliz codificación!