boonkgim/setup-project

Configurar un proyecto, rebanada por rebanada

Una rebanada por invocación, mediante un bucle fijo:

referencia → investigación → cableado → plan → ejecución → prueba local → conciliación → prueba en producción → conciliación → entregar al usuario los pasos manuales → commit

Los archivos slices/ son una referencia, no un script. Codifican una pila que fue verificada como un conjunto y, más valiosamente, las trampas que costaron tiempo real: el bloque devEngines que pnpm init escribe y que corepack rechaza, el segundo espacio de trabajo pnpm que create-next-app crea dentro de apps/web. Ese razonamiento perdura. Los pins de versión, las banderas CLI y las formas API a su alrededor, no. Ejecutar una rebanada directamente desde la referencia fallará en algo que se ha movido.

Por lo tanto, el plan que ejecutas nunca es la referencia en sí. Es un plan fresco, escrito en el proyecto para este proyecto, a partir de la referencia más lo que la investigación dice que es verdad ahora. Y debido a que ese plan se escribe antes de que se demuestre, el bucle no termina con una prueba verde — termina cuando el plan ha sido corregido para coincidir con lo que realmente funcionó, en ambos lugares donde vive, y el usuario ha recibido la breve lista de comprobaciones que solo una persona puede hacer.

La pila es fija: espacio de trabajo pnpm · Next.js en Cloudflare Workers mediante OpenNext · GraphQL Yoga Worker · Drizzle + Postgres, Docker localmente y Neon a través de Hyperdrive en producción · Tailwind + shadcn · opcionalmente Resend, Better Auth y Stripe. Si el usuario quiere una pila diferente, dilo claramente — este skill no tiene una.

0. Despacho

/setup-project [rebanada] construye una rebanada. El argumento es opcional y nombra una rebanada por número o nombre — 01, web shell, database, auth. Resuélvelo con reference/slices.md; si no coincide con nada, dilo y lista los nombres en lugar de adivinar.

ls docs/setup/ 2>/dev/null    # qué rebanadas ha construido realmente este proyecto
git status --short            # un árbol sucio significa que la última rebanada puede estar sin terminar

docs/setup/ es el registro de lo que se construyó, no una previsión de lo que podría construirse. Un archivo de rebanada está ahí porque esa rebanada fue construida y pasó la prueba verde. Entonces, el archivo con el número más alto es la respuesta a "dónde estamos", y no hay un marcador separado que mantener sincronizado.

Sin rebanada nombrada — muestra siempre el catálogo antes de recomendar. Lista cada rebanada de reference/slices.md con su número, nombre, y si docs/setup/ muestra que está construida, luego recomienda una y obtén confirmación antes de ejecutarla. Esto también aplica en la primera ejecución: primero se establece el nombre del proyecto (§1), luego se muestra el catálogo (todo sin construir, la rebanada 00 es la siguiente) y se confirma antes de construirla. Nunca te saltes el catálogo ni la confirmación porque el siguiente paso parezca obvio.

Estado	Qué hacer
Sin docs/setup/	Primera ejecución: establece el nombre del proyecto (§1), muestra el catálogo, confirma la rebanada 00
Rebanada nombrada	Constrúyela
Sin rebanada nombrada	Muestra el catálogo, recomienda la más alta construida + 1, y confirma

La rebanada 99 está fuera de esa aritmética. Es la auditoría de seguridad: no construye nada, solo necesita la rebanada 00, y se vuelve a ejecutar sobre lo que exista en lugar de ocupar un escalón en la cadena. Por lo tanto, que 99-security-audit.md esté en docs/setup/ no significa que la cadena esté terminada, y "la más alta construida + 1" debe ignorarlo — un repositorio que contiene 00–05 más 99 es un repositorio cuya siguiente construcción es 06. También se excluye de los rangos --through, porque un rango es la cadena de construcción e instalar una auditoría de rebanadas que no existen no audita nada. Recomiéndala después de cualquier rebanada que agregue superficie pública, y nómbrala explícitamente: /setup-project 99.

Nunca construyas dos rebanadas en una invocación. Detente cuando la rebanada esté confirmada.

Una rebanada que se salta una. Si el argumento es más de uno más allá de lo construido, nombra las rebanadas que salta y lo que construyen, luego deja que el usuario decida. La cadena es real: la 04 necesita tanto la 02 como la 03, y la 05–07 parchean archivos que las rebanadas anteriores escribieron, por lo que un requisito previo faltante es un error duro de docs:check en lugar de una advertencia. reference/slices.md §Dependencies tiene el razonamiento.

1. Solo en la primera ejecución: el nombre del proyecto

Letras minúsculas, dígitos y guiones — se convierte en el ámbito de npm (@nombre/db) y el prefijo del Worker (nombre-web, nombre-graphql). Por defecto, usa el nombre del directorio del repositorio si ya encaja. Pregunta una vez; cada rebanada posterior lo lee de package.json.

2. Lee la rebanada de referencia

