제안 큐 안전망 (The Proposal Queue Safety Net)

이 글은 AI 코딩 에이전트(AI coding agents)가 의존하는 점점 늘어나는 기술, 스크립트, 컨텍스트(context)를 관리하는 시리즈의 15번째 파트입니다. 10부에서는 개선 파이프라인(improve pipeline)과 그것이 제안(proposals)을 생성하는 방법을 소개했습니다. 12부에서는 여기서 다룰 신뢰도 점수(confidence scores)로 직접 이어지는 신념 인식 메모리(belief-aware memory)를 다루었습니다.

에이전트가 생성한 스태시(stash) 업데이트의 근본적인 문제는 신뢰입니다. 여러분은 에이전트가 학습한 내용—지난 화요일 세션에서 얻은 디버깅 통찰력, 20개의 PR을 검토하며 도출한 아키텍처 패턴 등—을 포착하고 싶겠지만, 다른 에이전트들이 의존하는 지식 베이스(knowledge base)에 검토되지 않은 내용을 맹목적으로 기록하고 싶지는 않을 것입니다. 단 한 번의 잘못된 승인(promotion)만으로도 누군가 알아차릴 때까지 계속 나타날 환각(hallucinated) 사실로 검색 결과가 오염될 수 있습니다.

akm의 제안 큐(proposal queue)가 그 문제에 대한 해답입니다. 0.7.0 버전에서 도입되어 0.8.0 버전에서 확장된 이 기능은 생성(generation)과 승인(promotion)을 분리합니다. 모든 에이전트 주도 변경 사항은 먼저 영구적인 큐(durable queue)에 기록됩니다. 여러분이 명시적으로 수락하기 전까지는 그 어떤 것도 라이브 스태시(live stash)에 도달하지 않습니다. 큐는 안전망 역할을 합니다.

큐의 작동 방식

akm improve 또는 akm propose가 실행되면, 출력 결과는 스태시(stash)가 아닌 제안 큐(proposal queue)로 전송됩니다. 제안(Proposals)은 에셋 트리(asset tree) 외부에 존재합니다. 이들은 akm search 결과에 절대 나타나지 않으며, 실제 에셋과 함께 인덱싱(indexed)되지도 않습니다. quality: "proposed" 마커가 데이터베이스 수준에서 이를 보장합니다. 즉, 제안된 에셋은 기본 검색에서 제외되며, akm proposal * 명령어나 명시적인 --include-proposed 플래그를 통해서만 나타납니다.

이는 에이전트가 단 한 번의 akm improve 실행으로 수십 개의 제안 (proposals)을 생성하더라도, 사용자가 결정하기 전까지는 그 중 어떤 것도 라이브 스태시 (live stash)에 영향을 미치지 않음을 의미합니다. 동일한 참조 (ref)에 대한 여러 제안이 파일 시스템 충돌 없이 공존합니다. 사용자는 자신의 속도에 맞춰 제안들을 검토하고, 좋지 않은 것은 거절하며, 나머지는 합리적인 순서에 따라 수락할 수 있습니다.

전체 검토 워크플로 (review workflow):

akm proposal list                        # 대기 중인 항목 확인
akm proposal show <id>                   # 전체 제안 내용 렌더링
akm proposal diff <id>                   # 해당 참조의 라이브 버전과 차이점(diff) 비교
...

akm proposal accept는 단순히 파일을 작성하는 것에 그치지 않습니다. 이는 전체 검증 (validation)을 실행하며, akm remember 및 akm import에서 사용하는 것과 동일한 writeAssetToSource() 경로를 통해 쓰기 작업을 수행합니다. 우회 경로는 존재하지 않습니다. 검증에 실패한 제안은 승격 (promoted)되지 않습니다.

0.8.0 추가 사항

0.8.0 버전은 제안 명령어를 akm proposal 서브커맨드 (subcommand) 아래로 재구성하였으며 (기존의 평면 동사들 — akm proposals, akm accept, akm reject 등 — 은 0.9.0 버전까지 지원 중단 예정인 별칭 (deprecated aliases)으로 계속 작동합니다), 대규모 환경에서 큐 (queue)와 상호작용하는 방식을 변화시키는 세 가지 기능인 신뢰도 점수 (confidence scores), 만료 (expiration), 그리고 제안별 되돌리기 (per-proposal revert)를 추가했습니다.

