アーキテクチャは、それがある場所で議論する

ある人が、Billing が ledger のデータベースに直接書き込んでいることに気づきます。ADR-12 では、書き込めるのは Ledger API だけのはずです。その人は Slack のスレッドで質問します。返信が 2 件、「いい指摘、見てみます」が 1 件。昼にはスレッドは画面の外へ流れています。1 か月後、矢印はまだダイアグラムにあり、ADR-12 は誰にも疑問を持たれたことがないかのように読め、「見てみます」と言った人は別のチームに移っています。質問は投げかけられ、答えも出ました。ただし、アーキテクチャからは見えない場所で。

今週取り組んだのは、この隙間です。10 月 18 日、アーキテクチャについての会話をモデルそのものの中に移す 6 つの機能をリリースしました。ダイアグラムにピン留めするコメント、@メンション、「引用元」リスト付きの # 引用、アプリ内と Slack でのリンクプレビュー、フォロー、そしてタスクです。どれも議論を、それが扱っている要素、決定、ページに結び付け、すべてが 10 月 10 日に追加した受信トレイに届きます。

同じ質問を、モデルの中で

先ほどの ledger の質問を、今回リリースしたもので追い直してみます。名前とプロジェクトは例です。挙動は実際の製品のものです。

Marie は見つけた場所にピン留めする。 彼女は Checkout プロジェクトを container レベルでレビューしています。C を押すとカーソルが十字になり、Billing から Ledger DB への矢印をクリックします。リレーションシップの中ほどにコメント欄が開き、彼女はこう書きます。

Billing writes to Ledger DB directly here. #ADR-12 says ledger writes
go through the Ledger API. @Sam, is this still intended?

# を入力すると、プロジェクトの要素、決定、ページの一覧が開き、ADR-12 はその決定を開くチップになりました。@ を入力すると、プロジェクトを開ける人の一覧が出て、Billing のオーナーである Sam もチップになりました。彼女は ⌘ Enter を押します。吹き出しに #7 という番号が付き、ダイアグラムのそのビューを開いた人には誰にでも見えます。

Sam に知らせが届く。 彼のベルには、Marie にメンションされたことが、彼女のコメントを抜粋として表示されます。ダイアグラムを見張っている必要も、正しい Slack チャンネルにいる必要もありません。

返答がタスクになる。 Sam は、それは ledger 移行の名残で、Ledger API の背後に移すと返信します。議論を始めた Marie は、彼の返信を受信トレイで受け取ります。議論全体を開き、Sam の返信の下にある タスク をクリックし、彼に割り当て、期日に金曜日を選んで タスクを作成 をクリックします。返信の下にチェックボックスが現れ、タスクは Sam の受信トレイの やること タブに入ります。

決定は、疑問を持たれたことを覚えている。 ADR-12 を開くと、展開したカードの下部に、Marie のコメントが 引用元 として、引用箇所の前後のテキストとともに並んでいます。次にこの決定を読む人は、決定が守っているはずのデータベースにまだ書き込みがあったことを知り、クリックして議論にたどり着けます。

修正は自ら知らせる。 Sam は変更リクエストを通じて矢印を置き換えます。その説明は #ADR-12 を引用し、議論 #7 へのリンクを貼っていて、それがテキストの下にプレビューカードとして表示されます。プロジェクトを編集できる全員には、これまでどおり、変更リクエストが開かれたことが通知されます。財務データチームの Léa はレビューできませんが、Checkout プロジェクトをフォローしているので、彼女にも 1 行届きます。フォロー中のプロジェクトで開かれた変更リクエストは、それをレビューできないフォロワーにも通知されます。

ループが閉じる。 Sam がタスクにチェックを入れます。タスクを作った Marie には「Sam さんがあなたの作成したタスクを完了しました」と届きます。彼女が #7 を解決すると、吹き出しはダイアグラムから消えます。Sam が変更リクエストのリンクを #payments に貼ると、Archyl ボットがタイトル、ステータス、プロジェクトとともに展開します。

このやり取りのどの部分も、モデルの中の何かに結び付いています。リレーションシップ、決定、オーナー、変更リクエスト。スレッドがどこにあったかを誰かが覚えていることに頼るものは、何もありません。

それぞれの機能がすること

ダイアグラム上のコメント

C を押すか、ダイアグラム下部のバーにある コメント をクリックし、コメントを置きたい場所をクリックします。

  • 何もない場所なら、吹き出しはその位置に留まります。
  • 要素の上なら、要素に結び付き、要素を動かすと一緒に動きます。議論は要素の詳細パネルにも表示されます。
  • リレーションシップの上なら、その中ほどに置かれます。

