6. Hacerlo tuyo — reglas, verificación, una instalación de equipo

Código: code/slashforge/check.sh, cuya salida l06_verify_glob comprueba la CI en Linux, Windows y macOS, y lab/run.sh para la única ejecución del modelo, la e5b del diario.

Tus convenciones van en tres sitios

Setup (lección 3) escribe una primera versión de cada uno. A partir de ahí son tuyos para editar:

Archivo	Se carga	Para
CLAUDE.md	en cada sesión	qué es el proyecto, y los comandos: build, test, lint
.claude/rules/*.md	al inicio de la sesión, o solo cuando se lee un archivo que coincide si la regla tiene paths:	las convenciones de una zona del código
.claude/skills/<name>/SKILL.md	cuando se invoca, o cuando Claude la juzga pertinente	una receta: «añade un endpoint aquí»

La fila del medio es la que hay que aprender. Una regla con paths: en su frontmatter no cuesta nada hasta que Claude lee un archivo que coincide, y así es como un repositorio grande mantiene cortas sus instrucciones. La documentación del directorio .claude añade la advertencia que vale para los tres: “Like CLAUDE.md, rules are guidance Claude reads, not configuration Claude Code enforces. For guaranteed behavior use hooks or permissions.”

La primera fila importa a SlashForge en particular. La fase 6 de /slashforge:code empieza comprobando que “lint, test, and build commands are defined in CLAUDE.md. If any are missing, ask the user for them before continuing.” Ese es tu contrato de verificación: lo que nombre CLAUDE.md es lo que el workflow ejecuta antes de declarar el éxito. /init escribió una sección Commands en la lección 3; setup pregunta por ellos.

Archivos del kit y archivos tuyos

Ejecuta setup de nuevo tras una nueva versión de SlashForge, y tiene que decidir qué archivos puede sobrescribir. forge-instructions.md hace que cada archivo que genera lleve una marca, generated_by: slashforge@4.4.3 en el frontmatter, o un comentario HTML en la primera línea de CLAUDE.md, y aplica tres casos en una nueva ejecución:

• la marca coincide con la versión actual del kit: el archivo se puede actualizar;
• la marca es de una versión anterior: “Propose a refresh; ask the user before overwriting”;
• la marca está “missing or edited”: el archivo es “user-owned. Edit to fill gaps only; do not overwrite”.

Es la cabecera // <auto-generated> de un archivo del diseñador de .NET, con la clase parcial como vía de escape. Aquí la vía de escape es editar la marca, o borrarla, y el archivo pasa a ser tuyo. Es el modelo el que aplica estas reglas en la nueva ejecución, así que son instrucciones, no un mecanismo; el curso no volvió a ejecutar setup para probarlas.

Dos reglamentos

El kit le da al modelo dos guías sobre las skills, y no coinciden.

	forge-instructions.md	forge-skills.md
Dónde va una skill	.claude/skills/*.md	“each skill is a directory containing a SKILL.md entrypoint, not a flat .md file”
Cuánto puede medir	“Every .md file — including this one — must stay under 200 lines”, entre las “Golden Rules (always enforced)”	“Keep SKILL.md under 500 lines”

Claude Code da la razón a la segunda en la primera fila: su documentación de skills lista cada ubicación como .claude/skills/<skill-name>/SKILL.md. Un archivo suelto en skills/ no está en esa tabla. En la segunda fila, los dos límites son del propio kit; la documentación de Claude Code usa 200 líneas como objetivo para CLAUDE.md.

Un paso de verificación que no ve las skills

Setup termina con un paso de verificación, en forge-instructions.md:

# No file exceeds 200 lines
wc -l CLAUDE.md .claude/**/*.md

En bash, ** solo significa «a cualquier profundidad» cuando la opción globstar está activada, y está desactivada por defecto. Sin ella, .claude/**/*.md es .claude/*/*.md: una carpeta de profundidad. check.sh construye un repositorio como lo pide forge-skills.md — una regla, una skill en su propia carpeta, de 300 líneas — y ejecuta el comando:

# the files, as find sees them
6 .claude/rules/api.md
300 .claude/skills/add-endpoint/SKILL.md
1 CLAUDE.md
# the files the verify step counts: wc -l CLAUDE.md .claude/**/*.md, in bash without globstar
1 CLAUDE.md
6 .claude/rules/api.md

