Cómo combinar prompt chaining y few'shot para automatizar la generación de documentación API coherente y actualizada en proyectos de software a gran escala

Pregunta clave:¿Qué combinación deprompt chainingyfew'shot examplesresulta más eficaz para producir una documentación API siempre alineada con el código en entornos empresariales?

En este artículo, dirigido a desarrolladores, equipos de DevOps y responsables de calidad, descubrirás paso a paso cómo diseñar prompts modulares, integrar los LLM en la canalización CI/CD y medir la calidad de la documentación generada. Encontrarás ejemplos prácticos en Python, configuraciones para GitHub Actions y consejos SEO para que tu documentación sea fácilmente indexable.

1. Prompt chaining y few'shot learning: definiciones y papel en los LLM

1.1 ¿Qué es el prompt chaining?

Elprompt chainingconsiste en encadenar varias solicitudes (prompts) a un Large Language Model (LLM) de forma secuencial, donde la salida de un paso se convierte en la entrada del siguiente. Este enfoque permite dividir tareas complejas "como la extracción de especificaciones API de un repositorio" en subtareas más manejables y controlables.

1.2 ¿Qué es el few'shot learning?

Elfew'shot learningproporciona al modelo algunos ejemplos (normalmente 3'5) del resultado deseado antes de solicitar la generación propiamente dicha. Estos ejemplos “enseñan” al modelo el estilo, el formato y las reglas de negocio, reduciendo la necesidad de prompts extensos y difíciles de mantener.

1.3 ¿Por qué combinarlos?

• Control fino:el chaining asegura que cada fase sea verificada; el few'shot garantiza la coherencia estilística.
• Escalabilidad:los módulos de prompt pueden reutilizarse en diferentes micro'servicios.
• Mantenibilidad:actualizar un ejemplo few'shot es más sencillo que reescribir un prompt monolítico.

2. Diseñar prompts modulares para extraer especificaciones API del código fuente

2.1 Arquitectura de tres niveles

Una canalización típica comprende tres bloques:

1. Recolección de metadatos:análisis estático (AST) o introspección en tiempo de ejecución.
2. Generación de descripción:LLM con few'shot para transformar metadatos en texto.
3. Validación y formateo:chaining para comprobar la coherencia y convertir a OpenAPI/Markdown.

2.2 Prompt de ejemplo " nivel 1 (Recolección)

# Prompt 1 " Extrae las firmas de las funciones
You are a code'analysis assistant. Analyze the following Python file and return a JSON array with each function name, its parameters (including types if annotated), and its docstring (if present). Return ONLY valid JSON.

```python
{{FILE_CONTENT}}
```

Este prompt es sencillo, pero con unfew'shotde dos ejemplos correctos el modelo entiende el formato requerido.

2.3 Prompt de ejemplo " nivel 2 (Generación de descripción)

# Prompt 2 " Transforma la firma en una descripción API
You are an API documentation writer. Using the JSON produced in the previous step, write a concise OpenAPI v3.0 path object for each function. Follow the style of the examples below.

Example 1:
Input: {"name": "create_user", "params": {"email": "str", "age": "int"}, "doc": "Crea un nuevo usuario."}
Output: 
```yaml
/create_user:
  post:
    summary: Crea un nuevo usuario.
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              email:
                type: string
              age:
                type: integer
    responses:
      '201':
        description: Usuario creado con éxito.
```

Now generate the OpenAPI snippet for the following input:
{{JSON_FROM_PROMPT1}}

El few'shot incluye tanto el JSON de entrada como el YAML de salida, de modo que el modelo aprende a mapear correctamente los tipos.

2.4 Prompt de ejemplo " nivel 3 (Validación)

# Prompt 3 " Verifica coherencia y añade etiquetas
You are a quality'assurance bot for API docs. Review the OpenAPI snippet below and ensure:
- todos los parámetros tengan una descripción (usa el docstring si está disponible)
- los códigos de respuesta incluyan al menos 200 y 400
- añade una etiqueta "User Management" si el nombre contiene "user"
Return the corrected snippet in the same YAML format.

```yaml
{{YAML_FROM_PROMPT2}}
```

3. Estrategias para mantener la coherencia y la actualización continua

3.1 Triggers basados en eventos de Git

