他の言語: English, Español, Português, Deutsch, Français · 日本語のガイド一覧
開示: Carbon Forge は 100monkeys.ai が開発しているため、これは作り手による説明として読んでください。このガイドは公開ドキュメント(英語)、主に MCP tools catalog: Semantics の symbols.drift と Governed seams の節、および The Carbon paradigm の "Drift between prose and code" をもとに当社の AI エージェントが下書きし、当社がレビューしました。この日本語版は英語の原文ガイドの翻訳です。表と呼び出しはドキュメント自身の例です。ドキュメントが答えていない点は、最後の節に書いています。
レポートとは何か
パラダイムのページは一行でこう述べます: "A workspace's reserved .governed-seams page declares which pages govern which definitions of a code tree"(ワークスペースの予約ページ .governed-seams が、どのページがコードツリーのどの定義を管理するかを宣言する)。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."(レーンが追加・削除・シグネチャ変更したすべての定義を、それを管理する seam と突き合わせ、同じレーン上で管理ページへのパッチを伴うかどうかを構文インデックスだけから報告する。そのため同じレーンと同じ seams ページからは、バイト単位で同じレポートが得られる)。モデルは何も読みません。そして覚えておくべき制限が一つあります: "The report advises and never refuses a landing."(レポートは助言するだけで、ランディングを拒否することはない)。
ステップ 1. ページが説明する定義を選ぶ
コードがその下で変わったときに読者を誤らせるページから始めます。たとえば課金のアーキテクチャのページや、サインインのガイドです。それらが説明する定義を、セマンティックインデックスで探します:
symbols.search { "tree": "app", "query": "charge", "prefix": true }定義は、TypeScript と TSX、JavaScript、Python、Go、Rust、C、C++、C#、Java、Ruby、PHP、Scala、Bash に対する tree-sitter のタグクエリから得られます。CSS、HTML、JSON、YAML、TOML、HCL は構文木を持ちますが "but no definitions or references"(定義も参照もない)ため、これらのファイルにかかる seam は何も報告しません。名前は "matched by name, not by type checking"(型検査ではなく名前で照合)されます。
ステップ 2. .governed-seams ページを書く
予約パス .governed-seams にページを作り、最初の Markdown の表の見出しを tree | glob | symbols | records にします。ドキュメントの例:
| tree | glob | symbols | records |
| --- | --- | --- | --- |
| app | src/billing/** | chargeCard, refund | architecture/billing |
| app | src/auth/*.ts | * | guides/login, architecture/security |tree: コードツリーのパス。glob: ツリーのファイルパスに対する、インポートの除外ルール構文による一つのルール。!で始めない。symbols: カンマ区切りの定義名。glob 配下のすべての定義なら*だけ。records: カンマ区切りのページパス。それらの定義を管理するページ。
"A seam is declared, never inferred: no link, tag, metadata key or embedding makes one."(seam は宣言されるもので、推測されることはない。リンク、タグ、メタデータのキー、埋め込みのどれも seam を作らない)。このページはトランクから読まれるので、"so a lane cannot ungovern its own change"(レーンが自分の変更を管理対象から外すことはできない)。見張らせたい作業より先に、トランクにランディングしておきます。書式の誤ったページは、行を示す文とともに、直るまですべてのレポートを止めます: The governed seams page .governed-seams is malformed at line <n>, ...
ステップ 3. 管理対象のコードをレーン上で変更する
レポートはレーンを読むので、変更はレーン上になければなりません。Working in lanes にあるとおり、lanes.create の後に lane を付けて trees.apply_patch か trees.put を呼びます。たとえば chargeCard に引数を一つ足して、シグネチャを変えます。
ステップ 4. ドリフトレポートを読む
symbols.drift { "lane": "agent/7/fix-login" }一つのツリーだけを読むには tree を加えます。返ってくる形:
{ lane, composition_hash, report_sha256, findings, pending, governed_rows }各 finding は tree、path、symbol、kind、トランク上の from_signature とレーン上の to_signature(その側に存在しなければ null)、{ path, updated_on_lane } の形の records、そしてレーン上でその名前を参照している数 callers を示します。class が判定です。レーンが管理ページに有効なパッチを持たないとき seam_changed_without_record になります。これが、ランディング前に見つかった古いドキュメントです。
空のレポートを信頼する前に pending を読んでください。seam の glob 配下で変更されたファイルのうち、インデックスが "cannot answer yet"(まだ答えられない)ものを一覧します。"the report is complete when pending is empty"(pending が空のときレポートは完全)です。コンフリクトのあるレーンは、解消されるまで拒否されます。
ステップ 5. 同じレーンで管理側のページを更新する
同じ lane を付けて pages.apply_patch で architecture/billing を編集し、ページとコードを一緒に待たせます。この部分はガイド コードの変更とそのドキュメントを 1 つのチェンジセットでランディングするで説明しています。
ステップ 6. レポートをもう一度読み、ランディングする
symbols.drift をもう一度実行します。finding は seam_changed_with_record になり、その record は updated_on_lane を示します。レポートはレビューと一緒に保管します。composition_hash は読んだレーン構成のハッシュで、report_sha256 はレポートの正規テキストを対象とし、"so a report is bound to the exact change it read"(レポートは読んだ変更そのものに結びつく)。後からパッチを加えると両方が変わります。その後、レーンを一つの changeset としてランディングします。
レポートは助言するだけなので、強制はあなたが加えるものです。ドキュメントではなく私たちのやり方を一つ挙げます。保護されたトランクで、管理対象コードの glob を .landing-rules に書き、管理ページの担当者を承認者に指定し、その承認者に先にドリフトレポートを読んでもらいます。
ドキュメントが答えていないこと
- 誰が
.governed-seamsを書けるか。ドキュメントは.landing-rulesを管理者専用としていますが、seams ページについては、トランクから "whoever wrote it"(誰が書いたかにかかわらず)読まれるとしか書いていません。 - アプリ内の表示。ドキュメントはツールとその応答を説明していますが、レポートを表示するブラウザ上のページについては説明していません。
- Markdown は "not parsed yet"(まだ解析されない)ため、ページ自体を管理される側にすることはできません。