핸드오프 문서: 세션 간 에이전트 메모리
2026년 3월 21일, 제 프로덕션 사이트는 캐시 퍼지로 성능 병목이 드러난 후 14초의 페이지 로드 시간을 보이고 있었습니다. 저는 두 번의 세션에 걸쳐 근본 원인을 조사했고, 느린 코드 경로를 식별했으며, 수정 계획을 작성하고, 모든 내용을 핸드오프 문서에 담았습니다.
핸드오프 문서는 세션 경계를 넘어 진단을 전달함으로써, 구현을 담당하는 에이전트가 동일한 잘못된 결론을 다시 도출하는 대신 수정된 이해를 상속받도록 합니다. 무엇을 해야 하는지만 적는 티켓과 달리, 핸드오프는 무엇을 시도했고, 무엇이 잘못되었으며, 이전 접근 방식이 왜 실패했는지를 기록합니다. 마켓 페이지 핸드오프는 4일에 걸쳐 3번의 수정을 거치며 살아남았고, 페이지 로드 시간을 14초에서 108밀리초로 줄인 구현을 이끌었습니다.
그 핸드오프의 첫 번째 초안은 잘못되었습니다. 잘못된 코드 경로를 겨냥하고 있었습니다. 코드 리뷰에서 측정된 느린 페이지들이 핸드오프가 가정한 _fetch_market_data()가 아니라 market_hub()에 의해 제공되고 있다는 점이 포착되었습니다. 핸드오프는 수정되었습니다.
두 번째 초안은 Apple Maps와 계층 카운트에 불필요한 HTMX 부분 렌더링을 제안했습니다. 리뷰에서 Apple Maps는 URL을 로컬에서 서명하므로 (지연시킬 외부 요청이 없음), 계층 카운트는 단일 집계 쿼리에서 나와야 한다는 점을 포착했습니다. 핸드오프는 다시 수정되었습니다.
세 번째 초안은 날씨 엔드포인트를 비동기로 만들 것을 제안했지만, 기존의 동기 HTTP 클라이언트가 HTMX 뒤에서도 여전히 이벤트 루프를 차단할 것이라는 점을 명시하지 않았습니다. 핸드오프는 세 번째로 수정되었습니다.
4일 후, 다른 세션이 세 번 수정된 핸드오프를 읽고 수정 사항을 구현했습니다. Austin은 14,290ms에서 108ms로 단축되었습니다. 구현은 올바른 코드 경로를 겨냥했고, 올바른 쿼리 접근 방식을 사용했으며, 불필요한 HTMX 부분 렌더링은 건너뛰었습니다. 세 번의 리뷰에서 나온 모든 수정 사항은 이미 반영되어 있었습니다.
핸드오프 문서는 4일과 여러 세션에 걸쳐 진단을 전달했습니다. 만약 핸드오프가 없었다면, 구현 세션은 처음부터 시작해서 동일한 잘못된 가정을 하고, 동일한 불필요한 최적화를 제안하고, 동일한 수정을 필요로 했을 것입니다. 핸드오프는 4일간의 조사를 구현 에이전트가 몇 초 만에 읽을 수 있는 문서로 압축했습니다. 이것은 특정 문제에 적용된 컨텍스트 윈도우 관리입니다. 즉, 진단을 정확하게 만드는 수정 사항을 잃지 않으면서 세션 경계를 넘어 진단을 전달하는 방법입니다.
핸드오프에 담기는 내용
핸드오프 문서는 티켓이 아닙니다. 티켓은 무엇을 해야 하는지를 말합니다. 핸드오프는 무엇을 시도했고, 무엇을 배웠으며, 무엇이 잘못되었고, 다음에 무엇을 해야 하는지를 말합니다. 그 차이는 제도적 기억입니다.
마켓 페이지 핸드오프에는 다음이 담겨 있었습니다.
진단. 6개 마켓 페이지의 콜드 렌더링 TTFB 측정값으로, 381ms(Tokyo, 소규모 마켓)부터 14,290ms(Austin, 500개 이상의 기업)까지 분포했습니다. 이 측정값은 문제가 기업 수에 비례해 커진다는 것을 증명했고, 이는 쿼리 형태가 병목이라는 점을 가리켰습니다.
근본 원인, 우선순위별로. 영향도 순으로 정렬된 네 가지 근본 원인: 쿼리 형태(주요), 차단하는 날씨 API(보조), 다른 코드 경로에서의 전체 테이블 스캔(3순위), 그리고 누락된 캐시 헤더(이미 부분적으로 해결됨). 각 근본 원인에는 파일 경로, 줄 번호, 그리고 속도 저하를 일으키는 구체적인 코드 패턴이 포함되어 있었습니다.
잘못된 방향. 첫 번째 초안은 market_hub() 대신 _fetch_market_data()를 겨냥했습니다. 핸드오프는 이 오류와 그 수정을 기록해, 구현 세션이 동일한 잘못된 결론을 다시 도출하지 않도록 했습니다. 또한 폐기된 HTMX 부분 렌더링과 그 이유도 기록했습니다. Apple Maps는 외부 요청이 없고, 계층 카운트는 집계 쿼리에 포함되어야 한다는 것입니다.
구현 계획. SQL 예제, 수용 기준, 검증 지침이 포함된 다섯 단계. 1단계: Python 측 페이지네이션을 데이터베이스 쿼리로 대체합니다. 2단계: 비동기 클라이언트를 사용한 HTMX 날씨 부분 렌더링을 추가합니다. 3단계: 보조 코드 경로를 캐시합니다. 4단계: 엣지 캐시 헤더를 추가합니다. 5단계: 동일한 6개 URL을 다시 측정합니다.
컨텍스트 윈도우 관리 게시물은 이 정도의 구체성이 왜 중요한지 설명합니다. 핸드오프의 모든 모호함은 구현 에이전트가 다시 도출해야 하는 결정이며, 컨텍스트 예산을 소모하고 동일한 잘못된 결론의 위험을 초래합니다.
컨텍스트 지뢰. 공유 템플릿 컨텍스트에는 해당 정보를 전혀 렌더링하지 않는 페이지를 포함해 모든 페이지에서 인증된 코인 잔액 조회가 포함되어 있습니다. 핸드오프는 이를 캐시 정확성 문제로 언급했습니다. 적절한 Vary 헤더 없이 s-maxage를 사용하면 익명 사용자에게 오래된 인증 데이터를 제공할 수 있습니다.
티켓이 실패하는 이유
동일한 작업에 대한 티켓은 이렇게 말할 것입니다. “마켓 페이지가 느립니다. 마켓 허브 쿼리를 최적화하세요.” 구현 세션은 다음을 수행해야 할 것입니다.
- 어떤 코드 경로가 마켓 페이지를 제공하는지 발견 (라우터를 읽지 않고는 명확하지 않음)
- 병목을 찾기 위해 코드 경로 프로파일링
- 다양한 최적화 접근 방식 고려
- 그중 하나를 구현
- 그 접근 방식이 부작용(인증 데이터가 있는 캐시 정확성)을 가진다는 것을 발견
- 접근 방식을 수정
1-3단계는 조사 세션에서 이미 완료되었습니다. 핸드오프는 그 작업을 이어갑니다. 티켓은 그것을 버립니다.
실패 모드는 게으름이 아닙니다. 실패 모드는 세션 경계를 넘나드는 컨텍스트 손실입니다. AI 에이전트 세션은 깨끗한 컨텍스트 윈도우로 시작합니다. 이전 세션이 발견한 것을 기억하지 못합니다. 이는 컨텍스트가 곧 아키텍처가 시스템 수준에서 다루는 것과 동일한 문제입니다. 컨텍스트 윈도우에 무엇을 넣느냐가 출력의 품질을 결정합니다. 티켓은 목표를 제공합니다. 핸드오프는 목표에 더해 그것을 올바르게 달성하는 데 필요한 누적된 이해를 제공합니다.
수정 이력이 중요한 이유
핸드오프의 수정 이력은 현재 내용만큼이나 가치 있습니다. 마켓 페이지 핸드오프는 타임스탬프와 이유가 포함된 세 번의 수정을 기록했습니다.
- 캡처됨: 2026-03-21T17:24 (원본 조사)
- 수정됨: 2026-03-21T18:20 (코드 리뷰 수정: 잘못된 코드 경로, 불필요한 HTMX)
- 수정됨: 2026-03-25T06:30 (구현 완료, 쿼리 수정 배포됨)
수정 이력은 구현 세션에 이렇게 알려줍니다. “이 진단은 이의 제기를 받고 수정되었습니다. 현재 버전은 그 수정 사항을 반영합니다.” 수정이 없는 핸드오프는 틀렸을 수 있습니다. 세 번의 수정을 거친 핸드오프는 스트레스 테스트를 거친 것입니다.
잘못된 방향은 가치의 일부입니다. “Apple Maps가 URL을 로컬에서 서명하기 때문에 /_map HTMX을 검토하고 거부했습니다”라고 말하는 핸드오프는, 구현 세션이 동일한 최적화를 제안하고, 검토받고, 거부당하는 일을 막아줍니다. 핸드오프는 거부를 미리 처리해 둡니다.
핸드오프를 작성해야 할 때
모든 작업에 핸드오프가 필요한 것은 아닙니다. 한 세션에서 끝나는 버그 수정은 세션 간 지속성이 필요하지 않습니다. 핸드오프는 다음과 같은 경우에 가치가 있습니다.
조사 비용이 큰 경우. 성능 병목 프로파일링, 보안 취약점 추적, 다중 시스템 상호작용 디버깅. 조사에 상당한 노력이 들었다면, 핸드오프가 그 노력을 보존합니다.
구현이 다른 세션에서 일어날 경우. 오늘 조사를 마치지만 내일 구현할 예정이라면, 핸드오프가 그 간극을 연결합니다. 그것 없이는 내일의 세션이 0에서 시작합니다.
진단이 자명하지 않은 경우. 올바른 수정이 세 가지의 그럴듯해 보이는 대안이 왜 틀렸는지를 이해해야 한다면, 핸드오프가 그 이해를 포착합니다. 복리 컨텍스트 시스템은 핸드오프가 프로젝트 지식의 더 넓은 축적에 어떻게 들어맞는지 설명합니다. “쿼리를 수정하라”는 티켓은 왜 그 쿼리에 특정 수정이 필요한지 설명하지 않습니다.
여러 사람(또는 에이전트)이 작업할 수 있는 경우. 핸드오프는 공유된 이해 문서입니다. 이를 읽는 모든 세션이 전체 조사 컨텍스트를 상속받습니다.
복리 컨텍스트로서의 핸드오프
핸드오프는 복리 컨텍스트 시스템에 대한 예치입니다. 각 핸드오프는 진단 시간을 포착해 재사용 가능한 산출물로 변환합니다. 구현 세션은 거의 0에 가까운 비용으로 진단을 인출합니다.
시간이 지남에 따라 핸드오프는 조사 이력으로 축적됩니다. 마켓 페이지 핸드오프는 캐시 퍼지 사건, 나이트체크 측정, 파괴적 API 가드, 그리고 코드 리뷰 시스템을 참조합니다. 이들 각각은 그 자체로 이전 세션의 산물입니다. 핸드오프는 이들을 새로운 세션이 따라갈 수 있는 서사로 연결합니다.
핸드오프는 이해를 대체하지 않습니다. 구현 세션은 여전히 코드를 읽고, 수정을 작성하고, 결과를 검증해야 합니다. 핸드오프는 재발견을 대체합니다. 세션은 이미 알려진 것을 발견할 필요가 없습니다. Ralph 에이전트 아키텍처는 핸드오프를 야간 실행 루프의 주요 세션 간 지속성 메커니즘으로 사용합니다. AI 엔지니어링 허브는 핸드오프가 훅, 스킬, 메모리 시스템의 더 넓은 인프라에 어떻게 들어맞아 에이전트 지원 개발을 시간에 따라 복리로 만드는지 문서화합니다.
FAQ
핸드오프는 얼마나 길어야 하나요?
진단, 잘못된 방향, 구현 계획을 포착할 만큼 길게. 에이전트가 한 번의 컨텍스트 로드로 읽을 수 있을 만큼 짧게. 마켓 페이지 핸드오프는 103줄이었습니다. 대부분의 핸드오프는 50-150줄입니다.
핸드오프는 어디에 저장하나요?
프로젝트의 메모리 디렉터리: ~/.claude/projects/{project}/memory/handoff-{topic}.md. 메모리 시스템은 frontmatter 설명을 기반으로 관련 파일을 로드하므로, 핸드오프는 명시적인 참조 없이도 향후 세션에서 발견 가능합니다.
핸드오프가 문서를 대체하나요?
아닙니다. 문서는 시스템이 어떻게 작동하는지 설명합니다. 핸드오프는 특정 문제에 대해 무엇을 배웠고 그것에 대해 무엇을 해야 하는지 설명합니다. 문서는 영구적입니다. 핸드오프는 구현 세션에 의해 소비된 후 역사적 컨텍스트가 됩니다.
핸드오프가 오래되면 어떻게 하나요?
핸드오프의 상태 필드가 이를 추적합니다. 활성 핸드오프는 PLANNED 또는 IN PROGRESS로 표시됩니다. 완료된 핸드오프는 구현 커밋 해시와 함께 RESOLVED로 표시됩니다. 오래된 핸드오프는 역사적 컨텍스트로 볼 수 있지만 실행 가능하지는 않습니다.
출처
이 기사는 마켓 페이지 성능 핸드오프(handoff-market-page-perf.md)를 바탕으로 하며, 이는 2026년 3월 25일에 배포된 쿼리 형태 수정을 이끌었습니다. 핸드오프는 4일에 걸쳐 세 번의 수정 주기를 살아남았고, 132배의 성능 개선을 달성한 구현에 정보를 제공했습니다. 복리 컨텍스트에서 참조됩니다.