<img src="../banner.png" width="100%" alt="pipeline-optimizer banner">

Español — Versión oficial en español de pipeline-optimizer.

Pipeline Optimizer / Project-Folder Optimizer (Español)

Renovación en 6 pasos sin incompatibilidades — aplicable a dos escalas:

Nombre de activador	Alcance	Ejemplo
Pipeline optimizer	Pipelines completos, stacks, estructuras de documentación	Sus pipelines temáticos, p. ej. software/, research/, games/, un sistema de agentes
Project-folder optimizer	Carpetas de proyecto individuales dentro de un pipeline	Una herramienta de software, un proyecto de artículo, un proyecto de juego

Un pipeline aquí significa una estructura de nivel superior orientada a temas en la que conviven múltiples proyectos bajo convenciones compartidas (p. ej. un pipeline de software con reglas de publicación, un pipeline de investigación con un procedimiento de publicación).

Ambos utilizan el mismo flujo de trabajo de 6 pasos — la única diferencia es el alcance (a nivel de pipeline completo vs. proyecto único) y, en consecuencia, la profundidad de la inspección del estado actual en el paso A.

Cuándo se aplica esta habilidad

Esta habilidad se aplica tan pronto como se le solicita mejorar, reconstruir o extender una estructura existente — no para construcciones desde cero (greenfield). Activadores concretos:

Nivel de pipeline (alcance: pipeline completo):

• "Hacer mejor el pipeline X"
• "Optimizar el stack"
• "Renovar el pipeline de software"
• "Consolidación de documentación en el pipeline de investigación"
• Intervención sustancial en un pipeline temático, _tools/ central o componentes del sistema

Nivel de carpeta de proyecto (alcance: carpeta de proyecto único):

• "Limpiar / optimizar carpeta de proyecto X"
• "Mejorar la estructura de carpetas en Y"
• "Refactorizar una sola herramienta"
• "Unificar la configuración de un proyecto de artículo"
• "Alinear una carpeta de proyecto de juego con el estándar del pipeline"

Transversal:

• "Reconstruir X / integrarlo en Y existente"
• "Refactorización", "consolidación"
• "Unificar convenciones"
• "Integrar en un sistema existente"

La metáfora de la edificación existente

Renovar una casa requiere primero saber de qué está hecha (piedra, madera, plástico), para qué sirve (refugio de montaña, forja de software) y dónde ya cumple funciones. La misma disciplina se aplica a los pipelines.

---

Procedimiento — 6 pasos (NO omitir, NO reordenar)

Paso A — Inspeccionar la edificación existente

Pregunta: ¿De qué está hecha la casa?

Alcance de pipeline (todos los documentos raíz + herramientas + plantillas):

• Leer todos los documentos raíz completamente (no solo fragmentos o puntos de inserción)
• Revisar carpetas de plantillas (_templates/, _TEMPLATES/) y carpetas de herramientas (_tools/)
• Archivos de políticas: p. ej. GITHUB-POLICY.md, RELEASE-MANAGEMENT.md, QUALITY_RULES.md, NAMING-SYSTEM.md, procedimientos de publicación, …
• Capturas de estado: p. ej. PROJECT_STATUS.md, resúmenes de estado, releases.json, archivos de registro
• Listas de verificación: p. ej. listas de verificación de lanzamientos, listas de verificación de compilación/PDF
• Flujos de trabajo: AGENTS.md, GUIDE.md, SKILL.md
• Archivos de lecciones aprendidas: LESSONS_LEARNED.md, MEMORY.md, archivos de estado de bucles

Alcance de carpeta de proyecto (sustancia del proyecto único + convenciones relevantes del pipeline):

• Leer todos los archivos markdown y de control en la carpeta del proyecto (README, CHANGELOG, TASKS/TODO, DONE, CONCEPT, plan de acción, notas de prueba, …)
• Inspeccionar la estructura del código: src/, tests/, configuración de compilación (pyproject.toml, requirements.txt, manifiestos del proyecto, archivos de cadena de herramientas, …)
• Tener en cuenta las convenciones del pipeline primario (p. ej. para un proyecto de software: política de GitHub, sistema de nombres, gestión de lanzamientos, plantillas)
• Escanear herramientas/scripts existentes en el proyecto (_tools/, _scripts/, build_*.bat, scripts START)
• Archivos de configuración: .gitignore, LICENSE, NOTICE, SECURITY.md, CODE_OF_CONDUCT.md

