Tutorial de code-review-graph: análisis de impacto de PR y grafos incrementales de CI para Codex y Claude Code

code-review-graph es una herramienta local de grafos de estructura de código. Usa Tree-sitter para analizar el código fuente, guarda llamadas, importaciones, herencia, pruebas y otras relaciones en una base de datos SQLite dentro del repositorio, y expone contexto estructurado a Codex, Claude Code y otras herramientas mediante CLI y MCP.

En lugar de “dejar que la IA apruebe automáticamente PR”, resuelve el problema de reducir el costo de que la IA investigue en todo el repositorio cada revisión y ayude a los revisores a localizar llamadas entre archivos, áreas de impacto potencial y lagunas en las pruebas. La conclusión final todavía depende de Git diff, los resultados de las pruebas y el juicio humano.

Dirección del proyecto: tirth8205/code-review-graph

¿Cuándo vale la pena usarlo?

Más adecuado para:

Almacén de cientos a miles de archivos;
proyecto monorepo o multilingüe;
Revisar con frecuencia las modificaciones entre archivos y módulos;
Necesidad de realizar un seguimiento de las personas que llaman, las dependencias, las pruebas y los flujos de ejecución;
Quiere que los datos del gráfico central permanezcan locales.

No necesariamente adecuado para:

Pequeños proyectos con sólo unos pocos archivos;
Las modificaciones se concentran en un único expediente independiente;
Principalmente revisar documentos, configuraciones o fotografías;
El equipo no está preparado para mantener la frescura del índice;
Tarea única, más rápida para leer diferencias directamente.

Para una diferencia pequeña, el resultado de la consulta del gráfico puede ser mayor que la diferencia original. Primero se debe utilizar el contexto mínimo y la detección de cambios antes de decidir si se expande el radio de impacto.

Principio de funcionamiento y límites de datos

El proceso principal es:

1
2
3
4
5
6


Git 跟踪文件
  -> Tree-sitter 解析
  -> 节点与关系
  -> .code-review-graph/ SQLite
  -> CLI / MCP 查询
  -> Codex、Claude Code 或人工审查

La composición central y las consultas se pueden realizar localmente, sin necesidad de cargar código en la nube. Las incorporaciones opcionales pueden utilizar modelos locales o proveedores de nube; Los límites de envío de códigos y las políticas del equipo deben confirmarse antes de habilitar las integraciones en la nube.

En el repositorio Git, solo los archivos rastreados devueltos por git ls-files se indexan de forma predeterminada. Para excluir archivos generados o código de terceros que todavía son rastreados por Git, cree en la raíz del repositorio:

1
2
3
4
5


