코딩 에이전트가 과거의 해결책을 기억하게 만드는 방법

어떤 엔지니어링 문제들은 아주 드물게 발생하기 때문에 고통스럽습니다. 코딩 에이전트(coding agent)를 사용하더라도 그 좌절감은 여전합니다. 평소에 자주 쓰지 않는 도구와 씨름하다가, 에러의 벽에 부딪히고, 마침내 해결책을 찾아내지만, 문제가 "해결되었기" 때문에 해결 방법을 기록하는 것을 소홀히 하게 됩니다.

최근에 릴리스 후 DevRel 작업을 위해 사용하는 커스텀 내부 GitHub Actions 워크플로우(workflow)에서 이런 일이 발생했습니다. 이를 작동시키려면 헤드리스 모드(headless mode)로 Entire를 실행하기 위해 특정 인증 토큰(authentication token)을 전달해야 합니다.

몇 달 전, 저는 이 설정을 처음 구성하기 위해 AI 에이전트와 함께 앉았습니다. Entire는 생소하고 우리의 설정은 완전히 문서화되어 있지 않았기 때문에, 로컬 디바이스 플로우(device-flow) 로그인을 통해 토큰을 생성하는 방법을 알아내는 데 고통스러운 시행착오 과정이 필요했습니다.

결국 우리는 답을 찾아냈습니다. 저는 토큰을 GitHub secrets에 붙여넣었고, 워크플로우는 초록색으로 변했으며, 저는 아무것도 적지 않은 채 일상으로 돌아갔습니다. 코딩 에이전트를 사용하면서 저는 메모를 거의 하지 않지만, 이는 지속 가능한 방식이 아닙니다. 해결책을 기록할 무언가가 필요합니다 (설령 그것이 저의 에이전트일지라도 말이죠).

오늘 토큰이 만료되었을 때, 저는 다시 원점으로 돌아왔습니다.

왜 스킬(Skill)을 만들지 않았는가

보통 저의 본능은 에이전트 스킬(Agent skill)이나 goose 레시피(recipe)와 같이 재사용 가능한 워크플로우를 구축하여 반복적인 작업을 자동화하는 것입니다. 하지만 여기서는 전용 스킬을 만드는 것이 의미가 없었습니다:

낮은 빈도: 이 일은 몇 달에 한 번 발생합니다. 거의 사용하지 않을 스킬을 위해 코드를 작성하고 유지 관리하는 것은 전형적인 오버엔지니어링(over-engineering)입니다.
보안 및 컨텍스트: 인증 토큰을 생성하는 것은 민감한 디바이스 플로우를 포함합니다. 저의 글로벌 자동화 스위트(automation suite)에 일반적인 토큰 생성 스크립트가 떠다니는 것을 원치 않았습니다.

제 에이전트에게 메모리(memory)가 있어서, "지난번에 그 GENERIC_ENTIRE_TOKEN을 어떻게 얻었지?"라고 물었을 때 컨텍스트(context)를 회상할 수 있다면 좋았을 텐데 말입니다.

대신, 저는 이미 해결했던 문제를 다시 디버깅(debugging)하는 데 한 시간을 허비했습니다. 저와 제 에이전트는 그저 추측만 반복하고 있었습니다.

다음 만료가 발생하기 전에 이 루프를 끊기 위해, 저는 Entire를 사용하기로 결정했습니다. (당시 저는 말 그대로 Entire의 저장소(repos)에서 작업하고 있었습니다. 저는 Entire에서 일하고 있고, '이것이야말로 완벽한 유스케이스(use case)다'라고 생각했죠).

Entire란 무엇인가?

Entire는 소프트웨어 작업 뒤에 숨겨진 컨텍스트(context)를 보존하기 위한 도구입니다.