Antipatrón: Usar grep -l "<keyword>" para buscar puntos de inserción e insertar allí sin conocer el contexto del archivo.

Resultado: Nota de inventario con todas las convenciones, herramientas y plantillas relevantes dentro del alcance elegido.

Paso B — Identificar el propósito

Pregunta: ¿Para qué existe la casa?

Explicitar el propósito en 1-2 frases.

Ejemplos de pipelines:

Pipeline	Propósito
Pipeline de software	Desarrollar, probar y lanzar aplicaciones de escritorio + herramientas web en tiendas/GitHub
Pipeline de investigación	Escribir artículos científicos, revisarlos entre pares, publicarlos en repositorios/servidores de preprints
Pipeline de juegos	Desarrollar juegos y publicarlos en la plataforma de destino
Sistema de agentes	Sistema LLM para orquestación multi-agente

Ejemplos de carpetas de proyecto:

Carpeta de proyecto	Propósito
software/PlannerApp	Aplicación de planificación de escritorio, comercial, repositorio privado
research/CosmologyModel	Serie de artículos sobre modelos + cálculos numéricos
games/SortingChaos	Juego de clasificación, etapa alfa, progresión de niveles

El propósito dirige cada intervención — las medidas que no sirvan al propósito se descartan.

Paso C — Esbozar el estado ideal

Pregunta: ¿Cómo sería una casa perfecta para este propósito?

• Esbozarlo desde su propia perspectiva (breve, máx. 10 puntos)
• Incorporar una comparación de mejores prácticas (p. ej. stack Vercel para SaaS, stack python científico para investigación)
• No descender a la optimización de detalles — un esquema de nivel superior es suficiente

Resultado: 5-10 puntos de "estado ideal por pipeline"

Paso D — Análisis de brechas + plan

Cuatro preguntas por pipeline:

1. ¿Qué tiene ya la casa? — Incluso si se resuelve de manera diferente al ideal pero es funcionalmente equivalente. Ejemplo: El ideal dice "pip-licenses para licencias de terceros". La realidad: un script generador personalizado lo envuelve → funcionalmente equivalente, no se requiere intervención.

2. ¿Qué impide la función? — Estructuras existentes que causan rupturas o esfuerzo extra en la actualidad.

3. ¿Qué no es funcional? — Código muerto, convenciones desactualizadas, herramientas sin uso.

4. ¿Qué mejoraría mensurablemente las funciones? — Intervenciones concretas con beneficio esperado.

→ A partir de esto, un plan concreto:

• ¿Qué se construye de nuevo?
• ¿Qué se extiende?
• ¿Qué se demuele?
• ¿Qué permanece sin cambios (¡importante especificar!)?

Resultado: Tabla de plan con columnas Intervención / Existente / Medida / Justificación

Paso E — Trabajar empíricamente

No planificar únicamente de arriba a abajo — recopilar puntos de dolor:

• Errores conocidos: rastreador de problemas (issue tracker), archivos TASKS/TODO/DONE
• Historial de errores: archivos de lecciones aprendidas, registros de corrección de errores, registros de comprobaciones
• Rupturas de automatización: "¿Qué tengo que hacer siempre manualmente?"
• Entrevista de usuario: preguntar específicamente — puntos de dolor, deseos, soluciones temporales
• Prueba propia: recorrer el pipeline (crear un nuevo proyecto, ejecutar una compilación, simular un lanzamiento) — ¿dónde se rompe?

Los puntos de dolor encontrados empíricamente priorizan el plan del paso D.

Paso F — Reevaluaciones tras la implementación

• Encargar a subagentes limpios (sin la carga del contexto de renovación) que recorran el flujo de trabajo modificado
• Valores mensurables antes/después: tiempo de configuración, tasa de error, número de pasos manuales, tiempo de compilación
• Comprobación anti-regresión: ¿siguen funcionando los flujos de trabajo existentes tras el cambio?
• Si no hay una mejora mensurable o hay una regresión: revertir la renovación o reajustar

Antipatrones (prohibidos)

