코드 에이전트에게는 문맥(Context)뿐만 아니라 지속 가능한 메모리(Durable Memory)가 필요합니다

이 글은 실제 리포지토리(Repository)에서 코드 에이전트(Code Agents)를 사용하는 구체적인 실무 경험에서 비롯되었습니다.
문제는 문맥(Context)이 부족한 것이 아니라, 몇몇 중요한 결정 사항들이 리포지토리가 기억할 수 없는 곳에 남겨진다는 점이었습니다.

코드 에이전트와 작업할 때, 우리는 흔히 문맥(Context)을 가장 먼저 떠올립니다:
관련 파일, 프로젝트 지침, 대화 기록, 최근 오류, 로그(Logs), 계획 및 테스트 등 말이죠.

이 모든 것들은 에이전트가 현재의 과업을 해결하는 데 도움을 줍니다.

하지만 실제 리포지토리에서는 금방 다른 문제가 나타납니다. 일부 기술적 결정은 단순히 채팅창 안에만 머물러서는 안 된다는 점입니다.

만약 어떤 결정이 서비스 경계(Service Boundary)를 변경하거나, 어떤 시스템이 진실의 원천(Source of Truth)인지 정의하거나, API 계약(Contract)을 확정하거나, 프로덕션 런타임(Runtime)을 결정하거나, 혹은 "조용한 폴백(Silent Fallbacks)을 사용하지 않는다"와 같은 기술 정책을 수립한다면, 그 결정은 향후 작업에 영향을 미칩니다. 현재의 에이전트가 이를 이해하는 것만으로는 충분하지 않습니다. 리포지토리 또한 이를 기억해야 합니다.

여기에서 리포지토리의 지속 가능한 메모리(Durable Memory)라는 개념이 등장합니다.

문제점

에이전트는 세션(Session) 동안 문맥(Context)을 기억할 수 있습니다. 도구에 따라 세션 간의 개인적인 메모리(Private Memory)를 가질 수도 있습니다. 하지만 그러한 메모리는 항상 다음과 같은 특성을 갖지는 않습니다:

팀 전체에 가시적(Visible)이지 않음;
풀 리퀘스트(Pull Requests)에서 검토(Review) 가능하지 않음;
코드와 함께 버전 관리(Versioned)되지 않음;
도구 간에 이식(Portable) 가능하지 않음;
어떤 결정이 수락되었고 어떤 결정이 여전히 평가 중인지 명시적(Explicit)이지 않음.

이것이 중요한 이유는 많은 기술적 결정이 미래의 변경 사항을 제약하기 때문입니다.

예를 들어:

"이 서비스는 워크플로우(Workflow)의 진실의 원천(Source of Truth)이다."
"이 API는 에이전트 도구를 위한 유일한 유효한 경계(Boundary)이다."
"필수 설정이 누락된 경우, 시스템은 명확하게 실패(Fail)해야 한다."
"로컬 환경은 명시적인 프로필(Profile)로 활성화되어야 한다."
"이 통합(Integration)은 후보 단계이며, 아직 수락되지 않았다."

만약 이러한 규칙들이 오직 대화 속에만 남아 있다면, 다음 개발자나 에이전트는 이를 다시 논의하거나, 중복시키거나, 혹은 알지 못하는 사이에 깨뜨릴 수 있습니다.

저장소의 메모리로서의 ADRs

이를 해결하는 간단한 방법은 ADRs, 즉 Architecture Decision Records (아키텍처 결정 기록)를 사용하는 것입니다.

ADR은 길 필요가 없습니다. 사실, 더 짧고 구체적일수록 좋습니다. ADR의 가치는 다음 사항을 기록하는 데 있습니다:

어떤 결정이 내려졌는가;
왜 그 결정이 필요했는가;
향후 작업이 준수해야 할 결과(consequences)는 무엇인가;
수락(accepted), 제안(proposed), 보류(pending) 또는 교체(replaced) 상태인가.

제가 사용하는 판단 기준 질문은 다음과 같습니다:

만약 다른 에이전트나 개발자가 두 달 뒤에 이 부분을 건드린다면, 아키텍처를 망가뜨리지 않기 위해 이 결정을 알아야 하는가?

만약 대답이 '예'라면, 그것은 아마도 ADR, ADR 업데이트, 또는 보류 중인 후보(candidate)로서 존재해야 합니다.

만약 대답이 '아니오'라면, 아마도 코드, 테스트 또는 구현 문서(implementation documentation)만으로 충분할 것입니다.

모든 것이 ADR이 될 필요는 없다

목표는 모든 것을 문서화하는 것이 아닙니다.