신뢰도 점수 (Confidence scores). 이제 각 제안에는 이를 생성한 파이프라인 (pipeline)에 의해 설정된 선택적 confidence 필드 (0에서 1 사이의 값)가 포함됩니다. akm proposal show <id>는 JSON 출력에 이 필드를 포함합니다. 신뢰도가 높은 제안은 파이프라인이 강력하고 충분히 뒷받침되는 개선 사항이라고 평가한 것입니다. 신뢰도가 낮은 제안은 추측성이거나 근거가 약한 것입니다. 이 점수는 결정의 관문 (gate)은 아닙니다 — 결정은 여전히 사용자가 합니다 — 하지만 분류 (triage)를 위한 신호를 제공합니다. 30개의 제안이 있고 검토 시간이 제한적이라면, 신뢰도가 높은 제안부터 먼저 작업하십시오. (이 점수를 구동하는 신념 모델 (belief model)은 Belief-Aware Memory에서 다룹니다.)

만료 (Expiration). 제안(Proposals)은 설정 가능한 일수가 지나면 만료됩니다. akm 설정에서 improve.archiveRetentionDays를 설정하여 이 기간을 제어할 수 있습니다 (기본값: 30일). 검토하지 못한 채 방치된 오래된 제안들은 무한히 쌓이는 대신 자동으로 아카이브(archive)됩니다. 조치를 취할 만큼 중요했던 사항은 만료되기 전에 검토되었어야 하며, 아카이브는 나중에 다시 확인해야 할 경우를 대비해 전체 감사 추적(audit trail)을 보존합니다.

제안별 되돌리기 (Per-proposal revert). 제안을 수락한 후, akm proposal revert <id>를 실행하면 이전 버전의 백업이 복구됩니다. 이는 일괄 작업(bulk operation)이 아니며, 배치(batch)로 되돌릴 수도 없습니다. ID를 통해 한 번에 하나의 제안씩 되돌려야 합니다:

akm proposal revert <id>    # 특정 수락된 제안에 대한 백업 복구

일괄 되돌리기를 제한하는 제약 조건은 의도된 것입니다. '일괄 수락은 가능하지만 일괄 되돌리기는 불가능하다'는 점이 신중한 검토를 강제하는 안전망(guardrail) 역할을 합니다. 만약 단일 명령으로 50개의 제안을 수락했는데 그중 3개가 잘못되었다면, 그 3개만 개별적으로 되돌려야 합니다. 이 규율이 핵심입니다. 만약 일괄 되돌리기를 하려 했다면, 그것은 검토 없이 일괄 수락했다는 의미이며, 큐(queue)가 존재하는 목적 자체가 바로 그러한 패턴을 방지하기 위함입니다.

일괄 수락 안전망 (Bulk Accept Guardrails)

판단을 완전히 건너뛰지 않으면서 한 번에 하나 이상의 제안을 처리하고자 하는 경우를 위해, 0.8.0 버전에서는 제너레이터 범위(generator-scoped)의 배치 플래그(batch flags)를 추가하여 akm proposal accept 기능을 확장했습니다.

**akm proposal accept**는 제너레이터 범위의 일괄 작업을 지원합니다. 특정 제너레이터의 모든 대기 중인 제안을 수락하려면, 위치 인자(positional id) 없이 --generator를 전달하십시오. 일괄 수락을 위해서는 -y/--yes 플래그가 반드시 필요합니다:

akm proposal accept --generator reflect --yes        # 모든 reflect 제안 수락
akm proposal accept --generator distill --yes        # 모든 distill 제안 수락

--yes 플래그는 비대화형 셸 (non-interactive shells)에서 요구되는 대화형 확인 프롬프트를 제거합니다. 이 플래그는 반드시 akm proposal list와 akm proposal diff를 통해 큐 (queue)를 이미 검토한 후에만 사용하십시오. 사전 검토 없이 일괄 수락하는 것은 바로 이 큐가 존재하는 목적(방지하고자 하는 패턴)에 정면으로 위배되는 행위입니다.

신뢰할 수 있는 소스에 대한 자동 수락 (Auto-Accept)

만약 당신이 완전히 신뢰하는 소스가 있다면 — 예를 들어, 선별된 입력 세트에 대해 실행되는 잘 제약된 태스크 에셋 (task asset)이나, 특정 카테고리만 다루는 distill 작업 등 — 해당 개선 프로필 (improve profile)에 높은 autoAccept 임계값 (threshold)을 설정할 수 있습니다. 신뢰도 (confidence)가 임계값에 도달하거나 이를 초과하는 제안들은 수동 검토 없이 스태시 (stash)로 직접 승격됩니다.

