luismori.

AI Coding Workflows

Gherkin BDD AI Coding

Cómo usar Gherkin en el desarrollo con IA y en flujos de ingeniería modernos

Una guía práctica de investigación para usar Gherkin, BDD, Spec-Driven Development y flujos guiados por evals, y así lograr que la entrega asistida por IA sea más clara, segura y fácil de revisar.

31 min de lectura Actualizado el 9 jun 2026

Resumen

  • Gherkin es útil en el desarrollo con IA porque convierte la intención de producto, a menudo ambigua, en ejemplos concretos que se pueden revisar.
  • Un buen escenario de Gherkin le da a un agente de código con IA tres cosas que necesita: contexto, acción y criterios de éxito observables.
  • No uses Gherkin como lenguaje de scripting para la interfaz. Úsalo para describir el comportamiento del negocio en el lenguaje del dominio.
  • Gherkin y GitHub Spec Kit resuelven distintas partes del flujo: Spec Kit le da al agente un proceso estructurado de entrega; Gherkin le da a ese proceso ejemplos concretos de aceptación.
  • Sí necesitas instalar e inicializar Spec Kit si quieres usar los comandos /speckit.*. Un archivo .feature por sí solo es una especificación en un formato convencional, a menos que también lo conectes a Cucumber u otro ejecutor de pruebas.
  • El mejor flujo no consiste en «escribir Gherkin y dejar que la IA programe todo». Consiste en:
    1. descubrir ejemplos junto con los equipos de producto, ingeniería y QA
    2. formular los ejemplos importantes en Gherkin
    3. pedirle a la IA que implemente la solución a partir de esos ejemplos
    4. automatizar las pruebas en el nivel adecuado
    5. mantener los ejemplos actualizados como documentación y protección contra regresiones
  • Gherkin encaja de forma natural con métodos modernos como BDD, Specification by Example, ATDD, TDD, Spec-Driven Development, desarrollo con IA guiado por evals y CI/CD.
  • El principal riesgo es escribir escenarios demasiado ambiguos, técnicos o extensos, o que no estén conectados con pruebas reales.

El June 9, 2026, revisé fuentes actuales de Cucumber, Agile Alliance, GitHub Spec Kit, Microsoft for Developers y la documentación de evals de OpenAI, así como artículos recientes de profesionales sobre Gherkin para programación asistida por IA. Los enlaces a las fuentes están al final.

Qué aprenderás aquí

Aprenderás:

  • por qué Gherkin está ganando utilidad, no perdiéndola, en el desarrollo asistido por IA
  • cómo escribir escenarios que ayuden tanto a las personas como a los agentes de código con IA
  • dónde encaja Gherkin en BDD, Spec-Driven Development, TDD y flujos de IA guiados por evals
  • cómo integrar Gherkin con GitHub Spec Kit sin confundir especificaciones, archivos de features, pruebas y comandos del agente
  • cómo pueden colaborar los ingenieros y PMs antes de pedirle a una IA que implemente una funcionalidad
  • cómo distinguir entre buenos y malos escenarios de Gherkin para trabajar con IA
  • cómo convertir un escenario de Gherkin en tareas de implementación, pruebas y criterios de revisión

Este artículo está dirigido a ingenieros, PMs, ingenieros de QA, gerentes de ingeniería y fundadores con perfil técnico que ya usan agentes de código con IA, o están por hacerlo, en el desarrollo de productos reales.

La idea básica

Las herramientas de programación con IA son muy buenas para generar código.

Son mucho menos eficaces cuando el equipo les da instrucciones ambiguas.

En realidad, no es un problema de IA. Es un problema de requisitos al que se le ha añadido un motor más rápido.

Gherkin ayuda porque crea un pequeño contrato:

Feature: Saved dashboard views

  Rule: A user can save a private dashboard view

    Scenario: Save a new dashboard view
      Given I am viewing a dashboard with active filters
      When I save the view as "Executive weekly"
      Then I should see "Executive weekly" in my saved views
      And the saved view should restore the same filters

Ese escenario no es solo una prueba.

Es un acuerdo conciso entre producto e ingeniería sobre:

  • para quién es el comportamiento
  • qué estado importa antes de la acción
  • qué acción importa
  • qué resultado debe ser observable
  • qué debe preservar un agente de código con IA durante la implementación

En el desarrollo con IA, ese acuerdo vale oro.

Gherkin no es lo mismo que BDD

Esta distinción importa.

BDD es el método de colaboración.

Gherkin es uno de los lenguajes que los equipos pueden usar para expresar ejemplos surgidos de esa colaboración.

