Claude Code Playbook: La guía completa para usarlo a diario

Claude Code es el agente de desarrollo de Anthropic que corre directamente en tu terminal. A diferencia de los copilots tradicionales que solo autocompletan, Claude Code puede leer tu repositorio completo, ejecutar comandos, escribir y refactorizar archivos, tuar como un agente autónomo en tu codebase.

Esta guía es un playbook práctico basado en uso real — no documentación oficial. Todo lo que está aquí lo uso en un stack de NestJS + AWS + TypeScript en producción.

Tabla de contenidos

1. Sistema de memoria — CLAUDE.md
2. MCP Servers — expandiendo las capacidades
3. Hooks — automatización y calidad de código
4. GitHub Workflow — Claude como agente en tu repo
5. Daily Driver Flow — cómo usarlo todos los días

Sistema de memoria — CLAUDE.md

El mayor error al empezar con Claude Code es tratarlo como un chatbot sin memoria. Claude Code tiene un sistema de memoria per Markdown que define cómo se comporta en cada contexto.

Los tres niveles de CLAUDE.md

¿Cuándo usar cada uno?

• CLAUDE.md: Convenciones del equipo, arquitectura del proyecto, módulos existentes, patrones obligatorios. Todo lo que un dev nuevo necesitaría saber.
• CLAUDE.local.md: Tus preferencias personales, rutas locales, instrucciones que no quieres que vean tus compañeros.
• ~/.claude/CLAUDE.md: Reglas que aplican a todos tus proyectos — por ejemplo, nunca usar any en TypeScript, siempre conventional commits, siempre DDD.

Generar el CLAUDE.md inicial

# Dentro de tu repo
claude /init

/init analiza tu repositorio y genera un CLAUDE.md de base. Siempre revisarlo y personalizarlo antes de cplo real para un proyecto NestJS + DDD

## Stack
 
- NestJS + TypeScript (strict, no `any`)
- DDD + Clean Architecture — domain / application / infrastructure
- AWS ECS Fargate + Terraform
- PostgreSQL + TypeORM
 
## Convenciones
 
- Conventional commits: feat/fix/chore/refactor/docs
- No business logic en controllers ni repositories
- Cada módulo tiene su propio bounded context
- Event-driven: usar outbox pattern para eventos cross-módulo
 
## Módulos activos
 
- `ledger` — contabilidad doble entrada
- `user` - registro de clientes
- `notification` - envio de mensajes, correos o eventos
 
## Antes de escribir código
 
1. Buscar si ya existe implementación similar en el repo
2. Respetar la estructura de módulos de arriba
3. Correr `tsc --noEmit` antes de terminar
4. Tests son obligatorios para lógica de dominio

Instrucciones inline con #

Dentro de una sesión podés darle contexto específico usando #. Clrucción, no como comentario de código:

# Estamos refactorizando el módulo ledger
# Mantener compatibilidad con la API existente
# No tocar los archivos de migración ya commiteados

Comandos de sesión esenciales

/init      # Genera CLAUDE.md analizando el repo
/compact   # Resume la conversación para liberar contexto (crucial en sesiones largas)
/commands  # Lista tus slash commands personalizados

MCP Servers — expandiendo las capacidades

Claude Code por defecto solo tiene acceso a filesystem, bash y git. Con MCP (Model Context Protocol) servers podés conectarle herramientas externas y transformarlo en un agente mucho más poderoso.

Agregar un MCP server

# Sintaxis básica
claude mcp add <nombre> <comando>
 
# Ejemplos prácticoadd playwright npx @playwright/mcp@latest
claude mcp add postgres npx @modelcontextprotocol/server-postgres postgresql://...
claude mcp add github npx @modelcontextprotocol/server-github
 
# Gestión
claude mcp list
claude mcp get <nombre>
claude mcp remove <nombre>

Tres scopes de configuración

claude mcp add --scope local    # Solo este proyecto (no commiteado)
claude mcp add --scope user     # Todos tus proyectos
claude mcp add --scope project  # Commiteado en .mcp.json — todo el equipo lo tiene

El --scope project es el equivalente al CLAUDE.md pero para tools. Commiteas .mcp.json y todos en el equipo tienen los mismos MCP servers disponibles automáticamente.

MCP servers más útiles para developers

Caso concreto: DB de staging conectada

El MCP de PostgreSQL es particularmente poderoso. Con la DB de staging conectada, Claude tiene contexto real del schema al momento de codear:

claude mcp add postgres \
  npx @modelcontextprotocol/server-postgres \
  postgresql://user:pass@staging-db:5432/myapp \
  --scope local

Con esto Claude puede:

• Inspeccionar tablas y relaciones sin que vos copie/pegues el schema
• Validar queries antes de escribirlos
• Sugerir índices basado en la estructura real
• Detectar N+1 con datos reales de staging

Hooks — automatización y calidad de código

Los hooks son el feature más subestimado de Claude Code. Te permiten ejecutar comandos automáticamente antes o después de que Claude realice acciones, creando un loop de autocorrección sin intervención manual.

Estructura básica

// .claude/settings.json
{
  "hooks": {
    "pre_tool_use": [
      {
        "matcher": "read_file",
        "command": "...",
        "on_failure": "block"
      }
    ],
    "post_tool_use": [
      {
        "matcher": "write_file|edit_file",
        "command": "...",
        "on_failure": "warn"
      }
    ]
  }
}

Matchers disponibles: write_file, edit_file, read_file, str_replace, bash

on_failure modes:

• warn — Claude ve el output y decide si continúa. Para sugerencias.
• block — Claude no puede continuar hasta resolver. Para hard rules.

Hook 1: TypeScript validation post-write

