APX Routines: 텍스트에는 exec_agent, 작업에는 super_agent를 사용하세요

가장 유용한 APX routine 결정은 가장 단순한 결정이기도 합니다. 모델이 텍스트를 작성하기를 원할 때는 exec_agent를 선택하고, routine이 실제로 작업을 수행해야 할 때는 super_agent를 선택하세요.

이 한 문장은 짧아 보이지만, 깔끔한 자동화와 지저분한 자동화를 가르는 차이입니다. APX routine은 APC project context 위에 위치하므로, 프로젝트 계약(contract)은 .apc/ 내에 이식 가능한 상태로 유지되는 한편, 런타임(runtime)은 예약된 작업(scheduled task)이 실제로 어느 정도의 권한을 필요로 하는지 결정합니다.

routine이란 무엇인가

routine은 APX 데몬(daemon)이 타이머에 따라 실행하는 예약된 작업입니다. 문서는 모델을 작고 명시적으로 유지합니다:

• heartbeat: 단순한 마커용
• shell: 일반적인 명령용
• exec_agent: 도구(tools) 없이 단일 LLM 호출용
• super_agent: 전체 도구 루프(tool loop)용
• telegram: 고정된 메시지용

이러한 분리는 적절하게 지루한 방식입니다. 이는 작성자가 모든 것을 하나의 모호한 "agent" 버튼 뒤에 숨기는 대신, 어떤 종류의 작업을 예약하고 있는지 명확히 말하도록 강제합니다.

exec_agent: 출력이 결과물일 때

routine이 산문, 요약, 요약본(digest) 또는 인간이나 다른 명령어가 소비할 다른 텍스트 조각을 반환해야 할 때 exec_agent를 사용하세요.

적합한 사례:

• 일일 상태 요약
• 아침 작업 요약본
• 변경 로그(changelog) 초안
• 짧은 Telegram 업데이트
• 이메일 작성 준비 완료된 텍스트
• 모델이 작동하는 것이 아니라 말해야 하는 모든 워크플로우(workflow)

핵심 속성은 exec_agent가 단 한 번의 모델 호출을 수행한다는 점입니다. 도구 루프(tool loop)도 없고, 숨겨진 부작용(side effects)도 없으며, MCP 서버를 돌아다니지도 않습니다.

작업이 기본적으로 "컨텍스트를 읽고 문단을 작성하라"인 경우 이것은 좋은 기본값입니다.

super_agent: routine이 행동해야 할 때

routine이 텍스트를 작성하는 것 이상의 일을 해야 할 때 super_agent를 사용하세요.

적합한 사례:

• 파일을 검사한 후 수정하기
• MCP 도구 호출
• 작업(tasks) 생성
• 동적인 Telegram 메시지 전송
• 결정 지점(decision points)과 함께 여러 단계 결합
• 프로젝트에서 입력을 수집한 후 조치 취하기

super_agent는 루프(loop) 내에서 동작하는 APX 그 자체입니다. 이 에이전트는 전체 도구 레지스트리(tool registry)를 가져오므로, 단순히 작업을 설명하는 것을 넘어 작업을 오케스트레이션(orchestrate)할 수 있습니다.

그러한 강력함은 유용하지만, 더 많은 복잡성을 초래합니다. 만약 루틴(routine)에 문장 하나만 필요하다면, 도구 접근 권한을 부여하는 것은 과잉(overkill)입니다.

명확한 규칙

제가 사용하는 규칙은 다음과 같습니다:

• 결과가 일반 텍스트(plain text)라면, exec_agent를 선택하세요.
• 루틴이 반드시 도구와 상호작용해야 한다면, super_agent를 선택하세요.
• 작업이 순수 셸(shell) 작업이라면, shell을 사용하세요.
• 메시지가 고정되어 있다면, telegram을 사용하세요.

여기서 APC가 중요한 이유는 루틴이 여전히 레포지토리(repo)로부터 프로젝트 컨텍스트(project context)를 읽기 때문입니다. APX는 이를 어떻게 실행할지만 결정합니다.

이러한 분리는 프로젝트 계약(project contract)을 이식 가능하게 유지하면서도, 런타임(runtime)은 주관적인(opinionated) 특성을 유지하게 합니다.

이중 메시지 함정

흔히 하는 실수 중 하나는 super_agent와 Telegram을 전송하는 post_commands 단계를 혼합하는 것입니다.

이 경우 두 개의 메시지가 생성될 수 있습니다:

• 에이전트 자체의 send_telegram 도구 호출(tool call)로부터 생성된 메시지 하나
• 셸 포스트(shell post) 단계로부터 생성된 메시지 하나

APX에는 피해를 줄이기 위한 억제(suppression) 로직이 있지만, 깔끔한 설계는 여전히 더 단순합니다. 즉, exec_agent가 메시지를 작성하게 하고, 그 다음 포스트 명령(post command)이 이를 한 번만 전송하게 하는 것입니다.

이것이 예약된 알림(scheduled notifications)을 위한 올바른 패턴입니다:

apx routine add daily-summary \
  --project my-app \
  --kind exec_agent \
...

만약 나중에 루틴에 도구 접근 권한이 필요해진다면, 의도적으로 super_agent로 전환하세요. 습관적으로 처음부터 super_agent로 시작하지 마세요.

이것이 APX를 유용하게 유지하는 이유

APX는 APC를 위한 일상적인 사용 런타임 계층(runtime layer)입니다. 이는 모든 자동화가 마치 미니 제품처럼 느껴지게 만들지 않으면서도, 프로젝트 컨텍스트를 구체적인 동작으로 전환해야 함을 의미합니다.

루틴 모델은 이를 잘 수행합니다:

• APC는 프로젝트 계약(project contract)을 저장합니다.
• APX는 런타임 상태(runtime state)를 저장합니다.
• 루틴은 일정(schedule)과 실행 스타일을 결정합니다.
• 에이전트 종류(agent kind)는 작업이 텍스트인지 작업(action)인지를 결정합니다.

이를 통해 통제력을 잃지 않으면서 실제 업무를 자동화할 수 있는 충분한 구조를 갖게 됩니다.

실질적인 요점

APX에서 예약된 워크플로(workflow)를 구축하고 있다면, 다음 순서로 시작하세요:

1. 루틴이 텍스트만 필요로 하는지 확인하세요.
2. 그렇다면, exec_agent를 사용하세요.
3. 그렇지 않다면, super_agent를 사용하세요.
4. 셸(shell) 작업에는 shell을 유지하세요.
5. 고정된 메시지에는 telegram을 유지하세요.

그러한 선택은 많은 우발적 복잡성(accidental complexity)을 제거해 줍니다.

그리고 이것이 더 깊은 핵심입니다: 최고의 자동화는 가장 강력한 자동화가 아닙니다. 작업에 딱 필요한 만큼의 런타임(runtime)만을 사용하는 자동화입니다.

APC는 컨텍스트(context)를 휴대 가능하게 유지합니다. APX는 액션(action)을 로컬(local)로 유지합니다. 루틴(Routines)은 정확히 그 경계에 위치하며, 그것이 바로 루틴이 작동하는 이유입니다.