Guía de Operaciones para Equipos Humanos + Agentes de IA

Llevo semanas construyendo un sistema donde humanos y agentes de IA trabajan juntos en los mismos proyectos. No como concepto — como operación real, con tickets, código, y deadlines.

Este documento es la guía que uso internamente en GNB Labs. La publico porque creo que el mayor valor no está en guardar el proceso, sino en compartirlo para que otros lo adapten.

Principio rector: Linear es la única fuente de verdad. Todo trabajo que no está en Linear, no existe.

Cómo funciona el equipo

Este equipo opera con dos tipos de miembros:

Tipo	Quién	Cómo se comunica
Humano	Gabriel, colaboradores	Slack (mensajes), Linear (issues), GitHub (PRs)
Agente	Claude Code via Trigger.dev	Linear (lee tickets, escribe comentarios), GitHub (crea branches, abre PRs), Slack (notificaciones de estado)

El flujo fundamental es siempre el mismo:

Ticket en Linear → Agente lo toma → Trabaja en GitHub → Abre PR → Humano revisa → Slack notifica

Linear — La fuente de verdad

Estructura del workspace

Workspace: GNB Labs
├── Team: Core (trabajo interno, infra, agentes)
├── Team: Clientes (un proyecto por cliente activo)
└── Team: Contenido (posts, diario, podcast)

Cómo escribir issues que los agentes entiendan

Los agentes leen el título del issue para entender qué hacer. Formato: verbo + objeto + contexto.

✅  Crear integración Airtable → GoHighLevel para cliente Oscar
✅  Refactorizar job check-tickets en Trigger.dev
✅  Generar post LinkedIn sobre arquitectura de agentes
❌  Fix bug
❌  Actualizar cosas

Labels obligatorios

Todos los issues deben tener al menos un label de cada grupo:

Grupo	Opciones
Tipo	`feature` · `bug` · `chore` · `content` · `research`
Ejecutor	`human-only` · `agent-ok` · `agent-first`
Stack	`n8n` · `airtable` · `trigger-dev` · `claude-code` · `github`

El label agent-ok indica que un agente puede intentarlo. agent-first indica que debe asignarse a un agente por defecto.

Estados del flujo

Backlog → Ready → In Progress → In Review → Waiting (cliente/humano) → Done

Ready = el issue tiene descripción completa y puede ser tomado
In Progress = alguien (humano o agente) está trabajando
Waiting = bloqueado por algo externo
In Review = PR abierto, esperando revisión humana

Anatomía de un issue bien escrito para agentes

Los agentes de Claude leen la descripción completa. Cuanto más contexto, mejor resultado:

## Objetivo
[Una oración de qué queremos lograr]

## Contexto
[Por qué esto importa, qué hay que saber antes]

## Criterios de aceptación
- [ ] Criterio 1
- [ ] Criterio 2
- [ ] Tests pasan / no hay errores

## Referencias
- Link a doc relacionado
- Issue relacionado: #123

## Notas para el agente
[Instrucciones específicas si aplica, ej: "no modificar archivo X"]

Ciclos semanales

Usar ciclos semanales (lunes a viernes). Al inicio de cada ciclo:

Mover issues Ready al ciclo actual
Asignar los agent-first sin asignar a @claude-agent
Revisar el ciclo anterior: cerrar o mover lo que quedó

Slack — El hub de comunicación

Estructura de canales

#gnb-general          → Conversaciones del equipo, anuncios
#gnb-dev              → Pull requests, CI/CD, código
#gnb-agentes          → Logs y notificaciones automáticas de agentes
#gnb-contenido        → Ideas, borradores, publicaciones
#gnb-clientes-[nombre]→ Un canal por cliente activo

Regla: Los agentes solo escriben en #gnb-agentes y en canales de cliente cuando se les indica explícitamente. Nunca en #gnb-general.

Protocolo de mensajes de agentes

🤖 [JOB_NAME] | LINEAR-123
Estado: ✅ Completado / ⚠️ Warning / ❌ Error
Resumen: [Una línea de qué hizo]
PR: https://github.com/gnb-labs/...

Slack como input de agentes via MCP

Con el MCP de Slack conectado a Claude, los agentes pueden leer canales, buscar contexto histórico de clientes, y postear actualizaciones sin intervención humana.

Ejemplo de prompt para un agente:

Lee los últimos 50 mensajes de #gnb-clientes-oscar,
identifica pendientes no resueltos, y crea issues en Linear
para cada uno con label "cliente" y prioridad "urgent".

GitHub — El entorno de ejecución

Convención de branches

feat/LINEAR-123-descripcion-corta
fix/LINEAR-456-descripcion-corta
chore/LINEAR-789-descripcion-corta
content/LINEAR-012-descripcion-corta

Los agentes siguen esta convención automáticamente si el CLAUDE.md del repo lo especifica.

CLAUDE.md — El manual del agente

Cada repo debe tener un CLAUDE.md en la raíz. Este archivo es leído automáticamente por Claude Code y define las reglas:

# CLAUDE.md — GNB Labs Main Repo

## Contexto del proyecto
[Descripción breve del repo y su propósito]

## Convenciones de código
- Usa ESLint con config existente
- Commits en español, imperativo: "Agregar job check-tickets"
- Un commit por cambio lógico

## Convenciones de branches
feat/LINEAR-[ID]-[descripcion] para features
fix/LINEAR-[ID]-[descripcion] para bugs

## Lo que NO debes hacer
- No modificar .env ni archivos de configuración de producción
- No mergear PRs — solo abrir
- No borrar branches existentes sin confirmación
- No instalar dependencias nuevas sin comentarlo en el issue

## Cómo reportar bloqueos
Si no puedes completar la tarea, deja un comentario en el issue de Linear
explicando el bloqueo y cambia el estado a "Waiting".