El más iás con TypeScript. Claude escribe un archivo → valida tipos → si hay errores los corrige en el mismo loop, sin que vos intervengas:

{
  "matcher": "write_file|edit_file|str_replace",
  "command": "npx tsc --noEmit",
  "on_failure": "warn"
}

Hook 2: Bloquear archivos sensibles

Hard block para que Claude no pueda leer .env, claves privadas ni archivos con secrets en el path:

{
  "matcher": "read_file",
  "command": "bash -c 'echo \"$TOOL_INPUT\" | grep -qE \"\\.env|\\.pem|\\.key|secrets\" && exit 1 || exit 0'",
  "on_failure": "block"
}

Hook 3: Anti-duplicidad

El hook más poderoso para mantener código limpio. Antes de crear un archivo nuevo, busca si ya existe algo con ese nombre en el proyecto. Claude investiga y decide si reutiliza en vez de duplicar:

{
  "matcher": "write_file",
  "command": "bash scripts/check-duplicates.sh $TOOL_INPUT_PATH",
  "on_failure": "warn"
}

Stack completo de hooks recomendado

{
  "hooks": {
    "pre_tool_use": [
      {
        "matcher": "read_file",
        "command": "bash -c 'echo \"$TOOL_INPUT\" | grep -qE \"\\.env|\\.pem|\\.key|secrets\" && exit 1 || exit 0'",
        "on_failure": "block"
      },
      {
        "matcher": "write_file",
        "command": "bash scripts/check-duplicates.sh $TOOL_INPUT_PATH",
        "on_failure": "warn"
      },
      {
        "matcher": "edit_file",
        "com": "bash -c 'echo \"$TOOL_INPUT_PATH\" | grep -q \"generated\\|dist\\|\\.d\\.ts\" && exit 1 || exit 0'",
        "on_failure": "block"
      }
    ],
    "post_tool_use": [
      {
        "matcher": "write_file|edit_file|str_replace",
        "command": "npx tsc --noEmit",
        "on_failure": "warn"
      },
      {
        "matcher": "edit_file",
        "command": "npx eslint $TOOL_INPUT_PATH --fix",
        "on_failure": "warn"
      },
      {
        "matcher": "write_file",
        "command": "npx jest --findRelatedTests $TOOL_INPUT_PATH --passWithNoTests",
        "on_failure": "warn"
      }
    ]
  }
}

GitHub Workflow — Claude como agente en tu repo

Con claude-code-action podés convertir a Claude en un agente que vive dentro de tu reorio de GitHub, activándose por eventos de PRs y issues.

Setup básico

# .github/workflows/claude.yml
name: Claude Code Agent
 
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
 
permissions:
  contents: write
  pull-requests: write
  issues: write
 
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Claude
        uses: anthropics/claude-code-action@beta
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Con esto, cualquier comentario que mencione @claude en un PR o issue activa el agente.

El caso de uso con Playwright: QA automatizado en PRs

El flujo más poderoso que mostraron es combinar el GitHub Action con el MCP server de Playwright para tener un QA agent que corre automáticamente en cada PR:

1. Dev hace PR con cambios en un flow de pago
2. Reviewer comenta: @claude verify the checkout flow on stg
3. Claude lee el diff del PR
4. Levanta Playwright y navega el staging environment
5. Valida el flow end-to-end
6. Responde en el PR con resultado + screenshots si algo falla

Trigger patterns más útiles

Daily Driver Flow — cómo usarlo todos los días

El flujo diario

Inicio  →  /init si es proyecto nuevo → revisar CLAUDE.md
Coding  →  Usar # para dar contexto de la tarea actual en la sesión
Review  →  "Review this for DDD violations and suggest improvements"
Commit  →  claude commit → Claude genera conventional commit del diff
Cierre  →  /compact para dejar contexto resumido

Prompts de alto valor

Arquitectura y diseño:

Think step by step before writing any code.
Design this module using DDD. Consider the tradeoffs before deciding.

Debug:

Explain why this test fails, then fix it without changing the test logic.

Refactor:

Refactor this without changing behavior. Check for duplicates first.

Code review:

Review this diff for N+1 queries, missing error handling, and DDD violations.

Documentación:

Generate JSDoc for all public methods in this file. Include @throws and @example.

Migraciones:

Write the migration. Verify it's reversible, then run tsc --noEmit.

Extended Thinking — cuándo usarlo

Para tareas complejas (diseño de arquitectura, debugging difícil, decisiones de tradeoffs), forzar razonamiento profundo mejora drásticamente la calidad:

"Think before responding: what are the risks of this implementation?"
"Consider multiple approaches before writing any code."
"What could go wrong with this design? Then proceed with the best option."

No es necesario para tareas mecánicas (generar un DTO, escribir un test simple). Usalo cuando el problema genuinamente requiere análisis.

Headless / CI mode

claude -p corre Claude sin interfaz interactiva — perfecto para pipelines, scripts de automatización y n8n workflows:

# Pipe directo desde stdin
claude -p "review this diff for security issues" < git.diff
 
# Generar changelog automáticamente
claude -p "summarize changes in CHANGELOG format" < release.diff >> CHANGELOG.md
 
# Como subprocess en n8n o scripts
claude -p "$(cat prompt.txt)" --output-format json

Resumen — el setle

Si empezás desde cero, este es el orden de prioridad:

1. ~/.claude/CLAUDE.md — tus reglas globales (no any, conventional commits, tu stack favorito)
2. CLAUDE.md en cada repo — arquitectura, módulos, convenciones del equipo
3. Hooks: tsc + duplicates — los dos que más impactan la calidad
4. MCP: postgres de staging — contexto real sin copy/paste
5. GitHub Action — cuando quieras automatizar reviews y QA

El setup completo toma menos de una hora y la diferencia en productividad es inmediata.