La documentación actual de Cucumber sobre BDD lo describe como una forma de cerrar la brecha entre las personas de negocio y las técnicas: construir un entendimiento compartido, trabajar en iteraciones pequeñas y producir documentación del sistema que se pueda contrastar con su comportamiento.

Esa es la parte importante: primero el entendimiento compartido, después la automatización.

Si un equipo omite la conversación y solo le pide a una IA que genere archivos .feature, en realidad no está haciendo BDD. Está generando suposiciones con formato.

Por qué Gherkin ayuda en el desarrollo con IA

Los agentes de IA necesitan límites.

Sin ellos, tienden a llenar los vacíos con suposiciones plausibles:

  • «¿Esto debería ser privado o compartido?»
  • «¿Se deberían permitir nombres duplicados?»
  • «¿Eliminar una vista guardada debería eliminar el dashboard subyacente?»
  • «¿Este comportamiento se debería probar a través de la API, la interfaz o la capa de pruebas unitarias?»

Gherkin reduce esas suposiciones implícitas al convertir el comportamiento en ejemplos.

Esta es la diferencia en la práctica:

vague prompt
  -> "Build saved dashboard views"
  -> AI guesses product rules
  -> reviewer finds mismatches late

gherkin-backed prompt
  -> examples define behavior
  -> AI implements against explicit scenarios
  -> reviewer checks code against agreed examples

El valor no está en que Gherkin sea mágico.

Está en que los ejemplos concretos son más fáciles de analizar tanto para las personas como para los modelos que los requisitos abstractos.

El flujo de trabajo moderno

Este es el flujo que recomiendo a los equipos que usan herramientas de programación con IA:

product intent
  -> example mapping
  -> Gherkin scenarios
  -> AI implementation plan
  -> code + tests
  -> CI checks
  -> human review
  -> living documentation

En términos más operativos:

PM / domain expert
  explains the user need

PM + engineer + QA
  discover rules, examples, and questions

engineer + QA
  formulate key examples in Gherkin

AI coding agent
  creates an implementation plan and code changes

test suite
  verifies behavior at the right level

reviewer
  checks whether the code still matches the examples

Este flujo mantiene a la IA en el rol adecuado.

No es la responsable de producto.

No es la fuente de verdad.

Es una colaboradora rápida para la implementación que trabaja a partir de un contrato más claro.

Comienza con el mapeo de ejemplos

Antes de escribir Gherkin formal, realiza una breve sesión de mapeo de ejemplos.

El equipo de Cucumber describe el mapeo de ejemplos como una forma ligera de registrar:

  • la historia
  • las reglas
  • ejemplos para cada regla
  • preguntas sin resolver
  • historias de seguimiento que conviene separar

Esto es especialmente útil en el desarrollo con IA porque las preguntas sin resolver son precisamente los espacios donde las herramientas de IA tienden a inventar respuestas.

Ejemplo:

Story:
  Users can save dashboard views.

Rules:
  - A saved view belongs to the user who created it.
  - A saved view restores filters, columns, and sort order.
  - Saved view names must be unique per user.

Examples:
  - The one where Ana saves a dashboard with two filters.
  - The one where Ana tries to reuse an existing saved view name.
  - The one where Ben cannot see Ana's private saved view.

Questions:
  - Should admins see users' private saved views?
  - Is there a maximum number of saved views per user?
  - Do saved views include relative dates like "last 7 days"?

Observa el punto clave: todavía no necesitas un Gherkin perfecto.

Necesitas que el equipo identifique las reglas y las preguntas antes de que la IA comience a implementar.

Después, escribe Gherkin preparado para la IA

Un buen Gherkin para trabajar con IA es:

  • concreto
  • breve
  • observable
  • escrito en lenguaje de producto
  • enfocado en un solo comportamiento
  • independiente de los detalles de implementación

Un mal Gherkin para trabajar con IA es:

  • ambiguo
  • sobrecargado
  • escrito como un script de interfaz que describe cada clic
  • lleno de detalles de la base de datos
  • diseñado para cubrir cinco comportamientos en un solo escenario

Compara estas dos versiones.

Escenario débil

Scenario: User saves dashboard
  Given the user is on the page
  When the user clicks save
  Then it works

La IA puede generar casi cualquier cosa a partir de esto.

Quien revise el resultado no puede saber qué significa «funciona».

Mejor escenario

