ihkaru/agent-skills

Craftsman Coder: SOLID, Impacto de AST CodeGraph e Ingeniería Basada en Evidencia

Un flujo de trabajo de ingeniería disciplinado y agnóstico del repositorio para construir software robusto, desacoplado y verificable.

---

Principios Fundamentales

1. Exploración de AST y CodeGraph Primero: Nunca modifique o refactorice código a ciegas. Siempre mapee las definiciones de símbolos, llamadores, llamados y el blast radius antes de alterar la implementación.
2. SOLID y Principio de Responsabilidad Única (SRP): Cada módulo, función y clase debe tener una única razón para cambiar. Separe la lógica de negocio de la E/S, persistencia y APIs externas.
   • Regla de Descomposición: Si un componente, clase o función es demasiado largo o maneja múltiples responsabilidades, descompóngalo inmediatamente en subcomponentes/servicios atómicos más pequeños con responsabilidades únicas.
3. Inyección de Dependencias (DI) e Inversión de Control: Inyecte dependencias (repositorios, clientes, loggers) a través de constructores o mecanismos del framework. Desacople la lógica de la infraestructura concreta. Evite instanciaciones externas directas hardcodeadas.
4. Arquitectura de Respaldo: Arquitectura de Rebanadas Verticales (VSA) + EIP: Si un repositorio no posee una convención de framework establecida, priorice siempre la Arquitectura de Rebanadas Verticales (VSA) junto con SOLID y los Patrones de Integración Empresarial (EIP):
   • Organice el código por capacidades de negocio (features/<feature_name>/) utilizando el patrón Solicitud-Endpoint-Respuesta (REPR) en lugar de capas técnicas horizontales.
   • Emplee patrones EIP para la coordinación de rebanadas: Enrutadores de Comando/Consulta, Tuberías y Filtros, Receptores Idempotentes y Publicación/Suscripción de Eventos de Dominio.
   • Guía detallada: Guía de VSA y EIP
5. Linting Determinista de Límites Arquitectónicos VSA: Cuando un repositorio implemente VSA, configure un linter de límites determinista (ej. dependency-cruiser para JS/TS, import-linter para Python, depguard para Go, o vsa_boundary_checker.py) para prohibir importaciones directas entre rebanadas.
   • Guía detallada: Guía de Cumplimiento de Límites VSA y GEMINI.md del Repo
6. Archivo GEMINI.md Obligatorio a Nivel de Repositorio (Portátil y Listo para Git): Al crear o inicializar cualquier repositorio, siempre genere un archivo GEMINI.md a nivel de proyecto en la raíz del repositorio para persistir las elecciones arquitectónicas, reglas de límites y comandos de Gauntlet.
   • Regla de Portabilidad Estricta: Debido a que este archivo se confirma y se envía, NUNCA haga referencia a rutas de host externas (ej. no ~/.gemini/config/..., no /data/data/...) ni a secretos específicos de la máquina. Debe ser 100% autocontenido y portátil.
7. Investigación Web en Tiempo Real y Complejidad Big-O Óptima: Seleccione siempre patrones de algoritmos y estructuras de datos con la complejidad Big-O de tiempo y espacio más óptima (búsquedas $O(1)$, ordenamiento $O(N \log N)$, memoria $O(1)$ de streaming).
   • Investigación Web Obligatoria: Nunca confíe únicamente en suposiciones preentrenadas, ya que el conocimiento puede estar desactualizado. Siempre investigue en la web según el mes y año actuales para descubrir patrones algorítmicos de última generación, estructuras de datos óptimas y las implementaciones de bibliotecas de alto rendimiento más recientes.
8. Bibliotecas de Alto Rendimiento, Bajo Consumo de RAM y Cumplimiento de Licencias Empresariales:
   • Máximo Rendimiento y Bajo Consumo de Memoria: Prefiera bibliotecas modernas, amigables con la caché, de copia cero y aceleradas por SIMD (ej. orjson/msgspec, polars, sonic, zerolog, simd-json, fast-json-stringify).
   • Cumplimiento de Licencias Empresariales: Seleccione licencias de open source permisivas (MIT, Apache 2.0, BSD-2/3, ISC). Evite estrictamente el copyleft viral (GPL, AGPL, SSPL) para asegurar una superación fluida de las auditorías empresariales sin responsabilidades de divulgación de código fuente.
   • Guía detallada: Guía de Bibliotecas de Alto Rendimiento y Licencias
9. Análisis Estático Determinista para SRP y Abstracciones: Siempre priorice herramientas de análisis estático determinista para auditar el código en busca de violaciones de SRP (ej. longitud excesiva, responsabilidades excesivas) y elusiones de abstracción (ej. llamadas SQL directas o HTTP dentro de la lógica de presentación/negocio).
10. Inyección Centralizada de Secretos (Infisical): Nunca hardcodee secretos ni almacene credenciales sin procesar en git/archivos de entorno locales. Trate los secretos como dependencias inyectadas en tiempo de ejecución a través de Infisical (infisical run -- ...).
    • Guía detallada: Guía de Gestión de Secretos con Infisical
