프로토콜

세션 프롬프트에 실리는 규약은 층이 둘입니다. 하나는 코어입니다. 엔진이 매 세션 맨 앞에 붙이고, 이 프로젝트만이 아니라 모든 프로젝트가 같은 것을 받습니다. 다른 하나가 프로젝트 프로토콜입니다. 이 화면이 고치는 것이 그쪽입니다. 누가 이 일을 맡는가는 페르소나가 따로 답합니다.

프로젝트 층의 본체는 파일 하나입니다. 큐의 protocols/AGENTS.md. 페르소나는 티켓이 골라서 실리지만 이 파일은 아무도 고르지 않습니다. 이 프로젝트에서 도는 모든 세션이 같은 문서를 받습니다. 페르소나가 붙었든 안 붙었든, 엔진이 claude든 codex든 같습니다.

첫 프로젝트를 만들 때 이 파일도 같이 섰습니다(첫 프로젝트 만들기). 티켓을 받아서 어떤 순서로 끝내는지, 결과를 어디로 올리는지, 막혔을 때 무엇을 남기는지가 이미 적혀 있습니다. 고치는 자리는 프로토콜 화면입니다.

프로토콜 화면 - 파일트리와 편집기

왼쪽 내비의 프로토콜. 왼쪽이 파일트리, 오른쪽이 편집기입니다. 들어가면 AGENTS.md가 이미 열려 있습니다. 이 화면에서 제일 자주 여는 파일이라 고르는 한 번을 아낍니다.

제목 밑 회색 글씨가 지금 보고 있는 디렉터리의 실제 경로입니다. 워커 파일에서 그 경로를 읽지 못하면 엔진 기본값(<루트>/protocols)으로 보고 옆에 기본값 가정이라고 적습니다.

편집기는 두 모드입니다. 들어가면 위지윅으로 열립니다. 제목은 제목 크기로, 표는 칸이 나뉜 표로 보이고 보이는 그대로 고칩니다. 파일에 든 마크다운을 직접 보려면 칸 오른쪽 위 구석의 아이콘 버튼을 누르세요. 마우스를 올리면 원문으로라고 뜹니다. 돌아올 때는 같은 자리에서 위지윅으로입니다. 고른 모드는 이 컴퓨터에 남습니다. 티켓 본문이든 온톨로지든 프로필이든 이 앱의 마크다운 칸은 전부 같은 모드로 열립니다. 모드를 오가도 저장 안 한 편집은 안 없어집니다.

위지윅으로 고쳤다고 파일이 통째로 다시 써지지는 않습니다. 저장하면 고친 자리만 갈리고 나머지 줄은 바이트 하나까지 그대로입니다. 이 파일들은 사람만 읽는 게 아니라 세션이 읽습니다. 표 정렬이 저 혼자 바뀌거나 <해시> 같은 표기가 달라지면 세션이 읽는 글이 달라집니다. 위지윅으로 고쳐도 그 일은 없습니다.

한 글자라도 고치면 오른쪽 아래 저장이 살아납니다. 저장하기 전으로 물리려면 그 옆 되돌리기를 누르세요. .md가 아닌 파일도 같은 편집기로 열립니다. 안 열리는 것은 디렉터리와 1MB가 넘는 파일, 텍스트가 아닌 파일입니다. 그때는 편집기 자리에 못 여는 이유가 대신 뜹니다.

파일이 하나도 없어도 이 프로젝트는 그냥 돕니다. 엔진은 AGENTS.md가 없으면 넘어갑니다. 에러도 경고도 없습니다. 세션이 이 프로젝트의 관습을 모른 채 시작할 뿐입니다. 코어는 그때도 실립니다.

트리 맨 위 자물쇠 - 코어 프로토콜

트리 맨 위에 자물쇠가 붙은 파일 세 장이 따로 섭니다. CORE.md, CORE-TICKETS.md, CORE-MEMORY.md. 여기서는 읽기만 합니다. 저장도 이름변경도 삭제도 없습니다.

엔진이 읽는 계약이 여기 삽니다. 파일명이 곧 티켓 상태라는 것, claim이 원자적 링크라는 것, ## 결과와 ## 블록이 앉는 자리. 세션이 이 문장을 어기면 결과물만 달라지는 게 아니라 큐가 망가집니다. 그래서 프로젝트가 손댈 수 있는 자리에 두지 않았습니다.

고를 때마다 위에 그 파일의 실제 경로가 뜹니다. 두 자리 중 하나입니다.

엔진 레포의 protocols/. 큐에 사본이 없으니 지울 수가 없습니다.
이 큐의 protocols/. 앱으로 새 프로젝트를 만들면 코어를 큐에 한 벌 복사받습니다. 그때는 세션이 실제로 받는 것이 큐 사본이라 화면도 그쪽을 보여줍니다.

프로젝트 문서가 코어와 어긋나게 적혀 있으면 코어가 이깁니다. 코어가 프롬프트에서 먼저 서고 그 머리에 우선순위가 한 줄로 적혀 있습니다.

세 장 중 프롬프트에 인라인되는 것은 CORE.md 하나입니다. 나머지 둘은 CORE.md가 가리키면 세션이 그때 직접 읽습니다. 티켓 frontmatter 문법이 CORE-TICKETS.md에, 회고를 남기는 형식이 CORE-MEMORY.md에 있습니다.