Scenario: Save a dashboard view with active filters
  Given I am viewing the revenue dashboard filtered by region "LATAM"
  And the table is sorted by "Closed revenue" descending
  When I save the view as "LATAM revenue"
  Then "LATAM revenue" should appear in my saved views
  And opening "LATAM revenue" should restore the region filter
  And the table should still be sorted by "Closed revenue" descending

Esto le da a la IA un contrato real.

Aun así, no dicta si la implementación usa estado de React, una tabla SQL, un endpoint de API o una caché. Esas decisiones pertenecen al plan técnico.

Patrón de prompt: dale a la IA el escenario y las reglas

Una vez que el equipo acuerde el comportamiento, dale a la IA un prompt con el escenario y las restricciones.

You are implementing the saved dashboard views feature.

Use these Gherkin scenarios as the acceptance contract:

Feature: Saved dashboard views

  Rule: Saved views are private per user

    Scenario: User saves a private dashboard view
      Given Ana is viewing the revenue dashboard filtered by region "LATAM"
      When Ana saves the view as "LATAM revenue"
      Then Ana should see "LATAM revenue" in her saved views
      And Ben should not see "LATAM revenue" in his saved views

Implementation instructions:
- First inspect the existing dashboard, auth, and persistence patterns.
- Propose a short plan before editing files.
- Add tests that map to each scenario.
- Prefer API or integration tests for business rules.
- Keep UI tests focused on the user-visible flow.
- Do not introduce a new persistence abstraction unless the repo already uses that pattern.

Este prompt hace cuatro cosas útiles:

  • le da a la IA ejemplos de comportamiento
  • separa el comportamiento de las instrucciones de implementación
  • le indica a la IA que revise los patrones existentes
  • hace que las pruebas sean parte de la tarea, no una ocurrencia posterior

Dónde encaja Gherkin con otras metodologías modernas

Gherkin es más útil cuando forma parte de un sistema de entrega más amplio.

No debería reemplazar todas las demás prácticas de planificación y pruebas.

BDD

BDD usa conversaciones, ejemplos y automatización para alinear a producto e ingeniería.

Gherkin es una herramienta eficaz para formular ejemplos en BDD porque los PMs pueden leerlo y los frameworks de pruebas pueden ejecutarlo.

Úsalo cuando el comportamiento requiera un entendimiento compartido entre distintos roles.

Specification by Example

Specification by Example es la idea más amplia de describir requisitos mediante ejemplos concretos en lugar de hacerlo solo con enunciados abstractos.

Gherkin es una sintaxis común para esos ejemplos.

Úsalo cuando el dominio tenga reglas, excepciones y casos límite.

ATDD

Acceptance Test-Driven Development comienza con los criterios de aceptación antes de la implementación.

Gherkin encaja bien porque cada escenario puede convertirse en una prueba de aceptación o en una lista de verificación para la revisión.

Úsalo cuando sea necesario definir explícitamente qué significa «terminado» antes de comenzar a programar.

TDD

TDD funciona en un nivel más bajo.

Un escenario de Gherkin podría decir:

Then the saved view should restore the same filters

La implementación podría requerir varias pruebas unitarias para:

  • serializar el estado de los filtros
  • validar los nombres de los filtros
  • cargar una vista guardada de un usuario
  • rechazar el acceso de otro usuario

Gherkin describe el comportamiento. TDD ayuda a diseñar el código interno.

Spec-Driven Development

GitHub Spec Kit popularizó una versión moderna de la entrega guiada por especificaciones, adecuada para trabajar con IA: define lo que quieres, acláralo, planifícalo, genera tareas y luego implementa.

Gherkin encaja en ese flujo como la capa de ejemplos de aceptación.

Spec Kit style workflow
  -> feature spec
  -> clarification
  -> plan
  -> tasks
  -> implementation

Gherkin contribution
  -> concrete examples
  -> business rules
  -> acceptance checks
  -> regression scenarios

En otras palabras, Spec-Driven Development aporta la estructura de entrega. Gherkin aporta precisión a nivel de comportamiento.

Cómo integrar Gherkin con GitHub Spec Kit

Esta parte puede resultar confusa al principio, así que separemos los componentes.

Spec Kit es una herramienta de flujo de trabajo.

Le da a tu agente de código con IA comandos y plantillas para avanzar por el proceso de entrega:

constitution
  -> specify
  -> clarify
  -> plan
  -> tasks
  -> analyze
  -> implement

Gherkin es un formato para describir comportamiento.

Le da a tu equipo una forma legible de expresar ejemplos:

Feature
  -> Rule
  -> Scenario
  -> Given / When / Then

