서브에이전트 제어 필드 4종 완전 해부 — permissionMode · memory · isolation · background

지난 글에서 서브에이전트 정의 파일의 frontmatter 8개 필드 중 "핵심 4개"(name·description·tools·model)를 다뤘다. 이번 글은 나머지 "제어 4개"를 파고든다. 핵심 4개가 "이 에이전트를 언제 켜고 무엇을 시킬지"를 정한다면, 제어 4개는 "켜진 에이전트를 어떤 환경에서 어떻게 굴릴지"를 정한다. 평소엔 생략해도 되지만, 한 번 필요해지면 이 필드 없이는 문제를 풀 수 없다.

제어 필드 4개가 푸는 4가지 문제

네 필드는 각각 권한·기억·공간·시간이라는 서로 다른 축을 다룬다. 하나씩 보면 모두 "기본값으로 두면 안전하지만 답답하고, 바꾸면 강력하지만 조심해야 하는" 트레이드오프를 담고 있다. 어디서 기본값을 깨야 하는지가 이 글의 핵심이다.

permissionMode — 확인의 빈도를 조절하는 손잡이

서브에이전트가 파일을 고치거나 명령을 실행할 때마다 사람에게 "이거 해도 될까요?"를 물으면 안전하지만 느리다. 반대로 다 알아서 하면 빠르지만 위험하다. permissionMode는 이 빈도를 조절하는 손잡이다.

▲ permissionMode 3단계 — default(매번 확인) → acceptEdits(편집만 자동) → bypass(대부분 자동)

왜 이 손잡이가 필요한가. 같은 도구라도 작업 성격에 따라 위험도가 다르기 때문이다. 아래는 "어떤 에이전트에 어떤 모드가 맞는지"의 판단 흐름이다.

▲ 판단 흐름 — "되돌리기 어려운 작업이 섞이는가"가 acceptEdits와 bypass를 가르는 분기

핵심은 "비가역성"이다. 파일 편집은 git이 있으면 되돌릴 수 있으니 자동 승인해도 부담이 작다. 하지만 삭제·배포·외부 전송처럼 되돌리기 어려운 작업은 빠르다는 이유로 확인을 건너뛰면 안 된다. permissionMode를 올릴 때는 "이 에이전트가 할 수 있는 가장 위험한 작업"을 기준으로 판단한다.

memory — 세션이 끝나도 살아남는 기억

기본적으로 서브에이전트는 대화가 끝나면 모든 것을 잊는다. 매번 백지에서 시작한다. memory 필드는 이 휘발성을 깨고, 에이전트가 작업하면서 얻은 사실·선호·맥락을 다음 세션으로 넘긴다.

▲ memory 없음 — 같은 사실을 매 세션 다시 알아내는 낭비

▲ memory 있음 — 한 번 알아낸 사실이 다음 세션의 출발점이 됨

참고로 memory의 기본값은 "비활성"이다. frontmatter에 memory: 줄이 없으면 에이전트는 매번 백지로 시작한다 — 별도의 "끄기" 옵션이 따로 있는 게 아니라, 필드를 적지 않는 것이 곧 비활성이다. 활성화하려면 다음 중 하나의 scope를 명시한다.

scope는 "같은 사실이라도 어디까지 따라다녀야 하는가"를 정한다. 셋 다 저장 위치가 다르고, 따라서 누구에게 보이고 어디까지 살아남는지가 다르다.

▲ memory scope — 사실의 유효 범위에 따라 user / project / local로 분리

scope를 잘못 고르면 두 가지 사고가 난다. 개인 선호를 project에 저장하면 다른 사람에게 강요되고, 프로젝트 규칙을 local에 저장하면 다음 머신에서 사라진다. "이 기억이 어디까지 따라가야 하는가"를 먼저 묻고 scope를 정한다. 잘 쓰면 memory는 에이전트가 같은 실수를 반복하지 않게 하는 학습의 토대가 된다.

isolation — 메인 작업 공간을 건드리지 않는 격리실

여러 에이전트가 동시에 같은 파일을 고치면 서로의 변경을 덮어쓴다. isolation: worktree는 에이전트마다 Git worktree(같은 저장소의 독립된 작업 복사본)를 따로 떼어 줘서, 각자 자기 공간에서만 일하게 만든다.

▲ isolation 없음 — 동시 수정이 같은 작업 공간에서 충돌

▲ isolation: worktree — 에이전트마다 독립 복사본, 충돌 없이 병렬 수정

다만 worktree는 공짜가 아니다. 만들고 지우는 데 시간과 디스크가 든다. 그래서 "언제 격리가 값을 하는지" 판단이 필요하다.

▲ 판단 흐름 — "동시 + 같은 파일"일 때만 worktree 비용이 정당화됨

isolation은 병렬 수정 작업의 안전장치다. 코드 마이그레이션처럼 수십 개 파일을 여러 에이전트가 동시에 고치는 상황에서 진가를 발휘한다. 반대로 읽기 전용 리뷰어나 단독 작업 에이전트에는 격리 비용만 늘 뿐 이득이 없다. 변경이 없으면 worktree가 자동 정리되므로, 의심스러우면 충돌 위험이 있는 쪽에만 켠다.

background — 기다리지 않고 병렬로 굴리는 비동기 실행

긴 작업을 시키고 그게 끝날 때까지 메인이 멈춰 기다리면 시간이 아깝다. background: true는 에이전트를 백그라운드로 떼어내, 메인이 다른 일을 하는 동안 따로 돌게 한다. 끝나면 알림이 온다.

▲ background 없음 — 에이전트가 끝날 때까지 메인이 멈춰 대기

▲ background: true — 에이전트를 떼어내고 메인은 멈춤 없이 계속

background가 진짜 이득을 주려면 작업들 사이에 의존성이 없어야 한다. A의 결과가 B의 입력이라면 병렬로 돌려봐야 소용없다. 아래가 그 판단이다.

▲ 판단 흐름 — "오래 걸림 + 결과가 당장 안 필요"가 background의 조건

background는 독립적이고 긴 작업을 겹쳐 돌릴 때 전체 시간을 줄인다. 대규모 테스트 실행, 긴 빌드, 여러 영역을 동시에 훑는 탐색이 대표적이다. 반대로 결과를 바로 이어 써야 하는 순차 작업이라면 비동기로 만들 이유가 없다. "기다리는 시간이 정말 낭비인가"를 먼저 확인한다.

네 손잡이를 함께 읽기 — 같은 축, 같은 트레이드오프

▲ 네 필드의 공통 구조 — 기본값은 단순·안전, 격상은 강력하지만 비용 동반

네 제어 필드는 모두 같은 모양이다. 기본값은 단순하고 안전한 쪽이고, 값을 바꾸면 강력해지는 대신 비용이나 위험이 따라온다. 그래서 원칙은 하나다 — 필요해지기 전까지는 기본값을 두고, 구체적인 문제(확인이 진짜 병목이다 / 같은 사실을 매번 다시 알아낸다 / 동시 수정이 충돌한다 / 긴 작업을 기다리느라 멈춘다)가 생겼을 때만 해당 손잡이를 올린다. 핵심 4개가 에이전트의 정체성을 정한다면, 제어 4개는 그 에이전트를 현실의 제약 속에서 효율적으로 굴리는 운영의 손잡이다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.