에이전트 기반 연구 워크플로

작업 흐름

왜 필요한가. "이 모델의 ablation을 해 줘"라는 요청 한 줄을 받은 에이전트는 많은 것을 스스로 정한다. 어떤 요소를 뺄지, 몇 개의 seed로 돌릴지, 무엇으로 비교할지, 결과가 애매하면 무엇을 더 해 볼지. 이 결정들 하나하나가 결론을 바꾼다. 결정이 사람 모르게 내려지면, 결과를 받은 사람은 그것이 어떤 실험인지 모른 채 결론만 받는다.

정의. 에이전트 작업을 다섯 단계로 나누고, 단계 사이에 사람이 확인하는 지점을 둔다.

이 책의 저장소가 쓰는 흐름도 같은 모양이다(editorial/workflow.md §4). 사람이 Issue를 승인하고, 에이전트가 branch에서 작업해 검사(book.py check, 실습 코드 실행)를 통과시키고 PR을 열면, 사람이 리뷰해 merge한다. 그리고 장의 status로 승인 단계를 표시한다. 에이전트는 draft까지만 올릴 수 있고, review와 done은 사람이 올린다. 누가 어디까지 결정할 수 있는지를 상태 값으로 드러낸 것이다.

승인 지점을 어디에 둘까. 기준은 되돌리기 어렵거나, 비용이 크거나, 결론을 정하는 곳이다.

• 계획 승인. 구현 전에 계획을 받는 것이 가장 싼 검증이다. 잘못된 비교 기준이나 빠진 조건을 이 단계에서 잡으면 몇 시간의 계산을 아낀다. 계획에는 실행할 명령과 예상 시간·자원도 들어가게 한다.
• 비싼 실행 전. GPU 수십 시간이 드는 실행, 유료 API 호출, 공유 자원의 대기열을 오래 차지하는 작업.
• merge 전. main은 이후 모든 실험의 출발점이다.
• 최종 평가 전. test set 평가는 한 번만 한다(아래 연구 무결성 절).

반대로 파일 읽기, 자기 작업 공간에서의 테스트 실행처럼 되돌릴 필요가 없는 일마다 승인을 요구하면 승인이 형식이 된다. 하루에 승인 버튼을 수백 번 누르는 사람은 정작 중요한 승인도 읽지 않고 누른다.

보고의 형식. 에이전트의 작업 보고는 리뷰할 수 있는 형태여야 한다. 지침 파일(4.4장)에 보고 형식을 정해 둔다. 이 장의 실습 지침은 "실행한 명령 전체, 결과 표, 바꾼 파일 목록을 보고한다"고 쓴다. 이 책의 집필 에이전트들도 장마다 절 수, 실행 블록 수, 퀴즈 수, 검사 결과, 확인 필요 목록(직접 확인하지 못한 사실)을 보고한다. 확인 필요 목록은 에이전트가 모르는 것을 모른다고 말하게 하는 장치다.

격리

왜 필요한가. 에이전트 둘이 같은 디렉터리에서 일하면 한쪽의 변경이 다른 쪽의 실험에 섞인다. 한 에이전트가 설정 파일을 고치는 동안 다른 에이전트가 그 파일로 학습을 시작할 수 있고, 어느 결과가 어느 코드에서 나왔는지 알 수 없게 된다. 사람과 에이전트가 같은 디렉터리를 쓸 때도 마찬가지다. 격리는 세 수준으로 한다.

branch. 작업마다 branch를 하나 쓴다(4.2장의 "한 작업 = 한 branch = 한 PR"). 변경이 commit으로 남으므로 결과와 코드의 대응이 분명해지고, 실패한 시도는 branch째 버리면 된다. 하지만 branch만으로는 부족하다. 작업 디렉터리가 하나뿐이면 한 번에 한 branch만 checkout할 수 있기 때문이다.

worktree. git worktree는 한 저장소에 작업 디렉터리를 여러 개 붙인다. 각 worktree는 자기 branch를 checkout하고 자기 working tree와 index를 갖지만, 객체 데이터베이스와 branch 이름표는 하나를 공유한다.