Lee slices/NN-*.md completamente antes de cualquier otra cosa, y reference/slices.md para ver qué prueba la puerta de esta rebanada y qué cuenta necesita. La prosa entre los bloques de código es la parte que conserva su valor — léela para entender el razonamiento, y trata cada número de versión, bandera y ruta de archivo en ella como una afirmación que verificar en lugar de un hecho.

Si la rebanada necesita una cuenta que el usuario no tiene (Cloudflare, Neon, Resend, Stripe), dilo ahora. Una cuenta faltante no bloquea la escritura del plan, pero deja la rebanada a medio camino de su prueba de producción con la parte local ya confirmada.

Mira hacia atrás, no hacia adelante. Lee lo que el proyecto ya tiene — docs/setup/, CLAUDE.md, los archivos del skill que las rebanadas anteriores escribieron — y sigue las convenciones que establecieron para que esta rebanada encaje en lugar de reinventarlas. Lo inverso nunca ocurre: ninguna rebanada asume que una posterior, nombrada o no, se construirá alguna vez — si se construye o no es decisión del usuario en el despacho (§0), no algo en lo que la referencia pueda confiar. Si una convención establecida ahora parece incorrecta para lo que necesita esta rebanada, dilo y deja que el usuario decida en lugar de sobrescribirla silenciosamente o cumplirla silenciosamente.

Retira los artefactos provisionales que esta rebanada reemplaza. Algunas cosas se construyen solo para probar un mecanismo antes de que exista la real — packages/mock es el primer y más claro caso: La rebanada 0 lo crea para probar el harness cuando no hay un paquete real para ejecutarlo. Un artefacto provisional nunca nombra a su sucesor, porque qué rebanada lo reemplaza se decide en el despacho (§0), no por la referencia. La obligación funciona al revés: cada rebanada mira lo que ya está ahí e incorpora la eliminación de lo que ahora hace redundante en su propio plan, junto con cualquier línea de CLAUDE.md que lo describiera.

Por lo tanto, si packages/mock todavía existe, esta rebanada es la primera cosa real que obtiene el espacio de trabajo, y retirarlo es parte del trabajo de esta rebanada. La misma regla cubre cualquier cosa que las rebanadas posteriores dejen atrás — un resolución estático que uno real reemplaza, un valor de marcador de posición que se convierte en un enlace.

Ese mecanismo solo funciona para artefactos con un sucesor, así que declara los que no lo tienen. packages/mock se retira porque un paquete real obviamente lo reemplaza. Nada reemplaza obviamente a sendTestEmail: La rebanada 6 agrega correo de verificación real junto a él, la rebanada 7 lo describe como parte del esquema, y una mutación no autenticada que envía correo real se envía como una característica permanente. Ninguna rebanada está equivocada — la eliminación no tiene dueño. Esperar que una rebanada posterior lo note no es un mecanismo; es una esperanza.

Por lo tanto, cada rebanada termina con un bloque Deja atrás que nombra dos listas, escritas cuando el artefacto se crea en lugar de cuando alguien lo detecta:

• Provisional — qué es, por qué existe, y la condición que lo retira. Si ninguna rebanada posterior cumpliría plausiblemente esa condición, dilo en la fila. Una entrada honesta de "nada retira esto" es la que hace el trabajo.
• Aceptado — un riesgo asumido con conocimiento, quién puede alcanzarlo, y el razonamiento. Escrito para que una rebanada posterior pueda redescidirlo en lugar de redescubrirlo, y para que un valor predeterminado heredado (Yoga sirviendo GraphiQL en producción) sea distinguible de uno elegido.

La rebanada 99 lee estos como una verificación cruzada — nunca como su entrada, porque un libro de contabilidad solo puede contener lo que alguien ya pensó en escribir. Lee el código primero.

3. Investiga lo que es verdad actualmente

Este es el paso que hace que la referencia sea segura de usar, así que hazlo deliberadamente y de manera económica. Para cada herramienta que esta rebanada instala o configura, verifica la realidad en lugar de la referencia:

npm view <pkg> version          # cuáles deberían ser realmente los pins
npx <cli> --help                # banderas, y qué indicaciones no son interactivas

Luego lee la documentación oficial para cualquier cosa de la que la rebanada dependa estructuralmente — la guía de adaptación actual del framework, las banderas de compatibilidad del runtime, la forma actual de la API de una biblioteca. Prefiere la documentación del proveedor sobre el resumen de la referencia, y nota dónde están en desacuerdo.

Lee lo que imprime la instalación, no solo su código de salida. Un paquete que se fusionó en otro, se renombró o se abandonó aún se instala, aún exporta los mismos nombres, y aún compila — npm view <pkg> version reporta una versión saludable para él, y los bloques de código de la referencia se vuelven verdes contra él. La única línea de [WARN] deprecated … en la salida de pnpm add es el único lugar donde se muestra. La rebanada 5 es donde esto pasó: @react-email/components se había fusionado en react-email cinco meses antes y nada más lo indicaba.

npm view <pkg> deprecated    # no vacío significa que la referencia describe un paquete obsoleto

Escribe lo que encontraste y dónde. Las contradicciones entre la referencia y la documentación actual son el resultado completo de este paso, y van al plan que estás a punto de escribir.

3b. Cablea en lo que ya está construido