# .code-review-graphignore
generated/**
*.generated.ts
vendor/**
node_modules/**

Las bases de datos de gráficos suelen estar ubicadas en:

1

.code-review-graph/

Es un artefacto reconstruible y no debe enviarse incondicionalmente a Git.

Prepare el entorno Python antes de la instalación

Requisitos del proyecto Python 3.10 o superior:

1
2


python --version
git --version

Se recomienda utilizar pipx para aislar el CLI global:

1
2
3


python -m pip install --user pipx
python -m pipx ensurepath
pipx install code-review-graph

También puedes instalarlo directamente:

1

python -m pip install code-review-graph

Verificación posterior a la instalación:

1
2


code-review-graph --help
code-review-graph status

Si el shell no puede encontrar el comando, primero verifique si el directorio bin de Python Scripts o pipx ha ingresado PATH. No instale repetidamente varias copias.

Configurar MCP para Codex o Claude Code

El comando de instalación unificada detectará la plataforma instalada:

1

code-review-graph install

Configurar solo Codex:

1

code-review-graph install --platform codex

Configurar solo Claude Code:

1

code-review-graph install --platform claude-code

El instalador escribirá la configuración MCP correspondiente y agregará enlaces, habilidades o descripciones de reglas en las plataformas compatibles. Haga una copia de seguridad de la configuración existente antes de la ejecución y verifique la diferencia después de la ejecución para evitar sobrescribir accidentalmente las personalizaciones del equipo.

Reinicie la herramienta AI cuando haya terminado. Claude Code puede verificar la conectividad a través de /mcp; otros clientes deben confirmar que el servidor code-review-graph está conectado y enumera las herramientas.

Construye el gráfico de código por primera vez.

Entre en el directorio raíz del repositorio que va a analizar:

1
2
3
4


git rev-parse --show-toplevel
git status --short
code-review-graph build
code-review-graph status

status debe al menos mostrar recuentos de archivos, nodos y bordes distintos de cero, y registrar ramas de compilación y confirmaciones. Si el nodo es cero, las razones comunes incluyen:

El directorio actual no es el repositorio de destino;
Git no rastrea el archivo;
El analizador no reconoce la extensión;
.code-review-graphignore excluye todo el contenido;
La construcción falló a mitad de camino.

Antes del uso formal, seleccione una función conocida para probar la consulta de estructura y confirmar que la relación de llamada puede volver al archivo real.

Actualizaciones diarias y detección de cambios

Ejecute actualizaciones incrementales después de cambios de código:

1
2


code-review-graph update
code-review-graph status

Cuando se necesitan resultados concisos e información que guarde contexto:

1
2


code-review-graph update --brief
code-review-graph detect-changes --brief

update Actualizar archivos de cambios; detect-changes analiza los cambios y el impacto actuales Git. Los dos tienen significados diferentes y no debes asumir que el gráfico está actualizado solo porque detect-changes funciona.

Para el desarrollo a largo plazo, puede utilizar:

1

code-review-graph watch

Sin embargo, en repositorios grandes se deben observar la CPU, los límites de escucha de archivos y el ruido de directorio generado; Los entornos CI generalmente son más adecuados para la ejecución explícita de build o update.

Deje que Codex o Claude Code revise PR

Después de instalar MCP y completar la composición, puedes proponer:

1
2
3


使用 code-review-graph 审查当前分支相对 main 的变化。
先检测变更，再给出跨文件影响、调用者、相关测试和测试缺口。
只读取必要上下文；所有结论附上文件路径，并与 git diff 对照。

Los proyectos también proporcionan plantillas de flujo de trabajo, como:

review_changes: Revisar los cambios actuales;
architecture_map: comprender la arquitectura;
debug_issue: solucionar problemas en las relaciones;
onboard_developer: genera contexto de introducción;
pre_merge_check: Comprobación previa a la fusión.

Ya sea que se utilicen plantillas o indicaciones gratuitas, se debe mantener el orden:

Confirme que la base de datos del gráfico esté actualizada;
Lea el Git diff real;
Consultar nodos modificados;
Ampliar las personas que llaman, las dependencias y las pruebas;
Ejecute pruebas reales;
Conclusión de la revisión manual.

Cómo interpretar el ahorro de tokens

Actualmente, CLI puede mostrar paneles para guardar contexto en detect-changes --brief y update --brief. El número predeterminado es una estimación definida por el proyecto y no es igual al Token exacto de la factura.

Para utilizar la validación cruzada del tokenizador, debe instalar dependencias adicionales y agregar --verify:

1
2


python -m pip install tiktoken
code-review-graph detect-changes --brief --verify

Registro durante la evaluación:

Diferencia sin formato y tamaño del repositorio;
La longitud del contexto devuelta por el gráfico;
El archivo que la IA realmente continúa leyendo;
Falsos negativos y falsos positivos;
La revisión lleva tiempo;
Pruebe si se encuentran problemas que no se muestran en la imagen.

No apliques el múltiplo más alto del punto de referencia oficial directamente al presupuesto del equipo. Los pequeños repositorios, las modificaciones de archivos individuales, la cobertura del análisis del lenguaje y los métodos de cuestionamiento cambian los resultados.

Qué aporta el ejemplo de GitHub Actions

El siguiente es un ejemplo de automantenimiento compilado por este sitio, no la acción GitHub publicada oficialmente por el proyecto. Solo instala CLI, restaura el caché del mapa local, realiza actualizaciones incrementales y genera informes. No aprueba automáticamente PR ni escribe los resultados en el área de comentarios.

Primero crea:

1

.github/workflows/code-review-graph.yml

Ejemplo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


name: code-review-graph

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read

jobs:
  impact:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install
        run: python -m pip install code-review-graph

      - name: Restore graph cache
        id: graph-cache
        uses: actions/cache@v4
        with:
          path: .code-review-graph
          key: crg-${{ runner.os }}-${{ github.event.pull_request.base.sha }}
          restore-keys: |
            crg-${{ runner.os }}-

      - name: Build or update graph
        shell: bash
        run: |
          if [ -d .code-review-graph ]; then
            code-review-graph update --brief
          else
            code-review-graph build
          fi
          code-review-graph status

      - name: Analyze changes
        run: code-review-graph detect-changes --brief | tee crg-review.txt

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: code-review-graph-report
          path: crg-review.txt
          if-no-files-found: warn

Al habilitarlo por primera vez, se recomienda eliminar el paso de caché, confirmar que la compilación limpia se realizó correctamente y luego agregar el caché. El almacenamiento en caché no es una fuente de corrección; se debe permitir una reconstrucción completa después de cambios en el analizador, el esquema o la estructura del proyecto.

Clave de caché y actualización del gráfico

El ejemplo envía la línea base PR a la clave de caché para reducir la probabilidad de reutilizar directamente imágenes antiguas entre diferentes líneas base. También puede agregar un resumen del archivo de bloqueo de dependencia:

1

key: crg-${{ runner.os }}-${{ hashFiles('pyproject.toml', 'package-lock.json') }}-${{ github.event.pull_request.base.sha }}

La caché debe eliminarse y reiniciarse en los siguientes casos build:

Actualizar code-review-graph o Tree-sitter analizador;
Modificar las reglas de exclusión;
Cambio de nombre de directorio masivo;
Disminución anormal de las estadísticas gráficas;
Los resultados locales y CI no se pueden reproducir;
Cambios de compatibilidad de esquema o base de datos.

El acierto de caché de aceptación no solo debe verificar la visualización de Acciones cache-hit, sino también verificar las ramas, confirmaciones, cantidad de archivos, cantidad de nodos y cantidad de bordes de status.

Límites de permiso para Fork PR

El análisis principal solo necesita leer el código fuente extraído. No requiere permisos de escritura en el repositorio ni debe usar secretos de despliegue. Mantenga estos permisos:

1
2


permissions:
  contents: read

No utilice pull_request_target en código Fork no revisado para ejecutar comandos después de revisar el encabezado PR; esta combinación puede exponer los permisos del repositorio subyacente o Secret.

Si los comentarios se van a publicar automáticamente en el futuro, se deben dividir en pasos controlados independientes y se deben revisar el contenido, los permisos y las fuentes del informe. La primera versión, más segura, solo carga artefactos para que los encargados de mantenimiento los revisen.

Monorepo y grandes cambios

.code-review-graphignore se puede utilizar en un monorepo para excluir directorios de compilación y proveedores que explícitamente no están sujetos a revisión. No excluya las bibliotecas compartidas por motivos de velocidad; de lo contrario, el análisis perderá las relaciones entre paquetes.

Las diferencias muy grandes primero deberían obtener una lista de archivos:

1

git diff --name-only origin/main...HEAD

Si la detección automática de MCP no responde durante mucho tiempo, puede pasar una lista clara de archivos modificados a la herramienta de análisis de impacto para evitar la ejecución repetida de la detección de Git con un alcance excesivo en el backend.

El proyecto también proporciona variables de entorno de límites para limitar frentes muy grandes, como CRG_MAX_CHANGED_FUNCS, CRG_MAX_TRANSITIVE_FRONTIER y CRG_TOOL_TIMEOUT. Registre el comportamiento predeterminado antes de realizar ajustes. Los límites demasiado bajos reducirán los retiros.

Solucionar fallos de conexión y bloqueos de MCP en Windows

CLI es normal pero MCP informa Invalid JSON: EOF while parsing o Connection closed:

Actualice code-review-graph;
Ejecute install nuevamente para actualizar la configuración;
Confirme que la versión FastMCP cumple con los requisitos actuales del proyecto;
Deje que MCP ejecute directamente .exe en el entorno virtual;
Configure PYTHONUTF8=1;
Reinicie el cliente y vea el registro MCP.

Configuración esquemática:

1
2
3
4
5
6
7


{
  "code-review-graph": {
    "command": "C:\\path\\to\\venv\\Scripts\\code-review-graph.exe",
    "args": ["serve", "--repo", "C:\\path\\to\\project"],
    "env": {"PYTHONUTF8": "1"}
  }
}

CLI status y detect-changes son muy rápidos, pero cuando la llamada de MCP se agota, el resultado de git diff --name-only primero se pasa explícitamente a la herramienta para distinguir entre la detección de cambios lentos de Git y la consulta de gráfico lento.

Cómo recuperarse cuando los datos del gráfico son incorrectos

Graba la escena primero:

1
2
3


code-review-graph status
git rev-parse HEAD
git status --short

Luego realice una actualización incremental:

1
2


code-review-graph update
code-review-graph status

Si el resultado sigue siendo incorrecto, haga una copia de seguridad o elimine el directorio reconstruible .code-review-graph y ejecute una compilación completa. Antes de borrarlo, confirme que esté dentro del repositorio previsto para no eliminar otros datos por error.

Esto también debería volverse a ejecutar después de la actualización:

1
2
3


python -m pip install -U code-review-graph
code-review-graph install
code-review-graph build

install se usa para actualizar la configuración de la plataforma y build se usa para actualizar los datos del gráfico. No confundas los dos pasos.

Desinstalar y revertir

Vista previa primero:

1

code-review-graph uninstall --dry-run

Desinstalar después de la confirmación:

1

code-review-graph uninstall

Solo elimina la integración y conserva los datos del gráfico:

1

code-review-graph uninstall --keep-data

Luego verifique si quedan elementos MCP en Codex, Claude Code y otras configuraciones, y confirme que se puede restaurar la copia de seguridad de la configuración original.

Lista de verificación de aceptación final

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


[ ] Python 版本至少为 3.10
[ ] CLI --help 和 status 可运行
[ ] build 后文件、节点和边数量非零
[ ] .code-review-graph 已加入忽略策略
[ ] Codex 或 Claude Code 能列出 MCP 工具
[ ] update 后图对应当前分支与提交
[ ] detect-changes 结果能回到真实 Git diff
[ ] 影响范围和测试缺口经过人工核对
[ ] Token 节省区分估算与 --verify 结果
[ ] CI 仅有 contents: read 权限
[ ] Fork PR 不接触 Secret
[ ] 缓存失效时可以完整重建
[ ] 卸载和恢复步骤已验证

Resumen

code-review-graph funciona como índice estructural para la revisión de código asistida por IA, no como aprobador automático. Un flujo fiable consiste en construir el grafo en el repositorio correcto, mantenerlo actualizado de forma incremental, obtener por MCP solo el contexto necesario y confirmar las conclusiones con Git diff, pruebas y revisión humana.

Al acceder a GitHub Actions, primero debe asegurarse de que la compilación limpia sea reproducible y luego agregar gradualmente caché y artefactos. Los permisos siguen siendo de solo lectura, Fork PR no usa Secret y poder recurrir a una diferencia normal y una reconstrucción completa cuando falla el gráfico es más importante que buscar los mayores ahorros de Token en un único punto de referencia.