FND-005: Cultura de contribución: colaboración humana, asociación con IA y crecimiento del equipo

A partir de v0.7.0 · Tipo: Cultura · Rev. 2

Referencia canónica · Ratificado por el equipo · Rev. 2 Discusión original de la RFC: #5615

Una nota para el equipo antes de que lean esto.

Este es el quinto documento del marco de madurez de ZeroClaw. Los otros cuatro abordan la arquitectura, la documentación, la gobernanza y la infraestructura de ingeniería, las capas estructurales que hacen que un proyecto funcione. Este aborda algo que esos cuatro dan por sentado pero nunca enseñan explícitamente: cómo trabajar en conjunto.

Las herramientas y los procesos de los otros RFCs solo funcionan tan bien como el equipo que los utiliza. Un pipeline de CI perfecto no ayuda a un equipo que no puede dar retroalimentación honesta. Una arquitectura limpia no sobrevive en un equipo que no puede disentir de manera productiva. Un modelo de gobernanza no fomenta la responsabilidad en personas que nunca han aprendido lo que significa la responsabilidad.

Este documento trata sobre la construcción de ese equipo, no solo de personas técnicamente capaces, sino de personas que saben cómo dar y recibir retroalimentación, cómo pedir ayuda, cómo usar herramientas poderosas de manera responsable y cómo crecer juntas con el tiempo. Estas son habilidades que se pueden aprender. Nadie llega con ellas completamente formadas. Este documento las nombra con la claridad suficiente para que puedas empezar a practicarlas de manera deliberada, aquí, en el contexto de trabajo real que importa.

Nada en este documento es una crítica de quién eres o de dónde partiste. Es un mapa de hacia dónde estamos tratando de ir juntos.

El Conjunto de Marcos de Madurez

Este RFC es el quinto de un conjunto de cinco documentos que juntos forman el marco de madurez de ZeroClaw. Están diseñados para ser leídos como un todo, aunque cada uno puede entenderse por sí mismo.

Los cuatro primeros RFCs responden a preguntas estructurales. Este responde a una pregunta humana: dada la estructura, ¿cómo se comportan las personas dentro de ella entre sí y con sus herramientas? Esta pregunta no tiene un compilador, un linter ni un filtro de CI. Solo tiene los hábitos que construimos, los ejemplos que establecemos y la intencionalidad que le aportamos.

Tabla de contenidos

1. ¿Por qué existe este documento?
2. El trabajo antes del trabajo
3. Trabajar con personas
   • Enviar comentarios
   • Recibir comentarios
   • Solicitar ayuda
   • Disentenderse de manera productiva
   • Propiedad
   • Apoyar a alguien que está luchando
4. Trabajando con IA
   • El modelo mental de delegación
   • La IA funciona en la capa de implementación
   • La amplificación no es magia
   • La disciplina de revisión
   • Lo que esto significa para tu carrera
5. La taxonomía de comentarios
6. Una nota para los revisores y mentores

Historial de revisiones

1. Por qué existe este documento

La mayoría de las guías de contribución te indican cómo abrir un PR. Te dicen qué etiquetas usar, cómo ejecutar el conjunto de pruebas y qué incluir en el mensaje del commit. Esas cosas son importantes, y tenemos documentos que las cubren.

Este documento aborda un tema diferente: las habilidades que determinan si un grupo de personas talentosas se convierte en un equipo funcional o en una colección de individuos que simplemente comparten un repositorio.

Estas son habilidades que se pueden aprender. No son rasgos de personalidad que se tienen o no se tienen. No son cosas que vienen automáticamente con la capacidad técnica. Se practican, lentamente, con retroalimentación, a lo largo del tiempo, de la misma manera que se aprende cualquier otra habilidad. La mayor parte de la educación en ingeniería de software se centra casi por completo en la capa técnica y deja la capa humana al azar. El resultado es que muchas personas técnicamente capaces terminan en equipos que no funcionan bien juntos, sin una comprensión clara de qué es lo que falta o cómo solucionarlo.

El objetivo de este documento es nombrar esas habilidades de manera clara para que puedas comenzar a practicarlas deliberadamente, aquí, en el contexto de un trabajo real que importa.