Antipatrón	Daño	Antídoto
Buscar puntos de inserción en lugar de leer documentos	Estándares paralelos	Paso A completo
Transferir "mejores prácticas de X" 1:1	Incompatibilidad	Paso D compara funcionalmente
Crear un nuevo archivo sin verificar convenciones	Duplicación (p. ej. NOTICE.md ↔ THIRD_PARTY_LICENSES.txt)	Paso A + paso D
Planificar de arriba a abajo sin datos empíricos	La solución no aborda el punto de dolor	Paso E antes de finalizar el plan
No probar los propios cambios	Regresión no detectada	Paso F con un agente limpio
"Aclarar más tarde" con estado incierto	El usuario descubre el conflicto después	En caso de duda, revisar el paso D nuevamente con el usuario

Estudio de caso — El incidente NOTICE.md

Tarea: Implementar mejoras de pipeline en varios pipelines temáticos (software, investigación, juegos).

Error: Se omitió el paso A — solo se buscaron puntos de inserción en lugar de leer los archivos de políticas completos.

Consecuencia: Se introdujo NOTICE.md como un "nuevo archivo de licencia" en 7 archivos, aunque THIRD_PARTY_LICENSES.txt + un generador de licencias personalizado (envoltorio alrededor de pip-licenses) ya estaban establecidos — documentado en la política de GitHub del pipeline (archivos obligatorios + lista de verificación de licencias). Todos los proyectos de software ya tenían archivos THIRD_PARTY.

Detección: Solo después de que el usuario preguntó ("Estoy seguro de que ya teníamos gestión de derechos").

Corrección: Se eliminó NOTICE.md de la plantilla del proyecto, se ajustaron 6 archivos adicionales y se hizo referencia al generador de licencias existente en lugar de pip-licenses.

Lección: Si el paso A se hubiera ejecutado por completo, el conflicto se habría detectado antes de escribir.

Reglas generales

1. Para "mejorar el pipeline", primero lea tanto tiempo como escriba.
2. Ningún estándar nuevo sin prueba de que no existe uno previo.
3. Utilice herramientas/envoltorios existentes en lugar de crear otros paralelos.
4. "Más de lo mismo" suele ser peor que "extender lo que existe".
5. Revertir en caso de conflicto siempre es mejor que mantener dos estándares paralelos.

Lista de verificación de finalización

Antes de reportar una renovación de pipeline como "completada":

• Paso A: ¿se leyeron todos los documentos raíz relevantes?
• Paso B: ¿se declaró el propósito del pipeline en 1-2 frases?
• Paso C: ¿se esbozó el estado ideal (5-10 puntos)?
• Paso D: ¿análisis de brechas con tabla (qué se mantiene / qué se extiende / qué es nuevo / qué se elimina)?
• Paso E: ¿se verificaron los datos empíricos (errores, lecciones, prueba propia, entrevista de usuario)?
• ¿Plan acordado con el usuario?
• Paso F: probado con un subagente limpio — ¿mejora mensurable?
• ¿No se introdujeron estándares paralelos?
• En caso de conflictos: ¿se revirtió o se justificó honestamente?

Estructura óptima de carpeta de proyecto (para el optimizador de carpeta de proyecto)

Cuando la habilidad se aplica a una sola carpeta de proyecto, la siguiente recomendación combinada sirve como referencia ideal (paso C):

Estándar Anthropic (Claude Code)

