브라우저 자동화 격리로 세션 충돌 없애고 확인 작업 속도 개선

브라우저 자동화 도구가 내 작업 세션이랑 충돌하는 건 꽤 오래된 문제였다. 새 탭을 열려다가 로그인 세션이 죽거나, Chromium 프로필 잠금이 걸려서 "닫고 다시 열어주세요" 같은 메시지가 뜨면 그냥 맥이 빠진다. 자동화 도구가 사람보다 빠르게 동작해야 하는데, 오히려 사람이 도구 뒤치다꺼리를 하고 있으면 뭔가 본말이 전도된 거다.

이번에 agent-browser 스킬을 새로 추가하면서 이 문제를 좀 제대로 잡았고, 같이 AGENTS.md 관리 방식도 손봤다. 작은 결정 두 가지인데, 체감 효과는 생각보다 컸다.

agent-browser 격리 구조와 폴백 순서

기존 방식의 문제는 단순했다. 브라우저 자동화 도구가 이미 열려 있는 내 세션에 붙어서 동작하니까, 탭을 열고 닫는 과정에서 상태가 꼬였다. 특히 로그인이 필요한 페이지를 건드릴 때 더 심해졌다. 새 컨텍스트를 만들려다 기존 컨텍스트가 날아가거나, 프로필 잠금 때문에 아예 시작도 못 하는 케이스가 반복됐다.

해결책은 별도 Chromium 인스턴스를 띄우는 것이었다. 메인 세션이랑 완전히 분리된 프로세스로 실행하면 두 작업이 서로 모르는 상태로 병렬 동작할 수 있다. 이렇게 격리하면 하나가 죽어도 다른 쪽엔 영향이 없다.

다만 격리 인스턴스가 항상 준비돼 있다고 보장할 수 없으니, 스킬 본문에 폴백 순서를 명시적으로 박아뒀다.

1) 새 탭 추가 → navigate
2) 같은 탭 navigate
3) incognito context
4) agent-browser(별도 인스턴스)로 전환

이 순서가 중요한 이유는 "어떻게 우회하지"를 매번 생각하지 않게 만들기 때문이다. 상황에 따라 달리 판단하면 일관성이 없고, 결국 실패했을 때 로그가 읽기 어려워진다. 순서가 고정돼 있으면 4번까지 다 실패한 경우에만 에러를 올리면 되고, 그게 아니면 그냥 다음 단계로 넘어간다. 스킬이 절차를 강제하는 구조다.

실제로 써보니 "브라우저 닫혀 있는데 어떻게 할까요" 류의 질문이 끼어드는 빈도가 눈에 띄게 줄었다. 확인 작업이 중간에 막히지 않으니 결과 보고까지 흐름이 끊기지 않는다.

부작용은 두 가지였다.

동시 작업을 여러 개 돌리면 격리 인스턴스가 누적돼서 메모리가 튄다. 작업 종료 시 정리 훅을 붙여서 막았다.
스킬 본문이 길어지면 컨텍스트 토큰 비용이 같이 늘어난다. 폴백 순서를 4줄짜리 목록으로 압축했더니 어느 정도 잡혔다.

메모리 쪽은 훅으로 해결됐지만, 토큰 비용은 트레이드오프가 남아 있다. 스킬 본문이 길수록 맥락은 명확해지고, 짧을수록 해석 여지가 생긴다. 지금은 "최소한 폴백 순서만큼은 명시"라는 선에서 타협하고 있다.

AGENTS.md를 실제 파일로 박은 이유

원래 AGENTS.md는 다른 문서를 참조하는 형태로 관리하고 있었다. 소스는 한 곳에 두고, AGENTS.md는 그걸 가리키는 방식. 이론적으로 깔끔하고, 수정이 생겼을 때 한 곳만 고치면 되니까 관리도 편하다.

근데 현실에서 도구 체인이 그 참조를 따라가지 못하는 케이스가 자꾸 생겼다. 링크가 깨지거나, 링크를 무시하고 파일 자체만 읽거나, 심한 경우엔 참조 대상 파일이 있는지조차 확인을 못 하는 도구도 있었다. 결과는 매번 같았다. 도구가 잘못된 컨텍스트로 동작하고, 나중에 원인 찾는 데 시간을 쓴다.

구분	이전(참조 방식)	변경 후(실제 텍스트)
도구 호환	일부 실패	전부 성공
추적·diff	참조 대상 파일 따로 봐야 함	파일 하나에서 완결
동기화	소스 수정 시 자동 반영	수동 (변경 빈도 낮아서 감수)
디버깅	링크 추적 필요	텍스트 그대로 읽으면 됨

동기화가 수동이 된다는 건 분명 단점이다. 소스가 바뀌면 AGENTS.md도 따로 고쳐야 한다. 그런데 실제로 이 내용이 바뀌는 빈도가 낮아서, 추상화 계층 하나가 주는 관리 편의보다 도구 호환 문제를 없애는 게 더 값어치 있다는 판단이 들었다.

추적·검색·diff 전부 실제 텍스트일 때 가장 단순하다. 링크를 따라가야 내용을 알 수 있는 구조보다, 파일 하나 열면 그 자리에서 읽을 수 있는 구조가 디버깅 시간을 아낀다. 추상화를 한 단계 줄였더니 생각지 못했던 곳에서도 편해졌다.

정리하면서 든 생각

이번 작업에서 공통적으로 나온 결론이 하나 있다면, "겉모양 깔끔함"보다 "도구가 그대로 읽을 수 있음"이 실용적으로 더 중요하다는 거다.

참조 링크는 깔끔하게 보이지만 도구가 못 읽으면 소용없다. 브라우저 자동화도 세션 공유가 이론적으로 효율적으로 보이지만, 충돌이 생기면 오히려 손이 더 간다. 간단함이 좋은 설계처럼 보여도, 그 간단함이 실제 사용 환경에서 유지되지 않으면 그냥 기술 부채다.

폴백 순서를 스킬에 박아두는 것도 비슷한 맥락이다. "알아서 판단"보다 "이 순서대로 시도"가 예측 가능하고, 실패했을 때 어디서 막혔는지 바로 알 수 있다. 도구가 자율적으로 판단하게 두는 게 능사가 아닐 때가 있다. 특히 실패 경로가 명확할 때는 그 경로를 그냥 코드로 적어두는 게 낫다.