• Push o Pull Request:inicia la canalización de generación de documentación.
• Tag de lanzamiento:publica la doc en un sitio estático (p. ej., Docusaurus).

3.2 Caché de resultados y diff inteligente

Guarda los hash del archivo fuente y del resultado generado. Si el diff es nulo, omite la fase de publicación, reduciendo costos de API.

3.3 Control de calidad automático

Utiliza métricas como:

• BLEU / ROUGE:compara la nueva descripción con la anterior para detectar regresiones.
• Validación de esquema:JSON Schema para OpenAPI garantiza que todos los campos requeridos estén presentes.
• Linter:herramientas comospectralpara verificar buenas prácticas OpenAPI.

3.4 Actualización incremental

Divide el repositorio en “módulos de API”. Cada módulo posee un archivoapi_prompt.ymlcon los few'shot locales, de modo que los cambios en un micro'servicio no afecten a los demás.

4. Integración en la canalización de compilación

4.1 Ejemplo con GitHub Actions

name: Generate API Docs
on:
  push:
    paths:
      - '**/*.py'
  pull_request:
    paths:
      - '**/*.py'
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: |
          pip install astor openai pyyaml
      - name: Run prompt chaining script
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          python scripts/generate_api_docs.py
      - name: Upload docs artifact
        uses: actions/upload-artifact@v3
        with:
          name: api-docs
          path: docs/openapi.yaml

El archivogenerate_api_docs.pyimplementa los tres prompts mostrados arriba, gestionando reintentos y registro de logs.

4.2 Ejemplo con Jenkins (Declarative Pipeline)

pipeline {
    agent any
    environment {
        OPENAI_API_KEY = credentials('openai-key')
    }
    stages {
        stage('Checkout') { steps { checkout scm } }
        stage('Generate Docs') {
            steps {
                sh 'python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt'
                sh 'python scripts/generate_api_docs.py'
            }
        }
        stage('Publish') {
            steps {
                archiveArtifacts artifacts: 'docs/**', fingerprint: true
                // Deploy to S3 or GitHub Pages
            }
        }
    }
    post { always { cleanWs() } }
}

4.3 Métricas de evaluación de calidad

5. SEO para la documentación API

• Enfoque de palabras clave:“documentación API automática”, “prompt chaining LLM”, “few'shot API docs”.
• Utiliza<h2>y<h3>descriptivos; incluye los términos clave en las primeras 100 palabras.
• Genera una página índice con<meta description>de 150'160 caracteres (ver extracto).
• Añadeschema.org/TechArticlepara mejorar el rich snippet.

6. Conclusiones accionables

1. Define un conjunto de few'shot estandarizadospara cada tipo de endpoint (GET, POST, DELETE).
2. Construye una cadena de tres prompts(extracción, generación, validación) y guarda los resultados en un archivo temporal.
3. Integra la cadena en CI/CDusando GitHub Actions o Jenkins; actívala solo ante cambios de código.
4. Monitorea las métricas(cobertura, errores de esquema, ROUGE) y falla la compilación si no se cumplen los umbrales.
5. Optimiza para SEOincluyendo las palabras clave en los encabezados y en la descripción de la página de documentación.

Conclusión

Combinarprompt chainingyfew'shot learninges la clave para transformar el código en documentación API coherente, actualizada y lista para publicación automática. Siguiendo la estructura modular propuesta, integrando la canalización en tu CI/CD y supervisando métricas de calidad, obtendrás una doc que reduce errores de integración, acelera el time'to'market y mejora la visibilidad SEO de tu producto.

Empieza ahora a experimentar con los prompts proporcionados, adapta los few'shot a tu lenguaje (Java, TypeScript, Go) y observa cómo tu documentación evoluciona de forma continua y fiable.

Preguntas frecuentes

¿Cuál es la diferencia principal entre prompt chaining y few'shot?

El prompt chaining enlaza varias solicitudes en secuencia, mientras que el few'shot brinda ejemplos al modelo para enseñarle el formato deseado dentro de un único prompt.

¿Puedo usar estos métodos con lenguajes diferentes a Python?

Sí. Basta adaptar el analizador del primer prompt (AST) al lenguaje objetivo y mantener los mismos few'shot para la generación de OpenAPI.