GOT, el companion de Git que suma el contexto que falta

En 30 segundos

Git es un genio rastreando cambios, pero nunca te cuenta el porqu� de las decisiones. Si alguna vez hiciste git log y te encontraste con commits como �fix�, �cambios� o �WIP�, sab�s de lo que hablo. GOT (Git Opinionated Toolkit) viene a cubrir ese vac�o: es un companion opinado que organiza tus ADRs, vincula contexto a cada commit y te da trazabilidad real de las decisiones t�cnicas. Sin cambiar Git de base, GOT te obliga a documentar el razonamiento detr�s de cada giro del c�digo, convirtiendo tu repo en un registro vivo de las decisiones del equipo. En criollo: dej�s de adivinar por qu� se hizo algo y empez�s a entenderlo.

El drama silencioso de los repositorios sin contexto

Ponete en situaci�n: ca�s a un proyecto que tiene tres a�os, abr�s el historial y ves commits con mensajes que parecen escritos a las apuradas antes del asado del viernes. �Cambios varios�, �fix final 3�, �esto deber�a andar�. Por m�s que el c�digo est� impecable, te falta el eslab�n que une el ticket de Jira o el capricho del PM con esa l�nea concreta de TypeScript. Los comentarios en los PR quedan perdidos en la herramienta de turno, y el famoso �git blame� te da un autor y una fecha, pero no el razonamiento.

Git es espectacular para lo que hace: versionar archivos, manejar ramas, bisectar bugs. Pero no fue dise�ado para capturar decisiones arquitect�nicas. El equipo discute si conviene usar Redis o memcached en Slack, debate en una call y despu�s alguien commitea el cliente de Redis sin una sola menci�n de por qu� se eligi� eso sobre la alternativa. Seis meses despu�s, cuando el cach� da problemas, nadie recuerda el contexto y el �nico que sab�a se fue a trabajar a una startup de delivery de hamburguesas.

Ac� es donde entra la posta de tener un companion como GOT: una herramienta que se apoya en Git pero extiende su alcance para responder la pregunta que m�s importa: ��Por qu� hicimos esto?�.

�Qu� es GOT exactamente?

GOT, acr�nimo de Git Opinionated Toolkit, es una extensi�n de tu workflow con Git que agrega de manera ligera una capa de documentaci�n viva. No es un nuevo sistema de control de versiones ni pretende reemplazar al que ya conoc�s. Se instala como una utilidad de l�nea de comandos, se configura con un par de pasos y autom�ticamente te induce a mantener un registro de decisiones de arquitectura, conocido como ADR (Architecture Decision Record), vinculado a los commits.

El concepto �opinionado� es clave. GOT no te pregunta si quer�s documentar; te propone una estructura, un formato y un almacenamiento est�ndar dentro del repositorio. Al igual que un framework te impone una manera organizada de laburar, GOT te impone una forma de capturar decisiones. El objetivo es que en lugar de tener una carpeta docs/ que junta polvo con PDFs de hace a�os, mantengas un directorio adrs/ donde cada decisi�n relevante queda como un archivo markdown simple, versionado por Git, junto con metadatos que GOT sabe leer y asociar.

Lo m�s groso es que GOT vincula los ADRs directamente desde los commits. Cuando hac�s un commit que implementa una decisi�n, pod�s referenciar el ADR correspondiente con un identificador, y GOT teje esa relaci�n. Despu�s, al revisar el historial, no solo ves el diff del c�digo sino tambi�n el razonamiento que llev� a eso. Est�s uniendo el �qu� del c�digo con el �porqu� de la decisi�n, todo dentro del mismo repo y sin necesidad de cambiar de herramienta.

Trazabilidad que no la baja nunca

La palabra trazabilidad suena a f�brica de tornillos, pero en software es oro puro. Imagin� que una decisi�n de usar microservicios afect� quince m�dulos, cada uno con su propio historial de commits. Con Git puro pod�s rastrear cada commit, pero �c�mo sab�s que todos esos commits dispersos responden a la misma decisi�n arquitect�nica del sprint 23? GOT te da una vista unificada: desde el ADR que registr� la elecci�n, pod�s saltar a todos los commits que lo materializan.

