En el Módulo 2 aprendiste a usar Git. Pero Git a solas es una libreta en blanco: dos personas pueden usarlo de formas tan distintas que la historia se vuelve ilegible. En una empresa, lo que separa un repo caótico de uno donde cualquiera se orienta son las convenciones: acuerdos sobre cómo nombrar ramas, escribir commits y proponer cambios. Este módulo es el reglamento no escrito que todo equipo espera que sepas.

La tesis del módulo

Las convenciones no son burocracia: son el lenguaje común que hace que la historia de Git se lea sola. Ramas con nombre, commits estandarizados y PRs bien escritos convierten un repo en algo que cualquiera del equipo entiende sin preguntar.

Nombres de ramas

Una rama debe decir, de un vistazo, qué tipo de trabajo lleva. El estándar es tipo/descripcion-corta, donde la descripción va en kebab-case (palabras en minúscula unidas por guiones):

git switch -c feature/tool-busqueda-web
git switch -c fix/parser-json-roto
git switch -c hotfix/prompt-que-rompia-produccion
git switch -c chore/actualizar-dependencias

Prefijo	Para qué
`feature/`	Una funcionalidad nueva
`fix/`	Corrección de un bug normal
`hotfix/`	Corrección urgente sobre producción
`chore/`	Tareas de mantenimiento (deps, configs, limpieza)

Conventional Commits

Conventional Commits es un estándar para escribir mensajes de commit con una estructura fija, de modo que tanto humanos como máquinas los entiendan. El formato:

tipo(scope): descripción

tipo: qué clase de cambio es (lista abajo).
scope (opcional): qué parte del proyecto toca, entre paréntesis — agent, api, tools.
descripción: en imperativo y minúscula, corta y clara.

Los tipos más usados — los de la especificación, más hotfix, que no está en el estándar pero muchos equipos agregan:

Tipo	Cuándo usarlo
`feat`	Una funcionalidad nueva
`fix`	Corrección de un bug
`hotfix`	Corrección urgente en producción (convención de equipo, fuera del estándar)
`chore`	Mantenimiento, sin cambio de comportamiento
`docs`	Solo documentación
`refactor`	Reestructura código sin cambiar qué hace
`test`	Agregar o corregir tests
`ci`	Cambios en el pipeline de CI/CD
`perf`	Mejoras de rendimiento
`build`	Cambios en el build o dependencias

Cuando un cambio rompe compatibilidad — obliga a quien usa tu agente a cambiar algo —, se marca con BREAKING CHANGE en el cuerpo del commit, o con un ! después del tipo:

feat(api)!: cambiar el formato de respuesta del endpoint /chat

BREAKING CHANGE: la respuesta ahora devuelve {data, meta}
en vez de un string plano. Los clientes deben actualizar
el parseo.

Por qué molestarse: historia, changelog y semver

Tres razones concretas:

Historia legible. git log --oneline se lee como un índice de qué pasó, no como un montón de “cambios varios”.
Changelog automático. Herramientas leen los tipos y generan el listado de novedades solo. Sin escribir nada a mano.
Conexión con semver. Los tipos alimentan el versionado automático.

Semver (Semantic Versioning) es el estándar de numerar versiones como MAJOR.MINOR.PATCH, por ejemplo 2.4.1:

Parte	Sube cuando…	Gatillado por
MAJOR (`2`.x.x)	Rompes compatibilidad	`BREAKING CHANGE`
MINOR (x.`4`.x)	Agregas algo nuevo compatible	`feat`
PATCH (x.x.`1`)	Arreglas un bug sin romper nada	`fix`

Así, tus commits bien escritos deciden solos el próximo número de versión. Esa es la magia: escribir feat o fix no es cosmético, es la entrada de una máquina que versiona y documenta por ti.

Cheat-sheet de prefijos con ejemplos reales

Guárdala. Ejemplos sacados del día a día de un agente:

Prefijo	Ejemplo de commit real
`feat`	`feat(agent): agregar tool de búsqueda web`
`fix`	`fix(parser): manejar respuesta del LLM sin JSON`
`hotfix`	`hotfix: revertir prompt que rompía el parser`
`chore`	`chore: subir openai a 1.40.0`
`docs`	`docs: documentar variables de entorno del agente`
`refactor`	`refactor(tools): separar cliente HTTP en su módulo`
`test`	`test(agent): cubrir el caso de timeout del modelo`
`ci`	`ci: correr evals en cada pull request`
`perf`	`perf: cachear embeddings de documentos frecuentes`
`build`	`build: fijar versión de Python en el Dockerfile`

Pull Requests

