연구 세션 절차

연구 프로젝트에서 세션을 시작하고 마치는 절차와, 모든 연구 스킬이 따르는 공통 규칙을 정한다. 도구가 하나인 프로젝트와 둘인 프로젝트에 같은 절차를 쓴다. 프로젝트를 새로 만드는 일은 research-scaffold가 맡는다.

0. 공통 규칙

다른 연구 스킬은 이 규칙을 "공통 규칙"으로 가리키고 되풀이하지 않는다. 프로젝트 규칙(AGENTS.md, 설정)은 스킬의 절차보다 앞서지만 공통 규칙 3, 8, 9, 10, 13보다 앞서지 않는다.

1. 기억이나 앞 대화가 아니라 파일을 읽고 시작한다.
2. 시각은 시계(date)에서 읽는다. 어림으로 적지 않는다.
3. 만든 쪽이 채점하지 않는다. 검산과 심사는 새로 띄운 에이전트가 하고, 앞선 대화를 넘기지 않는다. 사실 대조와 인용 검증은 원고를 고친 에이전트가 아닌 쪽이 한다. 따로 띄울 에이전트가 없으면 총괄이 하되, 고친 쪽이 총괄이었으면 그 사실을 보고에 적는다.
4. 에이전트가 낸 숫자는 총괄이 다시 계산한 뒤 문서에 넣는다.
5. 에이전트 호출이 실패나 거절로 표시돼도 저장소와 파일을 확인한 뒤 보고한다. 실제로는 커밋을 만든 경우가 있다.
6. 사용자만 하는 일(제출, 공개 저장소 push, 계정과 보안 설정, 되돌릴 수 없는 결정)은 직전 단계까지만 준비한다. 계획 승인과 실행 승인은 다르다.
7. 총괄이 사용자 대신 정한 것은 대리 판정으로 적고 대기열(docs/승인기록.md의 대리 판정 절)에 넣는다. 세션을 마칠 때 남은 수를 알린다.
8. 결과와 숫자는 숨기거나 바꾸지 않는다. 원고에서 약점을 필요 이상으로 고백하지 않는다. 불리한 결과에는 범위를 깎기 전에 설계로 답할 방법을 먼저 찾는다.
9. 결과를 본 뒤에는 고정한 기준을 바꾸지 않는다. 바꿔야 하면 사용자가 정하고 승인기록에 남긴다.
10. 사실이 아닌 기록을 남기지 않는다. 하지 않은 일, 보내지 않은 것, 확인하지 못한 것은 그렇다고 적는다.
11. 만들거나 고친 파일은 답에서 바로 열 수 있게 보인다(환경이 지원하면 링크).
12. 글은 국문 학술 문체(korean-academic-style)와 용어집(운영 체계 저장소의 docs/용어집.md)을 따른다. 영문은 english-academic-style을 따른다.
13. 진행은 사용자가 언제든 알 수 있게 보인다. 시작 안내, 진행판, 마침 보고의 틀과 상태어는 8절을 따르고, 사용자가 보는 곳에 5분 넘게 아무 표시도 없게 두지 않는다.

1. 시작할 때

