Vibe coding para el diseño 3D con OpenSCAD y Claude Code

OpenSCAD es una herramienta para diseñar modelos 3D basados en código. Tiene ya sus años —la última versión estable es de hace tiempo, aunque las versiones de desarrollo siguen actualizándose— y su paradigma de diseño es muy distinto al de las aplicaciones de modelado visual como FreeCAD, SolidWorks o Fusion 360.

Mi contacto con OpenSCAD fue hace ya bastantes años, cuando me hice con mi primera impresora 3D, la Arduino Materia 101 (básicamente una Sharebot Kiwi 3D), que compré en kit para montarla yo mismo. Necesitaba una herramienta para crear los modelos y OpenSCAD era la opción sencilla para mí, ya que estaba familiarizado con el diseño CSG por código gracias al raytracer POV-Ray, que conocí por un artículo publicado en la revista PCManía, de Hobby Press —¡qué tiempos!

Los diseños en OpenSCAD son, en esencia, código en un lenguaje de programación particular. Los objetos se modelan mediante operaciones sobre primitivas básicas —cubos, cilindros, esferas— o a partir de la extrusión de un polígono.

La IA es buena generando código y OpenSCAD no es una excepción. Pero una cosa es generar código y otra hacer vibe coding para diseñar piezas. A lo largo del artículo veremos la estructura de repositorio que monté a modo de harness alrededor de Claude Code para diseñar piezas imprimibles.

Estructura de proyectos

Todo vive en un monorepo, organizado de forma que favorezca reutilizar lo que ya está resuelto. La unidad es el proyecto, cada uno con su carpeta bajo projects/. Los proyectos no dependen entre sí — solo se les permite depender de componentes y de librerías:

• Componentes (components/) — módulos reutilizables entre proyectos. Son piezas físicas concretas y cada uno tiene un proyecto asociado donde se incluye toda su documentación.
• Librerías (lib/) — módulos reutilizables genéricos, sin proyecto asociado. Contienen primitivas muy básicas de las que tira todo lo demás.

Las dependencias solo bajan —projects → components → lib, y un proyecto puede tirar de lib directamente— y nada depende nunca de un proyecto.

También hay una herramienta que sirve el catálogo en el navegador, para ver de un vistazo todo lo que llevas diseñado: una tarjeta por proyecto con su render 3D y, dentro, cada pieza imprimible, sus planos y su documentación.

El catálogo servido en local con ./catalog.sh. Permite ver todas las piezas de una pasada, sin ir abriéndolas una a una.

El harness

Además de los proyectos, se incluye un conjunto de elementos que determinan el comportamiento del agente —Claude Code— para el diseño efectivo de piezas en 3D.

Contexto en capas. Un CLAUDE.md raíz define la arquitectura y las convenciones del repo; cada capa (projects/, components/, lib/) y cada proyecto llevan el suyo con sus reglas concretas. Cada hecho se define en un solo sitio y lo demás enlaza — el raíz mantiene un mapa de “quién es dueño de qué” para que el agente encuentre la regla sin cargarlo todo.

Documentación de referencia. docs/ concentra el resto: un glosario que fija el vocabulario CAD e impresión 3D, las normas de construcción y la guía de las herramientas. También se definen convenciones de generación de código, como por ejemplo la anotación MEASURED (verificada contra la pieza física) o ADJUST (estimación).

Skills — los flujos de trabajo. Dos skills conducen el diseño según el punto de partida. Si se parte de una especificación de diseño, el agente pide aclarar la intención y las medidas concretas, apoyándose en piezas de test baratas que se imprimen para verificar cada encaje contra la pieza real. Si en cambio se parte de un STL existente, el agente analiza primero el diseño para identificar sus características.

Subagentes. Dos agentes con contexto nuevo —para evitar sesgos— apoyan esos flujos. stl-analyzer mira la pieza —renders y secciones— y devuelve un mapa de sus features (taladros, cajeados, chaflanes, paredes) antes de empezar a modelar. design-conventions-reviewer hace de auditor para comprobar si el diseño sigue las normas y convenciones establecidas.

Hooks. Dos hooks cierran el sistema. Un guard bloquea usar trimesh o el binario de OpenSCAD a mano — todo pasa por las herramientas del repo. Y un aviso detecta en el prompt que la tarea es de diseño y recuerda invocar la skill que aplique en vez de improvisar el procedimiento.

Herramientas. Las utilidades —escritas en Python— (uv run tools/...) son lo que le da ojos al agente: validar que la pieza es imprimible y que las partes no chocan (check.py), seccionarla por planos y navegar las secciones en una GUI (slice.py, slice_viewer.py), verla entera en 3D con un heatmap de desviación contra una referencia (render3d.py), reconstruir las features de una malla (analyze.py) y comparar dos diseños evaluando por separado contorno, agujeros y volumen (compare.py). Más utilidades de preparación —centrar mallas de proveedor, suavizar contornos DXF, planos de cotas con la procedencia por color— y un health_check.py que verifica el entorno completo antes de empezar.