이 기능은 기본적으로 비활성화되어 있으며, 대부분의 소스에 대해 비활성 상태를 유지해야 합니다. 큐의 가치는 바로 에이전트 출력 (agent output)과 당신의 라이브 스태시 (live stash) 사이에 위치한다는 점에 있습니다. 자동 수락은 소스가 신뢰할 수 있고, 범위가 좁으며, 당신이 경험을 통해 출력 품질을 확신할 수 있을 때에만 의미가 있습니다.

일일 검토 습관

제안 큐는 당신이 실제로 검토할 때만 도움이 됩니다. 방치될 경우, 의미 있는 분류 (triage)가 불가능할 정도로 백로그 (backlog)가 쌓이거나, 검토하기도 전에 제안들이 만료되어 버립니다. 짧게라도 매일 검토하는 습관을 가지면 관리가 용이해집니다.

효과적인 워크플로 (workflow):

# 전체 대기 목록(pending list)으로 시작
akm proposal list

...

차이점 확인 (diff) 단계가 가장 유용합니다. akm proposal diff <id>는 제안 내용과 현재 라이브 스태시에 해당 참조 (ref)에 대해 존재하는 내용 사이의 차이 (delta)를 보여줍니다. 당신이 이미 유지 관리하고 있는 참조에 정확한 새로운 컨텍스트 (context)를 추가하는 제안은 수락하기 쉽습니다. 반면, 당신이 잘 알고 있는 참조를 확신에 찬 어조지만 검증 불가능한 주장으로 다시 쓰는 제안은 거절하기 쉽습니다. diff를 통해 그 차이를 명확히 확인할 수 있습니다.

큐(Queue)가 비어 있다면, 일일 검토는 30초면 충분합니다. 만약 akm improve가 밤새 실행되어 20개의 제안(Proposal)을 생성했다면, 10분 정도의 시간을 할당하세요. 핵심은 모든 제안을 처리하는 것이 아니라, 건너뛰어야 할 만큼 거대한 작업 덩어리로 쌓이지 않도록 큐에 충분히 밀착해 있는 것입니다.

akm improve를 정기적으로 실행하는 팀의 경우, 신뢰도 점수(Confidence scores)가 분류(Triage) 작업을 더 빠르게 만들어 줍니다. 신뢰도가 높은 제안은 빠른 diff 확인과 결정이 필요합니다. 신뢰도가 낮은 제안은 더 면밀한 읽기나 즉각적인 거절(Reject)이 필요합니다. 시간이 흐름에 따라, 파이프라인이 무엇을 고신뢰도로 표시하고 실제로 무엇이 유용했는지에 대한 패턴을 파악하면 어디에 주의를 집중해야 할지 배우게 됩니다.

안전한 에이전트 메모리의 형태

제안 큐(Proposal queue)는 관료적인 체크포인트가 아닙니다. 이는 akm improve를 지속적으로 실행하고, 에이전트 주도의 성찰 단계(Reflection passes)를 신뢰하면서도, 무엇이 들어있는지 그리고 왜 들어있는지를 파악할 수 있는 지식 베이스(Knowledge base)를 유지할 수 있게 만드는 메커니즘입니다.

큐가 없다면, 개선 파이프라인을 실행하거나(생성된 모든 것을 수용함) 실행하지 않거나(생성된 것이 아무것도 없음) 둘 중 하나를 선택해야 합니다. 큐는 제3의 선택지입니다. 즉, 파이프라인을 지속적으로 실행하되, 출력물을 신중하게 검토하고, 자격을 갖춘 것만을 승격(Promote)시키는 것입니다. 0.8.0 버전의 가드레일(Guardrails) — 신뢰도 점수, 만료(Expiration), 제안별 되돌리기(Per-proposal revert), 그리고 생성기 범위의 일괄 수락(Generator-scoped bulk accept) — 은 지속적인 운영이 만들어내는 규모에서 이러한 제3의 선택지를 실용적으로 만들어주는 도구들입니다.

제안 큐는 akm 0.7.0부터 사용할 수 있습니다. 0.8.0의 추가 기능인 신뢰도 점수, 만료, akm proposal revert, 그리고 생성기 범위의 일괄 수락을 사용하려면 0.8.0 이상의 버전이 필요합니다. 전체 참조 정보는 docs/cli.md 및 설정 참조(Configuration reference)에서 확인할 수 있습니다.