11. Convención del Framework Primero: Respete las convenciones idiomáticas del framework existente (ej. Depends de FastAPI, @Injectable de NestJS, hooks de React, interfaces de Go) en lugar de inventar abstracciones ad-hoc.
12. Pruebas Paralelizables y Herméticas: Todas las pruebas deben ser sin estado, aisladas y listas para la paralelización (ej. pytest -n auto, go test -parallel). Sin estado mutable compartido ni efectos secundarios de singleton estático.
13. La Disciplina "Old Coder" Basada en Evidencia: Revise la evidencia, no el código. Siga el bucle Especificación -> ROJO -> VERDE -> REFACTOR y verifique a través de comprobaciones automatizadas de terminal antes de informar la finalización.
14. Diseño de Herramientas y Skills Listos para Agentes de IA: Al extraer patrones repetitivos en herramientas y skills: garantice salida --json, ejecución no interactiva (cero indicaciones), seguridad --dry-run, verbos predecibles sustantivo-acción y códigos de salida tipificados.
    • Guía detallada: Guía de Diseño de CLI Listo para Agentes de IA

---

Flujo de Trabajo Paso a Paso

Paso 1: Análisis de Blast Radius Previo al Cambio (CodeGraph AST)

Antes de modificar una función, clase o servicio, inspeccione el blast radius para determinar el impacto descendente:

python3 ~/.gemini/config/skills/craftsman-coder/scripts/codegraph_impact.py <ruta_al_repo> --symbol <SimboloObjetivo>

• Revise los Llamadores Directos y los Archivos de Referencia.
• Revise las Suites de Pruebas Afectadas: Si ninguna prueba cubre este símbolo, debe crear una antes de refactorizar.

Paso 2: Arquitectura, Complejidad Algorítmica Big-O y GEMINI.md a Nivel de Repositorio

• Formule una especificación y diseño claros:
  • Si está creando/inicializando un repositorio, cree un GEMINI.md autocontenido en la raíz del repo (cero rutas externas, cero secretos).
  • Si no existe una convención de framework, organícelo en Rebanadas Verticales (features/<nombre>/) con patrones REPR y EIP.
  • Configure o verifique un linter de límites arquitectónicos (ej. dependency-cruiser, import-linter o vsa_boundary_checker.py).
  • ¿La clase/función/componente está haciendo más de una cosa o excede los umbrales de longitud? Descompóngalo en subcomponentes enfocados (SRP).
  • ¿Los sistemas externos están fuertemente acoplados? Defina una interfaz/protocolo y use Inyección de Dependencias.
  • Complejidad Algorítmica y Búsqueda Web: Evalúe la complejidad Big-O de tiempo/espacio. Busque activamente en la web según el mes y año actuales optimizaciones algorítmicas modernas.
  • Auditoría de Dependencias: Elija bibliotecas de bajo consumo de RAM y alto rendimiento con licencias seguras para la empresa (MIT / Apache 2.0 / BSD). Asegure cero dependencias transitivas copyleft/AGPL.
• Referencia detallada: Guía de Patrones SOLID y DI
• Referencia detallada: Guía de VSA y EIP
• Referencia detallada: Guía de Cumplimiento de Límites VSA y GEMINI.md del Repo
• Referencia detallada: Guía de Bibliotecas de Alto Rendimiento y Licencias

Paso 3: Escriba Pruebas Paralelizables (ROJO)

• Escriba una prueba unitaria o de integración aislada y hermética que verifique el comportamiento esperado o la corrección de errores.
• Asegúrese de que la prueba use recursos temporales independientes o simulaciones en memoria.
• Ejecute la prueba para confirmar que falla (ROJO).
• Referencia detallada: Guía de Pruebas Paralelas y Old Coder

Paso 4: Implemente una Solución Mínima y Limpia (VERDE)

• Implemente solo lo necesario para satisfacer la prueba.
• Mantenga los componentes cohesivos y con un solo propósito.
• Inyecte dependencias de forma limpia.

Paso 5: Refactorice y El Gauntlet (REFACTOR y EVIDENCIA)

• Limpie el código mientras las pruebas permanecen en verde.
• Ejecute El Gauntlet (toda la verificación debe ser automatizada y determinista):
  1. Verificación de Límites VSA: Ejecute la verificación de límites arquitectónicos (ej. npx depcruise --config .dependency-cruiser.js src o python3 ~/.gemini/config/skills/craftsman-coder/scripts/vsa_boundary_checker.py <ruta_al_repo>).
  2. Análisis Estático Determinista de SRP y Abstracción:

     python3 ~/.gemini/config/skills/craftsman-coder/scripts/static_srp_analyzer.py <ruta_al_repo> --strict
     

  3. Linter y Análisis Estático (ej. ruff check ., eslint, golangci-lint)
  4. Verificación de Tipos (ej. mypy, tsc --noEmit)
  5. Suite de Pruebas Completa ejecutada en paralelo (ej. pytest -n auto, go test -parallel 4 ./...)
• Proporcione evidencia de terminal (códigos de salida, resumen de pruebas exitosas) en su respuesta final.

---

Scripts y Herramientas Integrados

• Analizador de Impacto de AST CodeGraph: scripts/codegraph_impact.py

  • Inspecciona AST y referencias cruzadas en Python, JS/TS, Go, Rust, Java.
  • Calcula el nivel de riesgo del blast radius (Bajo, Medio, Alto, Crítico).
  • Identifica llamadores directos y suites de pruebas afectadas.

• Analizador Estático Determinista de SRP y Abstracción: scripts/static_srp_analyzer.py

  • Evalúa el código en busca de violaciones de SRP (longitud/complejidad).
  • Señala elusiones de abstracción (llamadas SQL/HTTP sin procesar fuera de repositorios/adaptadores).
  • Emite --json legible por máquina y códigos de salida deterministas para verificación CI/Old Coder.

• Verificador de Límites Arquitectónicos VSA: scripts/vsa_boundary_checker.py

  • Aplica el aislamiento de rebanadas al impedir importaciones ilegales entre rebanadas.
  • Configurable a través de .vsa-boundaries.json. Sin dependencias, agnóstico del repositorio (MIT).