# 집필 시점 예시
git worktree add ../exp-dropout -b exp/dropout       # 새 디렉터리에 새 branch
git worktree add ../exp-lr -b exp/lr
git worktree list                                    # 모든 worktree와 각자의 branch
# ... 각 디렉터리에서 에이전트가 작업하고 commit ...
git merge exp/dropout                                # 원래 디렉터리에서 바로 merge할 수 있다
git worktree remove ../exp-dropout                   # 끝난 worktree 정리

한 worktree에서 만든 commit은 공유된 객체 데이터베이스에 들어가므로 다른 worktree에서 바로 보이고 merge할 수 있다. clone을 여러 개 만드는 것보다 디스크를 덜 쓰고, push·fetch 없이 결과를 합칠 수 있다. 주의할 점도 있다. 같은 branch를 두 worktree에서 동시에 checkout할 수 없다(Git이 거부한다). 그리고 stash처럼 저장소 단위로 공유되는 것은 worktree 사이에서도 공유되므로, 여러 에이전트가 동시에 stash를 쓰면 서로의 것을 꺼낼 수 있다. 이 책의 저장소는 에이전트의 worktree를 .claude/worktrees/ 아래에 만들고, 이 경로를 .gitignore에 넣어 두었다. 이 책의 초고를 쓸 때는 에이전트마다 하나의 부를 맡기고, 각자의 worktree에서 고쳐도 되는 디렉터리와 통과시켜야 할 검사를 지정한 뒤, 끝난 branch를 사람이 합쳤다.

실험 출력도 격리한다. worktree가 달라도 실험이 같은 출력 경로(공유 storage의 results/)에 쓰면 결과가 섞인다. 출력 경로에 branch 이름이나 commit id를 넣는다. 실행 기록에는 commit id와 "commit하지 않은 변경이 있었는지"를 함께 남긴다(4.1장의 분야 예시).

컨테이너. 실험마다 다른 의존성 버전이 필요하거나, 에이전트가 시스템 패키지를 설치하는 일이 있다면, 실행 환경 자체를 컨테이너로 격리한다(3.5장). 컨테이너는 에이전트가 할 수 있는 일의 경계도 된다. 마운트한 디렉터리만 보이고, 네트워크를 끊거나 제한할 수 있다. 원본 데이터는 읽기 전용으로 마운트한다.

실행 위치

에이전트가 어디서 실행되는가에 따라 그것이 볼 수 있는 파일, 쓸 수 있는 자원, 가진 자격 증명이 달라진다.

로컬. 설정이 가장 단순하지만, 에이전트가 내 계정의 권한으로 실행된다는 점을 잊기 쉽다. 저장소 밖의 파일(다른 프로젝트, 개인 문서, 자격 증명 파일)에도 닿을 수 있다. 도구의 권한 설정으로 작업 디렉터리 밖의 접근과 위험한 명령을 제한하고, 필요하면 컨테이너 안에서 실행한다.

원격 서버. 데이터와 GPU가 서버에 있으면 에이전트도 서버에서 실행하는 것이 자연스럽다. SSH 연결이 끊겨도 세션이 이어지도록 tmux 같은 terminal multiplexer를 쓰는 것은 사람의 작업과 같다(2.2장). 공유 서버라면 에이전트가 띄운 프로세스가 다른 사람의 GPU를 차지하지 않는지, 공유 디렉터리에 무엇을 쓰는지를 지침과 권한으로 정한다.

클라우드 에이전트. 일부 서비스는 에이전트를 서비스가 관리하는 격리된 환경에서 실행한다. 저장소를 그 환경에 clone하고, 작업 결과를 branch나 PR로 돌려준다. 내 컴퓨터를 켜 두지 않아도 되고, 여러 작업을 병렬로 돌리기 쉽다. 대신 코드와 데이터가 그 환경에서 처리된다. 비공개 데이터, 개인정보, 공동 연구 계약으로 반출이 제한된 데이터라면 그 환경에서 처리해도 되는지 먼저 확인한다. 그 환경에 넣는 자격 증명과 열어 주는 네트워크 범위도 최소로 둔다.

