Flujo de trabajo con IA

Este proyecto se construyó con Claude Code. La mayoría de las afirmaciones de “construido con IA” se quedan en la etiqueta. Aquí está el panorama completo: qué sabe la IA, cómo funcionan las sesiones, cómo se ve el prompting en la práctica y dónde traza la línea el humano. Si estás construyendo con IA tú mismo, o simplemente tienes curiosidad por saber cómo es realmente, esto es para ti.

Lo que sabe la IA

Claude Code tiene un archivo de memoria persistente que mantiene el contexto entre sesiones. En lugar de re-explorar el código base en cada conversación, retoma donde lo dejamos. Esto es lo que contiene (sanitizado):

Identidad del proyecto

Nombre de la aplicación, ubicación del código fuente, licencia, identificador de la app
Relación de fork: el upstream es En Croissant de Francisco Salgueiro, nosotros mantenemos nuestro propio fork de forma independiente
Por qué existe el fork: el mantenedor del upstream declinó la funcionalidad de TTS, lo cual es justo — visiones diferentes para el mismo proyecto

Reglas de compilación

Solo pnpm — npm rompe vanillaExtract (pantalla en blanco en tiempo de ejecución, sin error, simplemente nada)
Se requiere Node.js 22+ (Vite 7 necesita crypto.hash)
Siempre ejecutar pnpm format && pnpm lint:fix antes de hacer commit
Cerrar la aplicación antes de sobrescribir el binario (“Text file busy”)
Después de mover directorios de código fuente, ejecutar cargo clean para limpiar referencias de rutas obsoletas

Conocimiento de la arquitectura

Qué archivos son responsables de qué funcionalidades (átomos en atoms.ts, navegación del árbol en tree.ts, motor TTS en tts.ts)
Por qué todos los átomos de TTS necesitan getOnInit: true (lecturas imperativas vía store.get() antes de que React se suscriba)
Cómo funciona la caché de audio (claves provider:voiceId:lang:text)
La corrección de coordenadas de chessground es del lado CSS, no un fork de la biblioteca
Disposición de los datos: qué vive dónde, qué está enlazado simbólicamente, qué sobrevive a los reinicios de la app

Lo que no sabe

La memoria no contiene claves API, contraseñas ni credenciales. Hace referencia a sus ubicaciones de almacenamiento (nombres de átomos en localStorage) pero nunca a los valores. La IA genera código que lee las claves desde la configuración — nunca ve ni manipula los secretos reales.

Lo que se le indica a la IA

Más allá del archivo de memoria, Claude Code sigue reglas incorporadas en su sistema:

No sobreingeniería. Solo hacer los cambios que se solicitan directamente. Una corrección de bug no necesita que se limpie el código circundante. Tres líneas similares de código son mejor que una abstracción prematura.
No inventar URLs. Nunca fabricar enlaces ni endpoints.
Leer antes de editar. Nunca proponer cambios a código que no se haya leído.
Preferir editar a crear. No crear archivos nuevos a menos que sea absolutamente necesario.
Sin vulnerabilidades de seguridad. Vigilar inyección, XSS y los problemas del top 10 de OWASP.
Preguntar ante la incertidumbre. Si una instrucción es ambigua, preguntar en lugar de adivinar.
Medir dos veces, cortar una. Las operaciones destructivas (force push, reset —hard, eliminar archivos) requieren aprobación humana explícita.

Escribir buenos prompts

La diferencia entre una interacción con IA útil y una frustrante es casi siempre el prompt.

Sé específico sobre lo que quieres. No “arregla el bug” sino “la clave de caché de TTS no incluye el nombre del proveedor, así que al cambiar de ElevenLabs a Google se reproduce el audio cacheado de ElevenLabs en lugar de generar audio nuevo.”

Incluye contexto que la IA no tiene. La IA puede leer tu código, pero no puede leer tu mente. “El usuario reportó que las coordenadas están al revés en el tablero” es menos útil que “el CSS en chessgroundBaseOverride.css tiene las filas y columnas intercambiadas — el original de Francisco las tenía al revés.”

Establece tus restricciones. “No crees archivos nuevos” o “usa el patrón de átomos existente” o “esto necesita funcionar sin clave API” le dicen a la IA dónde están los límites.

