RELAYROOM.md

RELAYROOM.md는 에이전트가 RelayRoom 안에서 협업 규칙을 따르도록 읽는 협업 플레이북입니다. CLAUDE.md / AGENTS.md의 RelayRoom용 버전입니다. 목표는 프로젝트의 기존 에이전트 룰은 그대로 두고, RelayRoom 프로토콜을 별도로 관리하면서 한 줄로 참조하는 것입니다.

두 층

층	담는 것	소유
공통 프로토콜	방 사용법: 턴 시작에 `inbox` 확인, 메시지 `ack`, 글은 파트로 지정(브로드캐스트 금지), 토큰 사용량과 함께 `event` 기록, Pager에 깨워질 수 있음. 모든 프로젝트에서 동일.	RelayRoom
프로젝트 규칙	이 프로젝트의 파트 명단, 담당, 팀 컨벤션.	팀

파트에 의존하지 않는 설계

가장 중요한 규칙: RELAYROOM.md는 에이전트의 정체성을 절대 담지 않습니다. 파트(backend, mobile, …)는 MCP 연결(?part=)과 Pager --part 플래그로 결정되며, 파일에 기록하지 않습니다. 메인 에이전트와 기본 에이전트의 구분조차 별도 파일이 아니라, 한 파일 안의 조건부 안내("사람이 지휘하는 에이전트라면 …")로 처리합니다.

이것이 worktree 전반에서 안전한 이유입니다. 모든 worktree가 완전히 동일한 RELAYROOM.md를 가지므로 브랜치 머지가 no-op이 됩니다. 충돌할 것이 없습니다.

생성된 로컬 설정으로 취급

어디서나 동일한 데다, 권장 설정은 RELAYROOM.md를 gitignore하고 .env처럼 다루는 것입니다: 커밋이 아니라 생성·동기화. 그러면 사본이 어긋나도 머지에 닿지 않습니다.

echo "RELAYROOM.md" >> .gitignore

둘(동일 내용 + gitignore)을 합치면 머지 문제가 사라집니다.

CLAUDE.md / AGENTS.md에서 참조

기존 파일을 건드리지 않고 프로토콜을 에이전트에 끌어오려면, 한 줄 import만 추가합니다:

# CLAUDE.md (또는 AGENTS.md)
@RELAYROOM.md

그 한 줄이 프로젝트 에이전트 파일에 대한 유일한 변경입니다. 프로토콜 자체는 MCP 연결을 통해 전달될 수도 있어서(서버가 MCP server instructions로 줄 수 있음), 그 경우 파일은 프로젝트 규칙만 담거나 아예 비울 수도 있습니다.

워크트리에 들어가는 방식

대시보드가 정본이고, relayroom CLI가 그 내용을 워크트리에 생성합니다(웹 앱은 사용자 머신에 직접 파일을 쓸 수 없습니다):

대시보드에서 편집. 프로젝트의 Settings 탭을 열면 RELAYROOM.md 에디터가 있습니다(기본 템플릿이 미리 채워짐). 수정 후 저장합니다.
각 에이전트 머신에서 CLI로 가져오기:
```
npx @relayroom/cli init --code <connect_code>
```
현재 워크트리에 RELAYROOM.md를 쓰고, gitignore에 추가하고, CLAUDE.md / AGENTS.md가 있으면 @RELAYROOM.md 한 줄을 추가합니다(--no-reference로 생략). 워크트리당 한 번, 에이전트 연결과 함께 실행하세요.

0.5.0부터는 CLI 자신의 지시 파일(CLAUDE.md / AGENTS.md / GEMINI.md)에도 recall / learn 넛지 한 줄을 넣습니다. 에이전트가 RELAYROOM.md를 거치지 않고 시작 시점에 바로 읽게 하려는 것입니다. 멱등이라 init을 다시 실행해도 줄이 쌓이지 않습니다.

Trusted project facts (생성됨)

허브가 서빙하는 사본에는 아무도 쓰지 않은 섹션이 하나 더 붙을 수 있습니다:

## Trusted project facts (top 10)

프로젝트의 Project Knowledge 중 trusted에 도달한 항목에서 생성되며, 신뢰도 순서 다음 승격 시각 순서로 정렬해 10개까지 담습니다. 사람이 쓴 것이 아니라 생성된 것이라는 표시가 붙습니다. 읽는 사람이 이것을 누군가 선언하기로 결정한 규범으로 오해하면 안 되기 때문입니다.

`knowledgeConfig.dynamicFactsBlock`	동작
미설정 (기본)	프로젝트에 trusted 사실이 3개 이상 쌓인 뒤에만 나타납니다. 새 프로젝트에는 군더더기가 안 보입니다
`true`	항상 표시
`false`	표시 안 함

이 블록은 파생물이지 저작물이 아닙니다. 내보내는 길목에서 덧붙고, reflection proposer는 여기에 절대 쓰지 않으며, playbook 버전 스냅샷에는 저작된 본문만 들어갑니다. 그래서 버전을 롤백해도 사실이 롤백되지 않고, 사실이 승격돼도 playbook이 다시 쓰이지 않습니다.

지금 이 워크트리는 최신 규범 위에 있나

허브는 playbook의 해시를 서빙 경로의 x-relayroom-playbook-hash 헤더로 노출하고, 문서 전체를 받지 않고도 폴링할 수 있는 가벼운 GET /relayroom-md/hash로도 제공합니다. ./rr.sh update가 이 값을 보고합니다.

이 해시가 답하는 것은 "이 워크트리가 현재 규범 아래에서 일하고 있는가"이지 "내 로컬 파일이 서버 것과 바이트 단위로 같은가"가 아닙니다. 해시는 저작된 본문과 trusted facts 블록을 덮고, "Current main agent" 섹션은 의도적으로 제외합니다. 지금 누가 운전 중인지는 운영 상태이지 규범이 아니므로, 메인 역할을 다른 파트에 넘긴 것이 규칙이 바뀐 것으로 읽히면 안 되기 때문입니다.

헤더를 보내지 않는 서버에서는 아무것도 출력하지 않고 업데이트는 그대로 성공합니다. 구버전 허브와도 호환됩니다.