Benchmarking: la misma tarea con y sin harness

Lo cierto es que Claude Code es capaz de generar diseños en OpenSCAD sin todo este conjunto de herramientas. De hecho, su tendencia natural es construirse sobre la marcha sus propias herramientas de análisis de STL, aunque ya le dé un conjunto preparado para ello.

Por lo general es preferible tener un conjunto reducido de herramientas genéricas antes que muchas herramientas específicas, como se explica en este artículo de Vercel. Sin embargo, durante los primeros diseños observé que el agente generaba una y otra vez el mismo tipo de código Python con trimesh para inspeccionar mallas —a veces con más éxito y otras con menos—, así que preferí fijar ese conjunto de utilidades con las lecciones aprendidas de esos primeros diseños.

No obstante, tras varias iteraciones tocaba probar la efectividad del harness — plantear un problema y dejar que el agente lo resuelva con y sin él.

La prueba consistió en generar un modelo 3D en OpenSCAD a partir de diseños ya creados en STL. Solo dos iteraciones: la primera presentando el STL con la orden de reproducirlo, y una segunda tras el feedback del primer resultado que yo daba tras inspeccionar el resultado.

Para hacerlo totalmente autónomo durante cada iteración, creé tres agentes usando sesiones de Claude Code independientes: uno diseñaba las piezas con todas las herramientas, otro sin ellas, y un tercero hacía de orquestador mediante un broker HTTP local, mandando las mismas tareas a cada agente y esperando a que terminaran todas. El proceso completo estuvo trabajando por su cuenta más de dos horas para las cuatro piezas.

Usé cuatro piezas reales publicadas por la comunidad en Printables (créditos al final). Estos son los resultados de cada una:

Pieza 1 (Hanger rod mount). En la 1ª pasada el harness ya casi la clava y el control deja estrechamientos raros en el hueco. En la 2ª el harness la cierra. El control mejora taladros y rebaje, pero el estrechamiento sigue ahí.

Pieza 2 (Camera monitor rod mount). El harness la resolvió bien ya en la 1ª pasada. El control, en ambas, sigue sin el hueco de la tuerca y con los taladros descentrados.

Pieza 3 (15mm rod mount). Las dos pasadas mejoran la forma, pero ninguna queda usable — huecos de tuerca hexagonal mal colocados o ciegos, y taladros que siguen tapados por un lado.

Pieza 4 (Tilta BMPCC OG rod mount). Aunque la versión sin harness consigue una apariencia más parecida, la ranura de los tornillos está mal resuelta — le falta el rebaje donde asienta la cabeza y está descentrada. La versión con harness sí la saca.

A simple vista casi todas se parecen al original — pero al bajar a los detalles se aprecia una mejora clara en la versión con harness, que respeta mucho mejor las tolerancias, las cotas y las ranuras.

Mi experiencia

Tras aquellas pruebas iniciales he seguido utilizándolo para crear nuevos diseños — carcasas de módulos de electrónica, adaptadores, accesorios.

La experiencia de hacer vibe coding para diseñar piezas ha sido muy buena — nunca me había costado tan poco llegar de la idea a algo imprimible.

En algunos casos la entrada era un simple prompt de lo que quería hacer, añadiendo una foto de la PCB sobre una cuadrícula, con algunas medidas, cuando lo que quería era una carcasa para ella. En otros, la idea expresada haciendo referencia a otros proyectos ya en el repo.

Ya no solo es que resuelva bien prácticamente con un solo prompt, sino que a veces sorprende con diseños interesantes. Además, conforme crece el número de diseños el sistema funciona mejor, porque tiene más ejemplos de cómo resolver ciertas partes — formas de agarre (a presión o con tornillos), rebajes, encajes. En muchos casos basta con decirle “quiero usar el mismo tipo de agarre que el proyecto tal”.

Otra característica que me ha resultado especialmente útil ha sido el modo de control remoto de Claude Code desde el móvil — el agente me va enseñando imágenes de lo que construye y puedo corregirlo incluso directamente por voz.

Diseñando sin estar delante del ordenador. El agente manda los renders y el corte por secciones, y se interactúa con él tecleando o por voz.

He publicado el esqueleto del repositorio en GitHub, con el harness completo, la documentación en inglés y un proyecto de ejemplo — como punto de partida para quien quiera adaptarlo a lo suyo. Cualquier feedback es bienvenido, no dudes en escribirme.

Referencias

• Proyecto: openscad-monorepo — el esqueleto del harness
• Pieza 1 — Hanger Rod Mount, de Tumblefluff
• Pieza 2 — Camera monitor rod mount, de ReMatrix
• Pieza 3 — 15mm Rod Mount for Video Rig – Universal Support Bracket, de dalbyte
• Pieza 4 — Tilta BMPCC OG Cage 15mm Rod Mount, de Ash