labrat

무엇인가

labrat은 Claude Code에 설치하는 플러그인으로, ML 연구 작업을 다루는 11개 스킬을 하나의 묶음으로 주입한다. 규율하는 영역은 논문 재현, 실험 설계, 학습 실행과 결과 비교, 논문 리뷰, 논문 검색이다. 각 스킬은 특정 작업을 대신 수행하는 스크립트가 아니라, 그 작업을 어떤 순서와 어떤 기준으로 처리할지 정한 방법이다. 따라서 에이전트는 사용자의 환경(wandb, neptune, 로컬 파일)에 맞는 코드를 직접 작성하되, 결과를 주장하기 전에 근거를 확인하는 단계를 반드시 거친다. 스킬은 사용자가 해당 작업을 서술할 때 시작되거나 /labrat: 접두 명령으로 직접 실행한다. 저장소가 내세우는 목표는 에이전트를 명령 실행기가 아니라 신중한 연구자처럼 동작하게 만드는 것이다. Claude Code에서는 결론을 실제 산출물과 대조하는 연구 피어 리뷰 훅이 함께 동작한다. 설치 한 번으로 Claude Code, Codex, Cursor, Gemini CLI가 같은 11개 스킬을 받지만, 연구 피어 리뷰와 알림은 Claude Code에서만 동작한다. 논문 검색 스킬만 Paper Search CLI(uv, Python 3.10+)를 요구하고 나머지는 추가 의존성이 없다.

어떻게 동작하나

이 규칙이 없을 때 나타나는 실패는 추상적인 품질 저하가 아니라 되돌릴 수 없는 자원 손실이다. 저장소는 2200건이 넘는 Claude Code·Codex 세션에서 나온 실제 사고를 근거로 든다. 에이전트가 'done?'을 'dont?'로 잘못 읽고 수천 개 파일 업로드를 시작한 사례, 참조 실행과 설정을 diff하지 않은 채 50시간 학습 작업을 재시작해 사흘을 잃은 사례가 있다. 또 아직 수렴하지 않은 대리 지표만 보고 하위 평가 결과가 나오기 전에 실험을 중단한 사례, 기억이 틀린 경로에 rm -rf를 실행해 로컬 체크포인트를 삭제한 사례도 있다. 공통점은 에이전트가 확인 가능한 증거를 건너뛰고 다음 행동으로 넘어간다는 것이다. 학습 재시작, 실험 중단, 파일 삭제는 되돌리는 비용이 크고, 잘못된 결론은 이후 실험 설계 전체를 오염시킨다. 연구 자동화에서 에이전트의 실수는 코드 오류보다 판단 순서의 누락에서 발생한다는 것이 이 스킬의 전제다. 그래서 labrat은 결과를 보고하는 시점과 실행을 시작하는 시점 양쪽에 검문을 둔다. 프록시 지표, 설정 파일, 경로처럼 사람이 당연히 확인하는 항목을 에이전트가 생략하는 것이 반복되는 원인이다.

무엇과 다른가

각 스킬은 명령 모음이 아니라 방법을 가르치는 형태로 쓰였다. 저장소는 스킬이 스크립트가 아니라 방법을 가르친다고 명시한다. 그래서 특정 도구에 종속된 실행 코드를 넣는 대신, 에이전트가 사용자의 스택에 맞춰 코드를 작성하되 지켜야 할 판단 기준을 남긴다. 하드 제약으로 남는 것은 되돌릴 수 없는 행동 앞의 확인 절차다. 학습 재시작 전 설정 diff, 실험 중단 전 지표 수렴 확인, 삭제 전 경로 검증처럼 실패 비용이 큰 지점에 검문을 배치한다. 반대로 구현 세부는 열어 둔다. wandb를 쓰든 로컬 파일을 쓰든 절차는 같아야 하기 때문이다. 모든 가드레일이 실제 실수에서 출발했다는 점도 설계 원리다. 추상적 모범 사례가 아니라 관측된 실패를 막는 최소 규칙만 남기고, 그 실패가 재현되지 않는 조건에서는 예외를 허용한다. 결과 비교 스킬이 같은 에폭 기준을 요구하는 것도 조건을 맞추지 않은 비교가 잘못된 결론을 낳기 때문이다. 규칙 문구가 짧고 단정적인 것도 에이전트가 해석 여지를 남기지 않게 하기 위해서다.

어떻게 쓰나

배포 형태는 플러그인이다. 마켓플레이스에 저장소를 등록하고 플러그인을 설치하면 스킬 묶음이 에이전트에 로드된다. Claude Code에서는 claude plugin marketplace add fcakyon/labrat 뒤 claude plugin install labrat@labrat을 실행한다. Codex, Cursor, Gemini CLI도 각각의 플러그인 명령으로 같은 11개 스킬을 받는다. 발동은 두 갈래다. 사용자가 논문 재현이나 실험 비교 같은 작업을 서술하면 해당 스킬이 시작되고, /labrat: 접두 명령으로 직접 호출할 수도 있다. Claude Code에서는 별도의 훅이 붙는다. 새 컨텍스트로 도는 연구 피어 리뷰 훅이 각 결론을 실제 산출물과 대조하고, 어긋나면 대응하는 스킬로 보낸다. 예를 들어 실행 전에는 런치 체크리스트로 유도한다. /labrat:setup은 감지된 환경을 보여주고 ntfy·Slack·이메일 알림, 명령 허용 목록, LaTeX 지원 같은 선택 기능을 켠다. 장시간 학습에는 /loop 30m 같은 주기 점검을 조합해 지표가 기준선을 넘거나 손실이 발산할 때 알림을 받는 구성이 제시된다.

전제와 한계

