Capacitación

Estándar de equipo para Claude Code

30 minutos · el estándar completo, más un quiz en vivo al final.

guia-presentador.html — speech completo por slide, para tener en otra pantalla.

Regla número uno

El desarrollo se hace en Claude Code CLI

⚠️ = funciona a medias: ven parte del repo abierto, pero no corren hooks y no aplican toda la jerarquía de CLAUDE.md. No es "anda distinto", es "le faltan piezas del estándar".

El chat es solo para preguntas generales y borradores — nunca para tocar código del repo.

Motivación

¿Por qué un estándar?

1. Contexto perdido: sin repo ni CLAUDE.md, las respuestas son genéricas.
2. Cambios sin red: sin tests corridos antes/después, no sabemos si rompimos algo.
3. Conocimiento que se pierde: cada sesión arranca de cero sin memoria ni hooks.

Y la razón de fondo: necesitamos que todos sigamos el mismo set de reglas, para que el desarrollo del equipo cumpla estándares de calidad y sea explicable — que cualquiera pueda entender por qué se hizo algo de una manera y no de otra.

Primer comando

/init

Genera el CLAUDE.md del proyecto: convenciones, estructura, comandos de build/test.

$ claude
> /init

Ejemplo real — el CLAUDE.md de este mismo proyecto:

# CAPACITACION-VIERNES

Deck + quiz en vivo para la charla de estándar de Claude Code.
Node nativo (sin dependencias), server HTTP a mano.

