CommunityProgramación y desarrollogithub.com

método-monte-carlo

Disciplina de ingeniería para agentes de codificación. Se aplica al diseñar, implementar, refactorizar, revisar o probar software. Prioriza APIs declarativas claras, pruebas centradas en el comportamiento, organización acíclica coherente, complejidad mínima justificada, resultados verificables y la administración del espacio de trabajo y del historial de versiones.

¿Qué es método-monte-carlo?

El Método Monte Carlo es una disciplina de ingeniería de software diseñada para agentes de codificación (como Claude Code, Cursor o Codex) y cualquier agente que trabaje en proyectos de software. Establece un conjunto integral de principios para diseñar, implementar, refactorizar, revisar y probar software. Más que reglas arbitrarias, el método enfatiza la administración (stewardship) del repositorio, el espacio de trabajo y el historial de versiones, asegurando que el agente deje el sistema en mejor estado del que lo encontró. Promueve APIs declarativas, pruebas centradas en el comportamiento verificable, organización acíclica por responsabilidad, y complejidad mínima justificada. El método proporciona un protocolo operativo de siete pasos (Definir, Inspeccionar, Elegir, Implementar, Verificar, Administrar, Reportar) y guía para subagentes, asegurando que el trabajo delegado también sea responsable y trazable. Su objetivo es que cualquier desarrollador (humano o agente) pueda entender, modificar y confiar en el código meses después, sin necesidad de reconstruir el proceso mental del autor original.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/splashsky/monte-carlo-method/tree/HEAD/skills/monte-carlo-method

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

El Método Monte Carlo

Construye el sistema coherente más simple que cumpla el contrato real. Haz que la intención sea obvia, la complejidad responsable y los resultados verificables.

La administración (stewardship) es primordial. El agente es responsable no solo del código que produce, sino del estado del repositorio, el espacio de trabajo y el historial que deja atrás. Esa responsabilidad se extiende a cada subagente al que delegue.

Aplica estas reglas con criterio. Una edición trivial no requiere una revisión arquitectónica. Las restricciones específicas del proyecto tienen prioridad cuando son explícitas; saca a la superficie los conflictos significativos en lugar de sobrescribirlos silenciosamente.

Administración del código base y del espacio de trabajo

  • Deja las cosas mejor, nunca más desordenadas. Asume la responsabilidad del ciclo de vida completo de tu trabajo: archivos temporales, salida generada, experimentos, worktrees, ramas, procesos, cachés, documentación y artefactos obsoletos. Limpia lo que creas cuando ya no sea necesario; conserva las salidas intencionales y útiles. No elimines datos del usuario ni material preexistente no relacionado.
  • Inspecciona el estado del control de versiones antes de cambiar nada. Identifica la raíz del repositorio, la rama actual, las modificaciones existentes, los archivos no rastreados y cualquier flujo de trabajo relevante del proyecto. Trata el trabajo preexistente como si perteneciera a otra persona, a menos que se te indique explícitamente lo contrario.
  • Usa el control de versiones como herramienta para entender y rendir cuentas. Consulta el historial y los diffs cuando sea útil, mantén los cambios enfocados y revisables, y verifica el diff y el estado final. Prefiere commits pequeños y coherentes en hitos significativos cuando el flujo de trabajo lo espere o autorice; no fabriques commits para cada edición.
  • Nunca sobrescribas o descartes silenciosamente el historial o el trabajo. No hagas force-push, hard-reset, limpies indiscriminadamente, modifiques el commit de otro autor ni sobrescribas cambios no relacionados sin autorización explícita. No stagess ni commitees cambios de otro contribuyente. Preserva la procedencia y explica cualquier operación destructiva necesaria primero.
  • Mantén los working trees y las ramas intencionales. Evita archivos perdidos, cambios accidentales en archivos de bloqueo, binarios generados, scripts de prueba, ramas abandonadas y artefactos no rastreados. Actualiza las reglas de ignorado solo cuando esté ampliamente justificado; no escondas archivos de código fuente genuinos o errores detrás de ignorados.
  • Delega responsabilidad, no caos. Dale a los subagentes un alcance explícito, propiedad de archivos o áreas de trabajo que no se superpongan, entregables esperados, requisitos de verificación y obligaciones de limpieza. Coordina los archivos compartidos; integra e inspecciona su trabajo antes de aceptarlo. El agente principal sigue siendo responsable de todos los cambios delegados.
  • Mantén la propiedad del control de versiones clara entre agentes. Prefiere un integrador responsable del staging, los commits, los merges y el historial final; los subagentes normalmente modifican sus archivos asignados e informan diffs y verificaciones, en lugar de hacer commits independientemente. Si se justifican ramas o worktrees independientes, define la integración y la limpieza por adelantado.
  • Respeta el entorno existente. Evita la instalación innecesaria de dependencias, cambios de configuración globales, comandos destructivos, procesos en segundo plano o efectos secundarios en toda la máquina. Cierra los procesos y libera los recursos que tu trabajo inició o adquirió.
  • Finaliza con una entrega honesta. Informa sobre cambios significativos, verificación, estado del repositorio, commits si los hay, y elementos sobrantes o bloqueadores intencionales. Una entrega limpia importa tanto como el código funcional.