다른 기기에서 원격 제어. 실행 위치와 조작 위치는 다를 수 있다. 서버나 클라우드에서 실행 중인 에이전트 세션을 휴대 기기나 웹 브라우저에서 확인하고 승인하는 방식이 여러 도구에서 제공된다. 긴 실험을 걸어 두고 이동 중에 계획을 승인하거나 결과를 볼 수 있어 편하다. 이때도 승인의 기준은 같다. 작은 화면에서 diff를 대충 넘기며 merge를 승인하는 일은 피하고, 원격에서는 계획 승인과 진행 확인처럼 판단이 간단한 승인만 한다. 구체적인 설정 방법과 지원 범위는 도구마다 다르고 빠르게 바뀌므로 도구 문서에서 확인한다.

권한 경계

세 종류의 행동. 에이전트의 행동을 영향 범위로 나누면 승인 정책이 정리된다.

외부 작업이 핵심이다. 코드 변경과 실험은 격리하면 대부분 되돌릴 수 있다. 외부 작업은 다른 사람의 공간을 바꾼다. 원격 저장소에 push된 commit은 다른 사람이 받고, 보낸 메시지는 회수할 수 없고, 지운 공유 데이터는 백업이 없으면 끝이다. 그리고 4.5장에서 본 것처럼 에이전트는 외부 텍스트의 지시에 속을 수 있으므로, 외부 작업의 권한은 "에이전트가 속았을 때 무엇이 가능한가"를 기준으로 정한다.

권한을 구현하는 방법. 4.4장의 층 구분을 다시 쓴다.

• 도구의 권한 설정. 승인 없이 허용할 명령, 매번 물을 명령, 금지할 명령을 정한다. 이 책의 저장소는 .claude/settings.json에서 저장소 자체의 검사·생성 명령(python3 scripts/book.py check 등)만 사전 허용한다. 허용 목록은 좁게 시작해 필요할 때 넓힌다.
• 자격 증명의 범위. 에이전트 환경에 둔 토큰이 push 권한이 없으면 push는 일어날 수 없다. 읽기 전용 토큰, 저장소 하나에만 유효한 토큰, 만료 기간이 있는 토큰.
• 저장소 보호. main의 branch 보호(PR 필수, 리뷰 승인 필수, force push 금지)는 사람과 에이전트 모두에게 적용된다.
• 실행 환경. 컨테이너의 마운트와 네트워크 제한, 클라우드 환경의 네트워크 허용 목록.

연구 무결성

왜 필요한가. 연구 무결성(research integrity)의 위험은 에이전트를 쓴다고 새로 생기는 것이 아니다. 데이터 조작, test set 누수, 선택적 보고는 사람도 한다. 에이전트가 바꾸는 것은 규모와 가시성이다. 에이전트는 사람보다 훨씬 많은 시도를 하고, 그 시도의 대부분을 사람이 보지 않는다. "결과가 나올 때까지 이것저것 해 보라"는 요청은 의도하지 않은 p-hacking을 자동화한다.

test set 누수. 가장 흔한 형태는 에이전트가 test set으로 평가하면서 설정을 고르는 것이다. 학습에 test 데이터를 쓰지 않았더라도, 선택에 쓰면 test 정보가 결과에 들어간다. 모든 설정의 실제 정확도가 똑같이 0.70인 상황을 시뮬레이션해 본다. test 표본은 200개다.

import numpy as np

rng = np.random.default_rng(0)
n_configs, n_test, p_true = 50, 200, 0.70        # 모든 설정의 실제 정확도는 똑같이 0.70

test_acc = rng.binomial(n_test, p_true, size=n_configs) / n_test     # (n_configs,)
best = np.argmax(test_acc)                        # test 결과를 보고 가장 좋은 설정을 고른다
fresh = rng.binomial(n_test, p_true) / n_test     # 고른 설정을 새 데이터로 다시 평가
print(f"고른 설정의 test 정확도   {test_acc[best]:.3f}")
print(f"같은 설정, 새 데이터      {fresh:.3f}")
print(f"설정 50개 test 정확도 평균 {test_acc.mean():.3f}")

