아키텍처는 그것이 있는 곳에서 논의하세요

누군가 Billing이 ledger 데이터베이스에 직접 쓰고 있다는 것을 알아챕니다. ADR-12에는 Ledger API만 쓸 수 있다고 되어 있는데도요. 그 사람은 Slack 스레드에 질문을 올립니다. 답글 두 개, "좋은 지적이네요, 확인해 볼게요" 하나. 점심시간쯤이면 스레드는 화면 밖으로 밀려나 있습니다. 한 달 뒤에도 화살표는 여전히 다이어그램에 있고, ADR-12는 여전히 아무도 의문을 제기한 적 없는 것처럼 읽히며, "확인해 볼게요"라고 했던 사람은 다른 팀으로 옮겨 갔습니다. 질문은 제기되었고 답도 나왔습니다. 아키텍처가 볼 수 없는 곳에서요.

이번 주에 저희가 다룬 것이 바로 이 틈입니다. 10월 18일, 아키텍처에 관한 대화를 모델 안으로 옮기는 여섯 가지 기능을 출시했습니다. 다이어그램에 고정하는 댓글, @멘션, "인용된 곳" 목록이 있는 # 인용, 앱과 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 프로젝트를 팔로우하고 있으므로 그녀에게도 한 줄이 갑니다. 팔로우하는 프로젝트에서 열린 변경 요청은 그것을 리뷰할 수 없는 팔로워에게도 알립니다.

루프가 닫힙니다. Sam이 작업에 체크합니다. 작업을 만든 Marie는 "Sam님이 회원님이 만든 작업을 완료했습니다"라는 알림을 받습니다. 그녀가 #7을 해결하면 말풍선은 다이어그램에서 사라집니다. Sam이 변경 요청 링크를 #payments에 올리면, Archyl 봇이 제목, 상태, 프로젝트와 함께 펼쳐 보여 줍니다.

이 대화의 모든 조각은 모델 안의 무언가에 붙어 있습니다. 관계, 결정, 담당자, 변경 요청. 스레드가 어디 있었는지 누군가가 기억하는 데 기대는 것은 아무것도 없습니다.

각 기능이 하는 일

다이어그램 위의 댓글

C를 누르거나 다이어그램 하단 바에서 댓글을 클릭한 다음, 댓글이 있어야 할 곳을 클릭합니다.

  • 빈 공간에서는 말풍선이 그 자리에 머뭅니다.
  • 요소 위에서는 요소에 붙어서 요소가 움직이면 따라가고, 논의는 요소의 세부 정보 패널에도 나타납니다.
  • 관계 위에서는 그 중간 지점에 놓입니다.

말풍선은 프로젝트별로 번호가 매겨지고 어떤 줌에서도 같은 크기를 유지합니다. 각 말풍선은 놓인 수준과 뷰에 속하므로, system context에 단 댓글이 시스템 내부에 나타나지는 않습니다. 해결된 말풍선은 숨겨집니다. 댓글 모드에서 해결된 항목 표시를 체크하면 회색으로 볼 수 있습니다. 그 밖에는 고정된 논의도 일반 논의와 같습니다. 프로젝트의 논의 목록에 표시되고, 답글은 참여자에게 알림을 보냅니다. 문서: 다이어그램 위의 댓글

@멘션

댓글이나 답글, ADR의 context·decision·consequences, 문서 페이지, 변경 요청의 설명·댓글·리뷰에서 @를 입력하세요. 목록에는 프로젝트를 열 수 있는 사람들과, 그런 사람이 한 명 이상 있는 팀이 표시됩니다. 팀을 멘션하면 그 팀원 중 프로젝트를 열 수 있는 사람에게 전달됩니다.

알림은 한 번만 갑니다. 텍스트를 다시 편집해도 이미 멘션된 사람에게는 알림이 가지 않습니다. 제목 안의 멘션은 감지되지 않으니 본문에 쓰세요. 받은편지함을 출시했을 때 멘션은 "아직 하지 않는 것" 목록의 첫 번째 항목이었습니다. 이제 들어왔습니다. 문서: 멘션, 인용, 링크

# 인용과 "인용된 곳"

같은 곳에서 #을 입력하면 system, container, component, code 요소(각각 상위 요소와 함께 표시), 결정(ADR-3처럼 제목과 함께 표시), 문서 페이지를 인용할 수 있습니다. 칩을 클릭하면 인용한 대상이 열립니다. 요소는 다이어그램에서 자기 수준으로, 이미 선택된 상태로 열립니다.