2. El trabajo antes del trabajo

Antes de escribir una línea de código, abrir una PR o solicitar a una IA que genere algo, hay un conjunto de preguntas que deberías poder responder. Este proyecto utiliza una jerarquía de decisiones para describirlas:

Vision
  └── Architecture
        └── Design
              └── Implementation
                    └── Testing
                          └── Documentation
                                └── Release

La jerarquía se describe en detalle en la RFC de arquitectura (#5574). Lo que importa aquí es el principio detrás de ella: toda decisión que tomes debe poder rastrearse hasta la cima.

En la práctica, esto significa preguntarte a ti mismo antes de comenzar a construir:

• ¿Qué problema estoy resolviendo? No “qué ticket estoy cerrando”: ¿qué problema real le resuelve esto a alguien?
• ¿Esto se ajusta a la arquitectura? Si no puedes describir dónde pertenece esto en la estructura del sistema, aún no comprendes el sistema lo suficientemente bien como para modificarlo.
• ¿Cómo se ve el trabajo completado? Antes de escribir el código, escribe los criterios de aceptación. “Funciona” no es un criterio de aceptación. “Un usuario puede instalar un plugin sin una cadena de herramientas de Rust y este se ejecuta correctamente” sí lo es.
• ¿Quién necesita saber sobre esto? Los cambios que afectan el trabajo de otras personas, o que implican decisiones que todo el equipo debería tomar, necesitan visibilidad antes de la implementación, no después.

Esto no es burocracia. Es la diferencia entre construir algo y construir lo correcto. También se aplica directamente a la forma en que trabajas con herramientas de IA, lo cual cubrimos en la Sección 4.

La versión honesta de lo que sucede cuando te saltas este paso: construyes algo que funciona, abres un PR y luego descubres en la revisión que resuelve el problema equivocado, o resuelve el problema correcto de una manera que entra en conflicto con una decisión que ya se tomó en otro lugar. Eso desperdicia tu tiempo, el tiempo del revisor y retrasa a las personas que dependen del trabajo. El trabajo previo no es algo extra. Es la forma de proteger tu propio esfuerzo.

3. Trabajar con personas

Dar retroalimentación

La retroalimentación es una de las acciones de mayor impacto que puedes ofrecer a otro ingeniero. Un comentario de revisión bien redactado puede enseñar algo que tomaría años aprender por tu cuenta. Por otro lado, uno mal redactado puede desanimar a alguien a volver a contribuir.

Sé específico. Los comentarios vagos generan ansiedad sin dirección.

❌ “Esto es difícil de leer.”

✅ “Esta función está manejando tres responsabilidades distintas: validación de entrada, lógica de negocio y formateo de la respuesta. Considera separarlas para que cada función haga una sola cosa. Eso facilita probar cada parte y entender de un vistazo qué hace cada una.”

La segunda versión es más larga, pero enseña algo. El lector ahora sabe cuál es el problema, por qué es importante y qué hacer al respecto.

Explica el principio, no solo el veredicto. Si le pides a alguien que cambie algo, diles por qué. “Cambia X por Y” produce una solución. “Cambia X por Y porque Z” produce comprensión que se aplica a las próximas diez situaciones donde se aplica el mismo principio.

Separa el trabajo de la persona. “Este enfoque tiene un problema” y “cometiste un error” no son lo mismo. El primero se refiere al código. El segundo se refiere a la persona. Mantén tus comentarios enfocados en el trabajo.

Nombra lo que está bien. No se trata de ser amable. Se trata de ser útil. Cuando le dices a alguien lo que hizo bien y explicas por qué está bien, le enseñas qué patrones repetir. Los elogios genéricos (“¡buen trabajo!”) no enseñan nada. Los elogios específicos (“extraer esto en su propio crate fue la decisión correcta porque significa que ahora podemos probar esta lógica de forma aislada sin levantar todo el bucle del agente”) enseñan el principio y refuerzan la decisión.

Utiliza la taxonomía de comentarios. La taxonomía de la Sección 5 asigna a cada comentario un peso claro. Los revisores que mezclan problemas bloqueantes con sugerencias menores sin distinguir entre ellos obligan al autor a adivinar qué cosas realmente necesitan cambiarse. No hagas que la gente tenga que adivinar.

Recibir comentarios

Esto es más difícil que dar retroalimentación para la mayoría de las personas, y vale la pena ser honesto sobre el porqué.

Cuando has dedicado horas a algo, resolviendo un problema, tomando decisiones, escribiendo el código, y alguien te dice que tiene problemas, la respuesta humana natural es sentir que la crítica es sobre ti. No lo es. Es sobre el trabajo. Aprender a mantener esas dos cosas separadas es una habilidad, y requiere práctica.

Algunas cosas que ayudan:

Lee los comentarios antes de responder a ellos. No solo la línea de resumen, sino el comentario completo, incluida la explicación. Muchas respuestas a los comentarios se escriben como reacción al veredicto antes de que la persona haya asimilado el razonamiento. Lee el porqué antes de decidir cómo te sientes respecto al qué.

Distingue entre “No estoy de acuerdo” y “No lo entiendo.” Estas situaciones requieren respuestas diferentes. Si no entiendes la retroalimentación, haz una pregunta aclaratoria. Si la entiendes y no estás de acuerdo, dilo con evidencia. Ambos son resultados positivos. Lo que no es útil es guardar silencio cuando tienes preguntas, o decir “está bien” cuando realmente no estás de acuerdo.

No tienes que estar de acuerdo con cada comentario para aprender de él. A veces los comentarios son incorrectos. A veces reflejan un conjunto de compensaciones diferente al que estabas optimizando. Tienes permitido objetar. Consulta Discrepar de manera productiva más abajo. Pero incluso los comentarios que finalmente rechaces merecen ser comprendidos por completo antes de decidir rechazarlos.

Cierra el ciclo. Cuando alguien dedica tiempo a revisar tu trabajo, avísale cuando hayas atendido sus comentarios. No tienes que agradecerle efusivamente. Un simple “atendido en el último commit” es suficiente. Le indica que su tiempo valió la pena y mantiene el PR en movimiento.

La retroalimentación sobre tu código no es un reflejo de tu valor. Esto parece obvio. No lo es cuando estás en medio de ello. Todo ingeniero experimentado ha tenido su código revisado por personas con más experiencia, y ese proceso es incómodo cada vez. La incomodidad es la sensación de aprender. No desaparece; simplemente te vuelves mejor para soportarla.

Solicitando ayuda

En la escuela, pedir ayuda puede sentirse como admitir que vas atrasado o que no perteneces. En un equipo, pedir ayuda es una de las cosas más profesionales que puedes hacer.

El costo de quedarse atascado y no preguntar casi siempre es mayor que el costo de preguntar. Tres horas dedicadas a resolver un problema que podría resolverse con una conversación de cinco minutos son tres horas de tu tiempo y del tiempo de tu equipo que se pierden. Saber cuándo preguntar es una habilidad, no una debilidad.

Una buena solicitud de ayuda tiene tres partes:

1. Lo que estás intentando hacer. No solo “está roto”: ¿cuál es el objetivo?
2. Lo que ya has intentado. Esto demuestra que has interactuado con el problema y le da a la persona que te ayuda un punto de partida que no es cero.
3. En lo que estás atascado específicamente. “No sé qué está mal” es un problema diferente a “Sé qué está mal pero no sé cómo solucionarlo” y “Lo solucioné pero no sé por qué mi solución funciona.”

Una solicitud de ayuda que contenga estos tres componentes se resuelve más rápido y te enseña más, porque la persona que te ayuda puede calibrarse exactamente a dónde estás.

Pregunta en público cuando puedas. Una pregunta hecha en un canal compartido o en un PR beneficia a todos los que tengan la misma pregunta más adelante. Una pregunta hecha en privado solo te beneficia a ti. Hay ocasiones en las que lo privado es lo correcto, como comentarios delicados o circunstancias personales, pero las preguntas técnicas sobre el código base casi siempre es mejor hacerlas abiertamente.

No saber algo no es vergonzoso. Nadie lo sabe todo. Los ingenieros que parecen saberlo todo han hecho muchas preguntas a lo largo del tiempo, y las respuestas se han acumulado. La única forma de llegar ahí es empezar a preguntar.

Discordar de manera productiva

Los desacuerdos sobre arquitectura son saludables. Significan que a las personas les importa cómo se construye el sistema y que están prestando atención a las decisiones que se toman. Un equipo donde nadie está en desacuerdo no es un equipo donde todos están de acuerdo. Es un equipo donde las personas han dejado de involucrarse.

La diferencia entre un desacuerdo productivo y uno improductivo suele estar en el enfoque.

Aborda primero la preocupación, no el veredicto.

❌ “Este enfoque es incorrecto.”

✅ “Tengo una inquietud sobre este enfoque: específicamente, si conectamos el gateway directamente al runtime aquí, rompemos la regla de dependencias del RFC §4.2. ¿Podemos discutir si hay una forma de lograr el mismo resultado sin ese acoplamiento?”

La segunda versión abre una conversación. La primera la cierra.

Presenta evidencia. Un desacuerdo arquitectural respaldado por un hecho medible, una sección específica de un RFC o un escenario de fallo concreto es una contribución. Un desacuerdo arquitectural respaldado por “solo siento que” es una opinión. Ambos merecen ser expresados, pero solo uno avanza rápidamente la conversación.

Sé genuinamente abierto a estar equivocado. Si entras en un desacuerdo habiendo decidido ya que tienes razón, no estás teniendo una conversación. Estás haciendo lobby. Las personas pueden notar la diferencia, y eso las hace menos propensas a involucrarse seriamente con tus inquietudes. El objetivo es el mejor resultado para el proyecto, no tener razón.

Cuando el equipo decide, avanza con el equipo. Puedes dejar constancia de tu desacuerdo: en el issue, en los comentarios del RFC, en el hilo del PR, y luego construyes lo que se decidió. Esto no es capitulación. Es así como funcionan los equipos. Un equipo que sigue relitigando decisiones ya tomadas no entrega resultados.

Algunas decisiones son reversibles y otras no. Conoce el tipo de decisión que estás debatiendo. Una decisión sobre el nombre es reversible. Una decisión sobre el protocolo de cable que estará en los binarios de producción durante dos años no lo es. Pondera tu energía en consecuencia.

Propiedad

La propiedad es una de esas palabras que se usa mucho sin una definición clara. Esto es lo que significa en la práctica en este proyecto:

La propiedad implica que ves el problema antes de que te lo pidan. Significa revisar un PR que afecta tu área y notar un efecto secundario que el autor no vio. Significa detectar un problema pendiente sin asignar y tomarlo. Significa no esperar a que te lo digan.

La propiedad significa que tu palabra vale algo. Si registras un issue de seguimiento con tu nombre, ese issue es tu compromiso. No “alguien debería hacer esto”: tú lo harás. Si las circunstancias cambian y no puedes, lo dices a tiempo y buscas a quién traspasarlo. Un sistema de seguimiento lleno de issues registrados y olvidados con nombres adjuntos es un registro de confianza roto.

La responsabilidad no es “yo hice mi parte”. Es “me importa que todo el conjunto funcione”. Puedes ser responsable de un crate sin ser indiferente a si el sistema en el que vive ese crate está sano. Puedes ser responsable de una funcionalidad sin ser indiferente a si los usuarios realmente pueden usarla. La responsabilidad estrecha, “yo hice mi parte, el resto es problema de otro”, produce sistemas que técnicamente tienen responsables para cada pieza y funcionalmente no tienen a nadie responsable de nada.

La propiedad incluye el seguimiento. Enviar código no es el final de la propiedad. Es el comienzo de la responsabilidad de asegurarse de que funcione, de corregir lo que se rompe y de enseñar a la siguiente persona que trabaje en esa área lo que aprendiste.

Apoyar a alguien que está luchando

En algún momento de este proyecto, tendrás más experiencia que otra persona en un hilo. Quizás lleves más tiempo aquí. Tal vez conozcas la parte del código en la que están trabajando. O quizás ya hayas visto este modo de fallo en particular.

Lo que hagas con esa posición es importante.

No solo lo arregles por ellos. Darle a alguien una solución funcional sin explicar qué estaba mal o por qué tu solución funciona produce un PR fusionado y cero aprendizaje. La próxima vez que se enfrenten a un problema similar, estarán en la misma situación. Tómate esos cinco minutos adicionales para explicar lo que viste y por qué el arreglo funciona.

Revise con intención de enseñar. Un PR malo no es solo un problema que cerrar. Es una oportunidad de enseñanza. Una revisión desdeñosa (“esto no sigue la arquitectura”) es menos útil que una revisión que nombra lo que se pasó por alto, explica el principio que se viola y señala dónde puede aprender más el contribuidor. El esfuerzo adicional es una inversión en un contribuidor que escribe mejores PRs a partir de ese momento.

Si alguien está bloqueado y no pide ayuda, di algo. A veces las personas no preguntan porque no quieren dar la impresión de que están teniendo dificultades. A veces no están seguras de a quién preguntar. A veces llevan tanto tiempo luchando que han dejado de notar lo atascadas que están. Un discreto “parece que este lleva abierto un buen tiempo. ¿hay algo que pueda ayudar a desbloquear?” no cuesta casi nada y puede significarlo todo para alguien que está dando vueltas sin avanzar.

Haz que sea seguro no saber cosas. Si las personas en tu equipo sienten que son juzgadas por no saber algo, fingirán que sí lo saben. Esto produce peores decisiones, no mejores. El equipo que hace que sea seguro decir “No lo sé, déjame averiguarlo” toma mejores decisiones que el equipo donde todos fingen confianza.

4. Trabajar con IA

Esta sección trata sobre un tema que la mayoría de las guías de contribución no cubren: cómo trabajar con herramientas de codificación de IA de manera que te haga mejor, no solo más rápido.

El modelo mental de delegación

Esta es la forma más útil de replantear la interacción con la IA para trabajar de manera efectiva:

Trabajar con una IA es la misma habilidad que delegar a una persona.

Cuando delegas trabajo a un colega o a un ingeniero junior, proporcionas contexto. Explicas el objetivo, las restricciones, cómo se ve algo bien hecho y cuáles son los límites. No te limitas a decir “desarrolla esta funcionalidad”. Dices: esto es lo que el usuario intenta hacer, así es como se integra en el sistema, así es cómo sabremos que está terminado y esto es lo que no debes hacer.

Luego, de manera crítica, revisas lo que recibes de vuelta. No aceptas el PR de un ingeniero junior sin leerlo. Verificas si hace lo que se pidió, si encaja con la arquitectura, si tiene cobertura de pruebas, si el manejo de errores es correcto. Das retroalimentación. Puedes iterar.

Las herramientas de IA funcionan exactamente de la misma manera. La calidad de lo que obtienes está determinada casi por completo por la calidad de lo que introduces. Un prompt vago produce una salida vaga. Un prompt con contexto claro, restricciones específicas y criterios de aceptación concretos produce una salida que realmente es útil como punto de partida.

Los ingenieros que tienen dificultades con las herramientas de IA suelen ser los que todavía están aprendiendo a dar instrucciones claras a cualquier cosa: humano o IA. Los ingenieros que prosperan con ellas son los que ya saben lo que quieren antes de pedirlo.

Este modelo mental también implica que la salida es tu responsabilidad. No puedes enviar un PR y decir “la IA lo escribió”. Tú lo revisaste. Tú abriste el PR. Es tu trabajo.

La IA funciona en la capa de implementación

Esta es la limitación técnica más importante que debes comprender.

La generación de código con IA funciona en la capa de implementación de la jerarquía de decisiones:

Vision          ← AI cannot set this. You must.
Architecture    ← AI cannot make these decisions. You must.
Design          ← AI will sometimes guess. You must verify.
Implementation  ← AI can help here.
Testing         ← AI can help, but you define what to test.
Documentation   ← AI can draft. You must review for accuracy.
Release         ← Human judgment required.

Una herramienta de IA generará una función que haga lo que has descrito. No te indicará si esa función pertenece a este crate o a otro diferente. No señalará que el enfoque contradice una decisión arquitectónica tomada hace tres meses. No preguntará si has considerado las implicaciones de seguridad. No notará que estás resolviendo el problema incorrecto.

ZeroClaw es en sí mismo un ejemplo útil. El codebase inicial se creó con asistencia de IA. El resultado, como lo describe el RFC de arquitectura, es “impresionantemente funcional pero arquitectónicamente accidental”. El código hace lo que necesita hacer hoy, pero no fue diseñado, se fue acumulando. Eso no es un fallo de las herramientas de IA. Es un resultado predecible de usar herramientas de la capa de implementación sin antes realizar el trabajo de visión, arquitectura y diseño que le da dirección a la implementación.

La solución no es usar menos IA. Es hacer tú mismo el trabajo de la parte superior de la jerarquía, siempre, antes de pedirle a la IA que construya algo.

La amplificación no es magia

Las herramientas de IA amplifican tus capacidades existentes. Esa es la descripción honesta de lo que hacen.

Si tienes una visión clara, una arquitectura definida, criterios de calidad que puedes articular y la capacidad de evaluar los resultados de forma crítica, la IA es un auténtico multiplicador de fuerza. Avanzas más rápido. Exploras más opciones. Escribes más pruebas. Redactas más documentación.

Si no tienes esas cosas. La IA genera mucho código que parece convincente y no se sostiene. Genera pruebas que pasan sin probar nada significativo. Genera documentación que describe el código pero no la intención. Genera arquitectura que es localmente consistente y globalmente incoherente.

La amplificación es neutral. Amplifica las entradas buenas y las malas con igual entusiasmo.

Esto significa que la habilidad más valiosa en un flujo de trabajo asistido por IA no es la ingeniería de prompts. Es la capacidad de evaluar la salida. Esto requiere saber cómo se ve algo bueno antes de solicitar cualquier cosa. Lo que te lleva de vuelta, una y otra vez, a la cima de la jerarquía de decisiones.

Una autoverificación útil antes de usar una herramienta de IA para implementar algo:

• ¿Puedo describir el problema en una oración sin mencionar detalles de implementación?
• ¿Puedo nombrar la sección del RFC o la decisión de diseño que esta implementación sirve?
• ¿Puedo describir cómo se ve una implementación correcta antes de ver una?
• ¿Puedo explicar por qué una implementación generada es correcta o no después de verla?

Si la respuesta a alguna de estas preguntas es no, aún no estás listo para implementar. Todavía estás en la fase de diseño.

La disciplina de revisión

El código generado por IA requiere la misma disciplina de revisión que el código escrito por humanos. En algunos aspectos, requiere más, porque el área de problemas que estás verificando es más amplia.

Cuando revises resultados generados por IA, ya sean tuyos o de otra persona, verifica lo siguiente:

Ajuste arquitectónico. ¿Respeta las reglas de dependencia? ¿Se encuentra en el crate adecuado? ¿Introduce un acoplamiento que el diseño evita explícitamente?

Corrección en los límites. Los modelos de IA son muy buenos en el caso común y frecuentemente fallan en el caso límite. Verifica qué sucede cuando las entradas están vacías, son nulas, están malformadas o tienen el tamaño máximo esperado. Verifica qué sucede cuando una dependencia no está disponible.

Implicaciones de seguridad. Las herramientas de IA no tienen una mentalidad de seguridad por defecto. Generarán código que acepta entradas del usuario sin validación, que registra valores sensibles, que utiliza primitivas criptográficas obsoletas y que abre rutas de archivos sin verificarlas. Debes aplicar explícitamente una perspectiva de seguridad.

Calidad de las pruebas. Las pruebas generadas por IA con frecuencia prueban la implementación en lugar del comportamiento. Una prueba que afirma que una función devuelve un valor de struct interno específico no es una prueba de comportamiento. Es una instantánea de la implementación que se romperá cada vez que la implementación cambie. Pregúntese: ¿esta prueba verifica que el sistema hace lo que el usuario o el invocador necesita, o verifica que el código hace lo que hace actualmente?

Completitud. Las herramientas de IA optimizan para una completitud que parece plausible. Generarán código que maneja exhaustivamente el caso de éxito y de manera superficial el caso de error. Verifica que los errores se propaguen, manejen o muestren de una manera que sea realmente útil para quien llama.

Lo que esto significa para tu carrera

Las habilidades que se describen aquí: dar instrucciones con claridad, evaluar resultados de forma crítica, entender dónde encaja un componente dentro de un sistema más grande, saber cómo se ve un buen resultado antes de construirlo, no son habilidades específicas de la IA. Son las habilidades que hacen de alguien un ingeniero eficaz, un líder técnico eficaz y, con el tiempo, un gerente de ingeniería eficaz.

Los ingenieros que serán más valiosos en un mundo saturado de código generado por IA no son aquellos que pueden escribir más código más rápido. Son aquellos que pueden determinar si el código es correcto. Eso requiere pensamiento sistémico, juicio arquitectónico y la capacidad de evaluar el trabajo en función de un estándar que has internalizado.

Todo lo que practicas aquí: entender el RFC antes de implementarlo, preguntar “por qué” antes de construir, revisar la salida de la IA con el mismo ojo crítico que aplicarías al PR de un ingeniero junior, es práctica para ese tipo de criterio. Se acumula. Cada PR en el que te involucras seriamente con la arquitectura es un punto de datos que facilita la siguiente decisión arquitectónica.

Los colaboradores de este proyecto tienen una ventaja inusual: están desarrollando estos hábitos en un sistema real, con restricciones arquitectónicas reales, con personas que revisarán su trabajo y explicarán por qué. Esa combinación es poco común. Vale la pena tomárselo en serio.

5. La taxonomía de retroalimentación

Cada comentario de revisión en este proyecto lleva un peso explícito. Usar esos pesos de forma coherente significa que los revisores se comunican con claridad y los autores saben exactamente qué requiere acción.

Las categorías a continuación describen la intención de revisión del proyecto. Las revisiones de PR plasman esa intención a través de los encabezados con emojis del protocolo de revisión: 🔴 bloqueante, 🟡 advertencia, 🔵 sugerencia, 🟢 elogio y ✅ resuelto. Usa docs/book/src/contributing/pr-review-protocol.md para conocer el formato exacto de revisión de PR.

✅ Reconocimiento

Algo que el autor hizo bien, nombrado específicamente y explicado para que el patrón se repita.

Esto no es cortesía. Los elogios genéricos (“¡buen trabajo!”) no enseñan nada. Los elogios específicos con una explicación enseñan el principio detrás de lo que se hizo bien, lo cual se aplica a cada decisión futura en la misma categoría.

Las felicitaciones no requieren acción. Su propósito es reforzar.

Ejemplo: “Extraer el analizador de llamadas a herramientas a su propio crate fue la decisión correcta: este código no tiene ninguna dependencia del estado del agente y ahora se puede probar de forma independiente. Las 91 pruebas que agregaste son exactamente el tipo de cobertura que sería imposible de lograr cuando esta lógica vivía dentro de loop_.rs.”

🔴 Bloqueando

Algo que debe resolverse antes de que se fusione la PR. Los elementos bloqueantes se dividen en dos categorías:

• Violaciones arquitectónicas: código que cruza un límite de dependencia que el diseño prohíbe explícitamente, o que contradice una decisión registrada en un RFC o ADR.
• Regresiones de calidad: falta de cobertura de pruebas para el nuevo comportamiento, problemas de seguridad, incompatibilidad con el contrato existente o código que introduce un defecto.

Un comentario bloqueante explica cuál es el problema, por qué es importante y, cuando es posible, cómo se ve una vía de resolución. Un comentario bloqueante no es un juicio sobre el autor. Es la responsabilidad del revisor hacia el código base y los usuarios que dependen de él.

Los autores no deben interpretar un comentario bloqueante como un rechazo. Es un problema específico y resoluble. Abórdalo y sigue adelante.

🟡 Condicional

Algo aceptable para posponer, pero solo con un problema rastreado comprometido y un asignado. Un elemento condicional es el revisor diciendo: Confío en que esto se abordará, pero necesito ese compromiso registrado antes de fusionar.

La distinción entre bloqueo y condicional a menudo se refiere al tiempo y al riesgo. Una función que falta y que se entregará en el próximo PR es condicional. Una función que falta y que crea una brecha de seguridad es de bloqueo.

Un aplazamiento condicional sin responsable asignado no es un aplazamiento. Es un deseo. Los issues registrados sin propietario tienden a permanecer abiertos indefinidamente. Cuando un revisor marca algo como condicional, está solicitando un compromiso con nombre y apellido, no una intención futura teórica.

🔵 Decisión del equipo

Una pregunta que el PR pone de manifiesto y que ningún revisor o autor debería responder de manera unilateral. Las decisiones de equipo implican compromisos que afectan la dirección del proyecto, su arquitectura o sus usuarios, y pertenecen al grupo.

Usar esta etiqueta es la forma en que los revisores evitan retrasar a los contribuidores individuales con preguntas que en realidad son sobre la dirección compartida. Saca a la luz la decisión, plantea las ventajas y desventajas, y pide al equipo que dé su opinión, sin hacer que el autor sienta que su PR está bloqueado por algo que no está bajo su control.

Las decisiones del equipo deben responderse en el hilo del PR, de manera documentada, por las personas que deben asumir la responsabilidad del resultado. Una decisión tomada en una conversación paralela que no se refleje en el hilo del PR no existe para quienes lean el historial más adelante.

6. Una nota para los revisores y mentores

Si estás en una posición de revisar el trabajo de otra persona, ya sea como propietario del código, como colaborador con más experiencia o simplemente como alguien que lleva más tiempo aquí, esta sección es para ti.

Estás modelando cómo se ve la colaboración. Cada revisión que escribes le enseña al autor cómo revisar. Cada pregunta que haces en un hilo de PR les enseña a los contribuidores más nuevos qué preguntas vale la pena hacer. No puedes optar por no hacerlo: la única opción es si lo haces de forma intencional o accidental.

La exhaustividad es un acto de respeto. Una revisión exhaustiva que explica su razonamiento es más respetuosa con el esfuerzo del autor que una aprobación rápida. El autor dedicó tiempo a su trabajo. Merece entender por qué está o no listo para fusionarse, y qué puede llevarse de la interacción.

El objetivo de cada interacción de revisión es dejar al autor mejor preparado de lo que estaba antes. No solo producir un PR fusionado. No demostrar tu propio conocimiento. No imponer reglas. Dejar al autor con algo que pueda usar: un principio, un patrón, una comprensión de un compromiso, que se aplique más allá del PR inmediato.

Nombra el patrón, no solo la instancia. Cuando pidas un cambio, explica el principio que hay detrás. “Renombra esta variable a algo que describa lo que contiene” es menos útil que “los nombres de variables deben describir su propósito desde la perspectiva de quien las llama, no desde la implementación: ¿qué le importa realmente a quien llama a esta función que represente este valor?” La segunda versión se aplica a cada variable de cada función que el autor escribirá en su vida.

Sé honesto sobre qué es tu preferencia y qué es un requisito. “Yo escribiría esto de otra manera” no es lo mismo que “esto debe cambiar”. Si estás expresando una preferencia, dilo. Si estás citando un requisito estricto: arquitectura, seguridad, compatibilidad, cita la razón específica. Los autores que no pueden distinguir entre la preferencia del revisor y la necesidad arquitectónica cambiarán todo o no cambiarán nada. Ninguna de las dos opciones les beneficia.

El equipo que estás ayudando a construir es el equipo en el que trabajarás. La inversión que haces en una revisión cuidadosa y educativa hoy se traduce en un colaborador que escribe mejor código, abre mejores PRs y revisa el trabajo de otros con más reflexión. Esto mejora el proyecto. También facilita tu propio trabajo, porque las personas a tu alrededor están creciendo.

Esto no es una habilidad blanda. Es trabajo de ingeniería.