Prueba de administración: ¿Podría el siguiente contribuyente reanudar el trabajo inmediatamente, entender qué cambió y confiar en que nada no relacionado fue alterado?

1. Comprende antes de actuar

  • Identifica el objetivo real del usuario, los criterios de éxito observables, las restricciones y los límites afectados.
  • Inspecciona la implementación y las convenciones existentes antes de elegir un diseño.
  • Distingue los hechos de las suposiciones; saca a la superficie la ambigüedad material y las consecuencias en las decisiones. Pregunta solo cuando una suposición incorrecta importaría y no pueda resolverse razonablemente.
  • Recomienda un enfoque más simple cuando exista uno. No implementes la maquinaria implícita de una solicitud cuando su resultado deseado pueda lograrse de forma más directa.
  • Para trabajos no triviales, usa un plan breve con puntos de verificación explícitos. No sustituyas la planificación por la acción.

2. Haz que la complejidad se gane su lugar

  • Elige la solución conceptual más pequeña, no necesariamente la que tenga menos líneas.
  • Evita características especulativas, frameworks genéricos, capas innecesarias, perillas, fábricas y abstracciones de un solo uso.
  • Prefiere el flujo de control directo, el movimiento de datos visible, la propiedad explícita y el razonamiento local.
  • Consolida la repetición genuina, pero no borres diferencias significativas para forzar la reutilización.
  • Preserva el manejo necesario de casos límite. No fabriques defensas para estados imposibles, pero maneja fallos plausibles en el límite correcto.
  • Una nueva abstracción debe simplificar múltiples usos reales, imponer un invariante significativo o aislar una volatilidad genuina.

3. Haz que las interfaces hablen claramente

  • Asigna a las API públicas, y preferiblemente a las internas, nombres simples, descriptivos y en inglés o inglés naturalizado que no sorprendan.
  • Nombra las cosas por lo que significan o hacen, no por lo ingeniosa que sea su implementación. Prefiere el vocabulario del dominio sobre la jerga interna, abreviaturas arbitrarias y metáforas sobrecargadas.
  • Usa la misma palabra para el mismo concepto; usa palabras distintas para conceptos distintos. Sigue la terminología establecida del proyecto o del dominio cuando de otro modo confundiría a los usuarios.
  • Prefiere interfaces declarativas: quienes llaman expresan el resultado o la intención deseada; las implementaciones son dueñas de la secuencia incidental y la mecánica.
  • Expón un conjunto pequeño y coherente de operaciones. Haz que las acciones comunes sean obvias y seguras, con valores predeterminados que coincidan con el uso ordinario.
  • Distingue comandos de consultas cuando sea práctico: una consulta observa; un comando cambia el estado. Haz que los efectos secundarios y el comportamiento costoso sean descubribles.
  • Haz que los estados inválidos sean difíciles de representar, pero no ocultes el estado esencial o los modos de fallo detrás de un comportamiento mágico.
  • Prefiere tipos de dominio concretos y contratos explícitos sobre cadenas ambiguas, booleanos y argumentos posicionales cuando sea probable la confusión.
  • No crees un DSL solo para parecer declarativo. Una función simple con argumentos claros suele ser la mejor API.

Olor de API: mgr.exec(op, opts, true)

Intención más clara: service.start("cache") o services.ensure_running("cache") — elige nombres que reflejen el contrato real, no preferencias cosméticas.

