diff --git a/ko/sections/07-4-memory-and-checkpoints.qmd b/ko/sections/07-4-memory-and-checkpoints.qmd index ef2e8b8..26e96ce 100644 --- a/ko/sections/07-4-memory-and-checkpoints.qmd +++ b/ko/sections/07-4-memory-and-checkpoints.qmd @@ -1,2 +1,213 @@ # §7.4 메모리와 체크포인트 설계 {.unnumbered} +통계학과 대학원생 A가 코딩 에이전트와 함께 설문 데이터 분석 보고서를 만든다고 하자. 첫날 A는 에이전트와 데이터 정제 규칙을 정했다. 응답 시간이 30초 미만인 응답은 성의 없는 응답으로 보고 제외하기로 했다. 다음 날 새 창을 열고 회귀분석을 부탁하자, 에이전트는 원자료 전체로 분석을 시작했다. 어제 정한 규칙을 전혀 모르고 있었다. (이 사례는 설명을 위해 만든 가상 사례다. 이 섹션 전체에서 이어서 쓴다.) + +며칠에 걸친 작업에서 에이전트가 앞의 결정을 잊는 일은 흔하다. 이 섹션은 그 문제를 줄이는 세 가지 장치를 다룬다. 작업 중에 쌓인 대화를 줄이는 압축, 끊긴 작업을 다시 잇는 세션 재개, 그리고 작업 상태를 대화 밖에 적어 두는 일이다. 여기에 일이 잘못됐을 때 되돌아갈 지점을 만드는 체크포인트를 더한다. §7.1이 메모리를 하네스의 구성요소로 소개했다면, 이 섹션은 그것을 어떻게 설계하는지를 다룬다. + +## 에이전트는 왜 잊어버리는가 + +출발점은 언어 모델 자체에는 대화를 기억하는 장치가 없다는 사실이다. Anthropic의 API 문서는 자사 Messages API가 상태를 저장하지 않으며(stateless), 그래서 요청할 때마다 대화 기록 전체를 보내야 한다고 설명한다 ([Anthropic, Using the Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages)). 우리가 채팅 화면에서 보는 "이어지는 대화"는, 하네스(모델을 실제 작업에 쓸 수 있게 감싸는 프로그램, §7.1 참조)가 지금까지의 대화를 매번 다시 모델에 넘겨주기 때문에 가능하다. 모델이 무언가를 기억하는 것처럼 보인다면, 그 기억은 모델 밖 어딘가에 저장되어 있다가 다시 들어간 것이다. + +모델이 한 번에 읽을 수 있는 분량에는 한계가 있다. 이 한계를 컨텍스트 윈도(context window)라고 한다. 작업대에 비유할 수 있다. 대화, 읽은 파일, 명령 실행 결과가 모두 이 작업대 위에 올라간다. 작업이 길어지면 작업대가 차고, 무언가를 치워야 새 일을 올릴 수 있다. 작업대가 넓어도 문제는 남는다. 입력이 길어질수록 단순한 과제에서도 모델의 성능이 떨어지고 들쭉날쭉해진다는 실험 보고가 있다 ([Hong 외, 2025](https://www.trychroma.com/research/context-rot)). 컨텍스트 윈도의 크기와 그 한계는 §5.2에서 자세히 다룬다. + +에이전트가 맥락을 잃는 경로는 크게 세 가지다. + +- **작업대가 넘친다.** 대화가 길어지면 하네스가 앞부분을 요약하거나 덜어낸다. 이때 세부가 빠진다. +- **세션이 끝난다.** 세션(session)은 하나의 대화 단위다. 창을 닫거나 새 대화를 열면, 따로 저장해 두지 않은 맥락은 다음 세션으로 넘어가지 않는다. Anthropic은 장기 작업에 관한 글에서 이 문제를 "each new session begins with no memory of what came before"라고 요약했다 ([Young, 2025](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)). +- **작업이 중단된다.** 오류, 네트워크 문제, 컴퓨터 종료로 작업이 도중에 끊긴다. + +결정 사항이 쌓일수록 하나를 잃었을 때의 비용도 커진다. A의 사례에서 정제 규칙 하나를 잃자 그 뒤의 분석 결과가 모두 틀렸다. 장기 작업에서 메모리를 설계해야 하는 이유가 여기에 있다. + +## 기억의 층위 + +에이전트의 "기억"은 한 종류가 아니다. 어디에 저장되고, 누가 쓰고, 언제 다시 읽히고, 얼마나 오래 남는지에 따라 나눠 볼 수 있다. + +| 층위 | 예 | 누가 쓰나 | 언제 읽히나 | 얼마나 남나 | +|---|---|---|---|---| +| 대화 맥락 | 지금 세션의 대화, 명령 실행 결과 | 자동으로 쌓임 | 모델을 호출할 때마다 | 세션이 끝날 때까지 | +| 지침 파일 | `CLAUDE.md`, `AGENTS.md` | 주로 사람 | 세션 시작 시 자동으로 | 저장소에 있는 동안 | +| 메모리 노트 | 사용자 선호, 프로젝트에서 배운 사실 | 에이전트 또는 사람 | 세션 시작 시 또는 필요할 때 | 지울 때까지 | +| 작업 상태 | 진행 기록, 할 일 목록, 계획 파일, git 이력 | 에이전트와 사람 | 작업을 이어갈 때 | 작업 기간 동안 | + +**지침 파일**은 "이 프로젝트에서 일하는 법"을 적은 문서다. 사람에게 README가 있듯 에이전트에게 주는 안내문이다. Claude Code는 `CLAUDE.md`라는 파일을 매 세션 시작 시 읽는다 ([Claude Code 문서, memory](https://code.claude.com/docs/en/memory)). `AGENTS.md`는 여러 코딩 에이전트가 함께 쓰는 개방형 형식으로, OpenAI Codex, Amp, Jules, Cursor, Factory의 협업에서 나왔고 현재 Linux Foundation 산하 Agentic AI Foundation이 관리한다 ([agents.md](https://agents.md/)). 지금 이 책의 저장소에도 `CLAUDE.md`가 있다. 원고의 구조, 빌드 명령, 문체 규칙을 적어 두어 에이전트가 세션마다 같은 규칙으로 일하게 한다. + +**메모리 노트**는 작업하면서 알게 된 사실을 적어 두는 공간이다. 2026년 10월 기준 Claude Code에는 사람이 쓰는 `CLAUDE.md`와 별도로, 에이전트가 사용자의 수정과 선호를 보고 스스로 노트를 남기는 auto memory 기능이 있다 ([Claude Code 문서, memory](https://code.claude.com/docs/en/memory)). + +**작업 상태**는 "이번 작업이 어디까지 왔나"를 적은 기록이다. 진행 기록, 할 일 목록, 계획 파일이 여기에 속한다. git(파일의 변경 이력을 저장하는 버전 관리 도구, §12.3 참조)의 커밋 기록도 작업 상태의 일부다. + +이 구분에서 중요한 것은 지침 파일과 작업 상태를 섞지 않는 일이다. "그림은 흑백으로"는 프로젝트가 끝날 때까지 유효한 규칙이므로 지침 파일에 들어간다. "회귀분석 진행 중, 다음은 잔차 확인"은 내일이면 바뀔 정보이므로 작업 상태 파일에 들어간다. 진행 상황을 지침 파일에 계속 덧붙이면 지침 파일이 길어지고 핵심 규칙이 묻힌다. + +검색 증강 생성(RAG, 필요한 문서를 찾아 그때그때 작업대에 올리는 방식)도 넓게 보면 기억 장치의 하나지만, 이 섹션에서는 다루지 않는다. 개념 사전의 RAG 항목을 참조하라. + +이렇게 기억을 여러 층으로 나누는 생각은 연구에서도 제안된 바 있다. 2023년 발표된 MemGPT는 운영체제가 빠른 저장 공간과 느린 저장 공간 사이에서 데이터를 옮기듯, 모델의 제한된 컨텍스트 밖에 여러 층의 기억 공간을 두고 필요한 정보를 들여오는 방식을 제안했다 ([Packer 외, 2023](https://arxiv.org/abs/2310.08560)). 오늘날 코딩 에이전트의 지침 파일과 메모리 노트도 같은 문제, 즉 작업대 밖에 무엇을 두고 언제 다시 올릴지를 다룬다. + +## 컨텍스트 압축: 작업대를 비우는 법 + +작업대가 차면 무언가를 치워야 한다. 압축(compaction)은 지금까지의 대화를 요약본으로 바꿔 공간을 되찾는 일이다. 회의가 길어졌을 때 지금까지의 논의를 몇 줄로 정리하고 다음 안건으로 넘어가는 것과 비슷하다. + +압축은 두 가지 방식으로 일어난다. 하나는 작업대가 한계에 가까워지면 하네스가 알아서 실행하는 자동 압축이다. 다른 하나는 사용자가 원하는 시점에 직접 실행하는 수동 압축이다. Claude Code에서는 `/compact` 명령으로 수동 압축을 하며, 요약할 때 무엇에 집중할지 지시를 덧붙일 수 있다 ([Claude Code 문서, sessions](https://code.claude.com/docs/en/sessions)). OpenAI의 Codex CLI에도 같은 이름의 명령이 있다 ([OpenAI Codex CLI 문서](https://learn.chatgpt.com/docs/codex/cli)). + +요약은 정보를 잃는다. Anthropic은 컨텍스트 관리에 관한 글에서, 무엇을 남기고 무엇을 버릴지 고르는 것이 압축의 핵심이며 지나치게 줄이면 나중에야 중요해지는 미묘한 정보를 잃는다고 썼다 ([Rajasekaran 외, 2025](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)). 같은 글은 더 가벼운 방법으로, 이미 쓰고 난 명령 실행 결과처럼 다시 볼 필요가 없는 내용만 지우는 방식도 소개한다. + +그렇다면 압축 뒤에 무엇이 남는가. Claude Code의 문서는 이를 구체적으로 밝힌다 ([Claude Code 문서, context window](https://code.claude.com/docs/en/context-window)). 2026년 10월 기준으로 정리하면 다음과 같다. + +- 대화 자체는 구조화된 요약으로 바뀐다. +- 프로젝트의 `CLAUDE.md`, auto memory, 계획 모드에서 작성한 계획은 디스크에서 다시 읽어 넣는다. +- 최근에 읽거나 고친 파일 몇 개를 다시 읽는다. + +여기서 중요한 원리가 나온다. **파일에 적힌 것은 압축 뒤에도 디스크에서 다시 읽히지만, 대화에서만 말한 것은 요약에 들어가야만 살아남는다.** A의 사례로 돌아가 보자. A는 30초 규칙을 대화 중에 말로만 정했다. 작업이 길어져 자동 압축이 일어났고, 요약에는 "데이터 정제를 마쳤다"는 내용만 남고 구체적인 기준은 빠졌다. 규칙이 정제 스크립트나 지침 파일에 적혀 있었다면 이 일은 일어나지 않았을 것이다. + +실무에서 쓸 만한 원칙을 정리하면 다음과 같다. + +- **중요한 결정은 압축 전에 파일로 옮긴다.** 규칙은 지침 파일에, 진행 상황은 작업 상태 파일에 적는다. +- **작업 단위가 끝난 시점에 압축한다.** 디버깅 도중처럼 세부가 중요한 순간에 압축하면 필요한 정보가 사라지기 쉽다. +- **수동 압축 때는 남길 것을 지시한다.** 예를 들어 "정제 기준과 제외한 응답 수는 반드시 남겨라"라고 덧붙인다. +- **압축 뒤에는 확인한다.** 에이전트에게 지금 적용 중인 핵심 규칙을 말해 보게 한다. + +긴 조사 작업을 하위 에이전트(subagent, 별도의 작업대에서 일하고 결과만 돌려주는 보조 에이전트)에게 맡겨 주 작업대를 덜 채우는 방법도 있다 ([Rajasekaran 외, 2025](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)). 이 방법은 §16.1에서 다룬다. + +## 세션을 끊고 다시 잇기 + +다음 날 작업을 이어갈 때 고를 수 있는 방법은 두 가지다. + +**첫째, 이전 대화를 재개한다.** 대부분의 코딩 에이전트는 대화 기록을 저장해 두었다가 다시 불러오는 기능을 제공한다. Claude Code에서는 `claude --continue`로 가장 최근 대화를, `claude --resume`으로 목록에서 고른 대화를 다시 연다. 재개하면 도구 호출과 그 결과를 포함한 대화 기록 전체가 복원된다 ([Claude Code 문서, sessions](https://code.claude.com/docs/en/sessions)). Codex CLI에도 저장된 대화로 돌아가는 `codex resume` 명령이 있다 ([OpenAI Codex CLI 문서](https://learn.chatgpt.com/docs/codex/cli)). + +**둘째, 새 세션에서 인수인계 메모를 읽힌다.** 빈 작업대에서 시작하되, 지금까지의 상황을 정리한 문서를 먼저 읽게 한다. 교대 근무자가 다음 근무자에게 남기는 인수인계 노트와 같다. + +두 방법은 장단점이 뚜렷하다. 재개는 맥락이 온전하다. 대신 이미 버린 시도와 오래된 논의도 함께 돌아오고, 작업대도 이미 찬 상태로 시작한다. 새로 시작하면 작업대가 깨끗하지만, 결과는 메모의 질에 달려 있다. Claude Code의 문서도 이 균형을 설명한다. 일정 조건에서 오래 쉰 긴 대화를 재개하면 요약본으로 이어갈지, 전체를 그대로 불러올지 묻는다. 요약으로 이어가면 이후 요청의 비용이 줄지만 요약에서 빠진 내용은 더 이상 작업대에 없다고 문서는 밝힌다 ([Claude Code 문서, sessions](https://code.claude.com/docs/en/sessions)). + +어느 쪽을 고를지는 대략 이렇게 정할 수 있다. 잠깐 쉬었다 같은 일을 이어간다면 재개가 편하다. 방향을 바꿨거나, 대화가 시행착오로 어지러워졌거나, 에이전트가 잘못된 가정에 계속 매달린다면 새로 시작하는 편이 낫다. + +새로 시작할 때 쓸 인수인계 메모에는 다음이 들어가야 한다. + +- 이 작업의 목표 +- 확정된 결정과 그 이유 +- 지금까지 끝난 일과 현재 상태 +- 다음에 할 일 +- 하지 말아야 할 일 (이미 시도했다가 버린 방법 등) + +셋째 날 A는 대화를 재개하지 않고 새 세션을 열었다. 그리고 다음 절에서 볼 진행 기록 파일을 먼저 읽게 했다. 에이전트는 정제 기준을 확인한 뒤 회귀분석의 다음 단계로 바로 넘어갔다. + +## 작업 상태를 밖에 적어 두기 + +앞의 두 절에서 반복해서 나온 원칙이 있다. 중요한 것은 대화가 아니라 파일에 둔다. 대화는 압축되거나 세션과 함께 사라지지만, 파일은 남고 사람도 읽을 수 있다. + +연구자가 실험 노트를 쓰는 이유와 같다. 실험 노트는 오늘 한 일, 조건, 결과, 다음에 할 일을 적어서 내일의 나나 다른 연구자가 이어받을 수 있게 한다. 에이전트에게 작업 상태 파일은 이 실험 노트에 해당한다. + +Anthropic은 여러 세션에 걸친 장기 코딩 작업을 실험하면서 이 원칙을 구체적인 구조로 만들었다 ([Young, 2025](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)). 이 글이 보고한 문제는 두 가지다. 에이전트가 한 번에 모든 것을 만들려다 중간에 작업대가 바닥나거나, 아직 덜 끝났는데 다 됐다고 선언했다. Anthropic이 보고한 해법은 다음과 같다. + +- 첫 세션에서 환경을 준비한다. 실행 스크립트(`init.sh`), 진행 기록 파일(`claude-progress.txt`), git 저장소를 만든다. +- 만들어야 할 기능 전체를 목록 파일(`feature_list.json`)로 정리하고, 기능마다 통과 여부를 표시한다. +- 이후 세션은 진행 기록과 git 기록을 읽고 시작해서, 기능 하나씩 진행한 뒤 진행 기록을 갱신하고 커밋한다. + +기능 목록에 통과 여부를 적어 두는 것은 "다 됐다"를 말이 아니라 기록으로 확인하게 만드는 장치다. 같은 이유로 테스트(코드가 의도대로 동작하는지 자동으로 확인하는 작은 프로그램, §10.1 참조)도 작업 상태 기록의 역할을 한다. "무엇이 끝났나"를 실행 결과로 보여주기 때문이다. 이 구조는 한 회사가 자기 실험에서 보고한 패턴이며, 모든 작업에 그대로 맞는 표준은 아니다. 다만 원리는 일반적이다. + +Anthropic의 다른 글은 이런 방식을 구조화된 노트 작성(structured note-taking)이라고 부르며, `NOTES.md` 같은 파일이나 할 일 목록을 예로 든다. Claude가 포켓몬 게임을 하면서 수천 단계에 걸쳐 목표와 지도, 전략을 노트로 남기며 진행한 사례도 소개한다 ([Rajasekaran 외, 2025](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)). + +A의 저장소에 있는 진행 기록 파일은 이런 모습일 수 있다. (예시로 만든 내용이다.) + +```markdown +# progress.md + +## 목표 +설문 데이터로 만족도 요인 회귀분석 보고서 작성 + +## 확정된 결정 +- 응답 시간 30초 미만 응답 제외 (성의 없는 응답으로 판단, 1일차 합의) +- 결측치는 해당 문항만 제외, 응답자 전체를 지우지 않음 + +## 진행 상황 +- [x] 데이터 정제 (clean.R) +- [x] 기술통계표 +- [ ] 회귀분석: 모형 1 완료, 모형 2 진행 중 +- [ ] 잔차 확인 + +## 하지 말 것 +- 원자료 파일(raw.csv) 직접 수정 금지 +``` + +이 파일을 누가 쓸지도 정해야 한다. 흔히 쓰는 방식은 에이전트에게 작업 단위가 끝날 때마다 이 파일을 갱신하라고 지시하고, 사람이 그 내용을 검토하는 것이다. 에이전트가 쓴 기록이 틀리면 다음 세션이 그 틀린 기록을 믿고 일하기 때문이다. 이 문제는 마지막 절에서 다시 다룬다. + +## 체크포인트: 되돌아갈 지점 만들기 + +체크포인트(checkpoint)는 특정 시점의 상태를 저장해 두었다가, 일이 잘못되면 그 시점으로 돌아갈 수 있게 하는 장치다. 게임의 저장 지점과 같은 개념이다. 체크포인트는 세 수준에서 볼 수 있다. + +**도구에 내장된 체크포인트.** Claude Code는 사용자가 요청을 보낼 때마다 그 직전의 코드 상태를 자동으로 저장한다. `/rewind` 명령으로 되감기 메뉴를 열어, 코드와 대화를 함께 되돌리거나 둘 중 하나만 되돌릴 수 있다. 체크포인트는 대화와 함께 저장되므로 세션을 재개한 뒤에도 쓸 수 있다 ([Claude Code 문서, checkpointing](https://code.claude.com/docs/en/checkpointing)). + +**git 커밋.** 사람이 의도적으로 남기는 저장 지점이다. 도구의 체크포인트가 자동으로 촘촘히 찍히는 임시 저장이라면, 커밋은 "여기까지는 제대로 동작한다"는 판단을 담은 저장이다. 에이전트와 일할 때는 작은 단위로 자주 커밋하는 습관이 특히 쓸모 있다. git을 이용한 변경 관리는 §12.3에서 다룬다. + +**워크플로 체크포인트.** 에이전트 작업을 여러 단계의 흐름(그래프)으로 설계할 때, 단계마다 상태를 저장하는 방식이다. 예를 들어 LangGraph라는 프레임워크는 하나의 작업 흐름(thread)의 상태를 단계마다 체크포인트로 저장한다. 이를 이용해 중간에 사람이 개입하거나, 이전 시점으로 돌아가거나, 장애 뒤에 이어서 실행할 수 있다. 같은 프레임워크는 여러 작업 흐름에 걸쳐 유지되는 장기 기억을 별도의 저장소(Store)로 구분한다 ([LangChain 문서, LangGraph persistence](https://docs.langchain.com/oss/python/langgraph/persistence)). 작업 흐름을 그래프로 설계하는 방법은 §6.4와 §16.2에서 다룬다. + +체크포인트에는 분명한 한계가 있다. Claude Code의 문서는 다음을 명시한다 ([Claude Code 문서, checkpointing](https://code.claude.com/docs/en/checkpointing)). + +- 에이전트가 파일 편집 도구가 아니라 셸 명령(`rm`, `mv`, `cp` 같은 터미널 명령)으로 바꾼 파일은 추적하지 않는다. 되감기로 되돌릴 수 없다. +- 대부분의 하위 에이전트가 한 편집도 되감기로 복원되지 않으며, git으로 되돌려야 한다. +- 사용자가 에이전트 밖에서 직접 고친 내용도 대개 추적하지 않는다. +- 체크포인트는 버전 관리(git)를 대체하지 않는다. + +이 목록에서 한 가지를 더 이끌어낼 수 있다. 체크포인트가 다루는 것은 작업 폴더 안의 파일이다. 데이터베이스에 쓴 내용, 보낸 이메일, 서버에 배포한 프로그램처럼 컴퓨터 밖으로 나간 변화는 처음부터 되감기의 대상이 아니다. 그래서 되돌릴 수 없는 작업 앞에는 사람의 승인 단계를 두는 것이 안전하다. 에이전트의 권한과 승인 설정은 §8.3에서 다룬다. + +A에게도 이 한계가 문제가 됐다. 둘째 날 에이전트가 분석 스크립트를 크게 고친 뒤 결과가 이상해지자, A는 되감기로 30분 전 상태로 돌아갔다. 스크립트는 되돌아왔다. 그런데 그 사이 에이전트가 셸 명령으로 정제된 데이터를 원자료 파일 위에 덮어쓴 일은 되돌아오지 않았다. 원자료를 git에 커밋해 두었거나, "원자료 직접 수정 금지"를 미리 지침 파일에 적어 두었다면 막을 수 있었던 일이다. + +## 기억이 해가 될 때 + +지금까지 기억을 남기는 방법을 다뤘다. 그런데 남긴 기억이 오히려 문제를 일으키기도 한다. + +**낡은 기억.** 첫날 지침 파일에 "그림은 흑백"이라고 적었다. 그 뒤 학회 제출 규정이 바뀌어 컬러 그림이 필요해졌지만 아무도 지침 파일을 고치지 않았다. 에이전트는 매 세션 흑백 그림을 만든다. 상황이 바뀌어도 기억은 스스로 바뀌지 않는다. + +**틀린 기억.** 에이전트가 잘못 추론한 내용을 메모리나 진행 기록에 적으면, 다음 세션은 그것을 사실로 믿고 출발한다. 사람의 착각은 대화 중에 바로잡히기도 하지만, 파일에 적힌 착각은 아무도 읽지 않으면 계속 남는다. + +**오염된 기억.** 웹 페이지나 문서에 숨겨진 지시가 에이전트를 속여 기억 공간에 무언가를 저장하게 만들 수 있다. 보안 연구자 Johann Rehberger는 2024년, 악성 웹사이트에 숨긴 지시로 ChatGPT의 장기 메모리에 공격자의 지시를 저장시키고, 그 뒤 모든 대화의 내용이 외부로 새어 나가게 할 수 있음을 보였다. 연구자에 따르면 OpenAI는 유출 경로를 수정했지만, 신뢰할 수 없는 웹사이트나 문서가 메모리 저장을 일으킬 수 있는 문제는 남아 있다 ([Rehberger, 2024](https://embracethered.com/blog/posts/2024/chatgpt-macos-app-persistent-data-exfiltration/)). 기억은 세션을 넘어 유지되기 때문에, 한 번 오염되면 그 영향도 다음 세션까지 따라간다. 숨은 지시의 공격 방식은 §9.3에서 다룬다. + +**민감 정보가 담긴 기억.** 비밀번호, API 키(외부 서비스에 접속할 때 쓰는 비밀 문자열), 개인정보가 진행 기록이나 메모리 노트에 적힐 수 있다. 이런 파일이 저장소에 커밋되어 공개되면 정보가 그대로 노출된다. 외부 모델에 보내는 데이터의 문제는 §9.5에서 다룬다. + +**비대해진 기억.** 지침 파일도 결국 작업대 위에 올라간다. Claude Code의 문서는 지침 파일이 길수록 작업대를 더 차지하고 지시를 따르는 정도가 떨어진다고 설명한다. 또 서로 모순되는 지시가 있으면 에이전트가 그중 하나를 임의로 고를 수 있으므로, 주기적으로 검토해 낡거나 충돌하는 지시를 지우라고 권한다. 같은 문서는 지침 파일이 강제 설정이 아니라 참고할 맥락으로 다뤄진다는 점도 밝힌다 ([Claude Code 문서, memory](https://code.claude.com/docs/en/memory)). 지침 파일에 적었다고 반드시 지켜지는 것은 아니다. + +대응 원칙은 기억을 코드처럼 다루는 것이다. + +- 지침 파일과 진행 기록도 변경 내용을 검토한다. +- 중요한 결정에는 날짜와 이유를 함께 적는다. 나중에 그 결정이 아직 유효한지 판단할 수 있다. +- 주기적으로 읽어 보고 낡은 내용을 지운다. +- 비밀 정보는 기억 파일에 넣지 않는다. + +## 정리 + +이 섹션의 내용을 장기 작업 전에 확인할 목록으로 정리한다. + +::: {.callout-tip} +## 장기 작업 전에 확인할 것 + +- 프로젝트 규칙은 지침 파일에, 진행 상황은 작업 상태 파일에 나눠 적었는가 +- 작업 단위가 끝날 때마다 작업 상태 파일을 갱신하고 커밋하는가 +- 압축 전에 중요한 결정을 파일로 옮겼는가 +- 다음 세션을 재개할지 새로 시작할지 정했고, 새로 시작한다면 인수인계 메모가 있는가 +- 되돌릴 수 없는 작업 앞에 사람의 승인 단계가 있는가 +- 기억 파일에 비밀 정보가 없는가, 마지막으로 검토한 날은 언제인가 +::: + +::: {.callout-note collapse="true"} +## 확장 포인터 + +- 이 섹션의 Claude Code 관련 서술은 2026년 10월 4일에 확인한 공식 문서를 기준으로 한다. 지침 파일 권장 길이, 체크포인트 보관 개수와 기간, 자동 압축 시점 같은 수치는 버전에 따라 바뀌므로 본문에 넣지 않았다. 갱신할 때 공식 문서를 다시 확인할 것. +- Codex CLI, Cursor 등 다른 도구의 압축·재개·체크포인트 동작 비교 (공식 문서 확인 필요) +- `AGENTS.md` 형식이 처음 공개된 시점 확인 +- 작업 상태 파일 패턴에 관한 Anthropic 외의 1차 자료 보강 +::: + +## 참고 자료 + +모든 링크는 2026년 10월 4일에 접속해 확인했다. + +- Anthropic. [Using the Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages). Claude 개발자 문서. +- Anthropic. [How Claude remembers your project](https://code.claude.com/docs/en/memory). Claude Code 문서. +- Anthropic. [Explore the context window](https://code.claude.com/docs/en/context-window). Claude Code 문서. +- Anthropic. [Manage sessions](https://code.claude.com/docs/en/sessions). Claude Code 문서. +- Anthropic. [Checkpointing](https://code.claude.com/docs/en/checkpointing). Claude Code 문서. +- Rajasekaran, P., Dixon, E., Ryan, C., Hadfield, J. 외 (2025-09-29). [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents). Anthropic Engineering. +- Young, J. (2025-11-26). [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents). Anthropic Engineering. +- Hong, K., Troynikov, A., Huber, J. (2025-07-14). [Context Rot: How Increasing Input Tokens Impacts LLM Performance](https://www.trychroma.com/research/context-rot). Chroma Research. +- Packer, C., Wooders, S., Lin, K., Fang, V., Patil, S. G., Stoica, I., Gonzalez, J. E. (2023). [MemGPT: Towards LLMs as Operating Systems](https://arxiv.org/abs/2310.08560). arXiv:2310.08560. +- AGENTS.md. [AGENTS.md](https://agents.md/). Agentic AI Foundation. +- OpenAI. [Codex CLI](https://learn.chatgpt.com/docs/codex/cli). Codex 문서. +- LangChain. [Persistence](https://docs.langchain.com/oss/python/langgraph/persistence). LangGraph 문서. +- Rehberger, J. (2024-09-20). [Spyware Injection Into Your ChatGPT's Long-Term Memory (SpAIware)](https://embracethered.com/blog/posts/2024/chatgpt-macos-app-persistent-data-exfiltration/). Embrace The Red.