Funcionan mejor juntos cuando Spec Kit se encarga del flujo de entrega y Gherkin de los ejemplos de aceptación.

¿Necesitas instalar Spec Kit?

Sí, si quieres usar el flujo de trabajo de Spec Kit.

Según el README actual de Spec Kit, el camino estándar es:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z
specify init my-project --integration copilot
cd my-project

La integración exacta puede variar según el agente. El README también indica que la mayoría de los agentes exponen comandos como /speckit.*, mientras que algunas integraciones exponen skills del agente en lugar de archivos de prompts para comandos con barra.

Después de la inicialización, tu agente puede usar comandos como:

/speckit.constitution
/speckit.specify
/speckit.clarify
/speckit.plan
/speckit.tasks
/speckit.analyze
/speckit.implement

Así que la respuesta corta es:

Want Spec Kit commands and generated artifacts?
  -> install and initialize Spec Kit.

Only want to write acceptance examples in Gherkin?
  -> no Spec Kit install required.

¿Un archivo de Gherkin es solo un archivo con un formato convencional?

Depende de cómo lo uses.

Un archivo .feature puede cumplir tres funciones distintas:

Uso¿Requiere instalación?Qué hace
Especificación de aceptación simpleNoLas personas y los agentes de IA lo leen como requisitos
Entrada o contexto para Spec KitSpec Kit sí, Cucumber noEl agente lo usa al especificar, planificar e implementar
Prueba BDD ejecutableCucumber o equivalente síUn ejecutor de pruebas vincula los pasos con código y verifica el comportamiento

Esta distinción es importante.

Si creas este archivo:

features/saved-dashboard-views.feature

pero no instalas Cucumber, Playwright-BDD, Behave, SpecFlow, pytest-bdd u otro ejecutor, nada lo ejecutará automáticamente.

Aun así, es útil. Puede ser un contrato de aceptación compartido.

Pero todavía no es una prueba automatizada.

Para hacerlo ejecutable, necesitas un framework de pruebas y definiciones de pasos:

features/saved-dashboard-views.feature
  -> step definitions
  -> app/test driver
  -> assertions
  -> CI result

Para la entrega asistida por IA, normalmente recomiendo comenzar con el archivo .feature como contrato legible y después automatizar solo los escenarios que merezcan cobertura de regresión.

Un flujo práctico con Spec Kit + Gherkin

Este es un flujo claro para un equipo real.

1. Initialize Spec Kit
   -> install specify-cli
   -> run specify init with your agent integration

2. Establish principles
   -> /speckit.constitution
   -> define quality, testing, security, UX, and review standards

3. Define the feature
   -> /speckit.specify
   -> describe what and why
   -> include Gherkin scenarios as acceptance examples

4. Clarify uncertainty
   -> /speckit.clarify
   -> turn vague scenario outcomes into decisions or out-of-scope notes

5. Plan implementation
   -> /speckit.plan
   -> choose architecture, data model, API shape, UI approach, and test strategy

6. Generate tasks
   -> /speckit.tasks
   -> ensure each important scenario maps to a task, test, eval, or manual check

7. Analyze consistency
   -> /speckit.analyze
   -> catch gaps between spec, plan, tasks, and acceptance examples

8. Implement
   -> /speckit.implement
   -> build against the spec and scenarios

La clave es introducir Gherkin en /speckit.specify y mantenerlo presente durante /speckit.tasks y /speckit.analyze.

Qué incluir en la especificación de la funcionalidad de Spec Kit

Dentro de la especificación de la funcionalidad generada por Spec Kit, incluiría una sección como esta:

## Acceptance Examples

```gherkin
Feature: Saved dashboard views

  Rule: Saved views are private per user

    Scenario: User saves a private dashboard view
      Given Ana is viewing the revenue dashboard filtered by region "LATAM"
      When Ana saves the view as "LATAM revenue"
      Then Ana should see "LATAM revenue" in her saved views
      And Ben should not see "LATAM revenue" in his saved views

  Rule: Saved view names are unique per user

    Scenario: User tries to reuse a saved view name
      Given Ana already has a saved view named "LATAM revenue"
      When Ana saves another view as "LATAM revenue"
      Then Ana should be asked to choose a different name
```

Después, añade una tabla de trazabilidad:

## Acceptance Traceability

| Scenario | Verification |
| --- | --- |
| User saves a private dashboard view | API integration test + one E2E happy path |
| User tries to reuse a saved view name | API integration test |
| Different users use the same saved view name | API integration test |
| Admin visibility for private views | Out of scope until product decision |