Esta trazabilidad se potencia cuando combin�s GOT con herramientas de CI/CD. Si un test empieza a fallar de manera misteriosa despu�s de un cambio de librer�a, pod�s ir al commit, levantar el ADR relacionado y leer la discusi�n completa de por qu� se decidi� migrar de librer�a, qu� alternativas se consideraron y qu� trade-offs se asumieron. Eso reduce el tiempo de �pregunt�logos� en Slack y corta de ra�z los dedos acusadores entre equipos. Nadie puede decir �yo no sab�a� si est� todo documentado en un lugar que el pipeline mismo puede consultar.

Adem�s, GOT soporta la noci�n de �estado� de una decisi�n. Un ADR puede estar propuesto, aceptado, deprecado o reemplazado por otro posterior. Esto significa que no solo sab�s por qu� se eligi� Redis hace dos a�os, sino tambi�n por qu� se lo reemplaz� por DynamoDB el trimestre pasado, con el razonamiento completo y el v�nculo entre ambos ADRs. Es una l�nea de tiempo de la inteligencia del equipo que no se pierde en el �ter.

ADRs concretos, no documentos eternos de Word

Un ADR t�pico con GOT es un archivo markdown de veinte l�neas como mucho. Nada de plantillas kilom�tricas que nadie completa. La estructura es simple: t�tulo, contexto, decisi�n, consecuencias y estado. Al estar en markdown, Git lo diffea, lo mergea y lo muestra en cualquier visualizador sin instalar nada raro. Esto es un golazo porque baja la fricci�n al m�nimo: si un dev tiene que escribir tres p�rrafos para justificar por qu� eligi� PostgreSQL antes que MySQL, lo hace en el momento, no lo pospone para �despu�s� (nunca).

GOT agrega un comando para crear ADRs desde la terminal con un template precargado. Algo como got adr new "Elegir base de datos principal". Se abre en el editor que uses para Git, complet�s los campos y listo. Autom�ticamente se asigna un n�mero, se guarda en adrs/ y se puede referenciar en futuros commits con ADR-012. La convenci�n es puramente num�rica y secuencial, lo que facilita la b�squeda y la menci�n cruzada.

Lo m�s piola de los ADRs con GOT es que te fuerzan a pensar en el momento exacto en que tom�s la decisi�n. Eso por s� solo ya mejora la calidad de lo que decid�s, porque el acto de escribir el contexto y las consecuencias te obliga a considerar trade-offs que quiz�s pasaste por alto en la charla de pasillo con el CTO.

Instalaci�n y primeros pasos: no es magia negra

Si ya est�s canchero con la terminal, poner GOT a andar te toma cinco minutos. B�sicamente instal�s el binario (est� disponible en los repos de paquetes m�s comunes), corr�s got init dentro de tu proyecto y acept�s la estructura opinada. Eso te crea el directorio adrs/, un archivo de configuraci�n en .got/config y una plantilla base para los ADRs. Tambi�n pod�s integrar hooks de Git para que GOT te recuerde vincular un ADR si el mensaje del commit es muy vago, pero eso es opcional.

Una vez inicializado, el flujo diario casi no cambia. Hac�s tus ramas, code�s, y cuando est�s por commitear una decisi�n importante, primero cre�s el ADR con got adr new y despu�s en el commit pon�s algo como feat: soporte de cach� distribuido (ADR-003). GOT reconoce la referencia, actualiza el ADR si el commit lo implementa, y te deja navegar la relaci�n en ambas direcciones. Cuando otro dev hace pull del repo, ya tiene toda la documentaci�n integrada sin correr nada extra: el ADR es texto plano y el historial de Git sigue funcionando igual, con el bonus de que los mensajes de commit ahora est�n anclados a decisiones expl�citas.