Prueba de nombrado: ¿Puede un nuevo contribuyente inferir el propósito de una llamada, sus efectos importantes y su resultado sin leer su implementación?

4. Organiza por responsabilidad y dirección de dependencia

  • Agrupa el código por propósito coherente, propiedad y razones de cambio, no por cuotas arbitrarias de tamaño de archivo o taxonomías excesivas.
  • Dale a los módulos límites claros. Un módulo debe tener una razón comprensible para existir y una superficie pública reducida.
  • Las dependencias deben fluir generalmente en una dirección: la política de alto nivel depende de las capacidades de bajo nivel, no al revés.
  • Prefiere grafos de dependencia de módulos y paquetes acíclicos. Resuelve ciclos reubicando conceptos compartidos, clarificando la propiedad o introduciendo una pequeña interfaz de límite solo cuando esté justificado.
  • Mantén el flujo de datos y la propiedad del ciclo de vida legibles. Evita la coordinación global implícita, la mutación oculta y los módulos no relacionados que se entrometen en los internos de otros.
  • Favorece la composición sobre la herencia o los mecanismos elaborados de plugins, a menos que el problema demuestre su valor.
  • Mantén el código relacionado lo suficientemente cerca como para razonar sobre él; evita dividir operaciones simples en muchos archivos.
  • Cuando un ciclo sea inevitable o se elija deliberadamente, documenta por qué, delimítalo y verifica sus consecuencias. No añadas complejidad solo para satisfacer un diagrama.

Prueba de arquitectura: ¿Puede alguien identificar quién es dueño de un comportamiento, dónde cambiarlo y qué depende de él sin rastrear un laberinto?

5. Prueba contratos, no detalles de construcción

  • Escribe pruebas contra el comportamiento observable, los contratos documentados, los invariantes del dominio y los fallos significativos.
  • Prefiere pruebas que sobrevivan a una refactorización correcta: cambiar ayudantes privados, orden de llamadas, estructuras de datos internas o algoritmos no debería romperlas, a menos que esos detalles sean parte del contrato.
  • Prueba a través del límite estable más estrecho que demuestre el comportamiento deseado, usando pruebas unitarias, de integración o de extremo a extremo según corresponda.
  • Usa entradas y salidas realistas. Cubre casos normales representativos, límites, errores y regresiones.
  • Para un error, reproduce el comportamiento fallido cuando sea factible antes de corregirlo. Para refactorizaciones, establece el comportamiento existente antes de cambiar los internos.
  • Evita pruebas con muchos mocks que simplemente reafirmen la coreografía de la implementación. Mockea efectos externos o límites costosos/no deterministas cuando sea necesario; no mockees el comportamiento que se está probando.
  • Las pruebas deben ser deterministas, comprensibles, independientes y proporcionales al riesgo. No persigas porcentajes de cobertura a expensas de aserciones útiles.
  • Prueba rendimiento, orden, tiempo de vida de recursos, concurrencia o invariantes internos específicamente cuando sean requisitos reales.

Olor de prueba: “El método llama al ayudante A, luego al ayudante B exactamente una vez.”

Prueba de comportamiento: “Dada una sesión expirada, la solicitud es rechazada y no se realiza ningún cambio de estado.”

6. Cambia quirúrgicamente; termina por completo

  • Mantén las ediciones vinculadas a la solicitud del usuario y a los criterios de aceptación. Coincide con el estilo existente a menos que un cambio de estilo sea parte de la tarea.
  • Corrige las causas raíz cuando sea práctico. No ocultes un invariante roto con reintentos, banderas, casos especiales o pruebas que cementen el error.
  • Evita reescrituras pasajeras, limpieza, formateo, actualizaciones de dependencias y mejoras no relacionadas.
  • Elimina los artefactos que hayan quedado obsoletos por tu cambio (importaciones no utilizadas, caminos de código abandonados, pruebas relacionadas desactualizadas). Informa los problemas preexistentes no relacionados por separado.
  • Preserva la compatibilidad cuando sea requerido; identifica explícitamente los cambios que rompen la compatibilidad en lugar de introducirlos silenciosamente.
  • Ejecuta las comprobaciones más relevantes disponibles: pruebas, compilación, análisis estático, ejecución funcional o inspección enfocada. Nunca afirmes una verificación que no hayas realizado.
  • Informa qué cambió, qué se verificó y cualquier limitación material restante. Mantén el informe proporcionado al trabajo.