Esa tabla es muy útil para los agentes de código con IA porque le indica al agente dónde debería estar la evidencia de que se cumple cada escenario.

Ejemplo de prompt para /speckit.specify

Usa un prompt como este:

/speckit.specify

Build saved dashboard views for authenticated users.

Goal:
Users should be able to save useful dashboard filter setups and return to them later.

Business rules:
- Saved views are private per user.
- Saved view names must be unique per user.
- Saved views restore filters, visible columns, and sort order.
- Deleting a saved view must not delete the underlying dashboard.

Acceptance examples:

Feature: Saved dashboard views

  Rule: Saved views are private per user

    Scenario: User saves a private dashboard view
      Given Ana is viewing the revenue dashboard filtered by region "LATAM"
      When Ana saves the view as "LATAM revenue"
      Then Ana should see "LATAM revenue" in her saved views
      And Ben should not see "LATAM revenue" in his saved views

  Rule: Saved view names are unique per user

    Scenario: User tries to reuse a saved view name
      Given Ana already has a saved view named "LATAM revenue"
      When Ana saves another view as "LATAM revenue"
      Then Ana should be asked to choose a different name

Open questions:
- Should admins see users' private saved views?
- Is there a maximum number of saved views per user?
- Do relative dates like "last 7 days" resolve dynamically when reopened?

Do not answer open questions by guessing. Mark them for clarification or explicitly out of scope.

Esto le da a Spec Kit suficiente contexto sobre la intención de producto para crear la especificación de la funcionalidad, a la vez que conserva los ejemplos de comportamiento que el equipo ya acordó.

¿Puede Spec Kit generar escenarios de Gherkin automáticamente?

Sí, pero con una advertencia importante.

Spec Kit no necesita un «generador de Gherkin» especial para hacerlo. Durante /speckit.specify o /speckit.clarify, el agente de IA puede redactar escenarios de Gherkin a partir del brief de producto, las reglas de negocio, los ejemplos y las preguntas abiertas que le proporciones.

Eso significa que esto es posible:

product brief
  -> /speckit.specify
  -> generated feature spec
  -> generated draft Gherkin scenarios
  -> human review
  -> clarified acceptance scenarios

Pero los escenarios generados deben tratarse como borradores de ejemplos de aceptación, no como la verdad definitiva.

La IA puede inferir casos útiles, pero también puede inventar reglas de producto que suenan razonables y son completamente incorrectas.

Un buen prompt es:

/speckit.specify

Create the feature spec and draft Gherkin acceptance scenarios.

Rules:
- Generate scenarios only from the provided business rules and examples.
- If a scenario requires an unstated product rule, put it under "Candidate scenarios needing clarification."
- Separate must-have scenarios from edge cases.
- Do not invent limits, roles, permissions, data retention rules, or admin behavior.
- Add open questions for anything ambiguous.

Output sections:
1. Feature summary
2. Business rules
3. Draft Gherkin scenarios
4. Candidate scenarios needing clarification
5. Open questions

Después, usa /speckit.clarify para afinar los escenarios generados:

/speckit.clarify

Review the draft Gherkin scenarios.

For each scenario:
- identify any hidden assumption
- ask a clarification question if the behavior is not explicit
- mark the scenario as accepted, revised, split, or removed
- move speculative behavior out of acceptance criteria

Esto crea un flujo más saludable:

AI drafts scenarios
  -> humans reject bad assumptions
  -> clarify missing rules
  -> accepted scenarios become the contract
  -> plan and tasks trace back to accepted scenarios

La regla que usaría es sencilla:

AI-generated Gherkin is allowed.
AI-approved Gherkin is not.

Alguien con autoridad sobre el producto o el dominio debe revisar los ejemplos antes de que la implementación los trate como criterios de aceptación.

Usa esta lista de verificación antes de aceptar escenarios generados:

[ ] Does each scenario come from a known business rule?
[ ] Does each scenario have one clear When action?
[ ] Are expected results observable by a user, API, test, or eval?
[ ] Did the AI invent roles, limits, permissions, defaults, or error states?
[ ] Are uncertain scenarios separated from accepted scenarios?
[ ] Can the team map each accepted scenario to a test, eval, or manual check?

Así que sí, la generación automática es útil.

Solo mantén una etapa de revisión entre los escenarios generados y la implementación.

Ejemplo de prompt para /speckit.plan

Después de la etapa de aclaración, usa los escenarios de Gherkin para dar forma al plan técnico:

/speckit.plan

Plan the implementation using the existing stack and repository conventions.