버튼의 텍스트를 변경하거나, 로컬 함수를 리팩터링(refactor)하거나, 시각적인 세부 사항을 조정하는 것은 보통 ADR이 필요하지 않습니다. 이는 제품에 중요한 변경 사항이지만, 반드시 미래의 아키텍처 결정을 지배하는 것은 아닙니다.

반면, 워크플로우(workflow)의 진실의 원천(source of truth)을 백엔드(backend) 서비스에서 프론트엔드(frontend) 상수로 옮기는 작업은 경고 신호를 울려야 합니다. 이는 소유권(ownership), 계약(contracts), 그리고 미래의 기대치를 변화시킵니다. 만약 이미 이전 결정이 존재했다면, 단순히 코드를 수정하는 것만으로는 부족합니다. 이를 명시적으로 업데이트하거나 교체해야 합니다.

지속 가능한 메모리(Durable memory)는 관료주의를 만들기 위한 것이 아닙니다. 중요한 결정이 보이지 않게 되는 것을 방지하기 위한 것입니다.

Decision Memory가 하는 일

Decision Memory는 코드 에이전트를 위한 오픈 소스 스킬(open source skill)입니다. 이 스킬의 역할은 기술적 결정이 다음 중 무엇을 해야 하는지 에이전트가 결정하도록 돕는 것입니다:

ADR 생성;
기존 ADR 업데이트;
이전 결정 교체;
보류 중인 후보로 유지;
또는 구현 문서로 유지.

핵심은 에이전트가 기본적으로 더 많은 문서를 작성하게 만드는 것이 아닙니다. 핵심은 에이전트가 지속 가능한 결정(durable decision)을 감지했을 때, 이를 임시 메모리(temporary memory)에서 리포지토리의 버전 관리되는 메모리(versioned memory)로 이동하도록 돕는 것입니다.

또한 이는 숨겨진 기술 부채(technical debt)의 신호를 감지하는 데에도 도움이 됩니다:

조용한 폴백 (silent fallbacks);
기본값으로 설정된 임의의 구성 (configuration inventada por defecto);
프로덕션 런타임에서의 모크(mocks) 또는 노옵(no-ops);
종료 기준이 없는 임시 결정;
프론트엔드와 백엔드 간의 도메인 규칙 중복.

에이전트 메모리 vs 리포지토리 메모리

에이전트의 메모리는 여전히 유용합니다. 선호도, 반복되는 패턴, 일상적인 명령 및 운영 문맥(context)을 위해 사용됩니다.

하지만 아키텍처 결정은 팀이 검토할 수 있는 곳, 즉 리포지토리에 있어야 합니다.

실무적인 구분은 다음과 같습니다:

에이전트 메모리: 선호도 및 작업 습관용;
리포지토리 지침 (repo instructions): 에이전트의 운영 규칙용;
ADR (Architecture Decision Records): 향후 아키텍처에 영향을 미치는 기술적 결정용;
구현 문서 (implementation documentation): 로컬 세부 사항용;
보류 중인 후보 (pending candidates): 아직 검증되지 않은 관련 아이디어용.

이러한 분리는 모호함을 줄여줍니다. 또한 다양한 도구들이 특정 세션이나 제공업체의 개인 메모리에 의존하지 않고 동일한 리포지토리를 읽을 수 있게 합니다.

사용 예시

에이전트에게 던질 수 있는 유용한 질문은 다음과 같습니다:

decision-memory를 사용하여 다음 결정을 평가해줘:
워크플로우의 신뢰할 수 있는 원천(source of truth)을 백엔드에서 프론트엔드 상수로 이동함.

...

예상되는 답변은 다음과 같습니다:

분류: ADR 생성 또는 기존 ADR 업데이트 필요.

이유: 신뢰할 수 있는 원천(source of truth), 도메인 소유권(ownership), 그리고 백엔드 간의 계약(contract)을 변경함
...

프로젝트

이 스킬은 오픈 소스로 공개되어 있습니다:

GitHub: https://github.com/ltorresu82/skills
skills.sh: https://www.skills.sh/ltorresu82/skills/decision-memory

설치:

npx skills add ltorresu82/skills --skill decision-memory

논지는 간단합니다. 코드 에이전트(Code Agents)에게는 단순히 더 많은 문맥(Context)이 필요한 것이 아닙니다. 더 나은 메모리(Memory)가 필요합니다. 그리고 시스템의 미래를 결정하는 결정 사항들은 코드와 가까운 곳에 존재하며, 버전 관리(Versioned)가 되고, 인간과 에이전트 모두에게 가시적(Visible)이어야 합니다.