Claude Code Action en GitHub

# .github/workflows/claude-review.yml
name: Claude PR Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Revisa este PR. Verifica:
            1. Que el código sigue las convenciones del CLAUDE.md
            2. Que no hay errores obvios ni side effects
            3. Que el issue de Linear referenciado queda resuelto
            Sé conciso. Si todo está bien, di "LGTM ✅".

Trigger.dev — El motor de automatización

Arquitectura del repo central

gnb-labs/main-repo
└── trigger/
    ├── internal/
    │   ├── check-tickets.ts      # Polling Linear cada 30min
    │   ├── daily-diary.ts        # Genera entrada de diario
    │   └── linkedin-post.ts      # Publica contenido
    ├── shared/
    │   ├── notify-slack.ts       # Notificaciones genéricas
    │   └── pr-webhook.ts         # Recibe webhooks de GitHub
    └── clients/
        └── [PROJECT_ID]/         # Jobs específicos por cliente

El job fundamental: check-tickets

Este job es el corazón del sistema. Corre cada 30 minutos y activa a los agentes:

import { schedules } from "@trigger.dev/sdk/v3";
import { LinearClient } from "@linear/sdk";

export const checkTickets = schedules.task({
  id: "check-tickets",
  cron: "*/30 * * * *",
  run: async () => {
    const linear = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });

    // Buscar issues con label "agent-first" en estado "Ready" sin asignar
    const issues = await linear.issues({
      filter: {
        labels: { name: { eq: "agent-first" } },
        state: { name: { eq: "Ready" } },
        assignee: { null: true }
      }
    });

    for (const issue of issues.nodes) {
      await notifySlack(`🎫 Nuevo ticket: ${issue.title} (${issue.identifier})`);
      await issue.update({ stateId: IN_PROGRESS_STATE_ID });
      // Invocación de Claude Code (siguiente fase)
    }
  }
});

Los 4 flujos de trabajo

Flujo A: Tarea técnica ejecutada por agente

1. Gabriel crea issue en Linear (label: agent-first, estado: Ready)
2. check-tickets detecta el issue → lo asigna → "In Progress"
3. Claude Code lee el issue → crea branch → implementa → abre PR
4. Claude revisa su propio PR via GitHub Actions
5. Linear cambia a "In Review" → Slack notifica
6. Gabriel revisa → merge o feedback

Flujo B: Revisión de PR con @claude

1. Humano abre PR en GitHub
2. Escribe: "@claude revisa esto, especialmente la autenticación"
3. Claude lee el diff + CLAUDE.md + comentario
4. Posta revisión estructurada en el PR

Flujo C: Generación de contenido

1. Gabriel deja log de trabajo en archivo/Notion
2. Job daily-diary corre a las 20:00
3. Claude estructura el log como entrada de diario
4. Crea issue en Linear "Revisar diario [fecha]"
5. Gabriel revisa, ajusta, publica

Flujo D: Petición ad-hoc desde Slack

1. Gabriel escribe en #gnb-agentes:
   "@claude-agent: busca mensajes de esta semana en #gnb-clientes-oscar
    y crea issues en Linear para cada pendiente"
2. Agente lee el canal → identifica pendientes → crea issues
3. Reporta en el mismo thread cuántos creó y con qué IDs

Reglas de operación para agentes

Siempre hacer

Leer el issue completo antes de empezar, incluyendo comentarios
Referenciar el issue en cada commit: feat: agregar X (LINEAR-123)
Comentar en el issue si encontrás algo inesperado
Cambiar el estado del issue cuando corresponde
Notificar en Slack al terminar o si hay un bloqueo

Nunca hacer

Mergear PRs — solo abrirlos
Borrar branches de main o production
Modificar archivos de configuración de producción
Crear issues nuevos sin que un humano lo haya solicitado
Asumir que un ticket ambiguo es claro — pedir aclaración

Ante la duda

Si un issue es ambiguo o la tarea está bloqueada:

Dejar comentario en el issue explicando el bloqueo
Cambiar estado a Waiting
Enviar mensaje a #gnb-agentes con el problema

Checklist de configuración inicial

Linear

Crear workspace GNB Labs con teams: Core, Clientes, Contenido
Crear labels: agent-ok, agent-first, human-only + tipos + stack
Crear estados: Backlog, Ready, In Progress, In Review, Waiting, Done
Conectar integración con Slack y GitHub
Generar API key para Trigger.dev

Slack

Crear canales según estructura definida
Instalar app de Linear en el workspace
Conectar MCP de Slack en Claude.ai
Configurar notificaciones por canal

GitHub

Crear repo con CLAUDE.md en la raíz
Instalar claude-code-action: claude → /install-github-app
Agregar secret ANTHROPIC_API_KEY
Crear workflow claude-review.yml

Trigger.dev

Crear proyecto e instalar SDK
Configurar variables: LINEAR_API_KEY, SLACK_BOT_TOKEN, ANTHROPIC_API_KEY
Implementar y deployar job check-tickets
Verificar en dashboard que el schedule está activo

Preguntas abiertas

Estas son las incógnitas que voy resolviendo conforme escalo:

Rate limits de Linear: ¿Cómo manejar throttling con muchos tickets?
Timeout de agentes: ¿Cómo detectar que Claude Code se colgó?
Git worktrees con múltiples agentes: ¿Escala bien con 5+ agentes en paralelo?
Costos de API: ¿Cuánto cuesta un ciclo completo ticket → PR en tokens?
Auditoría: ¿Cómo saber qué cambió un agente vs un humano en retrospectiva?

Próximo paso

Mañana implemento el primer agente real: un job en Trigger.dev que toma tareas de Linear, invoca Claude Code, y abre PRs automáticamente. Lo voy a documentar todo en el diario.