Testing strategy:
- Map each acceptance scenario to a verification method.
- Use API or integration tests for privacy and uniqueness rules.
- Use one E2E test for the happy path of saving and reopening a view.
- Do not automate unresolved questions.

Traceability requirement:
The plan should include a table mapping each Gherkin scenario to:
- implementation area
- test level
- file or test location
- owner of unresolved product decisions

Esto evita que el plan se convierta en un diseño técnico genérico.

Lo mantiene anclado al comportamiento.

Ejemplo de prompt para /speckit.tasks

La generación de tareas es donde muchos flujos de IA pierden el rumbo.

Pide tareas vinculadas a los escenarios:

/speckit.tasks

Generate implementation tasks from the plan.

Requirements:
- Group tasks by acceptance scenario when possible.
- Include tests beside the implementation tasks they verify.
- Add a final traceability task that checks every Gherkin scenario has proof.
- Keep unresolved questions out of implementation tasks unless clarified.

El resultado debería verse así:

Scenario: User saves a private dashboard view
  [ ] Add persistence model scoped by user ID
  [ ] Add create saved view API endpoint
  [ ] Add saved views list API endpoint filtered by current user
  [ ] Add integration test proving Ben cannot see Ana's saved view
  [ ] Add UI flow for save and reopen
  [ ] Add E2E happy-path test

Scenario: User tries to reuse a saved view name
  [ ] Add uniqueness constraint per user
  [ ] Return validation error for duplicate names
  [ ] Add integration test for duplicate name rejection

Ahora la IA no solo está generando una lista de tareas.

Está generando una lista de tareas vinculadas al comportamiento.

Dónde deberían estar los archivos

Una estructura práctica del repositorio puede verse así:

.specify/
  memory/
    constitution.md

specs/
  001-saved-dashboard-views/
    spec.md
    plan.md
    tasks.md

features/
  saved-dashboard-views.feature

tests/
  integration/
    saved-dashboard-views.test.ts
  e2e/
    saved-dashboard-views.spec.ts

Usa specs/ para los artefactos de Spec Kit.

Usa features/ para escenarios de Gherkin duraderos si tu equipo quiere que sean visibles fuera de la especificación generada.

Usa tests/ para las pruebas ejecutables.

Esa separación evita una confusión común:

spec.md
  explains the feature

.feature
  expresses examples

test files
  execute verification

Mi recomendación

Empieza de forma sencilla:

Week 1:
  Use Gherkin inside Spec Kit specs as acceptance examples.
  Do not install Cucumber yet.

Week 2:
  Require scenario-to-test traceability in /speckit.tasks.
  Automate key scenarios with normal test tools.

Week 3+:
  If the team likes executable Gherkin, add Cucumber or a BDD runner.
  If not, keep Gherkin as readable acceptance specs and automate behavior at API/E2E levels.

Este es el camino pragmático.

No empieces instalando todas las herramientas de BDD.

Empieza haciendo que la IA implemente a partir de mejores ejemplos.

Desarrollo con IA guiado por evals

Cuando el producto en sí incluye comportamiento de un LLM, Gherkin también puede servir de inspiración para casos de eval.

La documentación de evals de OpenAI describe las evals como pruebas estructuradas para comprobar si las respuestas de la IA cumplen criterios de estilo y contenido, y compara explícitamente el proceso con BDD: especificar el comportamiento esperado, ejecutar entradas de prueba, analizar los resultados e iterar.

Por ejemplo:

Feature: Support ticket classifier

  Rule: Billing questions are routed to the billing queue

    Scenario: Customer asks about an invoice charge
      Given a support ticket says "Why was I charged twice this month?"
      When the AI classifies the ticket
      Then the category should be "Billing"
      And the confidence should be high enough for automatic routing

Ese escenario podría no convertirse en una prueba de navegador con Cucumber.

Podría convertirse en una fila de un dataset de evals:

{
  "input": "Why was I charged twice this month?",
  "expected_category": "Billing",
  "minimum_confidence": 0.8
}

El principio es el mismo: define el comportamiento esperado antes de confiar en la automatización.

Cómo elegir el nivel de prueba adecuado

No todos los escenarios de Gherkin deberían convertirse en pruebas de extremo a extremo.

Esa es una de las formas más fáciles de crear una suite lenta y frágil.

Usa esta guía:

ComportamientoNivel de prueba más adecuado
Cálculo o transformación puraPrueba unitaria
Regla de autorización o de flujo de trabajoPrueba de integración/API
Recorrido crítico del usuarioPrueba E2E
Calidad de la respuesta de un LLMEval
Diseño visualPrueba de regresión visual o de componentes
Contrato entre serviciosPrueba de contrato