吹き出しはプロジェクトごとに番号が振られ、どのズームでも同じ大きさです。それぞれ置かれたレベルとビューに属するので、system context に付けたコメントがシステムの内側に現れることはありません。解決済みの吹き出しは非表示になります。コメントモードで 解決済みを表示 にチェックを入れると、グレーで表示されます。それ以外の点では、ピン留めした議論も普通の議論です。プロジェクトの議論一覧に並び、返信は参加者に通知されます。ドキュメント：ダイアグラム上のコメント

@メンション

コメントや返信、ADR の context・decision・consequences、ドキュメントページ、変更リクエストの説明・コメント・レビューで @ を入力します。一覧には、プロジェクトを開ける人と、その人たちを 1 人以上含むチームが表示されます。チームをメンションすると、そのメンバーのうちプロジェクトを開ける人に届きます。

通知は 1 人につき 1 回です。テキストを編集し直しても、すでにメンションされている人には通知されません。タイトル内のメンションは検出されないので、本文に書いてください。受信トレイをリリースしたとき、メンションは「まだできないこと」リストの筆頭でした。それが今、入りました。ドキュメント：メンション、引用、リンク

# 引用と「引用元」

同じ場所で # を入力すると、system、container、component、code 要素（それぞれ親とともに表示）、決定（ADR-3 のようにタイトル付きで表示）、ドキュメントページを引用できます。チップをクリックすると、引用先が開きます。要素は、それ自身のレベルのダイアグラムで、選択された状態で開きます。

もう半分はバックリンクです。すべての要素、決定、ページが、自分がどこで引用されているかを新しい順に、各引用の前後の抜粋とともに一覧にします。要素の詳細パネルの 引用元 セクション、決定の展開カードの下部、ページの末尾です。これが Slack のスレッドには提供できない部分です。会話が ADR を指し、ADR も会話を指し返します。

リンクプレビュー、Archyl でも Slack でも

リンクをコピー は、要素の詳細パネル、各決定カード、各ドキュメントページの上部にあります。要素のリンクは、その要素をそのレベルで選択した状態で開きます。変更リクエストと議論は、アドレスバーから共有します。

Archyl のリンクをコメント、変更リクエストの説明、レビューに貼ると、テキストの下にカードとして表示されます。タイトル、種類とステータス、プロジェクト、抜粋です。プレビューされるのは 1 メッセージにつきリンク 3 件までで、プロジェクトを開ける人に対してだけです。それ以外の人には普通のリンクとして見えます。

Slack では、ボットがプロジェクト、要素、決定、ドキュメントページ、変更リクエスト、議論へのリンクを、同じプレビューとして展開するようになりました。ボットがもともと持っていたルールに従います。プレビューはワークスペースを接続した admin の権限で作られ、対象はワークスペースが接続されている組織のプロジェクトだけです。スコープを設定したチャンネルでは、スコープ外のプロジェクトへのリンクは普通のリンクのままです。存在しないもの、あるいはボットから見えないものへのリンクも普通のリンクのままなので、プレビューがページの存在を裏付けてしまうことはありません。ドキュメント：Slack でのリンクプレビュー

フォロー

要素の詳細パネル、決定カード、ダイアグラムのツールバーにあるベルで、要素、決定、プロジェクト全体をフォローできます。塗りつぶされたベルはフォロー中を意味します。要素のオーナーは何もしなくてもその要素をフォローしていて、要素を所有するチームのメンバーも同様です。ベルをクリックすればフォローを外せて、要素のオーナーのままでも Archyl はそれを覚えています。

フォロワーに通知されるのは、フォローしているものが変更または削除されたとき（通知には変更されたフィールドが並びます）、フォロー中の要素にコメントが付いたとき、変更リクエストがフォロー中の要素に触れたときです。プロジェクトのフォロワーには、要素、決定、ページが追加されたときにも通知されます。フォローはアクセス権を与えません。プロジェクトへのアクセスを失えば、通知も止まります。ドキュメント：フォロー

タスク

プロジェクト内の任意のコメントや返信の下で タスク をクリックし、プロジェクトを開ける人の中から担当者（デフォルトは自分）と、任意で期日を選び、タスクを作成 をクリックします。1 つのコメントに付けられるタスクは最大 1 つです。タスクはコメントの下に、チェックボックス、担当者、期日とともに表示され、期日は過ぎると赤くなります。タスクを削除しても、コメントは残ります。

