Historia del estudio ~6 min de lectura
Capítulo 2 — Un senior sin estructura en la cabeza
Los agentes de código no son juniors. Son seniors sin estructura en la cabeza — y sin paredes, arman un Frankenstein excelente.
Guía de capítulos 6 capítulos
01 / Metáfora
Un senior sin estructura en la cabeza
Hay un momento al que llega todo el que trabaja con agentes de código. Le das una tarea real en un repo real, te vas, y volvés a algo raro: el código está bien. Bien de verdad — tipado, testeado, mejor de lo que habría escrito la mitad de los ingenieros que manejé. Y está en el lugar equivocado. Una carpeta helper nueva que no existía hace una hora. Un componente partido en tres ubicaciones, cada una defendible por sí sola, ninguna donde vive todo lo demás.
Nadie fue vago. Nadie fue desprolijo. La cosa simplemente… creció.
La línea estándar sobre las herramientas de código con IA es que son como desarrolladores juniors. Rápidos, con ganas, necesitan supervisión. Creí una versión de eso durante un tiempo, y está mal de una forma que importa.
Un junior tiene capacidad limitada y, si es bueno, lo sabe. El junior que choca con algo confuso y pregunta — ese crece hasta middle. El junior demasiado tímido para preguntar se queda bloqueado para siempre. De un modo u otro, los límites del junior te protegen. Solo puede hacer líos chicos.
Un agente de IA es el animal opuesto. Es un desarrollador senior — pero un senior sin estructura en la cabeza. Técnicamente puede hacer cualquier cosa. Vio cada patrón, cada framework, cada truco ingenioso de los datos de entrenamiento, y no sostiene ninguno como la forma en que hacemos las cosas acá. Así que si no lo enmarcás, no se traba como un junior tímido. Arranca. Con confianza, con competencia, en todas las direcciones a la vez — y te arma un Frankenstein. Cada extremidad excelente. El conjunto, un monstruo.
De eso trata este capítulo. No de escribir reglas. De construir paredes.
02 / Distracción
Lo que no se puede instalar con npm
Primero quiero sacar una cosa del medio, porque un montón de posts de "cómo hicimos que la IA escriba buen código" se gastan enteros en esto: el lint. Las reglas de lint son un problema resuelto desde hace una década. Existen configs compartidas para cada lenguaje; las instalás, las enganchás a un pre-commit hook, y listo. Lo hicimos en la primera semana y fue la semana de trabajo menos interesante del estudio. Si tu historia de calidad con IA termina en "agregamos ESLint," todavía no empezaste.
Lo que no se puede instalar con npm es un sistema de archivo.
03 / Paredes
Dale la estructura que no tiene
El nuestro empezó años antes que el estudio, en equipos humanos, como atomic design — esa vieja idea de front-end de ordenar componentes en átomos, moléculas, organismos. Era una forma decente de hacer que un equipo de personas coincida en dónde va cada cosa. Después el equipo dejó de ser gente, y la convención mutó bajo presión hacia otra cosa.
Lo que es ahora, más o menos: cada proyecto tiene el mismo esqueleto. El código de feature — lo que se shippea junto — vive en features/, cada feature con sus propios components, hooks, services y types adentro. Las utilidades transversales van a lib/. La UI compartida va a components/, y los primitives de vendor viven en una carpeta que nadie tiene permitido refactorizar. Un componente no es un archivo, es una carpeta: Button/ guarda Button.tsx, Button.types.ts, Button.hooks.ts, Button.test.tsx, y un barrel index.ts. Cuando un componente crece piezas privadas, no se van a pasear — se quedan en la carpeta como Profile.BookLine.tsx, con el nombre del padre en puntos. Hasta hay una tablita de decisión: ponelo acá cuando esto es verdad, allá cuando aquello lo es.
Nada de esto es ingenioso. Ese es el punto. Atomic design preguntaba "¿qué tan abstracto es esto?" — una pregunta por la que dos personas inteligentes pueden pelear una hora. El sistema actual pregunta "¿esto se shippea con un feature o no?" — una pregunta con respuesta.
Cuando escribí la primera versión de esta convención, la justificación que puse en el documento era que el naming consistente "reduce la carga cognitiva." Escribía para humanos cansados — para la próxima persona que abre el repo a las 2am. Ya no hay próxima persona. Pero la convención se recontrató para un laburo mejor: un agente que nunca vio el repo puede adivinar el path de cualquier cosa y acertar. ¿Dónde están los hooks de la página de perfil? Ya lo sabés. Nunca estuviste acá, y ya lo sabés.
Eso es lo que hace una pared por un senior sin estructura en la cabeza. No limita lo que puede construir — igual podría construir cualquier cosa. Responde, antes de que pregunte, la única pregunta que de otro modo contestaría distinto cada vez: ¿dónde va esto? Le das la estructura que no tiene. Un castillo de arena con paredes: adentro, andá tan rápido como quieras.
04 / Cumplimiento
No comparten el mismo destino
Ahora la parte que preferiría saltearme.
Hace un tiempo, hablando con mis propios agentes sobre exactamente esta convención, me escuché decir: "Escribí los requisitos de estructura, pero no estoy seguro de si ustedes de verdad lo hacen." Medio en joda. Después revisé.
Hay tres capas. No comparten el mismo destino.
El tamaño de archivo es una pared de verdad. check-file-size.ts — ningún archivo fuente pasa de 250 líneas efectivas, las líneas en blanco y los comentarios no cuentan, aviso a las 150. Los tests tienen 200/400 porque los tests se repiten. Corre en cada bun run lint, es uno de siete guards, y sale con código distinto de cero. El build muere. Ese siempre funcionó.
El naming de archivos es distinto. check-file-naming.ts chequea tres cosas concretas: CSS y SCSS tienen que ser kebab-case; los components de TypeScript y TSX tienen que ser PascalCase — Button.tsx, LandingPage.tsx; las migraciones tienen que ser YYYYMMDDHHMMSS_description.sql. Saltea tests y archivos generados. Tiene un ratchet para que las violaciones existentes no empeoren y los archivos nuevos obedezcan. El script está escrito. Funciona. Y no tenía ningún call site — nada en la cadena de lint de siete guards, nada en CI, nada en ningún lado lo invocaba. Estaba en la carpeta de scripts como una alarma de humo todavía en su caja.
Peor: standards/naming-conventions.md, el documento que escribí, dice en texto plano que está "Wired into each repo's lint script and runs in CI before per-directory lints." Esa oración nunca fue verdad.
La ubicación de carpetas es la tercera capa — la parte en la que este capítulo gastó sus mejores páginas. Features en features/, utilidades compartidas en lib/, components como carpetas y no como archivos, piezas privadas anidadas y nombradas según su padre. Hay una tabla de decisión de placement en el estándar. Nada chequea nada de eso. Nunca se escribió un guard. Vive solo en documentación que los agentes leen y eligen seguir.
05 / Admisión
Construir las paredes no es lo mismo que cerrarlas
Arreglé el del medio. Una línea de config. El guard de naming está en el lint ahora. Pasa limpio en 1.535 archivos — sin migración, solo un cable que nunca se había conectado. La convención de carpetas, la más nuestra de las tres, todavía no la hace cumplir nada en absoluto.
Construir las paredes no es lo mismo que cerrarlas. Escribí las reglas, escribí uno de los guards, escribí la documentación que decía que ese guard corría — y me salteé la línea aburrida que habría hecho verdadera la afirmación. El fallo más humano de todo el estudio, y es mío.
06 / Realidad
Una regla que no se hace cumplir es una sugerencia
Con estos sistemas, una regla que una máquina no hace cumplir es una sugerencia. Y un senior sin estructura en la cabeza es exactamente quien no va a tomar una sugerencia. Sigue el documento nueve de cada diez veces. La décima, a las tres de la mañana, en un archivo que no vas a leer por un mes, improvisa.
Lo cual me deja donde todavía estoy: una ventana de editor, un agente a la vez, leyendo cada diff yo mismo.
Próximo capítulo: por qué abandoné el editor por completo — y por qué la forma en que construyo software hoy no tiene una ventana de código en absoluto.