El escenario de Gherkin es el ejemplo expresado en términos de negocio.

La automatización puede estar en el nivel que ofrezca la mejor señal con el menor costo de mantenimiento.

Un patrón práctico para el repositorio

Para un equipo que trabaja con asistencia de IA, me gusta esta estructura:

features/
  saved-dashboard-views.feature

docs/specs/
  saved-dashboard-views.md

tests/
  integration/
    saved-dashboard-views.test.ts
  e2e/
    saved-dashboard-views.spec.ts

evals/
  support-ticket-routing.jsonl

El archivo .feature explica el comportamiento.

La especificación explica el alcance, las decisiones y las preguntas abiertas.

Las pruebas verifican el comportamiento determinista del software.

Las evals verifican el comportamiento probabilístico de la IA.

Esto les da tanto a las personas como a los agentes de IA un mejor mapa del sistema.

Lista de verificación para revisar código generado por IA

Cuando un PR se creó a partir de escenarios de Gherkin, revísalo contra los ejemplos.

[ ] Does each scenario map to at least one test, eval, or explicit manual check?
[ ] Did the AI preserve the business language from the scenario?
[ ] Are the tests checking observable outcomes instead of implementation details?
[ ] Did the implementation add behavior not covered by the examples?
[ ] Did the AI invent answers to unresolved product questions?
[ ] Are edge cases represented as separate scenarios instead of hidden in one big scenario?
[ ] Can a PM or QA read the examples and understand the behavior?

La falla más peligrosa no es una sintaxis incorrecta.

La falla más peligrosa ocurre cuando la IA implementa una funcionalidad razonable que no es la que el equipo acordó crear.

Antipatrones comunes

Antipatrón 1: Gherkin como script de interfaz

Scenario: Save view
  Given I click the dashboard menu
  And I click the three dots
  And I click the input
  And I type "LATAM revenue"
  When I click the blue save button
  Then I see a toast

Esto es frágil.

Le dice demasiado a la IA sobre la interfaz y muy poco sobre el comportamiento del negocio.

Prefiere:

Scenario: Save a named dashboard view
  Given I am viewing the revenue dashboard filtered by region "LATAM"
  When I save the view as "LATAM revenue"
  Then "LATAM revenue" should appear in my saved views

Antipatrón 2: un escenario gigante

Si un escenario tiene varios pasos When y varios resultados, probablemente contiene varios comportamientos.

Divídelo.

one rule
  -> one behavior
  -> one scenario
  -> one clear expected result

Antipatrón 3: ejemplos de relleno generados por IA

Las herramientas de IA suelen generar relleno:

Scenario: Valid input
Scenario: Invalid input
Scenario: Edge case

Exige ejemplos reales:

Scenario: Reject a duplicate saved view name for the same user
Scenario: Allow the same saved view name for different users
Scenario: Restore a relative date filter when opening a saved view tomorrow

Antipatrón 4: tratar Gherkin como la verdad definitiva

Los escenarios de Gherkin solo son útiles si reflejan las decisiones actuales de producto.

Si la implementación cambia el comportamiento, actualiza los ejemplos.

Si los ejemplos revelan una regla de producto incorrecta, cambia la regla.

La documentación viva debe mantenerse viva.

Un pequeño ejemplo de principio a fin

Imagina que un PM escribe esta solicitud:

Users should be able to save dashboard views so they can return to useful filter setups later.

Después del mapeo de ejemplos, el equipo identifica:

Rules:
  - saved views are private per user
  - names must be unique per user
  - saved views restore filters and sort order
  - deleting a view does not delete the dashboard

Questions:
  - should saved views be shareable later?
  - should admins see private views?

El equipo escribe:

Feature: Saved dashboard views

  Rule: Saved views are private per user

    Scenario: User saves a private dashboard view
      Given Ana is viewing the revenue dashboard filtered by region "LATAM"
      When Ana saves the view as "LATAM revenue"
      Then Ana should see "LATAM revenue" in her saved views
      And Ben should not see "LATAM revenue" in his saved views

  Rule: Saved view names are unique per user

    Scenario: User tries to reuse a saved view name
      Given Ana already has a saved view named "LATAM revenue"
      When Ana saves another view as "LATAM revenue"
      Then Ana should be asked to choose a different name

    Scenario: Different users use the same saved view name
      Given Ana has a saved view named "LATAM revenue"
      When Ben saves a view as "LATAM revenue"
      Then Ben's saved view should be created

