CodeClone
Análisis estructural de calidad de código para Python con gobernanza de CI consciente de línea base, informes canónicos y una superficie de control MCP priorizada por triaje para agentes e IDEs.
Documentación
Controlador determinista de cambios estructurales para desarrollo de Python asistido por IA
Deja que los agentes avancen rápido.
Mantén el cambio estructural explícito, acotado y verificable.
[!IMPORTANT] Las secciones marcadas con
2.1 alpharequieren la CodeClone 2.1 prerelease. Todo lo demás funciona con la versión estable actual, CodeClone 2.0.2.
¿Qué es CodeClone?
CodeClone ayuda a los desarrolladores a usar agentes de codificación con IA sin perder el control del cambio estructural.
Antes de que un agente edite código, CodeClone registra el cambio previsto, mapea el radio de impacto estructural y establece límites de edición explícitos. Después de la edición, compara el parche real con el alcance declarado, verifica regresiones estructurales y deja un recibo de revisión auditable.
CodeClone no genera ni reescribe archivos fuente, y no le pide a un LLM que decida si un cambio estructural es seguro. Cada hallazgo y cada compuerta provienen de hechos deterministas del repositorio compartidos entre agentes, revisores humanos, IDEs, informes y CI.
| Capacidad | Qué proporciona |
|---|---|
| Análisis estructural canónico | Un informe determinista: clones, complejidad, acoplamiento, cohesión, código muerto, mapa de módulos, inventario de API, uniones de cobertura |
| Gobernanza consciente de la línea base | Registra la deuda heredada aceptada y la separa de las regresiones introducidas por el cambio actual |
| Un informe, muchas superficies | CLI, HTML, JSON, Markdown, SARIF, MCP, integraciones de IDE y GitHub Actions desde un único payload canónico |
Controlador de Cambio Estructural — 2.1 alpha | Control de cambios basado en intención, radio de impacto, límites de edición explícitos, verificación de parches y recibos de revisión |
Contexto de Implementación en Vivo — 2.1 alpha | Contexto estructural y de grafo de llamadas en tiempo real servido desde la ejecución de análisis actual — sin índice obsoleto que mantener |
Memoria de Ingeniería — 2.1 alpha | Conocimiento local, tipado y vinculado a evidencia del proyecto, e historias reutilizables de cambios controlados previos |
Coordinación de agentes — 2.1 alpha | Intenciones multiagente seguras ante conflictos, colas, recuperación e higiene del espacio de trabajo |
CodeClone no requiere servicio alojado ni cuenta en la nube. El estado de análisis, el estado del controlador, la Memoria de Ingeniería y las trayectorias se almacenan localmente.
Por qué la intención viene antes del diff
La mayoría de las herramientas de revisión comienzan después de que el parche ya existe. CodeClone comienza antes:
task request
→ declared intent
→ structural blast radius
→ explicit boundary
→ actual patch
→ deterministic verification
La expansión del alcance del agente puede parecer razonable en el diff final. Una tarea estrecha puede extenderse silenciosamente a helpers compartidos, pruebas, configuración, APIs públicas o módulos no relacionados.
Para cuando esa expansión llega al diff final, ya parece intencional. CodeClone lo detecta en el límite declarado en su lugar — comparando lo que el agente dijo que cambiaría con lo que realmente cambió.
Inicio rápido
Requiere Python 3.10 o superior.
1. Analizar un repositorio
Ejecuta la versión estable sin instalar nada:
uvx codeclone@latest .
¿Prefieres un informe navegable? Genera la vista HTML y ábrela:
uvx codeclone@latest . --html --open-html-report
Una vez que lo uses con regularidad, instálalo como herramienta local:
uv tool install codeclone
codeclone .
2. Registrar la línea base estructural actual
Antes de pedirle a un agente que cambie el repositorio, captura el estado aceptado una vez:
codeclone . --update-baseline
git add codeclone.baseline.json
git commit -m "chore: add CodeClone structural baseline"
La línea base registra la deuda estructural que ya existe. El análisis futuro puede entonces separar nuevas regresiones de hallazgos que ya estaban presentes, para que los agentes y revisores se centren en lo que introdujo el cambio actual.
Actualizar la línea base es una acción de gobernanza explícita. No la regeneres solo para que una verificación fallida pase.
3. Conecta tu agente de IA — 2.1 alpha
Continúa a Control de cambios de agentes a continuación para instalar la superficie de control MCP y conectar CodeClone a Claude Code, Cursor, VS Code, Codex o Claude Desktop.
Un informe estructural canónico
CodeClone ejecuta un análisis determinista y renderiza el mismo informe canónico a través de cada superficie compatible.
El informe cubre:
- clones de función, bloque y segmento;
- deriva de clones y familias de ramas duplicadas;
- complejidad, acoplamiento, cohesión, ciclos de dependencia y código muerto;
- Mapa de Módulos — un grafo de dependencias de paquetes/módulos con vistas de ciclo, hub, módulo sobrecargado y candidatos a desenrollado;
- Revisión Guiada de Hallazgos — una cola de revisión priorizada con tarjetas de hallazgos compartidas, filtros y seguimiento de progreso;
- inventario de API pública y detección de rupturas de API consciente de la línea base;
- cobertura externa unida a puntos calientes estructurales;
- salud estructural determinista y prioridades de revisión.
codeclone . --json --html --md --sarif --text
Cómo funciona CodeClone · Contrato de informe canónico
Gobernanza consciente de la línea base y CI
La línea base es un contrato versionado y verificado por integridad que registra el estado estructural aceptado del repositorio.
Permite a CodeClone y a los agentes conectados distinguir:
- hallazgos que ya existían;
- regresiones introducidas por el cambio actual;
- actualizaciones deliberadas de la línea base aprobadas por el usuario.
Comprueba cambios futuros contra la línea base confirmada:
codeclone . --ci
Usa CodeClone en GitHub Actions:
- uses: orenlab/codeclone/.github/actions/codeclone@v2
with:
fail-on-new: "true"
sarif: "true"
pr-comment: "true"
CI puede rechazar clones recién introducidos, regresiones de métricas, rupturas de API y regresiones de cobertura sin requerir que el repositorio existente esté limpio primero.
Contrato de línea base · Integración de CI y compuertas de calidad
Cómo se diferencia CodeClone
Los linters verifican estilo y corrección archivo por archivo. Los detectores de clones informan duplicación y se detienen ahí. Los bots de revisión alojados le piden a un modelo una opinión sobre un diff terminado.
CodeClone combina detección de clones basada en CFG, gobernanza de línea base multi-métrica y una superficie de control MCP de solo lectura en un paquete local-first de código abierto — y las aplica antes de que ocurra la edición, no solo después. Los hechos estructurales se calculan de forma determinista, por lo que la misma entrada siempre produce el mismo veredicto, en la terminal, en CI y dentro del bucle de tu agente.
Control de cambios de agentes — 2.1 alpha
Instalar la superficie de control MCP
uv tool install --prerelease allow "codeclone[mcp]"
codeclone-mcp --transport stdio
El servidor expone 38 herramientas MCP que cubren análisis, control de cambios, radio de impacto, memoria y diagnósticos. Las respuestas están diseñadas para bucles de agentes: guía determinista next_tool, payloads conscientes del presupuesto de tokens y respuestas que mantienen los hechos de control obligatorios en línea mientras enlazan evidencia completa para profundizar.
Antes de controlar agentes o CI, confirma [tool.codeclone] y la higiene local de gitignore:
codeclone setup status
codeclone setup plan
codeclone setup apply # or: codeclone setup wizard
Consulta Configuración y preparación del repositorio.
Conéctalo a tu cliente
| Cliente | Configuración |
|---|---|
| VS Code | Configuración de extensión |
| Cursor | Plugin y habilidades |
| Claude Code | Configuración de plugin |
| Codex | Configuración de plugin |
| Claude Desktop | Configuración de bundle |
Cada cliente usa la misma interfaz MCP y los mismos hechos estructurales canónicos.
El flujo de trabajo de cambio controlado
Para un agente, el flujo de trabajo normal es:
analyze → start → edit → finish
Analizar. CodeClone construye un informe estructural canónico para el repositorio y lo compara con la línea base aceptada.
Iniciar. start_controlled_change:
- registra la intención del agente;
- mapea el radio de impacto estructural;
- separa las rutas editables del contexto de revisión y los límites de no tocar;
- expone el presupuesto de regresión relativo a la línea base aceptada;
- devuelve el resultado autoritativo
edit_allowed.
Editar. El agente escribe el código. CodeClone no genera ni reescribe archivos fuente. Donde el host soporta hooks, las integraciones pueden detener ediciones a menos que edit_allowed=true. Mientras edita, el agente se mantiene orientado a través de Contexto de Implementación en Vivo en lugar de redescubrir el repositorio con búsquedas amplias.
Finalizar. finish_controlled_change:
- resuelve los archivos realmente cambiados;
- comprueba el alcance declarado contra el parche real;
- verifica los cambios estructurales;
- valida afirmaciones de revisión opcionales;
- registra evidencia de Patch Trail;
- produce un recibo de revisión auditable.
Si el parche cruza el límite declarado o introduce regresiones más allá del presupuesto, la verificación falla — y el recibo registra exactamente dónde y por qué. El resultado no es una opinión de IA sobre el parche. Es una comparación determinista entre la intención declarada, la estructura del repositorio, la línea base aceptada y el cambio real.
Lee la guía del Controlador de Cambio Estructural
Contexto de Implementación en Vivo
get_implementation_context sirve al agente contexto acotado y limitado a la tarea directamente desde la ejecución de análisis actual:
- contexto estructural y relaciones de llamadas para el alcance de edición declarado;
- mapas de verdad orientados a contratos y anclas de prueba;
- señales de frescura y límites de intención activos.
No hay una base de datos vectorial separada que se quede atrás del código, ni un demonio observador que reindexe el árbol. El contexto proviene del mismo análisis que produce hallazgos y compuertas — así que lo que el agente lee es lo que el verificador comprobará. El contexto es de solo lectura: informa ediciones pero nunca las autoriza.
También en la línea 2.1
- Observabilidad de Plataforma — trazado en tiempo de desarrollo de CLI, MCP, fases de análisis, actividad de base de datos y presión de payload, para que puedas ver qué está haciendo CodeClone y cuánto cuesta.
- Analítica de Corpus — agrupación de intenciones fuera de línea e interpretabilidad sobre cambios controlados registrados, con perfiles versionados y salidas JSON/HTML inspeccionables.
Memoria de Ingeniería — 2.1 alpha
La Memoria de Ingeniería brinda a los agentes contexto duradero y específico del repositorio sin tratar la salida del modelo como verdad del proyecto.
El almacén local SQLite puede contener:
- notas de arquitectura y contratos;
- riesgos, anclas de prueba y superficies públicas;
- procedencia de git y control de cambios;
- trayectorias previas y evidencia de Patch Trail;
- patrones de asesoramiento recurrentes llamados Experiencias.
Los registros creados por agentes permanecen como borradores hasta que un humano los apruebe.
codeclone memory init --root .
codeclone memory search "baseline schema" --match all
La recuperación es híbrida: búsqueda léxica FTS5/BM25, búsqueda vectorial opcional con LanceDB y fusión de rango recíproco que combina ambas, con un ranking totalmente reproducible.
La memoria puede guiar a un agente. No puede autorizar ediciones, anular el radio de explosión, cambiar una compuerta ni reemplazar hechos canónicos de informes.
Documentación de memoria de ingeniería · Trayectorias y experiencias
Límites de confianza
- Los hallazgos estructurales y las compuertas provienen de análisis deterministas, no del juicio de un LLM.
edit_allowedes un resultado explícito del controlador; el estado o la propiedad de asesoría no otorgan permiso.- Los comandos de análisis de solo lectura no modifican el código fuente ni el estado de gobernanza del proyecto.
- Las actualizaciones de línea base son acciones de gobernanza explícitas aprobadas por el usuario.
- Las operaciones del controlador y de la memoria escriben únicamente en sus almacenes de estado locales explícitos.
- La memoria, la trayectoria y la evidencia del contexto de implementación siguen siendo de carácter consultivo.
stdioes el transporte recomendado para clientes locales.- La exposición HTTP remota requiere
--allow-remoteexplícito.
Contribuciones
Los informes de errores, las discusiones de funciones y las solicitudes de extracción son bienvenidos: comience con Issues o Discussions, o únase al Discord.
Ejecute la versión del repositorio desde el código fuente:
git clone https://github.com/orenlab/codeclone.git
cd codeclone
uv sync --all-extras
uv run codeclone .
Documentación
- Primeros pasos
- Controlador de cambios estructurales
- Memoria de ingeniería
- Uso de MCP
- Referencia de configuración
Licencia
- Código: MPL-2.0
- Documentación: MIT
Consulte LICENSES.md para ver el mapa del alcance de la licencia.