Si labur�s con varios repos, pod�s configurar un perfil global de GOT para que todos sigan las mismas convenciones. La configuraci�n es m�nima: ruta de ADRs, prefijo de referencia (ADR, DEC, etc.), y poco m�s. No hay servidores, no hay base de datos, no hay vendor lock-in. Todo sigue siendo archivos en tu repo, lo cual es una de las mayores ventajas frente a herramientas de documentaci�n externas que quedan desaparecidas cuando cambi�s de plataforma SaaS.

Equipos grandes, onboarding feliz y auditor�as relajadas

Cuando un pibe nuevo entra al equipo, uno de los mayores dolores de cabeza es transmitir el lore oral del sistema. �Esto lo hicimos as� porque en 2019 la API de terceros era inestable�, �Este flag lo agregamos por el bug aquel que volvi� loco al cliente de Brasil�. Con GOT, el onboarding incluye leer los ADRs en orden cronol�gico: es como una novela de la arquitectura del sistema. El nuevo dev entiende los porqu�s desde el d�a uno sin romper las bolas a los seniors con preguntas que ya est�n respondidas.

Para equipos que trabajan con compliance o necesitan cumplir normativas, la trazabilidad de GOT es un golazo. En una auditor�a de seguridad pod�s demostrar exactamente cu�ndo y por qu� se aplic� un cambio en el manejo de datos personales, con el commit que lo implement�, el ADR que lo justific� y la discusi�n que le dio origen si la almacenaste ah�. Todo dentro del mismo repositorio auditado. No hay que cruzar correos electr�nicos ni actas de reuni�n que guard� alguien en un Drive que ya no existe.

El hecho de que GOT sea companion y no core significa que si ma�ana decid�s dejar de usarlo, los ADRs quedan como archivos markdown perfectamente legibles sin la herramienta. No te genera deuda t�cnica de plataforma ni te ata a un formato propietario. Esto es un mont�n para equipos que ya sufrieron migraciones de herramientas que dejaron toneladas de documentaci�n inaccesible.

�En qu� se diferencia de otras herramientas de documentaci�n?

La diferencia principal es la cercan�a con el c�digo y el flujo de Git. Las wikis internas o Confluence viven en un plano paralelo: alguien las actualiza, otro no, se desincronizan con la realidad del repo. GOT vive adentro del repo, se versiona con el c�digo, se mergea con las ramas. Si una decisi�n cambia en un feature branch, el ADR nuevo viaja en esa rama y solo se mergea a main cuando el feature se integra. As� no hay documentaci�n desactualizada flotando por ah�; lo que est� en main es la verdad actual.

Tambi�n se diferencia de herramientas como ADR-tools porque es opinado y end-to-end. No es solo un generador de ADRs: es un companion que se engancha con los commits y ofrece comandos para consultar relaciones, generar res�menes de decisiones pendientes o ver el mapa de ADRs y sus estados. Y lo hace desde la misma terminal donde ya est�s codeando, sin necesidad de abrir navegador.

Por �ltimo, meterse en el ecosistema de GOT es una inversi�n chica porque no ten�s que cambiar de hosting, no necesit�s permisos especiales ni administradores de plataforma. Cualquier equipo que use Git puede adoptarlo hoy mismo sin convencer a nadie del �rea de IT. Eso baja la barrera de entrada y acelera la adopci�n, que es el principal enemigo de cualquier pr�ctica de documentaci�n.

Cuando el companion se vuelve indispensable

Al principio pod�s pensar que documentar decisiones es una p�rdida de tiempo. Pero la primera vez que te salva de reintroducir un bug que ya hab�a sido analizado y descartado hace dos a�os, te das cuenta del valor. GOT act�a como memoria colectiva del equipo. En proyectos que rotan gente cada seis meses, donde los fundadores iniciales ya no est�n, tener el porqu� de cada componente documentado hace la diferencia entre mantener y reescribir a ciegas.

Tambi�n es un b�lsamo para los momentos de incidentes. Cuando estalla una alerta a las tres de la ma�ana y el que atiende el celular de guardia no es el que dise�� el m�dulo fallado, poder hacer git log y ver que un commit referencia ADR-008, y luego leer ese ADR para entender que la decisi�n deliberada de no usar connection pooling fue por una limitaci�n del cl�ster de QA que ya no existe, acelera la resoluci�n del problema en lugar de andar adivinando.