Luego, el ingeniero le pide a la IA:

Implement the feature described in this Gherkin.

Before editing:
- inspect current dashboard state management
- inspect auth/user scoping patterns
- inspect existing API test patterns
- propose a file-level plan

During implementation:
- add API or integration tests for privacy and duplicate-name rules
- add one E2E test for the happy path
- do not implement sharing or admin visibility; those are unresolved future questions

Esa última línea importa.

Evita que la IA convierta preguntas abiertas en alcance no previsto.

Cómo pueden usarlo los PMs sin convertirse en ingenieros de pruebas

Los PMs no necesitan escribir Gherkin perfecto.

Necesitan ayudar a aportar:

  • ejemplos realistas
  • reglas de negocio
  • casos de excepción
  • palabras que los usuarios reconocerían
  • respuestas a preguntas de producto

Un PM puede comenzar con esto:

The one where Ana saves a LATAM revenue view.
The one where Ana tries to reuse the same name.
The one where Ben cannot see Ana's view.
The one where Ana deletes the saved view but the dashboard remains.

Después, ingeniería y QA pueden convertir los ejemplos importantes en Gherkin formal.

Esa es una división de trabajo saludable.

Cómo pueden usarlo los ingenieros sin perder velocidad

Los ingenieros no necesitan convertir cada ticket en una ceremonia.

Usa Gherkin cuando:

  • la funcionalidad tiene reglas de producto
  • varios roles necesitan acordar el comportamiento
  • el agente de IA podría hacer suposiciones peligrosas
  • el flujo de trabajo abarca varios componentes
  • las regresiones serían costosas
  • la funcionalidad incluye comportamiento de un LLM que necesita evals

Omite el Gherkin formal cuando:

  • el cambio es una refactorización puramente interna
  • el comportamiento ya está cubierto por pruebas claras
  • la tarea es una corrección mecánica pequeña
  • el costo de escribir escenarios es mayor que el riesgo de ambigüedad

El objetivo es entregar mejor, no seguir un ritual.

Acuerdo recomendado para el equipo

Para equipos que usan agentes de código con IA, propondría este acuerdo ligero:

For every non-trivial user-facing feature:

1. Capture rules, examples, and open questions before implementation.
2. Write Gherkin for the scenarios that define done.
3. Mark unresolved questions as out of scope until answered.
4. Give the AI the scenarios as the acceptance contract.
5. Require tests, evals, or manual checks that map back to the scenarios.
6. Review the PR against the scenarios, not only against the diff.

Es lo suficientemente sencillo para ponerlo en práctica.

También es lo suficientemente sólido para evitar muchos errores en la entrega asistida por IA.

Brechas actuales y oportunidades de mejora

La principal brecha en la conversación actual sobre desarrollo con IA es que los equipos hablan mucho de modelos y herramientas, pero no lo suficiente de contratos de comportamiento.

Gherkin puede ayudar, pero todavía hay preguntas abiertas:

  • ¿Cómo deberían mantener los equipos sincronizados los archivos .feature, las especificaciones, las pruebas y los datasets de evals a lo largo del tiempo?
  • ¿Qué escenarios merecen automatización E2E y cuáles deberían mantenerse como pruebas de API, pruebas unitarias o verificaciones manuales?
  • ¿Cómo deberían informar los agentes de IA la trazabilidad desde el escenario hasta el código y la prueba?
  • ¿Pueden los agentes de código detectar de forma confiable cuándo un escenario es demasiado ambiguo o demasiado específico de la implementación?
  • ¿Cómo deberían revisar los PMs el Gherkin generado por IA sin tener que involucrarse en la sintaxis de las herramientas?

Esas serían buenas secciones para un artículo posterior más profundo.

Mi recomendación práctica

Usa Gherkin como la capa de comportamiento de tu flujo de desarrollo con IA.

No lo conviertas en todo el flujo.

El patrón más sólido es:

BDD / Example Mapping
  gives shared understanding

Gherkin
  captures concrete behavior

Spec-Driven Development
  organizes the implementation path

TDD / integration tests / E2E tests
  verify deterministic software behavior

Evals
  verify probabilistic AI behavior

CI/CD
  keeps the whole thing honest

Si solo haces una cosa, haz esto:

Antes de pedirle a un agente de IA que implemente una funcionalidad, escribe tres ejemplos de cómo debería comportarse y un ejemplo de lo que no debe hacer.

Ese pequeño hábito mejorará tus prompts, tus pruebas, tus revisiones y tus conversaciones de producto.

Lista de fuentes