La skill está dos carpetas más abajo, así que la comprobación nunca la ve, y una skill de 300 líneas pasa una regla de 200 líneas. El /bin/bash 3.2 de macOS no tiene globstar en absoluto. zsh es distinto: ahí **/ es recursivo por defecto, así que la misma línea funciona en un shell zsh — la comprobación pasa o falla según el shell que la ejecute. Una comprobación que no puede fallar en el caso para el que existe es peor que ninguna comprobación, porque se reporta como hecha. find CLAUDE.md .claude -name '*.md' | xargs wc -l ve todos los archivos.

Una instalación de equipo, y qué copia se ejecuta

--project (lección 1) escribe el kit en el .claude/ del repositorio, con rutas relativas, para que un equipo pueda versionarlo: todos los que clonan obtienen /slashforge:code en la misma versión. A menos que alguien haya instalado también SlashForge de forma global, en ~/.claude/.

La regla de Claude Code para dos skills o comandos con el mismo nombre es “Enterprise over personal, and personal over project.” El laboratorio la probó con el comando más pequeño posible, /lab:which, presente dos veces: en el commands/lab/which.md personal del laboratorio, que responde GLOBAL, y en el .claude/commands/lab/which.md del repositorio, que responde PROJECT. La hipótesis, escrita antes de la ejecución a partir de esa frase, era GLOBAL.

subtype:   success
turns:     1
cost:      0.0896938 USD (as computed by Claude Code)
RESULT: "GLOBAL"

Se ejecuta la copia personal. Para un equipo, eso significa que la versión versionada solo es la que se ejecuta para quienes no instalaron el kit por su cuenta: un compañero con una instalación global más antigua ejecuta su /slashforge:code, con las puertas y las guías de su versión, sin ningún aviso. slashforge status y slashforge status --project informan de las dos instalaciones por separado, así que la comprobación es barata. Conviene acordar un solo modo por equipo y, si es el modo de proyecto, desinstalar el global.

Una nota sobre el coste de esa misma ejecución: el primer intento, con un tope de 0.10 USD, se detuvo con error_max_budget_usd en 0.103 USD — para una respuesta de ocho tokens. El tope funciona con un inicio de sesión por suscripción, pero se comprueba después de cada llamada, así que una ejecución puede terminar ligeramente por encima; y con este modelo, una sesión cuesta unos 0.09 USD antes de hacer nada, sobre todo por la escritura de la caché del prompt.

Puntos clave

• CLAUDE.md contiene los comandos que ejecuta la fase 6 de SlashForge; las reglas con paths: solo se cargan para los archivos que coinciden; las skills son carpetas con un SKILL.md.
• Los archivos generados por setup llevan una marca generated_by; un archivo cuya marca falta o está editada se trata como tuyo en una nueva ejecución.
• Las dos guías del kit no coinciden sobre dónde van las skills ni cuánto pueden medir; la documentación de Claude Code exige la forma de carpeta.
• El wc -l .claude/**/*.md del paso de verificación no mira dentro de las carpetas de skills en el modo por defecto de bash: una skill de 300 líneas pasa.
• Cuando un comando existe en ~/.claude y en el proyecto, se ejecuta la copia personal. Una instalación de equipo solo vale para los compañeros sin una global.

Ejercicios

1. Reescribe el paso de verificación para que falle, con un código de salida distinto de cero, cuando cualquier archivo bajo .claude/ o CLAUDE.md supere las 200 líneas, de forma que funcione en bash 3.2.
2. Quieres que /slashforge:code ejecute el npm run lint:strict de tu equipo en la fase 6. ¿Dónde lo pones, y qué pasa si no lo haces?
3. Un compañero dice que el kit versionado «no funciona» y describe puertas que la 4.4.3 no tiene. ¿Qué le pides que ejecute?

Solución

1. Por ejemplo:

   find CLAUDE.md .claude -name '*.md' -exec wc -l {} + \
     | awk '$2 != "total" && $1 > 200 { print; bad = 1 } END { exit bad }'

   find recorre todas las profundidades sin opciones del shell, y awk imprime los archivos infractores y fija el código de salida.

2. En la sección Commands de CLAUDE.md, como comando de lint. La fase 6 lee los comandos de CLAUDE.md; si falta lint, test o build, el workflow se detiene y lo pide — o, en modo headless, la ejecución termina ahí.

3. npx slashforge status y npx slashforge status --project: el primero muestra una instalación global y su versión. Si la hay, es la que se ejecuta; npx slashforge uninstall la quita, y la copia de proyecto versionada toma el relevo.