Repo: https://github.com/voku/agent-loop
Demo: https://voku.github.io/agent_loop_demo/

당신의 코딩 에이전트에게 필요한 것은 더 많은 메모리가 아닙니다. 통제된 루프(Governed Loop)가 필요합니다.

코딩 에이전트(Coding agents)는 실수를 반복합니다.

당연한 대응책은 그들에게 더 많은 메모리(Memory)를 제공하는 것입니다:

MEMORY.md
project-rules.md
agent-notes.md
...

곧 에이전트는 과거의 결정, 임시 방편, 복사된 트랜스크립트(Transcripts), 버려진 아이디어, 그리고 아무도 승인했는지 기억하지 못하는 규칙들을 받게 됩니다.

에이전트는 더 많은 컨텍스트(Context)를 갖게 됩니다.

하지만 반드시 더 나은 컨텍스트를 갖게 되는 것은 아닙니다.

어느 시점이 되면, 메모리는 쓰레기 매립지가 됩니다.

문제는 코딩 에이전트가 너무 많이 잊어버린다는 것이 아닙니다. 문제는 대부분의 워크플로(Workflows)가 임시 컨텍스트, 증거, 제안된 학습 내용, 그리고 승인된 프로젝트 가이드라인을 구분하지 못한다는 점입니다.

A transcript is not memory.
(트랜스크립트는 메모리가 아닙니다.)
A note is not a rule.
(노트는 규칙이 아닙니다.)
A finding is not guidance.
(발견 사항은 가이드라인이 아닙니다.)
...

에이전트에게 계속해서 커지는 하나의 컨텍스트 더미를 주는 대신, 저는 통제된 워크플로(Governed workflow)를 중심으로 voku/agent-loop를 구축했습니다:

task
  -> approved plan (승인된 계획)
  -> selective recall (선택적 회상)
...

승인된 범위(Approved scope)부터 시작하세요

코딩 에이전트는 티켓을 읽고 티켓이 언급하는 것을 잊어버린 모든 내용을 창의적으로 채워 넣는 것으로 시작해서는 안 됩니다.

명시적인 작업 브리프(Work brief)와 함께 시작해야 합니다:

• 목표 (goal)
• 허용된 범위 (permitted scope)
• 비목표 (non-goals)
• 영향을 받는 파일 (affected files)
• 필요한 검증 (required validation)
• 인간의 승인 (human approval)

예를 들어:

vendor/bin/agent-loop workflow plan PROJECT-123 \
  --by lars \
  --learning-root infra/doc/agent-learning \
...

그러면 인간이 해당 특정 리비전(Revision)을 승인합니다:

vendor/bin/agent-loop workflow approve PROJECT-123 --by lars

계획이 변경되면 이전 리비전은 superseded(대체됨) 상태가 되며, 새 리비전은 다시 승인을 받아야 합니다.

에이전트가 아무도 요청하지 않은 기술적으로 인상적인 리팩터링(Refactoring)을 수행하기 전까지는 이 방식이 다소 관료적으로 들릴 수 있습니다.

승인은 작업 ID(Task ID)에 영구적으로 적용되는 것이 아니라, 그 의미가 조용히 변할 수 있는 구체적인 계획(Concrete plan)에 적용되어야 합니다.

더 많은 컨텍스트를 로드하는 것이 아니라, 더 적게 로드하세요

에이전트는 보통 두 가지 서로 다른 종류의 컨텍스트 (Context)가 필요합니다:

1. 프로젝트 가이드라인 (Project guidance);
2. 코드 구조 (Code structure).

agent-recall-compiler는 작업 특화형 가이드라인을 선택합니다.

agent-map은 관련 코드에 대한 압축된 정보를 제공합니다.

이것들이 분리되어 있는 이유는 서로 다른 질문에 답하기 때문입니다:

Recall (회상):
- 어떤 규칙이 적용되는가?
- 이전의 어떤 결정이 중요한가?
...

목표는 전체 저장소 (Repository)를 프롬프트 (Prompt)에 압축하여 넣는 것이 아닙니다.

목표는 저장소의 대부분을 로드하는 것을 피하는 것입니다.

완전한 AST (Abstract Syntax Tree)나 몇 달 치의 트랜스크립트 (Transcripts)를 컨텍스트 윈도우 (Context window)에 쏟아붓는 것은 이해하는 것이 아닙니다. 그것은 유난히 자신만만한 자동 완성 (Autocomplete) 기능을 갖춘 대량 데이터 전송일 뿐입니다.

작업 메모리 (Working memory)를 일시적으로 유지하세요