구성은 11개 스킬과 이를 보조하는 훅·설정 명령으로 나뉜다. 스킬 쪽은 논문 재현, 실험 설계, 학습 실행, 결과 비교, 논문 리뷰, 논문 검색이라는 연구 주기의 각 국면을 담당한다. 실행 전 단계에는 런치 체크리스트가 놓인다. 학습을 시작하기 전에 참조 실행과 설정을 대조하도록 유도하는 절차다. 결과 비교 스킬은 같은 에폭에서 나온 수치만 비교 대상으로 삼게 한다. 논문 리뷰는 주장과 근거의 대응을 확인하는 순서로 구성된다. 별도 스크립트 대신 절차 단계와 판단 기준을 텍스트로 두기 때문에, 사용자의 로깅 스택이 wandb든 neptune이든 로컬 파일이든 같은 순서가 적용된다. 보조 계층은 /labrat:setup이 담당한다. 이 명령은 감지된 환경을 출력하고 ntfy·Slack·이메일 알림, 명령 허용 목록, LaTeX 지원 같은 선택 기능을 켠다. 장시간 학습에는 /loop 30m 같은 주기 점검을 붙여 지표가 기준선을 넘거나 손실이 발산할 때 알림이 오게 한다. Claude Code에서는 연구 피어 리뷰 훅이 결론을 산출물과 대조하고 대응 스킬로 라우팅한다.

CLAUDE.md나 AGENTS.md 한 파일에 규칙을 몰아넣는 방식과 다르다. 단일 규칙 파일은 프로젝트 전반에 상시 적용되는 반면, labrat은 작업 종류별로 스킬을 분리해 해당 작업이 시작될 때만 로드한다. 프롬프트를 매번 직접 작성하는 방식과도 다르다. 프롬프트는 세션마다 다시 쓰고 잊히지만, 스킬은 파일로 남아 재현된다. 실행 코드를 넣은 자동화 스크립트와도 구분된다. 스크립트는 도구가 바뀌면 깨지지만, 방법을 텍스트로 두면 에이전트가 환경에 맞는 코드를 새로 쓴다. README는 이 저장소가 phd-skills의 후속이라고 밝힌다. phd-skills를 쓰던 사용자는 먼저 claude plugin uninstall phd-skills@phd-skills와 claude plugin marketplace remove phd-skills로 제거한 뒤 설치하라고 안내한다. 즉 단일 규칙 파일, 즉석 프롬프트, 도구 종속 스크립트, 선행 플러그인 네 가지와 각각 다른 지점에서 갈린다.

설치 경로는 에이전트마다 다르다. Claude Code는 claude plugin marketplace add fcakyon/labrat 후 claude plugin install labrat@labrat을 실행하고, 갱신은 claude plugin update labrat@labrat으로 한다. Codex는 codex plugin marketplace add와 codex plugin add labrat@labrat, 갱신은 codex plugin marketplace upgrade labrat이다. Cursor는 cursor-agent plugin marketplace add https://github.com/fcakyon/labrat로 등록한 뒤 cursor-agent에서 /plugin을 열어 설치한다. Gemini CLI는 저장소를 ~/.labrat에 클론하고 gemini extensions link ~/.labrat/plugin으로 연결한다. Claude.ai와 Claude Desktop은 Customize → Plugins → Add → Add marketplace → Add from a repository에서 fcakyon/labrat을 입력하고 Discover 탭에서 설치한다. 첫 사용에서는 /labrat:setup을 실행해 감지된 환경과 켜진 선택 기능을 확인하는 것이 출발점이다.

지원 범위에는 비대칭이 있다. 11개 스킬은 Claude Code, Codex, Cursor, Gemini CLI가 동일하게 받지만, 연구 피어 리뷰와 알림은 Claude Code에서만 동작한다. 논문 검색 스킬은 Paper Search CLI를 요구하며 uv와 Python 3.10 이상이 필요하다. 나머지 스킬은 추가 의존성이 없다. Claude.ai와 Claude Desktop 경로는 유료 플랜이 필요하고, 채팅에서 스킬이 실행되며 같은 계정으로 Claude Code에 로그인하면 플러그인이 동기화된다. Cursor는 갱신 절차가 번거롭다. cursor-agent plugin marketplace remove labrat으로 제거한 뒤 다시 등록하고 재설치해야 한다. Gemini CLI는 git pull로 갱신한다. 라이선스는 MIT다. 저장소가 명시하지 않은 동작, 예컨대 특정 실험 추적 도구에 대한 내장 연동은 기대할 수 없다. 연동 코드는 에이전트가 작성한다.

선택 기준은 작업의 되돌림 비용과 반복성이다. 학습 재시작, 실험 중단, 체크포인트 삭제처럼 실패 비용이 큰 작업을 에이전트에 맡긴다면 이 스킬을 쓴다. 논문 재현과 결과 비교처럼 절차가 반복되고 기준선 대조가 필요한 작업도 대상이다. 반대로 한 번 쓰고 버리는 스크립트 작성, 도구 설정 변경, 저장소에 남길 필요 없는 탐색적 실행에는 스킬 묶음을 설치할 이유가 적다. 프로젝트 규칙이 이미 CLAUDE.md에 촘촘히 정리되어 있고 연구 절차가 그 안에 포함되어 있다면 중복이 된다. Claude Code가 아닌 에이전트를 쓰면서 연구 피어 리뷰와 알림이 필요하다면, 11개 스킬은 받아도 그 두 기능은 동작하지 않으므로 기대를 조정해야 한다. 논문 검색이 핵심이라면 Paper Search CLI 설치가 선행 조건이다. 장시간 학습을 돌리는 환경이라면 /loop 주기 점검과 알림을 함께 켜는 조합이 실효가 크다.