ナレッジ

ナレッジタブ: プロジェクトのすべてのメモリが、対象となる C4 要素の周りに集まっている

ナレッジタブは、プロジェクトの共有メモリを 1 つのマップとして表示します。メモリとは、コードからは読み取れない情報です。誰かが本番環境で踏んだ落とし穴、チームで合意した規約、エージェントが作業セッションの終わりに残したメモなどがこれにあたります。人はアプリから書き込み、エージェントは harness (remember、finish_work_session) を通じて書き込みます。どちらも同じ場所に保存され、システムの同じ部分に触れる次のエージェントに提供されます。

プロジェクトのヘッダー (ナレッジ)、コマンドパレット、または共有されたリンクから開けます。

マップの見方

  • 要素はリングです。ナレッジの対象となる C4 のシステム、コンテナ、コンポーネントを表します。各メモリは、紐付けられた要素の周りに配置されます。
  • メモリは点で、種類ごとに色分けされます: 落とし穴、規約、メモ。内側に明るいリングがある点は人が書いたもので、それ以外はエージェントによるものです。
  • 決定 (ADR) は四角形で、メモリが [[ADR-12]] のようにリンクしたときに表示されます。
  • 破線のゴーストは、まだ誰も書いていないリンクです。あるメモリが [[Rate limits]] に言及しているのに、そのタイトルのメモリが存在しない状態です。クリックするとそのメモリを書けます。

マップはメモリが数千件あっても読みやすさを保ちます。同じ事実を述べるメモリは 1 つの点にまとめられ、3 つのコピーが同じ内容なら ×3 と表示されます。セッション結果はデフォルトで非表示になっており、その要素の上で件数として数えられます。ツールバーのセッションボタンで表示を切り替えられます。種類の凡例はフィルターとしても機能し、下部のタイムラインでナレッジが蓄積されていく様子を再生できます。

点をクリックすると、リンクとバックリンクを含めてメモリ全体を読めます。要素をクリックすると、その要素に紐付けられたすべてを確認し、次のメモリを書けます。

キーボード: / で検索、N でメモリを書く、F でマップ全体を表示、Esc で 1 つ戻ります。

質問する

プロジェクトのメモリだけから書かれた回答。根拠となったメモリがマップ上でハイライトされている

検索ボックスに質問を入力し、質問を押します (疑問符の後に Enter でも可)。回答はプロジェクトのメモリだけから書かれ、エージェントと同じ検索が使われます: 単語と意味、さらに上位の結果にリンクされたメモリです。各主張には出典が番号で示されます。番号をクリックするとマップ上でそのメモリが見つかり、引用されたメモリがハイライトされます。

その話題についてメモリに何もない場合、回答は推測せずにそう伝えます。そのときこそ事実を書き残すタイミングです。次の人と次のエージェントがそれを見つけられます。AI プロバイダーが利用できない場合は、回答の代わりに最も近いメモリが表示されます。質問はエージェントへのメモリ提供としてカウントされないため、後述の利用状況の数値に影響しません。

回答には、他の harness 機能と同様に、組織の AI プロバイダーが使われます。

矛盾

プロジェクトがすでに持つ事実と食い違う事実を書いているところ

同じ要素についての既存メモリとほぼ同じ内容なのに異なる数値を述べるメモリ (「8 回リトライ」と「3 回リトライ」など) を書くと、Archyl はダイアログを閉じる前に止まり、両方を表示します。矛盾する 2 つの有効なメモリは、エージェントに提供されうる最悪のものです。そこで、どうするかを選びます:

  • 古いメモリを置き換える: 古いメモリは履歴に移ります。エージェントには見えなくなり、マップ上では置き換え先にリンクされたゴーストとして残ります。
  • 両方残す: 両方とも正しい場合 (2 つの環境、2 つのテナントなど) は両方を残し、違いを明記します。
  • 自分のメモリを破棄: 間違っていたのは自分のメモリだった場合です。

既存の事実を一字一句同じように書き直しても、2 つ目のコピーは保存されません。代わりに既存のメモリが確認済みとなり、ダイアログでそのことが伝えられます。エージェントも API を通じて同じ扱いを受け、remember の deduplicated と conflicts フィールドで結果が返されます。

任意の事実へのリンク

すべてのメモリと要素には固有のアドレスがあります。閲覧パネルのリンクでそれをコピーできます。プルリクエスト、ADR、Slack のスレッドに貼り付けると、そのメモリと周辺のメモリを中心にマップが開きます。メモリへのリンクは重複と統合された後も機能し、その後置き換えられたメモリへのリンクは履歴ビューを開くため、リンクが行き場を失うことはありません。

重複

エージェントが同じ事実をいくつかの書き方で書いた場合、重複ボタンで各グループを確認できます。1 つに統合は最も確認回数の多いコピーを残し、他を退役させ、それらのリンクを移します。統合するかどうかは常にあなたが決めます。異なる 2 つの要素についての似た文言や、数値が異なるものが重複として提案されることはありません。

要再確認

確認後に要素が変わったメモリと、エージェントが一度も使わないメモリ

誰も再確認しないメモリは、気づかないうちに誤りになります。マップの要再確認ビューでは、人の目が必要なメモリだけが強調表示され、一覧にまとめられます:

  • 要素が変わった: メモリが最後に確認された後、要素の下のコードが変化しました。エージェントには引き続き提供されますが、要確認の印が付きます。まだ正しければ 今も正しい で確認すると印が消えます。正しくなければ、開いて修正するか置き換えます。
  • エージェントが使わない: 5 回以上のセッションに提供されたのに、どのセッションも役に立ったと報告していません。開いて内容を明確にするか、正しい要素に紐付けるか、削除します。

この一覧から自動で削除されるものはありません。同じ項目は毎週のダイジェストでもチームに届くため、誰かがタブを開くかどうかに左右されません。

利用状況

エージェントに提供された回数でサイズが変わるメモリ。中空のものは提供されたが一度も使われていない

利用状況ビューでは、各メモリのサイズが、提供されたエージェントセッションの数に応じて変わります。塗りつぶされた点は少なくとも 1 回使われたもの (エージェントがセッション終了時に usedMemories で挙げたもの)、中空の点は提供されたが一度も使われていないもの、薄い点は一度も提供されていないものです。どのナレッジが実際にエージェントの作業を支えていて、どれがノイズなのか、という 2 つの問いにひと目で答えられます。

権限

プロジェクトを閲覧できる人は誰でも、マップを読み、質問できます。メモリの書き込み、確認、統合、置き換え、削除には、プロジェクトの編集権限が必要です。