나머지 절반은 백링크입니다. 모든 요소, 결정, 페이지는 자신이 어디에서 인용되었는지를 최신순으로, 각 인용 주변의 발췌와 함께 나열합니다. 요소 세부 정보 패널의 인용된 곳 섹션, 결정의 펼친 카드 하단, 페이지 하단입니다. Slack 스레드가 줄 수 없는 부분이 바로 이것입니다. 대화가 ADR을 가리키고, ADR이 다시 대화를 가리킵니다.

링크 미리보기, Archyl에서도 Slack에서도

링크 복사는 요소의 세부 정보 패널, 각 결정 카드, 각 문서 페이지 상단에 있습니다. 요소 링크는 그 요소를 해당 수준에서 선택된 상태로 엽니다. 변경 요청과 논의는 주소 표시줄에서 공유합니다.

Archyl 링크를 댓글, 변경 요청 설명, 리뷰에 붙여 넣으면 텍스트 아래에 카드로 표시됩니다. 제목, 유형과 상태, 프로젝트, 발췌입니다. 메시지당 최대 세 개의 링크가 미리보기로 표시되며, 프로젝트를 열 수 있는 사람에게만 보입니다. 다른 사람에게는 일반 링크로 보입니다.

Slack에서는 이제 봇이 프로젝트, 요소, 결정, 문서 페이지, 변경 요청, 논의로 가는 링크를 같은 미리보기로 펼칩니다. 봇이 이미 가지고 있던 규칙을 따릅니다. 미리보기는 워크스페이스를 연결한 admin의 권한으로 만들어지고, 워크스페이스가 연결된 조직의 프로젝트에 대해서만 만들어지며, 범위가 지정된 채널에서는 범위 밖 프로젝트로 가는 링크가 일반 링크로 남습니다. 존재하지 않거나 봇이 볼 수 없는 대상으로 가는 링크도 일반 링크로 남으므로, 미리보기가 어떤 페이지의 존재를 확인해 주는 일은 없습니다. 문서: Slack의 링크 미리보기

팔로우

요소의 세부 정보 패널, 결정 카드, 다이어그램 툴바에 있는 종 아이콘으로 요소, 결정, 또는 프로젝트 전체를 팔로우할 수 있습니다. 채워진 종은 팔로우 중이라는 뜻입니다. 요소의 담당자는 아무것도 하지 않아도 그 요소를 팔로우하며, 그 요소를 소유한 팀의 멤버도 마찬가지입니다. 종을 클릭해 팔로우를 해제하면, 여전히 요소의 담당자이더라도 Archyl이 그 선택을 기억합니다.

팔로워는 팔로우하는 대상이 변경되거나 삭제될 때(알림에 변경된 필드가 나열됩니다), 팔로우하는 요소에 댓글이 달릴 때, 변경 요청이 팔로우하는 요소를 건드릴 때 알림을 받습니다. 프로젝트 팔로워는 요소, 결정, 페이지가 추가될 때도 알림을 받습니다. 팔로우는 접근 권한을 주지 않습니다. 프로젝트에 대한 접근 권한을 잃으면 알림도 멈춥니다. 문서: 팔로우

작업

프로젝트의 어떤 댓글이나 답글 아래에서든 작업을 클릭하고, 프로젝트를 열 수 있는 사람 중에서 담당자(기본값은 나)를 고르고, 선택적으로 마감일을 정한 뒤 작업 만들기를 클릭하세요. 댓글 하나에는 작업이 최대 하나만 붙습니다. 작업은 댓글 아래에 체크박스, 담당자, 마감일과 함께 표시되며, 마감일이 지나면 빨간색으로 바뀝니다. 작업을 제거해도 댓글은 남습니다.

열려 있는 내 작업은 받은편지함의 할 일 탭에 마감이 가까운 순서로 있고, 탭에 개수가 표시됩니다. 각 요소의 세부 정보 패널에는 그 요소의 모든 논의에서 나온 작업을 나열하는 할 일 섹션이 있습니다. 담당자는 자신에게 작업이 만들어지거나 재할당될 때 알림을 받고, 작성자는 다른 사람이 작업을 완료했을 때 알림을 받습니다. 문서: 작업

에이전트도 태그할 수 있습니다

MCP 서버로 연결된 코딩 에이전트도 같은 모델에 씁니다. 변경 요청을 열고, 결정을 기록하고, 댓글을 남깁니다. 지금까지는 에이전트가 "@Sam, 확인해 줄 수 있나요?"라고 써도 아무에게도 알리지 않는 일반 텍스트가 될 뿐이었습니다.

