# Instrucciones para el agente: Bitbucket Agentic Pipelines: analiza fallos desde la CI

Pega este texto a tu agente (Claude Code, Codex, OpenCode, Hermes o el que uses) y dile «ayúdame a montarlo». Son los pasos para ponerlo en marcha; el porqué de cada pieza está en la guía completa.

- Dificultad: intermedio
- Guía completa: https://lab.wisd.ai/hub/bitbucket-agentic-pipelines

---

## Para el agente: cómo acompañar al usuario

1. Pregunta primero para qué lo quiere. Si su objetivo no necesita algún paso, sáltalo.
2. Antes de instalar, comprueba lo que ya tiene (versiones, claves, sistema operativo).
3. Avanza un paso cada vez: explica en una frase qué vas a hacer y deja que el usuario lo ejecute o lo apruebe.
4. Tras cada paso, comprueba que funcionó antes de seguir. Si falla, para y explica el error.
5. No inventes comandos ni opciones: si la documentación del proyecto contradice estos pasos, manda la documentación.
6. Al terminar, haz una prueba real con el objetivo del usuario y dile dónde profundizar.

---

## Pasos de configuración

### Paso 1: habilita la función

Comprueba que el repositorio tiene Pipelines disponible y que puedes cambiar los ajustes de IA del espacio de trabajo.

En Workspace settings, AI, AI features activa Agentic Pipelines. En AI, Agentic Pipelines habilita Claude si vas a usarlo.

### Paso 2: prepara autenticación

Para esta vía Claude, configura `ANTHROPIC_API_KEY` como variable segura del repositorio o espacio de trabajo. La alternativa oficial es `CLAUDE_CODE_OAUTH_TOKEN`; usa un método, con una credencial dedicada. No escribas su valor en `bitbucket-pipelines.yml`.

### Paso 3: usa el ejemplo oficial

Guarda esta adaptación del ejemplo [explain-test-failure](https://support.atlassian.com/bitbucket-cloud/docs/agentic-pipelines/#Quick-start-guide-to-run-your-first-agent) en `bitbucket-pipelines.yml`, en la raíz de un proyecto Node con script `test`:

```yaml
image: "atlassian/default-image:5"
definitions:
  agents:
    explain-test-failure:
      provider: claude
      prompt: |
        Lee $TEST_INPUT, identifica pruebas fallidas y sus causas probables.
        Relaciona cada hallazgo con archivos y líneas cuando haya evidencia.
        Guarda el diagnóstico y próximos pasos en $TEST_ANALYSIS_OUTPUT.
pipelines:
  custom:
    explain-test-failure:
      - step:
          name: Explain test failure
          script:
            - export TEST_INPUT=input.log
            - export TEST_ANALYSIS_OUTPUT=output.md
            - npm install
            - npm test > $TEST_INPUT || true
            - agent: explain-test-failure
          artifacts:
            - output.md
```

Adapta instalación y pruebas si tu proyecto usa otro gestor. `|| true` deja continuar el diagnóstico; no prueba que los tests hayan pasado.

### Paso 4: ejecuta manualmente

Desde Pipelines, Run pipeline, elige la ejecución custom de ejemplo.

## Comprobación

Comprueba que el paso produce output.md y que el informe cita fallos presentes en el log. Confirma por separado el resultado de los tests: el ejemplo de diagnóstico captura fallos para poder analizarlos.

## Si algo falla

Si no arranca, revisa la función del workspace, el proveedor, las variables seguras y sus límites. Si necesita acciones Bitbucket, comprueba sus permisos (scopes) antes de conceder escritura al repositorio.

[Fuente del procedimiento](https://support.atlassian.com/bitbucket-cloud/docs/agentic-pipelines/).