Con el tiempo, el conjunto de ADRs se convierte en un activo del proyecto en s� mismo. Un director t�cnico puede evaluar la madurez t�cnica de un equipo revisando sus ADRs: �est�n fundamentados? �Consideran alternativas? �Se actualizan cuando se deprecan? Es una herramienta de autoconocimiento del equipo que adem�s rinde frutos pr�cticos en la estabilidad y la mantenibilidad del sistema.

Conclusi�n

Git te dice qu� cambi� y qui�n lo cambi�; GOT te cuenta por qu�. Este companion opinionado llena un vac�o que todos sentimos al volver a c�digo de hace meses: la falta de contexto. Con ADRs breves, vinculados a commits y guardados como archivos markdown en el mismo repo, GOT transforma decisiones ef�meras en un historial claro y trazable. Es una herramienta ligera, sin servidores, que se integra en tu flujo de Git actual y que cualquier equipo puede adoptar hoy mismo sin riesgos. Si quer�s que tu repositorio deje de ser una colecci�n de misterios y se convierta en un registro vivo de sabidur�a t�cnica, dale una oportunidad a GOT. Tu yo del futuro (y tus compa�eros) te lo van a agradecer con birras incluidas.

Preguntas frecuentes

�GOT requiere cambiar el flujo de trabajo con Git?

No, para nada. GOT se suma como un companion, no reemplaza nada. Segu�s usando tus comandos de siempre (commit, push, pull). Solo agrega un paso cuando quer�s documentar una decisi�n: crear el ADR con got adr new y referenciarlo en el commit. Si no quer�s usarlo en alg�n commit, no lo hac�s y listo. No hay penalizaci�n.

�Puedo usar GOT en repositorios privados de la empresa sin preocuparme por licencias?

S�, GOT es open source con licencia MIT, as� que pod�s usarlo en proyectos privados y comerciales sin drama. No hay restricciones ni costos ocultos. Al guardar todo en el repo, no depend�s de ning�n servicio externo que te cobre por cantidad de ADRs o usuarios.

�Qu� pasa si mi equipo no quiere escribir ADRs?

La parte opinada de GOT es una sugerencia fuerte, pero no una obligaci�n t�cnica. Pod�s configurarlo para que sea m�s lava o m�s estricto seg�n la cultura del equipo. Incluso pod�s empezar vos solo documentando decisiones clave y mostrar el valor; generalmente cuando el resto ve c�mo los salva de perder horas buscando contexto, se copan. La barrera es cultural, no t�cnica.

�GOT se integra con GitHub, GitLab o Bitbucket?

Al vivir en el repositorio, GOT es compatible con cualquier plataforma de alojamiento Git. Los ADRs son archivos markdown, as� que se renderizan en la UI de GitHub/GitLab sin configurar nada. Si quer�s visualizaci�n avanzada de relaciones, hay herramientas complementarias, pero la funcionalidad base anda en cualquier lado.

�Puedo migrar ADRs existentes que tengo en Confluence o Google Docs a GOT?

Claro. El formato de ADR de GOT es markdown, as� que pod�s copiar el contenido y darle la estructura de contexto, decisi�n, consecuencias. Cre�s el archivo en adrs/ con el n�mero que corresponda y listo. No hay migraciones m�gicas, pero al ser texto plano, es trabajo de copiar y pegar con un poco de orden. Una vez adentro del repo, el resto de la herramienta los reconoce autom�ticamente.

�Hace falta instalar algo en el servidor o en CI/CD para que GOT funcione?

No, cero. GOT es solo una utilidad de l�nea de comandos que cada desarrollador instala localmente si quiere. Los hooks de Git son opcionales y viven en el directorio .git/hooks de cada repo local. Para el CI/CD, los ADRs son archivos normales, as� que pod�s leerlos con un script bash sin necesidad de tener GOT instalado en los runners.