이제 서버는 에이전트가 쓴 내용을 앱의 선택 목록과 같은 방식으로 읽습니다. 댓글, ADR, 문서 페이지, 변경 요청 안에서는 다음과 같습니다.

  • @Name은 사람이나 팀을 멘션하고, 다른 멘션과 마찬가지로 그들의 받은편지함에 알림이 갑니다. 에이전트는 list_mentionables를 호출해 정확한 이름을 얻을 수 있습니다.
  • #Label은 C4 요소, 결정(#ADR-12), 페이지를 인용하며, 인용된 쪽은 에이전트의 텍스트를 인용된 곳 아래에 나열합니다.

에이전트가 올린 댓글도 사람이 올린 댓글처럼 이미 논의에 참여한 사람들과 요소의 팔로워에게 전달됩니다. 쓰기를 할 때마다 무엇이 연결되었는지 에이전트에게 알려 주므로, @Sam이 정말 Sam에게 닿았는지 확인할 수 있습니다.

에이전트는 링크를 거꾸로 읽을 수도 있습니다. get_backlinks는 요소, 결정, 페이지가 어디에서 인용되었는지를 반환합니다. Ledger DB를 건드리기 전에 에이전트는 Marie의 댓글 #7과 ADR-12를 인용한 변경 요청을 찾을 수 있으므로, 같은 질문을 처음부터 다시 발견할 필요가 없습니다.

팔로우하되 파묻히지 않게

팔로우는 저희가 받은편지함에 정한 규칙과 부딪힙니다. 받은편지함에는 당신을 기다리는 일이나 당신이 한 일에 대한 답만 들어간다는 규칙입니다. 팔로우하는 요소가 바뀌는 것은 당신을 기다리는 일이 아닙니다. 그래도 들여보낸 것은 종을 클릭하거나 요소를 소유함으로써 당신이 요청했기 때문이고, 얼마나 시끄러워질 수 있는지에 한도를 두었습니다.

  • 요소를 옮기거나 스타일을 바꾸는 것은 아무에게도 알리지 않습니다.
  • 같은 대상에 대한 한 시간 이내의 여러 편집은, 아직 읽지 않았다면 알림 하나로 묶입니다.
  • 프로젝트는 팔로우하지만 요소는 팔로우하지 않는다면, 그 프로젝트에 대해 종류별로 시간당 최대 한 개의 알림을 받습니다. 요소 수백 개를 만드는 AI discovery를 승인해도 수백 줄이 아니라 한 줄입니다.
  • 두 번 알림을 받지 않습니다. 당신을 멘션한 댓글이나 당신이 참여한 논의의 답글은 그 알림으로만 전달됩니다.
  • 자신의 행동에 대해서는 절대 알림을 받지 않습니다.

조직 전체의 모든 변경을 원한다면, 여전히 이메일 알림과 히스토리 페이지가 그 자리입니다.

아직 하지 않는 것

  • 받은편지함 전용. 멘션, 팔로우, 작업은 이메일을 보내지 않습니다.
  • 마감일 리마인더 없음. 기한이 지난 작업은 빨간색으로 바뀌지만, 아무것도 알려 주지 않습니다.
  • 팔로우 목록 없음. 요소, 결정, 프로젝트마다 각각 관리합니다. 문서 페이지는 단독으로 팔로우할 수 없으니, 대신 그 프로젝트를 팔로우하세요.
  • 말풍선은 놓은 자리에 머뭅니다. 한번 놓은 말풍선은 옮길 수 없습니다. 관계의 말풍선은 선의 곡선 위가 아니라 두 요소 사이의 중간 지점에 놓입니다. 타임 트래블이 열려 있는 동안에는 말풍선이 숨겨집니다.
  • Microsoft Teams 미리보기 없음. 현재는 Slack만 지원합니다. 10월 18일 이전에 연결한 Slack 워크스페이스는 두 가지 새 권한 links:read와 links:write를 부여하기 위해 조직 → 봇에서 다시 연결해야 합니다.
  • 에이전트는 작업, 팔로우, 고정을 볼 수 없습니다. MCP 서버를 통해 멘션하고 인용할 수는 있지만, 작업을 읽거나 완료하고, 요소를 팔로우하고, 다이어그램에 댓글을 고정하는 것은 아직 할 수 없습니다.
  • 프로젝트 밖의 작업 없음. 조직 논의에는 작업을 붙일 수 없습니다.

사용해 보세요

다이어그램을 열고 C를 누른 다음, 그동안 물어보려던 관계를 클릭하세요. 반대쪽 끝의 담당자를 멘션하고, 그 관계가 따라야 할 결정을 인용하세요. 각 기능은 문서에 자세히 설명되어 있습니다.

함께 읽기: 위의 모든 알림이 따르는 규칙은 당신을 기다리는 일을 위한 받은편지함에서, Slack 채널이 무엇을 미리보기로 보여 줄 수 있는지는 채널별로 봇 범위 지정하기에서 확인하세요.