30분에서 8분으로: LLM-Mode Reflect가 작동하는 방식

이 글은 AI 코딩 에이전트(AI coding agents)가 의존하는 점점 늘어나는 기술, 스크립트, 그리고 컨텍스트(context)를 관리하는 시리즈의 13번째 파트입니다. 10부에서는 전체 개선 파이프라인(improve pipeline) — 5개 단계 전체와 그 연결 방식 — 을 다루었습니다. 14부에서는 하드웨어 벤치마크와 해당 빈도에서 발생하는 신뢰성 버그를 포함하여, 하루 48회 실행이 실제로 어떻게 이루어지는지를 다룹니다.

akm improve 내부의 reflect 패스(reflect pass)에는 세 가지 실행 모드가 있습니다. 대부분의 설치 환경은 여전히 가장 느린 모드로 실행되고 있습니다.

Agent 모드 — 오리지널 방식 — 는 각 reflect 호출마다 opencode 또는 Claude 서브프로세스(subprocess)를 생성합니다. 서브프로세스는 콜드 스타트(cold start) 상태로 시작하여, 세션을 획득하고, 컨텍스트를 조립하며, LLM 호출을 수행한 뒤 종료됩니다. 이러한 콜드 스타트 오버헤드(overhead)는 실재합니다. 조용한 상태의 머신에서 각 호출은 약 30초가 소요됩니다. 69개의 리파인먼트(ref)가 쌓인 스태시(stash)에 대해 akm improve를 실행하면, reflect 단계에서만 약 35분이 소요됩니다.

SDK 모드는 서브프로세스를 제거했습니다. reflect 호출이 프로세스 내부(in-process)에서 실행되어, 호출당 지연 시간(latency)을 10~~15초로 단축했습니다. 69-ref 실행 시간은 12~~17분으로 줄어들었지만, 여전히 reflect 작업에 실제로 필요하지 않은 왕복(round-trip) 오버헤드에 의해 제한됩니다.

LLM 모드는 왕복 과정을 완전히 제거합니다. reflect를 위한 컨텍스트가 정적으로 미리 조립되어 있어 — 실시간 도구 호출(tool calls), 파일 읽기, 외부 컨텍스트가 필요하지 않습니다. LLM 엔드포인트(endpoint)로의 직접적인 HTTP 호출만으로 충분하며, 호출당 6~~10초가 소요됩니다. 69-ref 실행은 8~~10분 만에 완료됩니다.

모드	호출당 지연 시간	69-ref 실행 시간
agent (CLI 서브프로세스)	~30초	~35분
...
3~4배의 엔드 투 엔드(end-to-end) 개선은 reflect가 수행하는 작업에 전혀 필요하지 않았던 오버헤드를 제거함으로써 이루어졌습니다.

Reflect에 Agent가 필요하지 않은 이유

reflect 패스는 stash 자산을 가져와 현재 콘텐츠를 검토하고, 개선된 버전을 제안합니다. 패스가 시작되기 전에 입력값(asset text, metadata, improvement prompt)은 고정됩니다. 호출 중간에 변경되는 것은 아무것도 없습니다. 파일을 열 필요도 없고, 검색 쿼리를 실행할 필요도 없으며, 외부 컨텍스트를 가져올 필요도 없습니다.

agent 모드는 akm의 improve 파이프라인이 처음 구축되었을 때 유용했습니다. 당시에는 agent 서브프로세스(subprocess)가 이미 주요 실행 모델이었고, reflect는 그에 따라 구현되었기 때문입니다. 하지만 에이전트를 가치 있게 만드는 특성들(도구 사용 (tool use), 실시간 컨텍스트 접근 (live context access), 변화하는 상태에 대한 다단계 추론 (multi-step reasoning))은 reflect에서 활용되지 않습니다. 상태가 없는 추론 호출 (stateless inference call)을 위해 전체 에이전트 프로세스를 생성하는 것은 품질상의 이점 없이 20초 이상의 오버헤드만을 초래합니다.

LLM 모드는 실행을 작업에 맞게 최적화합니다: 컨텍스트를 한 번 조립하고, 한 번의 HTTP 호출을 수행하여, 결과를 얻습니다.

