Antes de que un agente cambie tu código, Rationale le entrega las reglas, decisiones y relaciones que gobiernan ese código. Después del cambio, lo que sigue siendo cierto vuelve a tu repositorio de forma automática, y las reglas que fijas quedan fuera del alcance de cualquier agente.
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Ragosorio/Rationale/releases/latest/download/rationale-installer.sh | sh
Funciona en la conversación del lunes. El jueves, un agente nuevo solo ve el código, quita la guarda y lo llama limpieza.
“Nunca reintentes un pago que ya llegó al banco.”
Rationale mantiene la regla junto al código que gobierna y se la entrega a cada agente antes de que toque ese código.
No hay cola de aprobación. Los agentes capturan lo que aprenden; tú conservas la autoridad sobre lo que no debe moverse.
Encuentra el símbolo, sus callers y los archivos alrededor.
prepare_changeReglas gobernantes, relaciones explicadas, la vecindad estructural y el código del target, dentro de un techo de tokens.
El cambio mínimo coherente con ese contexto.
finalize_changeEl conocimiento durable se vuelve Records canónicos en la misma llamada. El ruido y los duplicados se descartan con motivo.
rationale pinFija las reglas que ningún agente puede reemplazar. Cualquier intento se vuelve un conflicto que solo tú resuelves.
Se instala una vez por máquina y se inicializa una vez por repositorio; después sigues trabajando como ya lo haces. Actualizar o desinstalar nunca toca .rationale/.
1Instala Codebase Memory (recomendado)
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
2Instala Rationale en macOS o Linux
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Ragosorio/Rationale/releases/latest/download/rationale-installer.sh | sh
El instalador verifica checksums, usa el canal estable y registra el servidor MCP en los agentes que encuentra.
3Inicializa tu repositorio
rationale init
Crea el canon en .rationale/ y escribe el protocolo en CLAUDE.md, AGENTS.md o la regla de Cursor.
4Reinicia tu agente y comprueba la conexión
En Claude Code ejecuta /rationale-health. En Codex pide «Comprueba la salud de Rationale».
5Pide un cambio real
“Haz que los reintentos de pago se detengan después de tres intentos.”
No necesitas mencionar Rationale. El agente prepara el cambio, lo hace y captura lo que sigue siendo cierto.
6Míralo en vivo y fija lo que no debe moverse
rationale ui
rationale pin <record-id>
En Windows, el instalador de PowerShell está en la guía rápida.
El protocolo en CLAUDE.md y AGENTS.md le dice al agente que prepare y capture. El skill rationale le muestra cómo. Un router corto carga solo el playbook de la operación en curso, así que esa profundidad no cuesta nada hasta que una tarea la necesita.
/rationale capture o $rationale explain <target> lo llaman por nombre.finalize_change.| Operación | Cuándo la usa el agente |
|---|---|
preflight | Antes de cambiar, mover o borrar código no trivial |
explain | Cuando el código parece redundante o raro, o preguntas por qué existe |
capture | Cuando un cambio está hecho y probado |
conflicts | Cuando un candidato choca con una regla fijada |
health | Cuando faltan herramientas o los resultados se ven degradados |
adopt | Al configurar Rationale y sembrar los primeros Records |
maintain | Cuando los bindings quedan obsoletos o rationale doctor reporta hallazgos |
Para cualquier otro agente que lea skills
npx skills add Ragosorio/Rationale
rationale init e install-agent ya lo instalan para Claude Code y Codex.
Un packet acotado, compilado para un target y una intención. El conocimiento gobernante nunca se recorta, y el presupuesto es un techo, no una meta.
{ "operation_id": "op_7f3c…", "critical_constraints": [{ "id": "constraint.payments-idempotent", "authority": "pinned", "provenance": "human_stated" }], "decisions": [{ "id": "decision.charge-after-reservation", "authority": "normal", "provenance": "agent_asserted" }], "relationships": [ { "edge": "charge → bank_client", "state": "observed" }, { "edge": "retry_worker → charge", "state": "indirect" } ], "structure": { "nodes": "12 / 52", "edges": "11 / 51" }, "estimated_tokens": 1707, // ≤ 2400 "known_unknowns": ["refunds → charge: orphaned"] }
Cada panel muestra una llamada y una respuesta abreviada. Cambia de panel con las flechas; donde hay pasos, recórrelos.
Ejemplo simulado. Un proyecto de envíos inventado para la evaluación de Rationale, ejecutado con el binario de desarrollo. Sin datos de clientes; ninguna cifra aquí es un resultado de un cliente.
El lunes un agente aprendió que una cancelación debe esperar al transportista y lo capturó. El jueves, una sesión nueva recibe el pedido de cancelar localmente cuando el transportista no responde.
Recibe la decisión del lunes con su motivo, atada a la función exacta, y debe pronunciarse antes de editar.
prepare_change(target="src/shipping/service.ts::cancelShipment", intent="Allow cancelling locally when the carrier API is down") { "retrieval": { "status": "found", "scope": "symbol" }, "decisions": [{ "id": "decision.cancel-requires-carrier-ack", "statement": "A shipment is cancelled only after the carrier acknowledges the cancellation.", "rationale": "Cancelling locally … left paid labels in transit with no record.", "provenance": "agent_asserted", "why": "bound to this symbol" }], "intent_conflicts": [{ "record_id": "decision.cancel-requires-carrier-ack", "detection": "governs-target" }], "governance_verdict_required": true }
La caché de cotizaciones guardaba precios cinco minutos; una decisión posterior la bajó a sesenta segundos.
La regla de cinco minutos es historia, con su reemplazo nombrado. Nunca se sirve como vigente junto a la regla que la reemplazó.
explain_target(target="src/shipping/rates.ts::quoteRate") { "governing_records": [{ "id": "decision.rate-cache-ttl-60s", "statement": "Carrier rate quotes are cached for 60 seconds per route and weight.", "replaces": ["decision.rate-cache-ttl-5m"] }], "history": [{ "id": "decision.rate-cache-ttl-5m", "status": "superseded", "replaced_by": "decision.rate-cache-ttl-60s" }] }
explain_target(target="src/shipping/rates.ts::quoteRate", include_history=true) { "history": [{ "id": "decision.rate-cache-ttl-5m", "status": "superseded", "statement": "Carrier rate quotes are cached for 5 minutes per route and weight.", "rationale": "Carrier APIs rate-limit quote calls; five minutes kept us under the limit at launch." }] }
Tras un incidente, una persona fijó «el dinero son centavos enteros» en el helper de envíos. Facturación nunca la ató, pero llama a ese helper.
El invariante fijado llega como restricción heredada, con la llamada observada que lo trae. La similitud nunca trae una.
prepare_change(target="src/billing/invoice.ts::issueInvoice", intent="Sum invoice lines as floats and round once at the end") { "decisions": [{ "id": "decision.invoice-rounding-bankers", "why": "bound to this symbol" }], "inherited_constraints": [{ "id": "constraint.money-in-integer-cents", "statement": "Monetary amounts are integers in cents from quote to invoice; never store, sum or compare floating-point currency.", "authority": "pinned", "provenance": "human_stated", "severity": "critical", "via": "issueInvoice calls toCents" }] }
Un presupuesto chico deja fuera la estructura; el packet dice qué quedó fuera y cómo recuperarlo.
El conocimiento que gobierna nunca se recorta. Lo que no cupo queda listado, con la llamada que lo devuelve.
prepare_change(target="src/shipping/service.ts::cancelShipment", max_tokens=800) { "decisions": [{ "id": "decision.cancel-requires-carrier-ack", … }], "omitted": [{ "section": "structure", "count": 1, "expand": "raise max_tokens" }], "budget": { "max_tokens": 800, "estimated_tokens": 754, "estimator": "upper-bound" } }
prepare_change(target="src/shipping/service.ts::cancelShipment", max_tokens=2400) { "decisions": [{ "id": "decision.cancel-requires-carrier-ack", … }], "structure": { "nodes": ["cancelShipment", …], "considered_nodes": 4 }, "relevant_code": { "file_path": "src/shipping/service.ts", "start_line": 10, … }, "budget": { "max_tokens": 2400, "estimated_tokens": 1037, "estimator": "upper-bound" } }
Un agente prepara un cambio, explora y decide no hacerlo.
El hook Stop de Claude Code pregunta una vez; el agente cierra la operación sin memoria y sin declarar un cambio.
prepare_change(target="src/shipping/rates.ts::applySurcharge", intent="Make the remote surcharge a percentage") { "operation_id": "op_1a13b671…", "packet": { … } }
Stop hook → el agente intenta terminar sin cerrar { "decision": "block", "reason": "Rationale: this session prepared 1 change(s) that are still open: op_1a13b671… If you did not change the code, call finalize_change(operation_id, abandon=true, summary=\"why\"). Do not finalize as done a change that did not happen." }
finalize_change(operation_id="op_1a13b671…", abandon=true, summary="Only explored; the surcharge stays flat.") { "state": "abandoned", "memory_written": false }
Llega en la versión posterior a v1.1.0. Con v1.1.0 hoy, preparar y capturar funcionan como se describe en el ciclo de arriba.Qué cambia y la evidencia
rationale ui abre un Control Room local y de solo lectura: el subgrafo de trabajo en 3D, la memoria que lo explica y la actividad de cada sesión mientras llega.
Solo en 127.0.0.1, solo peticiones GET, embebido en el binario.Docs del Control Room
Cada Record lleva de dónde viene y cuánto se puede mover. El gate de captura hace cumplir esa frontera.
provenancepinnedconflictsComandos solo humanos: exigen una terminal interactiva y autoridad declarada.
Un Record puede explicar una relación. En cada llamada Rationale vuelve a derivar su estado desde el proveedor, y nunca borra la explicación.
| Estado | Arista | Qué significa |
|---|---|---|
observed | La relación directa existe en el índice actual. | |
indirect | Ya no es directa, pero un camino acotado sigue conectando los extremos. | |
orphaned | No se puede localizar. La explicación puede estar obsoleta: se señala y nunca se borra. | |
unknown | El proveedor no pudo verificarla. La ausencia no es prueba. |
Los agentes solo llegan al canon a través del gate de captura, y el Control Room solo lee. Es el cableado real del binario, dibujado desde su propio grafo de llamadas.
El instalador registra un servidor MCP por agente con su ruta absoluta; install-agent escribe el protocolo en tu proyecto. Retíralo todo con uninstall-agent.
Claude Code
/rationale [operation]/rationale-preflight <target> <intent>/rationale-explain <target>/rationale-capture [statement]/rationale-conflicts/rationale-healthEl agente elige el skill por su cuenta; los atajos son para ti. /rationale-conflicts te deja la decisión a ti.
Codex
<target> con intención <intent>.”<target> antes de modificarlo.”Codex lee el protocolo en AGENTS.md, llama las herramientas MCP y carga el skill desde .agents/skills/. $rationale lo llama por nombre.
Cursor
Cursor recibe .cursor/rules/rationale.mdc en el proyecto y un servidor MCP por usuario que funciona desde el Dock.
.rationale/ es YAML plano, revisado en el mismo pull request que el código.5 herramientas MCP · 6 prompts MCP · 1 skill con 7 operaciones · 3 agentes soportados · 5 plataformas · sin cuentas ni telemetría
El ciclo completo está implementado, probado y en uso sobre el propio repositorio de Rationale desde 1.0, y 1.1 agrega el skill rationale.