1. 원격 저장소가 있으면 git pull --rebase origin main. 충돌이 나면 상대 것을 살리고 내 것을 다시 적는다. 공개 저장소를 하위 폴더로 두는 구조면 그 저장소도 pull한다.
2. 프로젝트 설정(docs/설정.md)을 읽는다. 도구, 역할과 모델, 원고, 지킬 것, 운영 체계가 여기 있다. 없으면 기본값을 쓰고 그렇게 했다고 말한다.
3. 운영 체계의 새 판을 확인한다. 설정의 운영 체계 절(없으면 확인 주기 7일, 갱신 방식 알림만)을 따른다.
   • 설치 기록(.research-ops.json)을 찾는다. 프로젝트의 .claude/skills/, .codex/skills/, 사용자 홈의 ~/.claude/skills/, ~/.codex/skills/ 순서다. 마지막 확인(last_check)이 주기보다 오래되지 않았으면 건너뛴다.
   • 설치 기록의 source 클론에서 찾은 설치 기록의 폴더를 인자로 넘겨 돌린다: <source>/code/scripts/install-skills.sh check <스킬 폴더> [<스킬 폴더> ...]. 인자 없이 돌리면 현재 폴더와 홈만 보므로 프로젝트 폴더의 설치를 놓친다. Codex 폴더가 CODEX_HOME 아래면 그 경로를 그대로 넘긴다.
   • source 경로가 이 환경에 없으면(다른 컴퓨터에서 설치했거나 클라우드 작업 공간이면) 확인을 건너뛰고 시작 안내에 "운영 체계 확인 못 함(클론 없음)"으로 적는다. 다시 클론할지는 사용자에게 묻고, 클론하면 기록의 repo 주소에서 사용자가 정한 곳(기본 ~/.cache/research-ops)에 받는다. check가 종료 코드 1을 내면(네트워크, 원격, 기록 문제) 같은 방식으로 "확인 못 함"과 이유 한 줄을 적고 세션을 이어 간다.
   • 스킬을 설치하지 않고 운영 체계 저장소의 클론에서 바로 읽어 쓰는 경우에는 그 클론을 git pull --ff-only 한다.
   • 새 판이 있으면(종료 코드 3) 시작 안내의 지금 줄에 "운영 체계 0.7 --> 0.8, 스킬 n개 갱신 가능"을 적고 바뀐 것 두세 줄을 보인다. 갱신 방식이 알림만이면 사용자가 원할 때 update를 돌린다. 자동이면 돌리고 결과를 알린다. 사용자가 고친 스킬은 덮지 않고 SKILL.md.new로 둔다는 것도 알린다.
   • 갱신한 스킬은 다음 세션부터 적용된다. 지금 세션은 이미 읽은 판으로 일한다.
   • 변경 기록에 스캐폴드나 틀의 변경이 있으면 이 프로젝트의 AGENTS.md, 00-교류/, docs/에 반영할지 사용자에게 묻는다. 묻지 않고 프로젝트 파일을 바꾸지 않는다.
   • claude.ai에 zip으로 올린 스킬은 자동으로 확인할 수 없다. 새 판이 있으면 zip을 다시 만들어 올리라고 알린다.