구현 과정 동안 에이전트는 다음 사항들을 추적해야 할 수도 있습니다:

• 가정 (Assumptions);
• 대상 파일 (Claimed files);
• 체크포인트 (Checkpoints);
• 미결 질문 (Open questions);
• 중간 결정 사항 (Intermediate decisions).

이러한 것들은 작업 세션 (Task session)에 속해야 합니다.

이는 검사 가능하고, 닫을 수 있으며, 제거할 수 있어야 합니다.

일시적인 관찰 내용이 조용히 영구적인 프로젝트 지식으로 변해서는 안 됩니다. 한 가지 작업에는 유용했던 임시 방편 (Workaround)이 코드가 변경된 후에는 적극적으로 오해를 불러일으키는 요소가 될 수 있습니다.

따라서 유용한 시스템은 최소한 세 가지 수준을 가집니다:

session state (세션 상태)       temporary (일시적)
finding (발견 사항)             evidence to review (검토할 증거)
guidance (가이드라인)           approved durable knowledge (승인된 지속적 지식)

이러한 수준들을 하나의 메모리 파일로 통합하는 것은 정보의 신뢰성을 만드는 출처 (Provenance)를 제거해 버립니다.

검증 (Verification)은 루프의 일부입니다

에이전트가 "완료했다"라고 말하는 것은 증거가 아닙니다.

작업 브리프 (Work brief)에는 이미 예상되는 검증 명령어가 포함되어 있습니다. 루프는 작업 상태, 회상 (Recall) 출력, 세션, 파일, 그리고 저장소 체크 사항들이 서로 일치하는지 검증할 수 있습니다.

예를 들어:

vendor/bin/agent-loop verify PROJECT-123

결과는 다음과 같은 저장소 특화형 체크를 기반으로 해야 합니다:

composer phpstan
composer test
composer cs

정확한 명령어보다 더 중요한 것은 다음 규칙입니다:

검증은 구현 전에 선언되어야 하며, 변경된 사항에 맞추기 위해 사후에 만들어져서는 안 된다.

테스트 스위트(test suite)를 통과했다는 사실 또한 에이전트가 범위를 벗어나지 않고 유지되었음을 증명하지는 않습니다. 이것이 바로 워크플로 검증(workflow verification)과 코드 검증(code validation)이 서로 관련되어 있지만 별개의 관심사(concerns)인 이유입니다.

선택된 가이드라인이 반드시 유용한 가이드라인인 것은 아니다

회상(Recall)은 특정 태스크를 위해 규칙을 선택할 수 있지만, 선택 그 자체만으로는 아무것도 증명하지 못합니다.

가이드라인은 다음과 같았을 수 있습니다:

HELPFUL (도움됨)
IRRELEVANT (무관함)
HARMFUL (해로움)
...

NOT_USED (사용되지 않음)는 특히 중요합니다.

가이드라인 항목이 감사(audit)나 조사(investigation)를 위해 선택되었을 수 있지만, 실제로 참조되지는 않을 수 있습니다. 이러한 결과(outcome)가 없다면, 선택 통계(selection statistics)는 조용히 사용 통계(usage statistics)로 변질되며, 지표(metrics)는 결코 일어나지 않은 워크플로를 설명하기 시작합니다.

구분은 간단합니다:

selection (선택) = 시스템이 이를 제공함
usage     (사용) = 에이전트가 이를 참조함
outcome   (결과) = 그것이 도움이 되었는지 여부

이것들을 별도로 기록하면, 생성된 프롬프트(prompt)에 파일이 얼마나 자주 나타났는지를 단순히 세는 대신, 회상(recall)을 개선하기 위한 증거를 얻을 수 있습니다.

학습에는 여전히 인간이 필요하다

태스크가 끝난 후, 에이전트는 발견 사항(findings)을 기록할 수 있습니다.

발견 사항은 증거이지, 새로운 규칙이 아닙니다.

이는 다음과 같은 액션을 포함하는 제안(proposal)이 될 수 있습니다:

ADD (추가)
REPLACE (교체)
DELETE (삭제)
...

영구적인 가이드라인(durable guidance)이 변경되기 전에 인간이 이 제안을 검토합니다.

대부분의 태스크는 아마도 다음과 같이 끝나야 할 것입니다:

NO_DURABLE_LEARNING (영구적 학습 없음)

버그 하나를 수정한다고 해서 반드시 재사용 가능한 프로젝트 규칙이 드러나는 것은 아닙니다. 때로는 버그가 수정되었다는 사실 자체가 올바른 교훈일 수 있습니다.

그 결론은 자체적인 종료 상태(terminal state)를 가집니다:

ACKNOWLEDGED (확인됨)

이는 가이드라인 변경으로 승인된 것도 아니고, 틀린 것으로 거부된 것도 아닙니다. 태스크가 검토되었으며 영구적인 변경이 필요하지 않았음을 기록합니다.

이것이 하나의 상태 이름치고는 과도하게 정밀해 보일 수도 있습니다. 하지만 그렇지 않습니다.

라이프사이클 상태(lifecycle states)가 잘못된 동사를 사용하면, 감사 추적(audit trails)은 실제로 무슨 일이 일어났는지를 점차 말해주지 않게 됩니다.

우리는 루프를 그 자체에 실행했다

우리가 agent-learning 자체를 감사하는 데 이 접근 방식을 사용했을 때, 이 방식은 더욱 신뢰할 수 있게 되었습니다.

감사 결과 세 가지의 실제 결함(defects)이 발견되었습니다:

1. NO_DURABLE_LEARNING에 의미론적으로 올바른 종료 전이(terminal transition)가 없었습니다.
2. 여러 명령어가 전체 제안 경로(proposal paths)는 수락했지만, 자연스러운 bare 제안 ID(bare proposal ID)가 주어졌을 때는 실패했습니다.
3. 오래된 결과 기록(outcome records)이 가이드 통계(guidance statistics)에서 조용히 제외되었습니다.

수정 사항은 0.8.2, 0.8.3, 그리고 0.8.4 버전에 배포되었습니다.

그 중 어떤 것도 새로운 에이전트 아키텍처를 필요로 하지 않았습니다.

필요했던 것은 다음과 같습니다:

• 하나의 명시적인 라이프사이클 전이(lifecycle transition);
• 하나의 일관된 경로 해결사(path resolver);
• 조용한 제외 대신 하나의 가시적인 경고(visible warning).

이것이 실제 도그푸딩(dogfooding)이 보통 찾아내는 것입니다.

혁명적인 새로운 자율 플랫폼이 아닙니다. 누락된 상태(state), 일관성 없는 헬퍼 호출(helper call), 그리고 조용한 continue입니다.

누군가가 README에 "에이전트 방식(agentic)"이라는 단어를 추가하더라도, 소프트웨어는 여전히 소프트웨어입니다.

agent-loop가 실제로 하는 일

voku/agent-loop는 여러 개의 집중된 패키지들을 조정하는 PHP 8.3 CLI입니다:

agent-kanban           작업 및 태스크 상태 (work and task state)
agent-session          임시 작업 메모리 (temporary working memory)
agent-recall-compiler  선택적 프로젝트 가이드 (selective project guidance)
...

이것은 유지보수자, 코드 리뷰(code review), 정적 분석(static analysis), 테스트, 또는 도메인 지식(domain knowledge)을 대체하지 않습니다.

대신, 코딩 에이전트를 위한 명시적인 워크플로(workflow)를 기존의 엔지니어링 관행들에 부여합니다.

전형적인 작업은 대략 다음과 같습니다:

vendor/bin/agent-loop board card show PROJECT-123

vendor/bin/agent-loop workflow plan PROJECT-123 ...
...

중요한 부분은 CLI 구문이 아닙니다.

중요한 부분은 모든 전이(transition)가 가시적이라는 점입니다:

무엇이 요청되었는가?
무엇이 승인되었는가?
어떤 컨텍스트(context)가 선택되었는가?
...

실제 교훈

코딩 에이전트는 모든 것을 기억할 필요가 없습니다.

그들에게 필요한 것은 다음과 같습니다:

• 명시적 범위 (explicit scope);
• 버전 관리된 승인 (revisioned approval);
• 선택적 컨텍스트 (selective context);
• 임시 작업 메모리 (temporary working memory);
• 선언된 검증 (declared validation);
• 기록된 결과 (recorded outcomes);
• 인간이 검토한 학습 (human-reviewed learning);
• 의도적인 망각 (intentional forgetting).

더 많은 메모리는 잘못된 컨텍스트 관리(context management)를 숨길 뿐입니다.

통제된 루프(governed loop)는 그것을 드러냅니다.

그리고 워크플로우(workflow)가 오래된 승인(stale approvals), 무관한 지침(irrelevant guidance), 지원되지 않는 주장(unsupported claims), 그리고 우발적인 "교훈(accidental lessons)"을 거부할 수 있게 되면, 에이전트(agent)는 전체 저장소(repository)를 기억하는 것처럼 행동할 필요가 없습니다.

단지 하나의 통제된 작업(controlled task)을 완료하는 데 필요한 충분한 검증된 컨텍스트(verified context)만 있으면 됩니다.