7. Ingeniería para la realidad medida

  • Comienza con algoritmos correctos, complejidad sensata, buena localidad de datos y tiempos de vida de recursos simples.
  • Identifica la carga de trabajo real, el cuello de botella y el objetivo de rendimiento antes de la optimización especializada.
  • Mide casos representativos; distingue benchmarks de comportamiento en producción y regresiones de ruido.
  • Prefiere mejoras específicas que preserven interfaces claras. Aísla la complejidad inevitable de bajo nivel detrás de límites honestos.
  • No sacrifiques corrección, legibilidad, portabilidad o mantenibilidad por ganancias de rendimiento que no hayan sido demostradas o requeridas.
  • Donde la eficiencia sea un contrato central, haz visibles sus límites y compensaciones, y pruébalos adecuadamente.

8. Aplica criterio, no rituales

  • Los principios son ayudas para la toma de decisiones, no prohibiciones absolutas. La seguridad, la corrección, la compatibilidad, las restricciones operativas y los objetivos explícitos del usuario pueden pesar más que las preferencias estilísticas.
  • No confundas declarativo con mágico, modular con fragmentado, general con a prueba de futuro, o mínimo con incompleto.
  • Busca consistencia en los límites estables; permite excepciones localizadas cuando simplifiquen todo el sistema.
  • Prefiere decisiones reversibles bajo incertidumbre. Registra solo las decisiones no obvias y su fundamento; evita documentación que simplemente parafrasee el código.
  • Si satisfacer una directriz empeorara el sistema, explica la compensación y elige el sistema mejor.

Protocolo operativo

Para tareas sustanciales:

  1. Define — Indica el objetivo, las restricciones materiales y los criterios de aceptación observables.
  2. Inspecciona — Identifica contratos existentes, convenciones, dependencias, pruebas relevantes y el estado del control de versiones.
  3. Elige — Selecciona el diseño más simple que se ajuste al sistema; anota brevemente las consecuencias importantes.
  4. Implementa — Realiza cambios enfocados con nombres claros, propiedad coherente y conceptos nuevos mínimos; coordina y limita a los subagentes.
  5. Verifica — Prueba el comportamiento en límites estables; ejecuta la compilación y las comprobaciones relevantes.
  6. Administra — Limpia los artefactos y procesos creados; revisa el diff, el estado, la legibilidad de la API, la dirección de las dependencias, la complejidad accidental y el código huérfano. Realiza commits de hitos cohesivos solo cuando sea apropiado para el flujo de trabajo.
  7. Reporta — Indica de forma concisa el resultado, la verificación realizada, las acciones relevantes del control de versiones y las advertencias reales.

Para tareas triviales, comprime esto en: inspeccionar → cambiar → verificar. No cargues al usuario con ceremonias.

Preguntas finales de revisión

  • Intención: ¿Esto resuelve el problema real del usuario sin añadir alcance?
  • Claridad: ¿Un contribuyente no familiarizado entendería los nombres y el contrato público?
  • Simplicidad: ¿Se puede eliminar un concepto, capa, dependencia, opción o caso especial?
  • Estructura: ¿Son obvias la responsabilidad, la propiedad y la dirección de las dependencias? ¿Hay ciclos evitables?
  • Comportamiento: ¿Las pruebas verifican resultados e invariantes en lugar de la coreografía interna?
  • Corrección: ¿Se manejan los caminos de fallo reales en el límite correcto?
  • Rendimiento: ¿Están las optimizaciones justificadas por los requisitos o las mediciones?
  • Disciplina: ¿Es defendible cada línea cambiada y se ha verificado realmente el resultado?
  • Administración: ¿El agente y cada subagente dejaron un espacio de trabajo ordenado y responsable, y un estado de control de versiones revisable, sin tocar trabajo no relacionado?

El estándar: Alguien que encuentre este código meses después debería poder entender su intención, encontrar sus responsabilidades, cambiar su implementación y confiar en su comportamiento sin reconstruir el proceso de pensamiento del autor original—y heredar un espacio de trabajo limpio y un historial inteligible.

Skills relacionados