4. 현황(00-교류/현황.md)을 읽는다. 어느 문서의 어느 판이 현행이고 누가 맡는지는 여기가 기준이다.
5. 세션 기록(00-교류/log/)에서 최근 세 파일을 읽는다.
6. 자기 앞으로 온 인계 노트 가운데 status: 대기를 읽고 확인으로 바꾸고 read:에 날짜를 적는다. 요청은 이번 할 일에 넣는다.
7. git log --oneline -20으로 다른 도구의 커밋을 본다.
8. 할일목록과 승인기록(대리 판정 대기열 포함)을 본다. 사용자 확인이 남은 것이 있으면 먼저 알린다.
9. git fetch origin 뒤 origin/away/* 브랜치에 사용자 표시가 비어 있는 검토서가 있으면 다른 일보다 먼저 보이고 research-batch 8.3대로 검토한다.
10. 읽은 것을 시작 안내(8.2)로 보인다. 목표 줄 앞에 지금 : 줄을 하나 더해 현행 판, 대기 중인 사용자 결정 수, 대리 판정 대기 수, 검토하지 않은 검토서 수, 운영 체계의 새 판 여부를 적는다.

2. 일하는 동안

• 현황의 담당 칸에 적힌 쪽만 그 문서를 고친다. 담당이 아니면 심사와 의견까지만 낸다.
• 새 판을 만들면 지난 판은 같은 폴더의 구판/으로 내린다. 지우지 않는다.
• 브랜치는 main 하나다. 며칠 걸리는 실험은 exp/<이름>, 사용자가 자리를 비운 동안의 작업은 away/<시작>을 쓴다. away/ 브랜치는 사용자 검토 전에 main에 합치지 않는다.
• 커밋은 작업 단위마다 한다. 여러 세션이 같은 폴더를 함께 고칠 수 있으므로 git add -A를 쓰지 않고 바꾼 파일만 더한다.
• 다른 도구가 만든 파일을 지우거나 옮길 때는 인계 노트에 적는다.
• .env, 키 파일, 원자료(data/raw/, results/raw/)는 커밋하지 않는다.
• git 이력을 고쳐 쓰지 않는다. 잘못되면 되돌리는 커밋을 새로 만든다. 이력 정리가 필요하면 사용자가 정한다.

3. 마칠 때

1. 다른 도구가 있는 프로젝트에서 바꾼 것이 있으면 인계 노트 한 장을 쓴다(5절 양식).
2. 현황을 갱신한다. 현행 판이 바뀌었으면 반드시.
3. 사용자가 한동안 자리를 비우면(밤, 회의, 주말) 그 시간에 맡길 만한 항목이 있는지 본다. 있으면 무엇을 얼마나 맡길지 한두 줄로 제안하고, 사용자가 원하면 research-batch 8.1대로 맡김 지시서를 쓴다. 원하지 않으면 하지 않는다.
4. 세션 기록 파일 하나를 남긴다(5절 양식).
5. 이번 세션의 사용자 결정을 승인기록에 시각과 함께 적는다. 대리 판정은 승인기록의 대리 판정 절에 따로 적는다.
6. 도구 이름을 접두로 붙여 커밋한다(예: [claude]). 접두는 프로젝트 설정의 도구 목록을 따른다. 커밋은 사용자와 함께 만든다. 작성자는 사용자로 두고(도구의 작업 공간은 기본 작성자가 도구인 경우가 많으니 git config user.email을 먼저 본다), 메시지 끝에 프로젝트 설정 커밋 작성자 절의 공동 작성자 줄을 붙인다. 설정에 그 절이 없는 프로젝트는 Co-Authored-By: <도구 이름> <주소>를 쓴다.
7. 비공개 저장소는 push한다. 거절되면 pull --rebase 뒤 다시 한다. force push는 하지 않는다. 공개 저장소의 push는 사용자 확인 뒤에 한다.
8. 마침 보고(8.2)로 끝낸다. 남은 것 줄에 남은 일, 대리 판정 대기 수, push하지 않은 커밋을 적는다.

4. 도구가 하나일 때와 둘일 때

• 도구가 하나면 인계 노트 폴더를 만들지 않고 세션 기록만 남긴다.
• 두 번째 도구는 반론자로 쓸 때 가장 쓸모가 있었다. 관문 판정이나 원고 심사에서 반박을 맡길 때 인계 노트에 무엇을 반박할지, 무엇을 받지 않는지(앞선 대화, 이전 심사평)를 적는다.
• 두 번째 도구가 한동안 쉬면 현황에 그 사실을 적고, 그 도구가 담당이던 문서의 담당을 다시 정한다.

5. 양식

세션 기록 00-교류/log/YYYY-MM-DD-NN-<도구>.md:

---
date: YYYY-MM-DD
who: <도구>
commit: <이 세션의 마지막 커밋, 저장소가 둘이면 둘 다. 없으면 미커밋>
note: <인계 노트 경로, 없으면 없음>
---
(한두 줄. 무엇을 했고 다음에 무엇이 남았나)

인계 노트 00-교류/<보낸 도구>-to-<받는 도구>/YYYY-MM-DD-NN-<주제>.md:

---
from: <보낸 도구>
to: <받는 도구>
date: YYYY-MM-DD
commit: <직전 커밋>
status: 대기
read:
---
## 무엇을 했나 (판단 근거 포함)
## 바뀐 파일
## 상대에게 요청
## 사용자 판단이 필요한 것 (하지 않은 것도 적는다)

6. 옛 규약 프로젝트 옮기기

00-교류/LOG.md 한 파일에 줄을 쌓던 프로젝트를 이 절차로 옮긴다.

1. 00-교류/log/를 만들고 README.md(5절 양식)를 둔다.
2. LOG.md는 지우지 않고 00-교류/구판/LOG.md로 내린다. 옮긴 날을 현황에 적는다.
3. AGENTS.md(또는 도구별 규칙 파일)의 세션 절차를 이 스킬을 가리키는 한 줄로 바꾼다.
4. 인계 노트 폴더는 그대로 둔다.
5. 옮긴 사실을 인계 노트와 세션 기록에 적는다.

7. 환경 문제

8. 진행 보이기

모든 연구 스킬의 보고는 이 절의 틀을 쓴다. 어느 프로젝트, 어느 세션, 어느 도구에서든 같은 모양이어야 사용자가 한눈에 읽는다. 스킬마다 정한 보고 내용(관문 판정, 바퀴 기록, 대조 결과)은 이 틀의 결과 줄과 스킬이 더한 줄에 넣는다. 이유와 예시는 운영 체계 저장소의 docs/09-진행-보이기.md, 복사할 양식은 templates/진행판.md에 있다. 이 절의 시간 기준(5분, 2분, 1.5배, 30분)은 프로젝트 설정으로 줄일 수는 있어도 늘릴 수는 없다.

8.1 상태어

상태는 아래 일곱 낱말로만 적는다. 대괄호까지 그대로 쓰고, 다른 표시에는 대괄호를 쓰지 않는다.

진척 막대는 12칸이고 단계 표에 적힌 단위(가장 작은 번호, 예: 2a와 2b는 둘)의 수로 센다. [######------] 6/12 50%. 바뀐 파일 수나 출력 줄 수로 세지 않는다. 시각은 시계에서 읽은 HH:MM으로 적는다.

8.2 세 가지 틀

블록은 고정폭 코드 블록에 넣는다. 고정폭으로 보이지 않는 곳에서는 같은 칸을 표로 보인다. 첫 줄은 == <틀> | <프로젝트> | <할 일> | <시각> ==다. 진행판의 괄호에는 시작, 경과, 남은 어림을 적고, 어림을 넘겼으면 어림 n분을 넘김으로, 바퀴나 배치처럼 이름이 있으면 그 이름을 앞에 붙인다. 여러 프로젝트의 현황판처럼 시간이 뜻이 없으면 괄호를 뺀다. 줄 이름은 고정폭 일곱 칸(한글 한 자는 두 칸)에 맞추고, 시작 안내와 마침 보고에서만 콜론을 붙인다. 진행판은 표처럼 읽히게 콜론을 쓰지 않는다. 에이전트 표의 칸은 넘치면 줄여 쓴다. 그림은 코드 블록 안에서 ASCII로만 그린다(-->, ||, +, |, -). 블록 앞뒤의 설명은 한두 문장으로 줄인다.

스킬은 틀의 줄 사이에 자기 줄을 더할 수 있다(예: 관문, 바퀴, 지적, 요건). 첫 줄과, 시작 안내의 목표와 어림, 진행판의 전체와 결정, 마침 보고의 결과와 확인과 남은 것은 빼지 않는다.

시작 안내. 단계가 셋 이상이거나 5분 넘게 걸릴 일은 시작하기 전에 보인다. 지금 줄은 세션을 시작할 때만 넣는다(1절 10번).

== 시작 | <프로젝트> | <할 일> | HH:MM ==
지금   : <세션을 시작할 때만. 현행 판, 결정 대기, 대리 판정 대기, 검토서>
목표   : <끝나면 무엇이 생기나>
순서   : 1 <단계> --> 2 <단계> --> 3 <단계>
         (2a || 2b 함께)
어림   : <전체> (<단계별>)
사용자 : <사용자가 할 일과 그 시점, 없으면 없음>
멈춤   : <멈춤 조건, 없으면 없음>

진행판. 상태가 바뀔 때(단계의 시작과 끝, 에이전트의 시작과 반환, 막힘과 대기) 보인다. 에이전트나 배경 작업이 하나라도 돌고 있으면 에이전트 표를 넣는다. 에이전트의 [대기]에 붙일 것(무엇을, 어림, 다음 알림)은 진척 칸에 적는다. 대기 줄은 총괄이 지금 기다리는 것과 다음 알림 시각이고, 에이전트 표의 상태와 따로 적는다.

== 진행 | <프로젝트> | <할 일> | HH:MM (시작 HH:MM, 경과 n분, 남은 어림 n분) ==
전체   [####--------] 4/12  33%
단계   1 <이름> [완료]  2 <이름> [진행]  3 <이름> [예정]

에이전트    역할        맡은 일              상태     시작   마지막 신호  진척
<이름>      <역할>      <한 줄>              [진행]   HH:MM  HH:MM        34/80
<이름>      <역할>      <한 줄>              [예정]   -      -            1 뒤

최근   HH:MM <일어난 일 한 줄>
대기   <무엇을>, 어림 n분, HH:MM에 다시 알림
결정   <사용자 결정이 필요한 것, 없으면 없음>

마침 보고. 일을 끝낼 때 보인다. 파일 링크는 블록 밖에 둔다. 확인할 것이 없는 일이면 확인 줄에 해당 없음(이유)를 적는다. 미검산은 확인해야 하는데 하지 못한 것에만 쓴다.

== 끝 | <프로젝트> | <할 일> | HH:MM (걸린 시간 n분, 어림 n분) ==
결과   : <핵심 한두 줄, 숫자>
확인   : <독립 검산이나 대조 결과 / 미검산 / 해당 없음(이유)>
바뀐 것: <파일 n개, 아래 링크>
남은 것: <결정 n건, 할 일 n건, 하지 않은 것, push하지 않은 커밋>
다음   : <제안 하나>

8.3 멈춘 것처럼 보이지 않게

1. 사용자가 보는 곳에 5분 넘게 아무 표시도 없게 두지 않는다.
2. 2분 넘게 걸릴 것 같은 명령, 에이전트 호출, 빌드, 수집을 시작하기 직전에 무엇을 기다리는지, 어림, 다음에 알릴 시각을 먼저 보인다.
3. 긴 일은 환경이 허락하면 배경으로 돌리고 5분 안의 간격으로 확인하며 진행판을 갱신한다. 배경으로 돌릴 수 없는 명령은 5분 안팎으로 쪼갠다.
4. 에이전트 호출이 끝날 때까지 화면을 붙잡는 도구에서는 2번의 직전 안내가 5분 규칙을 대신한다. 이때 다음 알림 시각은 호출이 끝날 어림 시각으로 적고, 호출이 끝나면 바로 진행판을 보이며 어림과 실제 시간을 함께 적는다. 서로 의존하지 않는 호출은 함께 띄워 기다리는 횟수를 줄인다.
5. 어림의 1.5배를 넘기면 넘겼다고 알리고 이유와 새 어림을 적는다. 이유를 모르면 모른다고 적고 계속할지 멈출지를 적는다.
6. 응답이 없는 에이전트를 [진행]으로 두지 않는다. 어림을 넘기고 5분이 더 지나도 소식이 없으면 [대기]로 바꾸고 진척 칸에 "응답 없음 n분, HH:MM까지 없으면 다시 띄움"을 적는다. 다시 띄워도 응답이 없거나 환경이 막혔으면 [막힘]으로 바꾸고 필요한 것을 적는다.
7. 중간 신호를 받을 수 없는 도구에서는 마지막 신호 칸에 -(신호 없음)을 적고, 어림의 1.5배까지는 [진행]으로 둔다. 그 뒤는 6번을 따른다.
8. 도구에 작업 목록 위젯이 있으면 진행판의 단계와 같은 이름으로 올리고 상태를 맞춘다. 위젯에는 숫자와 대기 이유가 없으므로 진행판을 대신하지 않는다.
9. 사용자가 자리를 비운 동안(research-batch 8절)에는 진행판 대신 검토서의 진행 칸을 같은 상태어로 갱신하고, [진행] 항목은 30분 안의 간격으로 마지막 신호를 고친다. 마지막 신호가 30분 넘게 지난 [진행]은 다음 실행과 검토하는 사용자가 멈춘 것으로 본다.