`전원 프롬프트에 인라인` 배지

배지가 붙는 파일은 트리 전체에서 둘입니다. 맨 위의 CORE.md와 프로젝트 층의 AGENTS.md. 나머지에는 세션이 필요할 때 읽음이라고 적힙니다. 이 화면에서 제일 중요한 구분이 이 둘입니다.

n은 지금 이 파일의 글자 수입니다. 타이핑하는 동안 같이 움직입니다. 저장한 뒤에 알려주면 늦기 때문입니다.
길이가 곧 매 세션의 비용입니다. 여기에 100줄을 더 쓰면 그 100줄이 앞으로 도는 모든 세션의 프롬프트에 들어갑니다.
엔진이 읽는 이름은 AGENTS.md 하나입니다. 하위 디렉터리에 같은 이름으로 만들어도 인라인되지 않습니다.

조립된 프롬프트는 이 순서입니다. 맨 앞이 CORE.md, 그다음이 페르소나 프로필과 온톨로지 블록, 그 뒤가 이 파일, 마지막이 티켓 지시입니다. 뒤로 갈수록 구체적입니다.

적는 것 - 큐를 다루는 규약

무엇을 만들지는 티켓이 정하고, 어떻게 만들지는 프로젝트의 스펙 문서가 정합니다. 이 파일이 맡는 것은 그 사이입니다. 티켓 하나를 받아 끝낼 때까지 누구든 매번 똑같이 하는 일입니다. 만들어질 때 들어 있는 것이 그 보기입니다.

세션이 어느 디렉터리에서 도는가. 워커마다 git 워크트리를 따로 쓸 것인가
시작할 때 무엇을 받아 오고, 끝나면 결과를 어디로 올리는가
계정 한도에 걸렸을 때 물러나는 절차
페르소나 메모리에 쌓을 수 있는 총량
티켓을 끝내면서 아카이브 티켓을 한 장 낼 것인가(아카이빙과 온톨로지)
브라우저를 띄우는 방법

여기 안 적는 것도 분명합니다. 티켓 하나에만 걸리는 지시는 그 티켓에 적고, 한 역할에만 걸리는 판단 기준은 페르소나 프로필에 적습니다. 큐를 다루는 문법은 이미 코어에 있으니 베껴 오지 마세요. 전원이 매번 읽어야 하는 문장만 이 파일에 남기시면 됩니다.

옆 파일로 빼는 시점

길어졌다 싶으면 세부를 옆 파일로 빼세요. 새로 만든 프로젝트에 tickets.md와 ontology.md가 이미 그렇게 서 있습니다. 티켓 쪼개는 기준, 온톨로지에 무엇을 어떻게 적는가. 전부 그 일을 할 때만 필요한 것들이라, AGENTS.md는 한 줄로 가리키기만 합니다.

빼면 둘이 달라집니다. 매 세션이 무는 프롬프트가 그 분량만큼 줄고, 정작 그 일을 하는 세션은 여전히 전문을 읽습니다. 트리에서 그 파일은 세션이 필요할 때 읽음으로 섭니다.

기준은 한 문장입니다. 모든 세션이 알아야 하면 AGENTS.md에, 어떤 일을 할 때만 필요하면 옆 파일에. 디렉터리를 중첩해도 됩니다.

새 파일 - 이름변경 - 삭제

새 파일은 화면 오른쪽 위에 있습니다. 경로 한 칸을 채우면 빈 파일이 생기고 편집기가 바로 열립니다. /를 넣으면 하위 디렉터리까지 같이 만듭니다. 프로토콜 디렉터리 밖으로 나가는 경로(../나 절대경로)는 서버가 거부합니다.

이름변경과 삭제는 편집기 오른쪽 위, 파일 이름 맞은편에 있습니다. 이름변경은 경로를 바꾸는 것이라 하위 디렉터리로 옮기는 데에도 씁니다. 같은 이름이 이미 있으면 거부합니다. 조용히 덮어쓰지 않습니다. 삭제는 되돌릴 수 없습니다.

AGENTS.md는 둘 다 경고를 먼저 보여줍니다. 이름을 바꾸려 하면 이름을 바꾸면 프롬프트에서 빠집니다, 지우려 하면 모든 세션이 협업 프로토콜 없이 시작합니다가 그 다이얼로그에 뜹니다. 엔진이 읽는 이름이 하나라서 그렇습니다. 이름이 달라지는 순간 그 파일은 그냥 옆 파일이 되고, 세션은 규약 없이 시작합니다. 에러가 나지 않으니 화면이 미리 말해 주는 것 말고는 알 자리가 없습니다.

고친 내용이 실리는 시점

저장을 누르면 파일은 그 자리에서 바뀝니다. 그런데 지금 도는 세션은 이미 프롬프트를 받은 뒤입니다. 프롬프트는 디스패치 순간에 한 번 조립되고, 그 뒤로 파일이 어떻게 바뀌든 돌고 있는 세션은 모릅니다. 고친 규약이 실리는 것은 다음에 디스패치되는 티켓부터입니다.

도는 세션에 지금 무언가를 말해야 한다면 그건 다른 자리입니다. 도는 세션에 말 걸기를 보세요.

다음은 아카이빙과 온톨로지입니다.