## Stack y comandos
- Node 22+, gestor de paquetes pnpm (no npm).
- pnpm start — levanta server.js (puerto 3000, fallback 3001).
- pnpm test — corre node --test sobre test/*.test.js.

## Convenciones
- Contenido de usuario en español; código y comandos en inglés.
- TDD: tests antes que la implementación.
- data/results.json y data/host-key.txt no se versionan.

Jerarquía

Los dos niveles de CLAUDE.md que usamos

(Existe también CLAUDE.local.md, gitignored, para overrides personales de un repo — el equipo no lo usa hoy, así que no es parte del estándar.)

Template base de usuario (sin credenciales):

Contestá siempre en español.
Antes de editar un .html, guardá una copia en temp_old/.
Registrá el trabajo en un .txt o .md con marcas de tiempo.
Al interactuar con una base de datos, confirmá dos veces
  cualquier acción que no sea de solo lectura.
Nunca pongas credenciales en este archivo.

La garantía

Hooks: el estándar que se aplica solo

CLAUDE.md es una petición. Un hook es una garantía: corre siempre, pase lo que pase. Click en cada fila para ver el código real.

#!/usr/bin/env python3
"""Append the conversation to a per-project .log in ~/.claude/logs/.
Usage: log_conversation.py [user|stop]   (reads hook JSON on stdin)"""
import sys, json, os, re, datetime

def main():
    event = sys.argv[1] if len(sys.argv) > 1 else "user"
    try:
        data = json.load(sys.stdin)
    except Exception:
        return
    cwd = data.get("cwd") or "unknown"
    name = re.sub(r"[^A-Za-z0-9]", "_", cwd).strip("_") or "session"
    logdir = os.path.join(os.path.expanduser("~"), ".claude", "logs")
    os.makedirs(logdir, exist_ok=True)
    path = os.path.join(logdir, name + ".log")
    ts = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")

    if event == "user":
        text = data.get("prompt", "")
        label = "USER"
    else:
        label = "ASSISTANT"
        # ...lee el último mensaje del assistant desde transcript_path...

    with open(path, "a", encoding="utf-8") as f:
        f.write(f"[{ts}] {label}:\n{text}\n\n")

if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Before an Edit/Write to an existing .html file, copy it into a sibling
temp_old/ folder with a timestamp. Reads PreToolUse hook JSON on stdin.
Never blocks the edit (always exits 0)."""
import sys, json, os, shutil, datetime

def main():
    try:
        data = json.load(sys.stdin)
    except Exception:
        return
    f = (data.get("tool_input") or {}).get("file_path", "")
    if not f or not f.lower().endswith(".html"):
        return
    if not os.path.isfile(f):
        return  # new file, nothing to snapshot
    d = os.path.dirname(f)
    backup_dir = os.path.join(d, "temp_old")
    os.makedirs(backup_dir, exist_ok=True)
    ts = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
    dest = os.path.join(backup_dir, f"{os.path.basename(f)}.{ts}.bak")
    try:
        shutil.copy2(f, dest)
    except Exception:
        pass

if __name__ == "__main__":
    main()
    sys.exit(0)

Antes de tocar código

Modo /plan

Explorar → preguntas → plan → aprobar → ejecutar. No cambia ningún archivo hasta que lo aprobás.

Shift+Tab o /plan · obligatorio para cambios en varios archivos, features nuevas o riesgosas.

Ejemplo real — extracto del plan que armó esta misma charla (PLAN.md):

## Implementation steps
1. git init, TODO.md y WORKLOG.md. Copiar este spec a docs/. Commit.
2. Test first (TDD): escribir scoring.test.js y game.test.js,
   después lib/scoring.js y lib/game.js hasta que pasen. Commit.
3. store.js, sse.js, csv.js, server.js y api.test.js. Commit.
4. data/questions.json y data/roster.json (placeholder). Commit.
...

Vocabulario

Plugins, skills y MCP

Skills del equipo

Qué instalamos y por qué

Por rol (opcional): Ansible (infra) · docx/pdf/pptx/xlsx (documentos) · /code-review, /security-review, /simplify (todos).

QA sin backend

Checklist HTML con localStorage

Sirve para hacer QA manual después de un cambio hecho con Claude: un ítem por cada cosa que Claude tocó, para revalidarla vos mismo una por una y no dejar nada sin mirar. Guarda lo tildado en localStorage, así que sobrevive a un reload.

Ideal para frontend (un ítem por pantalla/componente que cambió), pero aplica igual a backend (un ítem por endpoint o caso de uso afectado).

Prompt estándar:
"Generá un checklist de QA en HTML para [funcionalidad],
que guarde el progreso en localStorage."

Demo en vivo: qa-checklist.html — tildar ítems → recargar → siguen tildados.

Red de contención

Tests: antes y después

Baseline → cambio → correr de nuevo → comparar.

Prompt estándar:
"Antes de tocar nada, corré los tests y guardá el resultado
como baseline. Hacé el cambio. Corré los tests de nuevo
y compará contra el baseline."

Ejemplo real 1 — test_documentacion.py (824-golang-api):

python test_documentacion.py --out baseline_run
# ...se edita el endpoint...
python test_documentacion.py --baseline baseline_run/snapshot.json

Ejemplo real 2 — comparación "threeway" (COMEX):

Repaso

El estándar en 7 puntos

1. Desarrollo solo en Claude Code CLI — el resto de los entornos funcionan a medias (⚠️).
2. /init genera el CLAUDE.md del proyecto, se commitea.
3. Usuario vs. proyecto: reglas para Claude vs. información del repo. Nunca credenciales.
4. Los hooks garantizan lo que CLAUDE.md solo pide.
5. Modo /plan para cambios grandes o riesgosos.
6. claude-mem, superpowers, impeccable, task-observer y find-skills: obligatorias. graphify: opcional.
7. Tests antes y después de cada cambio — como en test_documentacion.py.

Segunda parte

Calidad de servicio

Servir software, no solo entregarlo.

Nada de IA en esta parte: qué hace que un cliente quede conforme con lo que le entregamos, y dónde se pierde la calidad en el camino.

Qué le damos al cliente

Los tres beneficios

Dónde se pierde la calidad

“Satisfacción”: el ciclo de los 6 gaps

Donde empieza todo

Gap 1: el 80% de los quilombos de calidad están acá

Git hooks

Detección de secretos: cliente + servidor

GitLab CE no tiene secret push protection nativo (es Premium/Ultimate) — así que lo armamos con hooks propios, en dos capas.

Ambos comparten los mismos patrones (secret-patterns.sh): claves privadas, tokens de GitLab (glpat-/glrt-), claves de AWS, tokens de Slack, connection strings de DB con credenciales, y .env con valores reales.

Cuidado con esto

El costo de saltear el chequeo del servidor

git push -o secret-override="bypass" origin <branch>

Es literalmente lo que pasó el lunes-martes con zyss-web-backend: un secreto viejo reapareció por el merge de un clone desactualizado, y arreglarlo bien costó bastante más que haberlo evitado de entrada.

Ahora, en vivo

🎮 Quiz — 30 preguntas, 20s cada una

Entrá con tu nombre en /play.html

El presentador maneja el quiz desde /host.html?key=…