También en: English, Português, 日本語, Deutsch, Français · Todas las guías en español
Aviso: construimos Carbon Forge en 100monkeys.ai, así que lee esto como el relato de quien lo fabrica. Esta guía la redactó uno de nuestros agentes de IA a partir de la documentación pública (en inglés), sobre todo las secciones symbols.drift y Governed seams de MCP tools catalog: Semantics y "Drift between prose and code" de The Carbon paradigm, y la revisó la empresa; esta versión en español es una traducción de la guía original en inglés. La tabla y las llamadas son los ejemplos de la propia documentación. Donde la documentación deja una pregunta abierta, la última sección lo dice.
Qué es el informe
La página del paradigma, en una línea: "A workspace's reserved .governed-seams page declares which pages govern which definitions of a code tree" (la página reservada .governed-seams de un espacio de trabajo declara qué páginas gobiernan qué definiciones de un árbol de código). symbols.drift "joins every definition a lane adds, removes or re-signs to the seams that govern it and reports each as changed with or without a patch to its governing page on the same lane, from the syntax index alone, so the same lane and the same seams page answer the same report byte for byte." (cruza cada definición que una lane añade, elimina o cambia de firma con los seams que la gobiernan, e informa de cada una como cambiada con o sin un parche a su página gobernante en la misma lane, solo a partir del índice sintáctico, de modo que la misma lane y la misma página de seams dan el mismo informe byte a byte). Ningún modelo lee nada. Y un límite que conviene tener presente: "The report advises and never refuses a landing." (El informe aconseja y nunca rechaza una integración).
Paso 1. Elige las definiciones que describe una página
Empieza por las páginas que engañarían a quien las lea si el código se moviera debajo de ellas: una página de arquitectura de facturación, una guía de inicio de sesión. Encuentra las definiciones que describen con el índice semántico:
symbols.search { "tree": "app", "query": "charge", "prefix": true }Las definiciones salen de las consultas de etiquetas de tree-sitter para TypeScript y TSX, JavaScript, Python, Go, Rust, C, C++, C#, Java, Ruby, PHP, Scala y Bash. CSS, HTML, JSON, YAML, TOML y HCL tienen árboles sintácticos "but no definitions or references" (pero ni definiciones ni referencias), así que un seam sobre esos archivos no informa de nada. Los nombres se emparejan "matched by name, not by type checking" (por nombre, sin comprobación de tipos).
Paso 2. Escribe la página .governed-seams
Crea una página en la ruta reservada .governed-seams cuya primera tabla Markdown tenga como cabecera tree | glob | symbols | records. El ejemplo de la documentación:
| tree | glob | symbols | records |
| --- | --- | --- | --- |
| app | src/billing/** | chargeCard, refund | architecture/billing |
| app | src/auth/*.ts | * | guides/login, architecture/security |tree: la ruta de un árbol de código.glob: una regla con la sintaxis de reglas de exclusión de la importación sobre las rutas de archivo del árbol, sin empezar por!.symbols: nombres de definiciones separados por comas, o*solo para todas las definiciones bajo el glob.records: rutas de página separadas por comas, las páginas que gobiernan esas definiciones.
"A seam is declared, never inferred: no link, tag, metadata key or embedding makes one." (Un seam se declara, nunca se infiere: ningún enlace, etiqueta, clave de metadatos ni embedding crea uno). La página se lee del trunk, "so a lane cannot ungovern its own change" (así que una lane no puede dejar de gobernar su propio cambio). Intégrala en el trunk antes del trabajo que debe vigilar. Una página mal formada detiene todos los informes hasta que se corrige, con una frase que nombra la línea: The governed seams page .governed-seams is malformed at line <n>, ...
Paso 3. Cambia código gobernado en una lane
El informe lee una lane, así que el cambio tiene que estar en una: lanes.create y después trees.apply_patch o trees.put con lane, como muestra Working in lanes. Cambia la firma de chargeCard, por ejemplo, añadiendo un parámetro.
Paso 4. Lee el informe de deriva
symbols.drift { "lane": "agent/7/fix-login" }Añade tree para leer un solo árbol. La respuesta:
{ lane, composition_hash, report_sha256, findings, pending, governed_rows }Cada hallazgo indica el tree, path, symbol y kind, la from_signature en el trunk y la to_signature en la lane (null cuando un lado no la tiene), records como { path, updated_on_lane }, y callers, el número de referencias al nombre en la lane. El class es el veredicto: seam_changed_without_record cuando la lane no tiene ningún parche vivo en una página gobernante. Esa es tu documentación obsoleta, detectada antes de la integración.
Lee pending antes de fiarte de un informe vacío: enumera los archivos cambiados bajo el glob de un seam que el índice "cannot answer yet" (aún no puede responder), y "the report is complete when pending is empty" (el informe está completo cuando pending está vacío). Una lane en conflicto se rechaza hasta que se resuelve el conflicto.
Paso 5. Actualiza la página que gobierna en la misma lane
Edita architecture/billing con pages.apply_patch y la misma lane, para que la página y el código esperen juntos. La guía Integra un cambio de código y su documentación en un solo changeset recorre esa parte.
Paso 6. Vuelve a leer el informe y después integra
Ejecuta symbols.drift otra vez. El hallazgo dice ahora seam_changed_with_record, y su registro muestra updated_on_lane. Guarda el informe junto con la revisión de código: composition_hash es el hash de la composición de la lane que leyó, y report_sha256 cubre el texto canónico del informe, "so a report is bound to the exact change it read" (así que un informe queda ligado al cambio exacto que leyó). Un parche posterior cambia ambos. Después integra la lane como un solo changeset.
Como el informe solo aconseja, la obligación la añades tú. Un patrón, nuestro y no de la documentación: en un trunk protegido, nombra el glob del código gobernado en .landing-rules con el responsable de la página gobernante como aprobador, y pide a ese aprobador que lea antes el informe de deriva.
Lo que la documentación deja sin responder
- Quién puede escribir
.governed-seams. La documentación hace.landing-rulesexclusiva de administradores; de la página de seams solo dice que se lee del trunk "whoever wrote it" (la haya escrito quien la haya escrito). - Una vista en la aplicación. La documentación describe la herramienta y su respuesta, no una página en el navegador que muestre el informe.
- Markdown "not parsed yet" (aún no se analiza), así que una página no puede ser ella misma el lado gobernado.