Também em: English, Español, 日本語, Deutsch, Français · Todos os guias em português
Aviso: desenvolvemos o Carbon Forge na 100monkeys.ai, então leia isto como o relato de quem o fabrica. Este guia foi redigido por um dos nossos agentes de IA a partir da documentação pública (em inglês), sobretudo as seções symbols.drift e Governed seams de MCP tools catalog: Semantics e "Drift between prose and code" de The Carbon paradigm, e revisado pela empresa; esta versão em português é uma tradução do guia original em inglês. A tabela e as chamadas são os exemplos da própria documentação. Onde a documentação deixa uma pergunta em aberto, a última seção diz isso.
O que é o relatório
A página do paradigma, em uma linha: "A workspace's reserved .governed-seams page declares which pages govern which definitions of a code tree" (a página reservada .governed-seams de um workspace declara quais páginas governam quais definições de uma árvore 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 definição que uma lane adiciona, remove ou muda de assinatura com os seams que a governam e informa cada uma como alterada com ou sem um patch na sua página governante na mesma lane, só a partir do índice sintático, de modo que a mesma lane e a mesma página de seams dão o mesmo relatório byte a byte). Nenhum modelo lê nada. E um limite para guardar: "The report advises and never refuses a landing." (O relatório aconselha e nunca recusa uma integração.)
Passo 1. Escolha as definições que uma página descreve
Comece pelas páginas que enganariam quem as lê se o código mudasse por baixo delas: uma página de arquitetura de cobrança, um guia de login. Encontre as definições que elas descrevem com o índice semântico:
symbols.search { "tree": "app", "query": "charge", "prefix": true }As definições vêm das consultas de tags do tree-sitter para TypeScript e TSX, JavaScript, Python, Go, Rust, C, C++, C#, Java, Ruby, PHP, Scala e Bash. CSS, HTML, JSON, YAML, TOML e HCL têm árvores sintáticas "but no definitions or references" (mas nem definições nem referências), então um seam sobre esses arquivos não informa nada. Os nomes são "matched by name, not by type checking" (casados pelo nome, sem checagem de tipos).
Passo 2. Escreva a página .governed-seams
Crie uma página no caminho reservado .governed-seams cuja primeira tabela Markdown tenha o cabeçalho tree | glob | symbols | records. O exemplo da documentação:
| tree | glob | symbols | records |
| --- | --- | --- | --- |
| app | src/billing/** | chargeCard, refund | architecture/billing |
| app | src/auth/*.ts | * | guides/login, architecture/security |tree: o caminho de uma árvore de código.glob: uma regra na sintaxe de regras de exclusão da importação sobre os caminhos de arquivo da árvore, sem começar com!.symbols: nomes de definições separados por vírgula, ou*sozinho para todas as definições sob o glob.records: caminhos de página separados por vírgula, as páginas que governam essas definições.
"A seam is declared, never inferred: no link, tag, metadata key or embedding makes one." (Um seam é declarado, nunca inferido: nenhum link, tag, chave de metadados ou embedding cria um.) A página é lida do trunk, "so a lane cannot ungovern its own change" (então uma lane não consegue deixar de governar a própria mudança). Integre-a no trunk antes do trabalho que ela deve vigiar. Uma página malformada interrompe todos os relatórios até ser corrigida, com uma frase que aponta a linha: The governed seams page .governed-seams is malformed at line <n>, ...
Passo 3. Altere código governado numa lane
O relatório lê uma lane, então a mudança precisa estar numa: lanes.create, depois trees.apply_patch ou trees.put com lane, como mostra Working in lanes. Mude a assinatura de chargeCard, por exemplo, acrescentando um parâmetro.
Passo 4. Leia o relatório de deriva
symbols.drift { "lane": "agent/7/fix-login" }Acrescente tree para ler uma árvore só. A resposta:
{ lane, composition_hash, report_sha256, findings, pending, governed_rows }Cada achado indica tree, path, symbol e kind, a from_signature no trunk e a to_signature na lane (null quando um lado não a tem), records como { path, updated_on_lane }, e callers, a contagem de referências ao nome na lane. O class é o veredito: seam_changed_without_record quando a lane não tem nenhum patch vivo numa página governante. Essa é a sua documentação desatualizada, pega antes da integração.
Leia pending antes de confiar num relatório vazio: ele lista os arquivos alterados sob o glob de um seam que o índice "cannot answer yet" (ainda não consegue responder), e "the report is complete when pending is empty" (o relatório está completo quando pending está vazio). Uma lane em conflito é recusada até o conflito ser resolvido.
Passo 5. Atualize a página que governa na mesma lane
Edite architecture/billing com pages.apply_patch e a mesma lane, para que a página e o código esperem juntos. O guia Integre uma mudança de código e a sua documentação num único changeset percorre essa parte.
Passo 6. Leia o relatório de novo e depois integre
Rode symbols.drift de novo. O achado agora diz seam_changed_with_record, e o registro dele mostra updated_on_lane. Guarde o relatório junto com a revisão de código: composition_hash é o hash da composição da lane que ele leu, e report_sha256 cobre o texto canônico do relatório, "so a report is bound to the exact change it read" (então um relatório fica vinculado à mudança exata que leu). Um patch posterior muda os dois. Depois integre a lane como um único changeset.
Como o relatório só aconselha, a obrigatoriedade fica por sua conta. Um padrão, nosso e não da documentação: num trunk protegido, nomeie o glob do código governado em .landing-rules com o responsável pela página governante como aprovador, e peça que esse aprovador leia antes o relatório de deriva.
O que a documentação deixa sem resposta
- Quem pode escrever
.governed-seams. A documentação torna.landing-rulesexclusiva de administradores; da página de seams diz apenas que é lida do trunk "whoever wrote it" (seja quem for que a escreveu). - Uma visualização no aplicativo. A documentação descreve a ferramenta e a resposta dela, não uma página no navegador que mostre o relatório.
- Markdown "not parsed yet" (ainda não é analisado), então uma página não pode ser ela mesma o lado governado.