프로토콜

세션 프롬프트에 실리는 규약은 두 층으로 나뉩니다. 하나는 코어입니다. 엔진이 매 세션 맨 앞에 붙이며 프로젝트를 가리지 않고 모든 프로젝트가 같은 문서를 받습니다. 다른 하나가 프로젝트 프로토콜이며 이 화면에서 고치는 대상이 그것입니다. 누가 이 일을 맡는지는 페르소나에서 따로 다룹니다.

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

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

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

왼쪽 내비의 프로토콜을 누르세요. 들어가면 AGENTS.md가 오른쪽에 이미 열려 있습니다. 이 화면에서 제일 자주 여는 파일이라 따로 고를 필요가 없습니다.

왼쪽이 파일 목록, 오른쪽이 편집기입니다. 편집기가 좁다 싶으면 목록을 접으세요. 접는 곳은 목록 오른쪽 위 구석의 작은 아이콘이고, 마우스를 올리면 파일 목록 접기가 뜹니다. 누르면 파일 이름이 하나도 안 남고 그 아이콘이 든 작은 사각형만 편집기 왼쪽에 뜹니다. 다시 펴는 곳도 같은 자리이며 그때는 파일 목록 펴기라고 뜹니다. 창이 좁으면 접힌 목록이 왼쪽 대신 편집기 위에 가로 막대 형태로 놓입니다. 아이콘은 그때도 오른쪽 끝입니다.

접은 상태는 주소에 남습니다 - ?sidebar=off. 파일을 고르거나 저장해도 다시 펴지지 않고, 그 주소를 그대로 복사해 주면 받는 사람도 접힌 채로 들어옵니다. 파라미터가 없는 주소는 편 상태로 열립니다.

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

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

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

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

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

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

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

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

고를 때마다 위에 그 파일의 실제 경로가 뜹니다. 세션이 실제로 받는 것은 대개 이 큐의 protocols/에 있는 사본이라 화면도 그 경로를 보여줍니다. 그 사본이 어디서 오는지는 아래 §정본은 패키지에 있습니다에 있습니다.

프로젝트 문서가 코어와 어긋나게 적혀 있으면 코어가 우선합니다. 코어가 프롬프트에서 먼저 뜨고 그 앞부분에 우선순위가 한 줄로 적혀 있습니다.

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

정본은 패키지에 있습니다 - .dira/protocols는 생성물

큐 폴더에 .dira/team/apm.yml이 있으면 프로토콜 정본은 두 곳입니다.

큐의 .dira/protocols/는 이 둘을 합친 결과입니다. 공용 위에 로컬을 덮어 쓰고, 이름이 같으면 로컬이 이깁니다. 패키지를 설치할 때마다(python3 dira_apm.py install <프로젝트 루트>, 프로젝트 등록, 로컬로 복사, 마켓에서 받기) dira가 이 폴더를 다시 씁니다. 그래서 거기 있는 파일은 첫 줄이 아래와 같습니다.

<!-- dira_apm materialize: 고치지 말고 .dira/team/protocols 또는 packages/dira-protocols를 고친다 -->

이 화면에서 저장한 내용은 다음 설치 뒤에도 남습니다. .dira/team/apm.yml이 있는 프로젝트에서 protocols/ 바로 아래 파일을 저장하면, dira가 같은 내용을 .dira/team/protocols/의 같은 이름 파일에 쓰고 큐의 .dira/protocols/를 다시 만듭니다. 다음 디스패치부터 실립니다. 공용 문서를 저장해도 같아서, 그 순간 .dira/team/protocols/에 로컬 파일이 생기고 이 프로젝트에서는 로컬 쪽이 이깁니다. .dira/team/은 큐 안이라 저장해도 프로젝트 저장소에는 커밋할 것이 생기지 않습니다.

하위 폴더 안의 파일과 apm.yml, AGENTS.template.md는 예외입니다. 이 파일들은 큐에만 저장되므로, 오래 남길 수정이면 .dira/team/protocols/에서 직접 고칩니다. 공용 문서를 모든 프로젝트에서 바꾸려면 dira 저장소의 packages/dira-protocols/에서 고칩니다. 각 프로젝트는 .dira/team/apm.yml에 적힌 태그를 올려야 그 수정을 받습니다.

공용에 없는 큐 전용 파일은 다시 쓸 때도 지우지 않습니다. .dira/team/apm.yml이 없는 프로젝트는 지금까지처럼 큐의 protocols/가 정본이고, 이 화면에서 저장하면 그 파일만 바뀝니다.

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

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

• 배지는 3,496 / 3,500 B처럼 읽습니다. 앞이 지금 이 파일의 크기고 뒤가 예산입니다. 단위가 바이트라 터미널에서 wc -c로 잰 수와 같습니다. 앞의 수는 타이핑하는 동안 같이 갱신됩니다. 저장한 뒤에 알려주면 늦으니까요.
• 예산은 파일마다 다릅니다. CORE.md가 3,500 B, AGENTS.md가 6,500 B. 넘으면 뒤에 초과 한 낱말이 붙습니다. 색은 그대로고 저장도 막지 않습니다. 넘어 있는 것 자체는 위반이 아닙니다. 위반이 되는 순간은 넘은 채로 더 쓸 때입니다. 그때는 더하는 바이트보다 많이 지우고 더하세요.
• 길이가 곧 매 세션의 비용입니다. 여기에 100줄을 더 쓰면 그 100줄이 앞으로 도는 모든 세션의 프롬프트에 들어갑니다.
• 엔진이 읽는 이름은 AGENTS.md 하나입니다. 하위 디렉터리에 같은 이름으로 만들어도 인라인되지 않습니다.

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

적는 것 - 큐를 다루는 규약

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

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

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

옆 파일로 빼는 시점

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

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

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

새 파일 - 이름변경 - 삭제

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

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

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

고친 내용이 실리는 시점

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

도는 세션에 지금 무언가를 말해야 한다면 그 일은 다른 화면에서 합니다. 도는 세션에 말 걸기를 보세요.

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