코딩 에이전트(coding agents)와 함께 작업할 때, 많은 중요한 정보가 최종 디프(diff) 외부에 존재합니다. 즉, 당신이 준 프롬프트(prompt), 에이전트가 시도했던 막다른 길(dead ends), 에이전트가 실행한 명령(commands), 변경이 이루어진 이유, 그리고 코드 주석에는 결코 포함되지 않는 사소한 디버깅(debugging) 발견 사항들이 그러합니다.

Entire는 해당 세션 기록(session history)을 캡처하여 이를 당신의 git 히스토리(git history)와 연결합니다. 따라서 다음과 같은 일반적인 커밋 메시지(commit message)만 보는 대신:

docs: note dispatch auth refresh process

해당 커밋으로 이어진 에이전트 세션을 복구하여 다음과 같은 질문에 대한 답을 찾을 수 있습니다:

당신과 에이전트가 어떤 문제를 해결했는지,
당신과 에이전트가 어떤 파일들을 수정하거나 검토했는지,
당신과 에이전트가 어떤 시나리오들을 배제했는지,
최종 해결책(final fix)은 무엇이었는지

세션 기록을 아티팩트(artifact)로 사용하기

불행히도, 제 에이전트는 2개월 전의 해결책을 기억할 수 없었습니다. Entire가 에이전트 세션을 커밋(commit)에 연결해주기 때문입니다.

제가 처음 문제를 해결했을 때, 저는 코드를 전혀 변경하지 않았습니다. 그저 에이전트에게 질문을 던졌고 에이전트가 답변을 주었을 뿐입니다. 이는 제가 커밋을 하지 않았음을 의미합니다. 커밋이 없었기 때문에, 에이전트가 검토할 수 있는 영구적인 기록이나 세션 트랜스크립트(session transcript)도 없었습니다.

그래서 오늘, 문제를 두 번째로 해결한 후, 저는 흔적(breadcrumb)을 남기기로 했습니다.

저는 저장소(repo)에 작은 마크다운(markdown) 파일을 하나 만들었습니다. 터미널 명령어를 단계별로 정확하게 문서화하고 싶지도 않았고, 민감한 출력값이나 토큰(token) 패턴을 파일에 붙여넣어 보안 취약점(security vulnerability)을 노출시킬 위험도 감수하고 싶지 않았습니다. 제가 문서화해야 했던 것은 '자격 증명(credential)'이 아니라 '과정(process)'이었습니다.

저는 다음과 같은 최소한의 노트를 체크인(check in)했습니다:

# 워크플로우 토큰 갱신 (Workflow Token Refresh)

만약 토큰이 누락되었거나, 비어 있거나, 거부되어 이 워크플로우가 실패한다면, 이 커밋의 세션 기록(session history)에 캡처된 흐름을 사용하여 토큰을 갱신하십시오.
...

내 에이전트가 응답한 방식

이제, 이 이론이 실제로 미래에 작동할지 테스트해보고 싶었습니다. 저는 에이전트에게 다음과 같은 질문을 던졌습니다:

GENERIC_ENTIRE_TOKEN을 어떻게 얻나요?
내 GitHub Action 워크플로우에서 해당 토큰이 만료되었다고 나옵니다.

이 질문은 에이전트가 using-entire라는 스킬 (skill)을 실행하도록 유도했습니다. 이 스킬은 코드베이스 탐색 및 "우리가 왜 이렇게 했지?"라는 질문을 추적하기 위해 구축된 오케스트레이터 (orchestrator)입니다. 이 스킬의 핵심 지침은 간단합니다: 원시 코드 (raw code)에서 추측하기 전에 저장소의 기록된 세션 기록 (session history)을 읽는 것입니다.

다음은 에이전트가 답을 찾기 위해 백그라운드에서 자율적으로 수행한 정확한 단계별 추적 (trace) 과정입니다:

먼저, 에이전트는 로컬 프로젝트 워크스페이스 (workspace)에서 Entire가 활성화되어 있는지 확인하기 위해 빠른 상태 체크를 실행했습니다.

entire status