Un Pull Request (PR) es la propuesta formal de fusionar tu rama al código principal. No subes directo a main: abres un PR y alguien lo revisa. Un buen PR tiene:

Título con el mismo estilo de Conventional Commits: feat(agent): agregar tool de búsqueda web.
Descripción que responda tres preguntas:
- Qué cambia.
- Por qué (el problema que resuelve).
- Cómo probarlo (pasos para que el revisor lo verifique).

## Qué
Agrega una tool de búsqueda web al agente usando la API de Tavily.

## Por qué
El agente no podía responder sobre eventos recientes. Cierra #142.

## Cómo probar
1. Configura TAVILY_API_KEY en tu .env
2. Corre `pytest tests/test_tools.py`
3. Pregúntale al agente por una noticia de esta semana

Dos hábitos que marcan la diferencia:

PRs chicos. Un PR de 50 líneas se revisa bien; uno de 2.000 se aprueba a ciegas. Divide el trabajo.
Draft PRs. Un PR en borrador (draft) señala “trabajo en progreso, aún no lo revises”. Sirve para pedir feedback temprano o correr CI sin pedir aprobación todavía.

Code review

El code review es la revisión del PR por otra persona antes de fusionar. No es un examen: es una red de seguridad. Qué se mira:

¿El cambio hace lo que dice y resuelve el problema?
¿Hay tests que lo respalden?
¿Se coló algún secreto, print() de debug o TODO olvidado?
¿Se entiende el código, o necesitará arqueología en tres meses?
¿Rompe algo de lo que ya existía?

El revisor deja comentarios y, cuando está conforme, aprueba el PR. Muchos equipos exigen una o dos aprobaciones antes de permitir el merge — eso se configura en el repositorio, como veremos en módulos de CI.

El flujo completo: de la rama al merge

 RAMA
   │  git switch -c feature/tool-web
   ▼
 ┌──────────────────────────────┐
 │ commits (Conventional)       │
 └──────────────┬───────────────┘
                ▼
 ┌──────────────────────────────┐
 │ Pull Request (qué/por qué)   │
 └──────────────┬───────────────┘
                ▼
 ┌──────────────────────────────┐
 │ Code review + aprobación     │
 └──────────────┬───────────────┘
                ▼
 ┌──────────────────────────────┐
 │ Merge a main                 │
 └──────────────┬───────────────┘
                ▼
              MAIN

GitFlow vs trunk-based

Hay dos filosofías sobre cómo organizar las ramas del equipo:

GitFlow: muchas ramas de larga vida (main, develop, release/*, ramas de feature). Ceremonioso y ordenado, pensado para lanzamientos por versión programada.
Trunk-based: una sola rama principal (el trunk), ramas de feature muy cortas que se fusionan a diario. Menos ramas vivas, integración constante. Es el flujo que habilita el CI/CD moderno.

	GitFlow	Trunk-based
Ramas de larga vida	Varias (`main`, `develop`, `release`)	Una (`main`)
Vida de una feature	Días o semanas	Horas o pocos días
Encaja con	Releases programados	Entrega continua
Riesgo de conflictos	Mayor (ramas viejas)	Menor (integras seguido)
Complejidad	Alta	Baja

Ojo: para un agente que despliegas seguido, trunk-based casi siempre gana. Ramas cortas significan menos conflictos, integración constante y un pipeline de deploy más simple. GitFlow brilla en productos con versiones formales y varios entornos de release.

Errores comunes

Ramas sin prefijo ni sentido (mis-cambios, test2). Nadie sabe qué llevan. Usa tipo/descripcion.
Ignorar Conventional Commits “porque da lo mismo”. No da lo mismo: rompes el changelog y el versionado automáticos que el equipo espera.
PRs gigantes. Imposibles de revisar bien; se aprueban a ojo y ahí entran los bugs. Divide.
Descripción de PR vacía. Obligas al revisor a adivinar qué y por qué. Tres párrafos ahorran tres reuniones.
Confundir hotfix con fix. El hotfix es urgencia sobre producción; usarlo para todo le quita el sentido de alarma.
Mezclar GitFlow y trunk-based sin acuerdo. El equipo elige uno. La consistencia importa más que cuál.

La frase para llevarse

“Un commit bien escrito no es para hoy: es un mensaje a quien lea el log en seis meses — y muy probablemente ese alguien seas tú.”

Qué viene

Módulo 4: estructura del proyecto, entornos y secretos. Cierra el bloque básico: cómo se organiza el repo de un agente, los principios 12-factor, la diferencia entre dev, staging y prod, y — lo más delicado — dónde vive cada secreto sin que termine en Git.

Deploy de Agentes — Módulo 3: convenciones de equipo — ramas, commits y PRs como en la empresa