Multi-Turn Self-Refine

LLM 모드는 agent 모드에는 없는 기능인 다회차 자기 개선 (multi-turn self-refine) 능력을 추가합니다.

reflect가 LLM 모드에서 실행될 때, 초기 초안을 어시스턴트 턴 (assistant turn)으로 다시 보냅니다. 모델은 자신의 이전 출력물과 개선 프롬프트 (refine prompt)를 동일한 컨텍스트 창 (context window) 내에서 함께 보게 됩니다. 이는 반복적 생성 (iterative generation)을 위한 표준적인 다회차 패턴입니다. 모델은 두 번째 최상위 호출을 요구하지 않고도 불일치를 포착하고, 추론을 강화하며, 초안을 개선할 수 있습니다.

반면, agent 모드는 프롬프트 텍스트를 통해 컨텍스트를 앞으로 전달합니다. 각 서브프로세스 실행은 새로 시작됩니다. 추론의 근거로 삼을 대화 기록 (conversation history)이 존재하지 않습니다.

실질적인 차이는 더 길거나 복잡한 자산에서 나타납니다. 단일 순방향 패스 (forward pass)가 불일치가 포함된 초안을 생성하더라도, 모델은 자신의 출력을 보는 즉시 이를 포착할 수 있습니다. 다회차 자기 개선 (multi-turn self-refine)은 단일 reflect 호출 내부에서 이 과정을 처리합니다.

Structured Output

프로필 설정에서 supportsJsonSchema: true를 지원한다고 광고하는 제공업체의 경우, LLM 모드는 구조화된 JSON 출력을 요청합니다. 응답은 제안으로 수락되기 전에 reflect 출력 스키마 (output schema)에 따라 검증됩니다.

이는 모델이 잘 짜여진 산문(prose)을 반환하더라도, 섹션 마커나 포맷팅이 예상되는 출력 형태(output shape)와 일치하지 않을 때 발생하는 일련의 파싱 실패(parse failures)를 제거합니다. 모델은 응답을 생성하기 전에 스키마(schema)를 알고 있으므로, 사후 파싱(post-hoc parsing)되는 대신 출력이 스키마를 준수하게 됩니다.

에이전트 모드(Agent mode)는 파이프라인이 휴리스틱(heuristics)을 사용하여 파싱하는 비구조화된 텍스트를 생성합니다. supportsJsonSchema: true를 사용하는 LLM 모드는 이러한 휴리스틱을 제거합니다.

LLM 모드 활성화를 위한 설정

LLM 모드를 사용하려면 Config v2 (configVersion: "0.8.0")가 필요합니다. 아직 마이그레이션(migration)을 완료하지 않았다면 다음을 수행하세요:

# 변환 내용 미리보기
akm config migrate --dry-run

...

v2가 적용된 상태에서, 이름이 지정된 LLM 프로필(profile)을 추가하고 reflect 프로세스가 이를 가리키도록 설정합니다:

{
  "configVersion": "0.8.0",
  "profiles": {
...

이것이 변경 사항의 전부입니다. 다음 akm improve 실행 시, reflect는 서브프로세스(subprocesses)를 생성하는 대신 openai-mini 프로필로 HTTP 호출을 보냅니다. 제안 큐(proposal queue), 리뷰 워크플로(review workflow), 그리고 그 이후의 모든 다운스트림(downstream) 과정은 변경되지 않습니다.

로컬 모델 및 LM Studio

프로필 설정은 엔드포인트(endpoint)와 모델 이름으로 구성됩니다. LLM 모드 경로의 어떤 것도 OpenAI 전용이 아닙니다. 이는 표준 채팅 완료(chat completions) 요청을 발행합니다. 로컬에서 실행되는 LM Studio를 포함하여 OpenAI와 호환되는 모든 서버가 작동합니다.

reflect가 로컬 LM Studio 인스턴스를 가리키도록 설정하려면 다음과 같이 합니다:

{
  "configVersion": "0.8.0",
  "profiles": {
...

로컬 모델과 LM Studio 버전이 구조화된 출력(structured output)을 지원하는지 확인하지 않았다면 supportsJsonSchema: false로 설정하세요. 대부분의 로컬 모델은 스키마 강제(schema enforcement) 없이도 표준 채팅 완료를 통해 reflect 작업을 올바르게 처리합니다. 출력 내용이 통합 계획(consolidation plans)보다 작고 예측 가능하기 때문에 파싱 실패가 드물게 발생하기 때문입니다.

RTX 4060 Ti에서 9B 모델을 실행하는 머신의 경우, LLM 모드 reflect 벤치마크는 호출당 8~12초 범위를 기록합니다. 이는 위 표의 클라우드 수치와 유사하며, API 비용이 발생하지 않고 데이터가 네트워크를 벗어나지 않습니다.

에이전트 모드를 유지해야 하는 경우

reflect는 정적인 입력(static inputs)을 가지기 때문에 LLM 모드 (LLM mode)가 적합합니다. 다른 개선 프로세스들은 이러한 특성을 공유하지 않습니다.

프로세스가 실시간 도구 호출 (live tool calls)을 필요로 하는 경우에는 에이전트 모드 (agent mode)를 유지해야 합니다. 만약 파일을 읽거나, akm search를 호출하거나, 실행 중간에 외부 컨텍스트 (external context)를 가져오는 커스텀 개선 워크플로우 (custom improve workflow)를 가지고 있다면, 해당 프로세스는 도구를 실행할 수 있는 에이전트가 필요합니다. LLM 모드는 도구 디스패치 (tool dispatch) 기능이 없습니다. 이는 단지 컴플리션 엔드포인트 (completions endpoint)에 대한 직접적인 HTTP 호출일 뿐이며, 그 이상도 이하도 아닙니다.

특정 자산 유형 (asset type)에 대한 reflect 작업이 검색 결과, 그래프 조회 (graph lookups), 또는 자산의 콘텐츠에 따라 달라지는 파일 읽기와 같이 동적으로 조립되는 컨텍스트를 필요로 하는 경우에도 에이전트 모드를 유지해야 합니다. 이러한 조회 작업들은 실행 중인 에이전트가 필요합니다.

표준 reflect 패스 (standard reflect pass) — 즉, 콘텐츠와 메타데이터를 기반으로 기존 자산을 정제하는 작업 — 는 이 중 어느 것도 필요로 하지 않습니다. 따라서 LLM 모드가 이를 위한 적절한 기본값입니다.

실제 적용 시 변화하는 점

기존에 35분 동안 차단(block)되었던 69-ref akm improve 실행이 이제 10분 미만으로 완료됩니다. reflect 제안의 품질은 동일하며, 어떤 경우에는 멀티턴 셀프 리파인 (multi-turn self-refine)이 초안의 불일치를 잡아내기 때문에 더 낫기도 합니다. 클라우드 제공업체를 위한 구조화된 출력 (Structured output)은 이전에 수동 재시도가 필요했던 파싱 실패 (parse failures)를 제거합니다.

이 변경 사항은 설정 업데이트를 통해 이루어집니다:

# 여전히 v1을 사용 중이라면 설정을 마이그레이션하세요
akm config migrate

...

그 이후의 다음 improve 실행에서는 reflect 호출이 30초가 아닌 6~10초 범위 내에서 완료되는 것을 확인할 수 있습니다.

LLM 모드 reflect는 akm 0.8.0에서 사용할 수 있습니다. 전체 설정 참조는 docs/configuration.md에 있습니다. Config v2 키 매핑은 v0.7 to v0.8 migration guide에서 확인할 수 있습니다.

개선 파이프라인(improve pipeline)에 대한 더 넓은 관점 — 5개 단계 전체, 스케줄링(scheduling), 그리고 reflect가 어떻게 다운스트림 통합(consolidation) 및 증류(distill) 단계로 데이터를 전달하는지에 대해서는 The Improvement Loop: How akm Keeps Your Agent Sharp를 참조하세요. 무언가 잘못되었을 때(오래된 DB 엔트리, 환각된 병합 계획, 사전 점검 필터 등) 개선 실행(improve runs)을 디버깅하려면 Your Agent Has a Memory That Runs While You Sleep를 참조하세요.