Una rebanada que aterriza desconectada es una rebanada que nadie puede decir que funciona. Antes de escribir el plan, mira lo que docs/setup/ dice que existe y pregunta con cuáles de esas capas esta rebanada ahora tiene una unión — luego ofrece probar esa unión en esta rebanada en lugar de dejarla para una posterior que puede que nunca se construya.

Cuatro reglas evitan que esto se convierta en una expansión del alcance:

• Solo hacia atrás. Cablea en rebanadas ya construidas. Nunca especules sobre las que pueden no existir — esa es la misma regla que el "una rebanada puede citar cualquier rebanada anterior, nunca una posterior" de adapting.md.
• Una sonda, no una característica. La barra es una cosa que fallaría si la unión se rompiera. Si necesita decisiones de producto, es una rebanada propia, no una sonda.
• Es una oferta. El cableado amplía la rebanada, por lo que va a la revisión del §4 con todo lo demás y necesita el consentimiento del usuario.
• Obtiene una fila de puerta, o no prueba nada.

Una sonda es un artefacto provisional, y la regla del §2 ya cubre su eliminación: no dice nada sobre qué lo reemplazará, y cualquier rebanada que lo reemplace lo retira.

4. Escribe el plan de ejecución en el proyecto

node <dir del skill>/scripts/install-plan.mjs \
  --repo <dir del repo> --name <proyecto> --slices NN

<dir del skill> es donde esté instalado este skill: ~/.claude/skills/setup-project, ~/.agents/skills/setup-project, o el .claude/skills/setup-project propio de un proyecto. El script resuelve sus rebanadas en relación a sí mismo, por lo que se ejecuta correctamente desde cualquiera de ellas.

Esto renderiza slices/NN-*.md en docs/setup/ con __PROJECT__ y __DOCS__ resueltos, y no escribe nada más — sin índice, sin lista de fuentes. docs/setup/ contiene solo archivos de rebanada, uno por rebanada construida, y ls es el índice. No se instala, construye ni confirma nada.

Un archivo de rebanada ya existente se deja intacto a menos que pases --force, porque para entonces es el registro de ejecución de este proyecto en lugar de una copia de la referencia.

Luego edita lo que escribió, antes de ejecutar algo — este es el plan, no una copia de la referencia. Incorpora la investigación del §3: corrige los pins, arregla las banderas que se movieron, ajusta los pasos cuya API cambió, y elimina o reescribe cualquier cosa que la documentación actual contradiga. Di por qué en la prosa, como hace el resto del archivo.

Muestra al usuario lo que cambiaste en relación con la referencia y por qué, y obtén su acuerdo antes de ejecutar. El plan no está probado en este punto y vale un minuto de su atención.

5. Ejecuta

Ejecuta los bloques del plan en orden. Las líneas cd están escritas desde donde el bloque anterior te dejó, así que no reordenes los bloques ni ejecutes uno de forma aislada.

Espera fallos. Este plan nunca se ha ejecutado. Un fallo aquí es el bucle funcionando, no el bucle rompiéndose — es exactamente la información que el §7 existe para capturar. Arregla la causa, nota qué fue, y continúa.

6. Puertas — tres rondas, en este orden

Una rebanada se prueba en tres pasadas, y no son variaciones de una misma cosa. Dos son tuyas para ejecutar y actuar sobre ellas; la tercera es una transferencia. Cada una de las dos primeras termina corrigiendo el plan y este skill (§7) — antes de que comience la siguiente, mientras lo que se rompió todavía está frente a ti. Conciliar una vez al final en lugar de eso pierde las lecciones locales detrás de las de producción.

Ronda 1 — automatizada, local

Ejecuta la tabla de la Ronda 1 de la rebanada exactamente como está escrita, desde la columna Dónde que nombra — typecheck y los scripts de prueba desde la raíz del repositorio, los servidores de desarrollo y preview desde el paquete. Esa división no es administrativa: la raíz distribuye los scripts a través de turbo, por lo que responde "está el espacio de trabajo verde", que es la única pregunta que hace una puerta. Ejecuta el mismo script dentro de un paquete y obtienes el recuento de ese paquete, que permanece verde mientras otro paquete se quema. Cada paquete está dos niveles hacia abajo, por lo que cd ../.. regresa desde cualquiera de ellos — y el cuerpo de la rebanada generalmente te deja en el lugar equivocado, por lo que cada fila nombra dónde se ejecuta.

Ejecuta las filas en el orden dado: algunas filas generan lo que una fila posterior necesita. Lee el recuento de pruebas, no el código de salida — passWithNoTests hace que una ejecución vacía sea verde, por lo que Pruebas N pasadas con la N que nombra la puerta es la única evidencia. Lee lo que los comandos imprimen, no solo lo que devuelven: un aviso de obsolescencia es todo el hallazgo en el peor caso del §3.

Arregla lo que falla, luego concilia ahora (§7) — tanto el documento de la rebanada del proyecto como el de este skill.

Rebanadas cuya puerta sigue siendo una tabla combinada. Solo algunas rebanadas han pasado por esta forma de tres rondas; el resto lleva una tabla única que mezcla t...

... [truncado para traducción]