自分の未完了タスクは、受信トレイの やること タブに、期日の近い順で並び、タブには件数が表示されます。各要素の詳細パネルには やること セクションがあり、その要素のすべての議論のタスクが並びます。担当者には、自分宛てにタスクが作られたときや再割り当てされたときに通知され、作成者には、他の誰かがタスクを完了したときに通知されます。ドキュメント：タスク

エージェントもタグ付けできる

MCP サーバー経由で接続したコーディングエージェントも、同じモデルに書き込みます。変更リクエストを開き、決定を記録し、コメントを残します。これまでは、エージェントが「@Sam、確認してもらえますか？」と書いても、誰にも知らせないただのテキストになっていました。

これからは、サーバーがエージェントの書いた内容を、アプリのピッカーと同じように読み取ります。コメント、ADR、ドキュメントページ、変更リクエストの中では、次のとおりです。

  • @Name は人またはチームをメンションし、ほかのメンションと同じく受信トレイに通知が届きます。エージェントは list_mentionables を呼び出して正確な名前を取得できます。
  • #Label は C4 要素、決定（#ADR-12）、ページを引用し、引用された側ではエージェントのテキストが 引用元 に並びます。

エージェントが投稿したコメントも、人が投稿したコメントと同じく、すでに議論に参加している人と要素のフォロワーに届きます。書き込みのたびに、何がリンクされたかがエージェントに返されるので、@Sam が本当に Sam に届いたかを確認できます。

エージェントはリンクを逆にたどることもできます。get_backlinks は、要素、決定、ページがどこで引用されているかを返します。Ledger DB に手を入れる前に、エージェントは Marie のコメント #7 と、ADR-12 を引用した変更リクエストを見つけられます。同じ疑問を一から掘り起こす必要はありません。

フォローしても溺れないために

フォローは、受信トレイに設けたルールとぶつかります。受信トレイに入るのは、あなたを待っているものか、あなたがしたことへの返答だけ、というルールです。フォロー中の要素が変わっても、それはあなたを待ってはいません。それでも入れたのは、ベルをクリックするか要素を所有することで、あなたが求めたからです。そして、どこまで騒がしくなれるかに上限を設けました。

  • 要素を動かしたりスタイルを変えたりしても、誰にも通知されません。
  • 同じものへの 1 時間以内の複数の編集は、まだ読んでいない限り、1 件の通知にまとまります。
  • プロジェクトはフォローしていても要素はフォローしていない場合、そのプロジェクトについて受け取る通知は、種類ごとに 1 時間あたり最大 1 件です。数百の要素を作る AI discovery を承認しても、届くのは数百行ではなく 1 行です。
  • 二重には通知されません。あなたをメンションしたコメントや、あなたが参加している議論への返信は、その通知だけで届きます。
  • 自分自身の操作が通知されることはありません。

組織全体のあらゆる変更を知りたいなら、これまでどおりメール通知と 履歴 ページを使ってください。

まだできないこと

  • 受信トレイのみ。 メンション、フォロー、タスクはメールを送りません。
  • 期日のリマインダーはありません。 期限切れのタスクは赤くなりますが、何も知らせてはくれません。
  • フォロー中の一覧はありません。 要素、決定、プロジェクトごとに管理します。ドキュメントページは単独ではフォローできないので、代わりにそのプロジェクトをフォローしてください。
  • 吹き出しは置いた場所から動きません。 一度置いた吹き出しは移動できません。リレーションシップの吹き出しは、線のカーブ上ではなく、2 つの要素の中点に置かれます。タイムトラベルを開いている間、吹き出しは非表示になります。
  • Microsoft Teams ではプレビューされません。 今のところ Slack のみです。10 月 18 日より前に接続した Slack ワークスペースは、2 つの新しい権限 links:read と links:write を付与するため、組織 → ボット から接続し直す必要があります。
  • エージェントはタスク、フォロー、ピン留めを扱えません。 MCP サーバー経由でメンションと引用はできますが、タスクを読んだり完了したり、要素をフォローしたり、ダイアグラムにコメントをピン留めしたりすることはまだできません。
  • プロジェクト外のタスクはありません。 組織の議論にはタスクを付けられません。

試してみる

ダイアグラムを開き、C を押して、ずっと聞こうと思っていたリレーションシップをクリックしてください。反対側の端のオーナーをメンションし、そのリレーションシップが従うはずの決定を引用しましょう。各機能の詳細はドキュメントにあります。

関連記事：上記のすべての通知が従うルールについてはあなたを待っているもののための受信トレイを、Slack チャンネルが何をプレビューできるかについてはチャンネルごとにボットのスコープを設定するをご覧ください。