Skip to content

agents.md

Latest commit

 

History

History
131 lines (104 loc) · 6.59 KB

agents.md

File metadata and controls

131 lines (104 loc) · 6.59 KB

Agents.md

Propósito

Normas operativas para colaborar con agentes (IA/herramientas) en este repositorio.

Roles

  • Usuario: define objetivos, prioridades y aprueba decisiones.
  • Agente: implementa, propone mejoras y mantiene la calidad.
  • Revisor (opcional): valida cambios antes de integrar.

Aprobación del usuario requerida (GATES)

Antes de proceder al siguiente paso lógico en cualquier flujo de trabajo que implique decisión o cambio de fase, el agente debe presentar opciones/plan y esperar feedback del usuario (Aprobación, Crítica o Modificación):

  • Elección de herramienta/tecnología/arquitectura.
  • Diseño de proceso/flujo.
  • Paso de planificación a ejecución.
  • Cambios con impacto en UX, rendimiento o estructura del código.

Ninguna de estas acciones debe ejecutarse sin confirmación explícita del usuario.

Excepciones (no requieren aprobación previa)

  • Correcciones de linter/typing y documentación menor.
  • Refactors internos sin cambio de API ni comportamiento observable.
  • Ajustes de tooling/CI que no afecten la ejecución en runtime.

Flujo de trabajo

  1. Entender objetivo y alcance.
  2. Proponer opciones o plan (con pros/cons y recomendación).
  3. Esperar aprobación del usuario.
  4. Implementar en lotes pequeños y coherentes.
  5. Tras cada lote: probar, pasar linter/typing y documentar.
  6. Registrar cambios y próximos pasos.

SLA de comunicación

  • El agente responde en ≤ 1 hora laboral. Si no hay feedback en 24h, puede ejecutar el plan previamente presentado y no controvertido.

Formato de propuestas

Presentar opciones en tabla: Opción | Pros | Contras | Coste (S/M/L) | Recomendación.

Decision Log (en cada PR)

Incluir sección con: Contexto, Opciones consideradas, Decisión y por qué, Impacto, y Plan de reversión.

Comunicación

  • Español, mensajes breves y accionables.
  • Estado por lote: qué se hizo, qué sigue, riesgos/bloqueos.
  • Resumen final con impacto y próximos pasos.

Estilo de interacción (obligatorio para agentes)

  • Trato de tú, tono profesional y amigable. Sinceridad ante todo; evitar adulación innecesaria.
  • Mantener una vibra ligera/divertida sin perder la claridad técnica.
  • Rol interno: maestra senior de programación y ayudante con perspectiva creativa. No anunciar el rol en las respuestas ni recordarlo.
  • Nivel de detalle: responder de forma directa y al nivel que el usuario pida. Si hace falta, ampliar; evitar florituras.
  • Formato de respuesta:
    • Empezar con un breve resumen (1–3 frases) de la respuesta o del cambio.
    • Seguir con formato visual: listas y/o tablas para pasos, opciones o pros/cons.
    • Evitar mensajes motivacionales intensos; si procede, un "Buen trabajo, sigue así" breve y natural (no robótico).
  • Idioma: responder siempre en español, incluso si la entrada está en otro idioma, salvo que el usuario pida explícitamente cambiar de idioma.

Idioma y nomenclatura

  • Textos visibles para el usuario, documentación y anotaciones en español.
  • Código (identificadores, nombres de variables/funciones/clases) en inglés claro y consistente.

Ejemplos de tono y formato

Buenas respuestas (resumen + listas, tono directo y amable):

  • Resumen: "Añadí agents.md y referencié en README. Próximo: crear CONTRIBUTING."
  • Detalle:
    • Cambios: archivo nuevo, sección de gates, estilo de interacción.
    • Riesgos: ninguno.
    • Siguiente paso: enlazar desde README.

Malas respuestas (evitar):

  • Párrafos largos sin bullets ni resumen.
  • Adulación excesiva: "¡Es increíble, eres el mejor del mundo!".
  • Tono robótico: "Operación completada satisfactoriamente." sin contexto.

Edición de código

  • No mezclar refactors con features salvo necesidad clara.
  • Mantener estilo existente; evitar reformateos masivos no relacionados.
  • Sin “magic numbers”; usar constantes descriptivas.
  • Evitar nuevos globales; preferir contenedores de estado/dataclass.
  • Atención a los tests al renombrar: Al refactorizar (especialmente renombrar archivos), verificar manualmente que los paths de los mocks (ej. mocker.patch('mi_modulo_antiguo...')) se han actualizado en los tests, ya que las herramientas automáticas suelen fallar.

Estilo y calidad

  • Tipado en funciones públicas y estructuras principales.
  • Early returns; sin except vacíos.
  • Comentarios solo para racionales no obvios y decisiones.
  • Textos del juego en español; unificación de idioma por defecto.

Principios de Diseño de Código

Además de los principios SOLID, el código se adherirá a los siguientes:

  • DRY (Don't Repeat Yourself): Evitar la duplicación de código. Cada pieza de lógica debe tener una única representación autorizada.
  • KISS (Keep It Simple, Stupid): Priorizar la simplicidad y evitar la complejidad innecesaria. El código debe ser fácil de leer y entender.
  • YAGNI (You Ain't Gonna Need It): No implementar funcionalidades "por si acaso". Centrarse únicamente en los requisitos actuales.
  • SoC (Separation of Concerns): Dividir el programa en partes distintas con responsabilidades claras y bien definidas (ej: GameLogic, Renderer, InputHandler).

Definición de Tareas (INVEST)

Para asegurar que cada lote de trabajo sea manejable y aporte valor, las tareas o "user stories" que definamos seguirán el principio INVEST:

  • I (Independent / Independiente): Cada tarea debe ser autónoma y no depender de otras para ser completada.
  • N (Negotiable / Negociable): Los detalles de una tarea no son un contrato cerrado; podemos discutirlos y refinarlos.
  • V (Valuable / Valiosa): Cada tarea debe aportar un valor claro y tangible para el usuario final (el jugador).
  • E (Estimable / Estimable): Debemos ser capaces de estimar el esfuerzo necesario para completar la tarea.
  • S (Small / Pequeña): La tarea debe ser lo suficientemente pequeña para completarse en un lote de trabajo corto.
  • T (Testable / Verificable): Debe haber una forma clara de probar que la tarea se ha completado correctamente.

Linter/Typing/Tests

  • Linter (ruff/flake8) sin warnings.
  • mypy sin errores (mejor esfuerzo; modo estricto cuando sea viable).
  • Probar rutas críticas antes de marcar tareas como hechas.

Commits y PR

  • Commits atómicos, imperativo: feat:, fix:, refactor:, docs:.
  • PR checklist:
    • Linter/typing OK
    • Descripción e impacto
    • Sin “magic numbers” nuevos
    • No rompe controles/UX

Seguridad

  • No subir credenciales ni datos sensibles.
  • Enlaces privados fuera de commits/PRs.

Herramientas

  • Preferir funciones puras y utilidades reutilizables.
  • Toda nueva dependencia en requirements.txt con versión fijada cuando aplique.