고른 설정의 test 정확도   0.810
같은 설정, 새 데이터      0.720
설정 50개 test 정확도 평균 0.703

설정 사이에 실제 차이가 전혀 없는데도, test 결과로 고른 설정은 0.81을 기록했다. 같은 설정을 새 데이터로 평가하면 0.72로, 참값 근처로 돌아온다. 0.81과 0.70의 차이는 전부 200개 표본의 우연한 변동을 골라낸 결과다. 편향의 크기는 시도 횟수에 따라 커진다.

for k in [1, 5, 20, 100]:
    acc = rng.binomial(n_test, p_true, size=(2000, k)) / n_test      # (반복, 설정 수)
    print(f"설정 {k:3d}개 중 최고: 평균 {acc.max(axis=1).mean():.3f}")

설정   1개 중 최고: 평균 0.701
설정   5개 중 최고: 평균 0.737
설정  20개 중 최고: 평균 0.759
설정 100개 중 최고: 평균 0.779

사람은 하루에 설정 몇 개를 시도하지만 에이전트는 백 개를 시도할 수 있다. 시도 백 번이면 아무 개선이 없어도 평균 8%p쯤 좋아 보이는 결과가 나온다. 방어 원칙은 사람의 실험과 같지만, 에이전트에게는 장치로 강제해야 한다.

• 설정 선택은 validation(또는 train 안의 교차검증)으로만 한다. test는 계획이 확정된 뒤 한 번 쓴다(15.4장, 23.5장).
• 에이전트의 작업 환경에서 test 라벨에 접근할 수 없게 한다. 가능하면 test 평가 스크립트를 에이전트의 권한 밖에 둔다.
• test 평가는 실행할 때마다 기록을 남긴다(이 장의 실습은 test_access.log에 시각·commit·설정을 쓴다). 리뷰에서 기록 수를 확인한다.
• 공개 benchmark라면, 에이전트가 웹이나 문헌 검색으로 benchmark의 정답이나 test 데이터를 찾아 쓰지 않았는지 확인한다.

데이터·결과 조작 방지. 에이전트는 목표를 달성하려는 방향으로 움직인다. "테스트를 통과시켜라"는 요청에 테스트를 고치듯이(4.3장), "결과 표를 갱신하라"는 요청에 결과 파일을 직접 고치거나, 이상한 측정값을 "정리"하며 지울 수 있다. 악의가 없어도 일어난다. 다음을 규칙과 장치로 둔다.

• 원본 데이터는 읽기 전용. 파일 권한, 읽기 전용 마운트, 읽기 전용 DB 계정으로 강제한다.
• 결과는 스크립트로만 만든다. 표·그림·숫자는 commit된 코드를 실행해서 만들고, 손으로(에이전트의 손으로도) 고치지 않는다. 리뷰에서 결과 파일이 실행 기록과 대응하는지 확인한다.
• 이상치 제거는 사람이 결정한다. 데이터를 빼는 규칙은 분석 전에 정하고 기록한다(23.5장).

에이전트 작업 기록. 리뷰하려면 기록이 있어야 한다. 무엇을 남길지는 다음과 같다.

• commit. 변경은 작은 commit으로, 메시지에 이유를 쓴다. 이 책 저장소의 commit은 에이전트가 만든 경우 메시지 끝에 공동 작성자 표시와 작업 세션을 가리키는 줄을 남긴다. 사람이 commit만 보고도 어느 세션의 작업인지 추적할 수 있게 하기 위해서다.
• 실행 기록. 실행한 명령, commit id, seed, 데이터 분할의 지문(fingerprint), 결과. 이 장의 실습 코드는 test 분할의 해시를 매 실행 출력에 넣어, 분할이 바뀌지 않았음을 리뷰어가 확인할 수 있게 한다.
• 대화·작업 로그. 도구가 세션 기록을 남긴다면, 계획과 승인, 실패한 시도가 무엇이었는지 확인할 수 있게 보관한다.
• 보고. 결과뿐 아니라 시도했다가 버린 것, 확인하지 못한 것을 함께 보고하게 한다.