Di lo que no quieres. “No agregues manejo de errores para casos que no pueden ocurrir” o “no refactorices el código circundante” previene la sobreingeniería — el modo de fallo más común de la IA.

El patrón es: intención + contexto + restricciones. Domina eso y la IA se vuelve dramáticamente más útil.

Modo planificación: usar un Claude para dar instrucciones a otro

Claude Code tiene un “modo planificación” que separa el pensamiento de la ejecución. En modo planificación, la IA lee archivos, explora el código base y produce un plan — pero no escribe código. Tú revisas el plan, lo ajustas, y luego cambias al modo de implementación donde la IA ejecuta.

¿Por qué funciona? Porque la parte más difícil de cualquier tarea de programación no es escribir el código. Es descubrir qué código escribir — qué archivos cambiar, qué patrones seguir, qué casos límite existen. El modo planificación dedica toda la atención a esa pregunta antes de que se escriba una sola línea.

De este proyecto: cuando reestructuramos el menú de Ayuda para agregar el selector de Idioma, la conversación en modo planificación exploró cómo funcionan los menús de Tauri, qué átomos ya existían, cómo el visor de documentación resolvía las rutas de recursos y cómo era la API del diálogo de confirmación. Para cuando cambiamos a implementación, la IA tenía un mapa completo de los cambios. Sin arranques en falso.

Esencialmente estás usando una instancia de la IA como arquitecto senior y otra como desarrollador. El mismo modelo, roles diferentes.

Cómo funcionan las sesiones

Una sesión típica se ve así:

El humano declara la intención. “Agregar nota de caché a la sección de KittenTTS.” “Eliminar la telemetría de PostHog.” “Las calificaciones de calidad están mal, aquí está lo que deberían ser.”
La IA lee los archivos relevantes. No adivina qué hay en un archivo. Lo lee, comprende el estado actual y luego propone cambios. Se leen múltiples archivos en paralelo cuando son independientes.
La IA hace el cambio. Ediciones dirigidas a archivos existentes. No reescrituras — modificaciones quirúrgicas que preservan todo lo que las rodea.
El humano revisa. Cada edición se muestra antes de escribirse en disco. El humano aprueba, rechaza o redirige. “No, eso es demasiado suave — di que genuinamente apesta.” “Mueve ese párrafo más arriba.” “Eso no es lo que quise decir.”
Commit cuando se indica. La IA nunca hace commit por iniciativa propia. El humano dice “commit” o “commit and push.” Los commits incluyen Co-Authored-By: Claude Opus 4.6 — siempre atribuidos, nunca ocultos.

Ventanas de contexto y puntos de guardado

Toda conversación con IA tiene una ventana de contexto — la cantidad total de texto que puede mantener en memoria a la vez. Cuando la conversación se hace lo suficientemente larga, los mensajes más antiguos se comprimen para hacer espacio.

Dos estrategias: mantener las conversaciones enfocadas (una tarea por conversación), y usar puntos de guardado (Claude Code guarda las transcripciones como archivos JSONL que puedes retomar con el contexto completo restaurado). El archivo de memoria sirve un propósito diferente — es una base de conocimiento persistente que sobrevive a todas las conversaciones.

Lo que propone la IA vs. lo que se publica

La primera sugerencia de la IA rara vez es la versión final. Un intercambio típico:

La IA redacta algo razonable
El humano dice “demasiado corporativo” o “sé más directo” o “eso está mal, aquí está el porqué”
La IA ajusta
El humano aprueba

El gusto, el tono y la decisión final son siempre humanos. La IA se encarga de la velocidad — leer archivos, comprender el contexto, hacer ediciones precisas a lo largo de un código base que puede mantener en memoria. El humano se encarga del juicio — qué construir, cómo debería sentirse, cuándo parar.

Habilidades y comandos slash

Claude Code soporta “habilidades” — prompts reutilizables almacenados como archivos markdown en el directorio .claude/commands/. Se invocan con un comando slash, como /translate-docs.

Este proyecto usa una habilidad /translate-docs que automatiza la traducción de documentación a múltiples idiomas. El archivo de la habilidad contiene las instrucciones completas: qué archivos traducir, qué formato usar, cómo manejar los bloques de código y enlaces, qué tono mantener. En lugar de explicar todo eso cada vez, simplemente escribes /translate-docs y la IA sabe exactamente qué hacer.