에이전트는 내 프롬프트의 검색 키워드를 사용하여 코드베이스를 스캔했고, 제가 이전에 체크인했던 마크다운 (markdown) 파일을 성공적으로 찾아냈습니다.

docs/runbooks/dispatch-workflow-auth-refresh.md

파일을 찾은 후, 제 에이전트는 해당 파일의 Git 커밋 기록 (git commit history)을 확인하여 연관된 Entire 체크포인트 (Entire Checkpoint)를 찾았습니다.

git log --format='%H %b' -5 -- docs/runbooks/dispatch-workflow-auth-refresh.md | grep -B1 'Entire-Checkpoint:'

이 명령어를 통해 에이전트는 커밋에 직접 연결된 고유 세션 식별자 (session identifier)를 추출할 수 있습니다:

Entire-Checkpoint: f3aaa4d4eafd

이 체크포인트 해시 (checkpoint hash)는 영구적인 앵커 (anchor) 역할을 하여, 코드베이스를 우리가 원래 문제를 해결했던 정확한 과거 세션 기록 (session transcript)으로 직접 연결해 줍니다.

체크포인트 ID를 확보한 후, 에이전트는 기록을 가져오기 위해 Entire의 설명 도구 (explanation tools)를 호출했습니다.

entire explain --checkpoint f3aaa4d4eafd --transcript

트랜스크립트 (transcript)가 스트리밍되면, 에이전트는 oauth/device/code 및 oauth/token과 같은 관련 인증 문구가 있는지 텍스트를 스캔합니다.
에이전트가 해당 과거 컨텍스트 (context)를 성공적으로 찾아냈기 때문에, 토큰을 검색하여 GitHub Actions secrets에 추가하기 위해 제가 실행해야 할 정확한 명령어를 전달해 주었습니다.

리포지토리 (repo)에 파일을 커밋함으로써, 저는 Entire가 해당 특정 커밋에 대한 영구적인 세션 히스토리 (session history)를 생성하도록 강제했습니다.

조직 지식 (institutional knowledge)에 대한 새로운 접근 방식

2025년 중반에 에이전트 메모리 도구 (agent memory tool)를 처음 사용했을 때는 본질적으로 수동적인 지식 그래프 (knowledge graph)였습니다. 그것은 제가 명시적으로 기억하라고 말한 것을 기억하고, 명령에 따라 이를 검색했습니다.

하지만 저는 에이전트에게 특정 시나리오를 기억하라고 수동으로 프롬프트 (prompt)를 주고 싶지 않습니다. 저는 앞으로 어떤 정보가 필요할지 알 수 있는 사후 확신 (hindsight)이 부족할 때가 많습니다. 이것이 Entire의 백그라운드 녹화 (background recording)가 매우 가치 있는 이유입니다. 세션 트랜스크립트 (session transcripts)를 자동으로 저장함으로써, 이는 가공되지 않은 개발자 활동을 에이전트가 언제든 활용할 수 있는 검색 가능한 아티팩트 (artifact)로 변환합니다.

불과 몇 년 전만 해도, 모든 회사는 코드만으로는 포착할 수 없는 컨텍스트 (context), 즉 아키텍처 결정의 배경, 이해관계자 간의 트레이드오프 (trade-offs), 그리고 과거의 임시 해결책 (workarounds)을 모두 알고 있는 그 한 명의 엔지니어를 높게 평가했습니다.

우리는 답변을 얻기 위해 그 사람을 찾아다녀야 했습니다. 이제 우리는 대신 에이전트에게 질의할 수 있습니다. 하지만 이를 효과적으로 수행하려면, 문제 해결 단계와 과거의 실패 사례에 관한 적절한 컨텍스트 (context)를 에이전트에게 갖추어 주어야 합니다.

에이전트 세션을 캡처하고 이를 버전 관리 (version controlling)하는 것은, 이러한 풍부한 결정 이력이 프로젝트 리포지토리 (project repository)의 살아있는 영구적인 일부가 되도록 보장합니다.