Archivo/carpeta	Función
CLAUDE.md (raíz)	Cargado automáticamente por Claude Code, instrucciones específicas del proyecto
.claude/settings.json	Permisos, variables de entorno, selección de modelo (registrado/commit)
.claude/settings.local.json	Anulaciones locales (NO registrar en commit, añadir a .gitignore)
.claude/commands/*.md	Comandos slash personalizados
.claude/agents/*.md	Subagentes personalizados
.claude/skills/<name>/SKILL.md	Habilidades del proyecto

Su propia plantilla de documentación de proyecto (recomendado)

Si mantiene su propia plantilla de documentación de proyectos (p. ej. en <your-workspace>/_templates/project-docs/), tres perfiles de implementación resultan rentables. Ejemplo de división: MINIMAL proporciona el conjunto central de sesión con 7 archivos raíz (AGENTS.md, CLAUDE.md, README.md, START.md, STATE.md, TODO.md, DONE.md) más _tools/. STANDARD añade CHANGELOG.md, DECISIONS.md y PATTERNS.md. FULL se amplía a 14 archivos raíz y añade además ARCHITECTURE.md, WORKFLOWS.md, TOOLS.md, GLOSSARY.md, así como workflows/ y .github/.

→ Utilice dicha plantilla como base para nuevos proyectos (copiar en lugar de crear manualmente).

Adiciones específicas según el pipeline (ejemplos)

Según el pipeline, se añaden archivos obligatorios adicionales — patrones típicos:

• Proyecto de software: LICENSE, CODE_OF_CONDUCT.md, SECURITY.md, CONTRIBUTING.md, THIRD_PARTY_LICENSES.txt (generado), pyproject.toml/requirements.txt, entrada en el registro central de lanzamientos del pipeline. → Si está disponible: utilice la plantilla cookiecutter del pipeline.
• Proyecto de investigación: documento de concepto, plan de acción, plan de publicación, carpetas de archivo/fuentes/resultados/datos (_archive/, _sources/, _results/, _data/), paper/ para LaTeX. Para proyectos de demostración: un archivo de notas de demostración con la cadena de demostración y su estado.
• Proyecto de juegos: manifiesto del proyecto y archivos de cadena de herramientas del motor (p. ej. para Roblox/Rojo: default.project.json, rokit.toml, wally.toml, selene.toml), documento de diseño de juego, src/{server,client,shared}/ según la convención del motor.

Referencia detallada completa

→ Ver references/optimal-project-structure.md en esta carpeta de habilidad (alemán). Contiene:

• Ejemplo de settings.json (esquema Anthropic)
• Entradas obligatorias en .gitignore
• Antipatrones (lo que NO pertenece a las carpetas de proyectos)
• Flujos de trabajo recomendados según el tipo de pipeline (software/investigación/juego)
• Convención de encabezado YAML para archivos de documentación
• Boceto de autochequeo

Habilidades relacionadas (¿cuándo usar en lugar de esta?)

Habilidad	Cuándo usar
project-onboarding	Incorporar un repositorio externo existente a su propio sistema
Project bootstrapper (si está disponible)	Crear un NUEVO proyecto en un pipeline existente (greenfield, sin reconstrucción)
Pipeline bootstrapper (si está disponible)	Crear un pipeline COMPLETAMENTE NUEVO (caso raro)
System onboarding (si está disponible)	Configurar un equipo nuevo

El pipeline optimizer es responsable de la renovación, no de la nueva construcción ni de la incorporación. Si su colección de habilidades tiene un índice de habilidades, búsquelo para encontrar habilidades de arranque coincidentes.

Referencias cruzadas

• Referencia de detalles: references/optimal-project-structure.md (en esta carpeta de habilidad)
• Documentación Anthropic Claude Code: https://docs.claude.com/en/docs/claude-code
• Si están disponibles: reglas globales de usuario (p. ej. una sección de "renovaciones" en su ~/CLAUDE.md) y descripciones de stacks específicas por pipeline

Elección de alcance: pipeline vs. carpeta de proyecto

Si no está claro qué alcance se pretende, aclarar antes del paso A:

Pista	Alcance
"Mejorar todo el pipeline de software"	Pipeline
"Limpiar la carpeta de la herramienta X"	Carpeta de proyecto
"Sincronizar el registro central de lanzamientos"	Pipeline (activo central)
"Refactorizar AssetBuilder en el juego Y"	Carpeta de proyecto
"Introducir una convención de comprobación en todo el pipeline"	Pipeline
"Crear un archivo de comprobación en el proyecto Z"	Carpeta de proyecto

En el alcance de carpeta de proyecto, verifique también brevemente las convenciones del pipeline primario (paso A extendido) para que la intervención siga siendo compatible con el pipeline.

---

Historial de cambios

1.2.0 (2026-06-13)

• Primera publicación en la biblioteca de habilidades: rutas personales, nombres concretos de pipelines/proyectos y referencias a habilidades privadas reemplazadas por ejemplos genéricos; el procedimiento en sí (6 pasos, antipatrones, estudio de caso, listas de verificación) sin cambios

1.1.1 (2026-06-01) y anteriores

• Versiones internas (directorio de habilidades privado, antes de la publicación)