Las habilidades codifican proceso, no solo información. Puedes construirlas para cualquier flujo de trabajo recurrente: ejecutar pruebas, desplegar, revisar PRs, actualizar changelogs.

Principios de programación

El documento completo de principios vive en el repositorio en .claude/01_UNIVERSAL_PRINCIPLES.md. Comenzó como Clean Code de Robert C. Martin (2008) más adiciones para la era de la IA. Luego tuvimos una conversación honesta sobre qué sigue vigente y qué no.

Lo que es atemporal

Nombres que revelan la intención. Siempre. Para siempre.
Las funciones hacen una sola cosa. El verdadero principio es la coherencia, no el tamaño.
Sin efectos secundarios. Sigue siendo la fuente de la mayoría de los bugs.
Los comentarios explican el porqué, no el qué.
Responsabilidad única. Un módulo debería tener una sola razón para cambiar.
Programar contra interfaces, no implementaciones.
No silenciar errores. Cada error es información.
Diseño emergente: pasa todas las pruebas, sin duplicación, expresa intención, minimiza complejidad. En ese orden.

Lo que es contextual

Estos principios son sólidos, pero las reglas específicas reflejan un mundo pre-IA o específico de un lenguaje. Aplicamos el espíritu, no la letra:

DRY. La duplicación que diverge con el tiempo es peligrosa. Pero extraer cada patrón repetido en una abstracción crea indirección que puede ser peor. A veces tres líneas legibles aquí mismo son mejor que una abstracción prematura en otro archivo.
Ceremonia estricta de TDD. El principio — publicar código probado, saber que funciona — es innegociable. La ceremonia — el test debe existir antes que el código — fue diseñada para un flujo de trabajo donde los humanos escriben lento. Escribe pruebas. Asegúrate de que pasen. Si el test o el código vino primero es menos importante que si ambos existen.
La Regla del Boy Scout. “Deja el campamento más limpio” — sí. Pero el Boy Scout limpiaba el campamento, no todo el bosque. Arregla lo que tocas. No refactorices la estructura completa de un archivo porque cambiaste una línea en él.

Adiciones de la era de la IA

La guía basada en principios escala mejor que las reglas. El principio permite el juicio; la regla es frágil.
Si el agente lo construye, el agente puede mantenerlo. Conserva el contexto de la conversación y los artefactos. Documenta el proceso de construcción, no solo el resultado.
Claro antes que ingenioso. El sistema que construyó esto necesita reconstruir el razonamiento y modificarlo correctamente. La estructura explícita supera a las pequeñas abstracciones ingeniosas.
¿Podría esto convertirse en infraestructura? Una herramienta resuelve un problema para ti. La infraestructura permite que otros construyan sobre ella. Diseña en consecuencia.

Dónde traza la línea el humano

La IA es una herramienta. Una notablemente buena. Pero hay cosas que no hace:

Decisiones de producto. Qué funcionalidades construir, qué eliminar, cómo debería sentirse la app. “La calificación de calidad de System TTS debería decir ‘pasable’ porque genuinamente apesta” — esa es una decisión humana basada en haberlo escuchado realmente.
Gusto. La IA puede escribir prosa limpia, pero la voz del proyecto, la decisión de ser directo sobre la calidad, la elección de dar crédito a Francisco de forma prominente — esas son decisiones humanas.
Ética. Eliminar PostHog no fue una tarea de refactorización. Fue “la página de configuración dice que no recopilamos telemetría, pero hay una clave API activa de PostHog en el código. Eso es mentira. Arréglalo.” La IA ejecutó. El humano identificó el problema y le importó.
Ajedrez. Al tablero no le importa tu tooling.

Por qué compartir esto

Porque “construido con IA” se ha vuelto un término sin sentido. Todos lo dicen. Nadie lo muestra. La pregunta interesante no es si la IA estuvo involucrada — es cómo estuvo involucrada, y qué contribuyó realmente el humano.

Esta es la respuesta. El humano aporta la visión, el gusto, el juicio y la responsabilidad. La IA aporta la velocidad, la memoria y la voluntad incansable de leer mensajes de error de Rust a las 2 de la mañana.

Ninguno construye esto solo. Ambos son reconocidos. Ese es el trato.

En Parlant~ es un fork de En Croissant de Francisco Salgueiro, construido con Claude Code de Anthropic.