모든 코딩 에이전트 세션은 빈 상태에서 시작합니다. Claude Code도 자체 문서에서 이렇게 밝힙니다. 각 세션은 새로운 컨텍스트 윈도우에서 시작한다고요. 대화 외부의 무언가가 이어주지 않는 한, 이 도구는 어제 알려준 내용을 기억하지 못합니다. 따라서 AI 세션 간에 컨텍스트를 유지하는 방법을 익힌다는 것은 하나의 요령이 아닙니다. 어떤 컨텍스트가 네 가지 계층 중 어디에 속하는지 파악하고, 세션이 끝나기 전에 그 자리에 넣어두는 일입니다.
이 가이드에서는 네 가지 계층을 순서대로 살펴봅니다. 도구가 실행 시 읽는 지침 파일, 도구가 스스로 작성하는 노트, 세션 재개, 그리고 앞의 세 가지가 제공하지 못하는 공유 작업 기록입니다. 앞의 세 가지는 Claude Code, Codex, Gemini CLI의 기능입니다. 네 번째가 바로 Sharkly가 자리하는 곳입니다. 목표와 논의, 실행, 승인까지 담는 Task는 다른 사람이 읽을 수 있는 유일한 계층이기 때문입니다. 대화와 할당 중 무엇을 선택할지 고민 중이라면, AI 에이전트와 대화하기, 아니면 Task 할당하기 가이드가 함께 보면 좋은 글입니다.
TL;DR
컨텍스트는 네 곳에서 세션을 넘어 살아남습니다. 지침 파일(CLAUDE.md, AGENTS.md, GEMINI.md)은 도구가 매번 지켜야 할 규칙을 담습니다. 자동 메모리는 도구가 학습한 수정 사항과 선호도를 담습니다. 세션 재개는 한 사람이 한 기기에서 이어가는 하나의 대화를 담습니다. 작업 기록, 즉 설명과 댓글, 실행 로그를 갖춘 Task는 무엇이 결정되고 무엇이 실행되었으며 누가 승인했는지를 담으며, 유일하게 공유되는 계층입니다. 각 컨텍스트를 제 계층에 넣어두면 새로운 컨텍스트 윈도우는 더 이상 손실이 아닙니다.
계층 1: 도구가 실행 시 읽는 지침 파일
지침 파일은 한 번 작성해두면 도구가 모든 세션에서 불러오는 컨텍스트입니다. 주요 CLI마다 하나씩 있으며, 비슷한 방식으로 해석됩니다.
| 도구 | 파일 | 해석 방식 |
|---|---|---|
| Claude Code | CLAUDE.md(프로젝트 또는 .claude/CLAUDE.md), ~/.claude/CLAUDE.md(사용자), CLAUDE.local.md(개인용, gitignore됨) |
작업 디렉터리와 그 상위 모든 디렉터리에서 로드되며 루트부터 아래로 이어 붙여집니다. 하위 디렉터리 파일은 필요할 때 로드됩니다 |
| Codex | AGENTS.md, 전역 범위용 ~/.codex/AGENTS.md, 임시 재정의용 AGENTS.override.md |
Git 루트부터 아래로 이어 붙이며, project_doc_max_bytes로 제한되고 기본값은 32KiB입니다 |
| Gemini CLI | GEMINI.md, 전역 범위용 ~/.gemini/GEMINI.md |
전역, 워크스페이스, 필요 시점(just-in-time) 탐색을 지원하며 /memory show로 병합된 결과를 확인할 수 있습니다 |
이 계층을 유용하게 유지하는 두 가지 습관이 있습니다. 먼저 파일을 짧게 유지하세요. Claude Code의 가이드라인은 파일당 200줄 이하를 권장하는데, 파일이 길어질수록 준수율이 떨어지기 때문입니다. 그리고 빌드 명령어나 컨벤션, 지난 세션에서 채팅에 입력했던 규칙처럼 다시 설명하게 될 사실을 적어두세요. 저장소에 이미 AGENTS.md가 있다면 @AGENTS.md만 담은 CLAUDE.md가 이를 불러오므로, 두 도구가 하나의 소스를 읽게 됩니다. 이 계층의 모든 내용은 강제가 아니라 컨텍스트입니다. Claude Code 메모리 문서는 행동을 차단하는 것이 지침이 아니라 훅이라고 분명히 밝히고 있습니다.
계층 2: 도구가 스스로 작성하는 노트
Claude Code의 자동 메모리는 사람들이 존재 자체를 잊고 지내는 계층입니다. 작업하는 동안 Claude는 사용자의 역할과 선호도, 사용자가 준 수정 사항, 코드에서 도출할 수 없는 프로젝트 컨텍스트, 저장소 외부에서 무언가를 찾는 위치에 대한 노트를 저장합니다. 이 노트는 ~/.claude/projects/<project>/memory/에 위치하며, MEMORY.md가 색인 역할을 하여 매 세션 시작 시 처음 200줄 또는 25KB가 로드됩니다. 주제 파일은 필요할 때 로드됩니다.
세 가지 경계를 기억해야 합니다. 자동 메모리는 저장소 단위이며 워크트리 간에 공유됩니다. 기기에 로컬로 저장되므로 데스크톱에 있는 노트는 노트북에 존재하지 않습니다. 또한 /compact 이후에도 살아남습니다. 압축은 대화를 다시 쓰는 것이지 디스크의 파일을 바꾸는 게 아니기 때문입니다. 저장된 내용을 보려면 /memory를 실행하고, 끄려면 autoMemoryEnabled를 false로 설정하거나 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1을 내보내면 됩니다.
한 번 말하면 계속 유지되길 바라는 내용에 이 계층을 사용하세요. 예를 들어 "항상 pnpm을 써", "API 테스트에는 로컬 Redis가 필요해" 같은 것입니다. 팀 동료가 알아야 할 결정 사항을 여기에 의존하지 마세요. 이건 오롯이 당신만의 것입니다.
계층 3: 세션 재개
때로는 필요한 컨텍스트가 대화 자체일 때가 있습니다. Claude Code는 세션을 디스크에 보관합니다. claude --continue는 현재 디렉터리의 가장 최근 대화를 다시 열고, claude --resume <id-or-name>은 특정 대화를 다시 열며, --fork-session은 새 세션 ID를 만들어 체크포인트에서 덮어쓰지 않고 분기할 수 있게 해줍니다. /clear하기 전에 /rename으로 세션 이름을 바꿔두면 나중에 다시 찾을 수 있습니다. Codex는 codex resume으로 현재 저장소의 최근 채팅을 다시 열 수 있습니다.
재개에는 비용이 따릅니다. 모든 요청이 전체 대화를 함께 실어 나르기 때문에, 오래 유지된 세션은 한 줄짜리 질문에도 새 세션보다 더 많은 사용량을 소모합니다. /compact Focus on the migration plan처럼 초점을 지정한 /compact는 세부 사항을 공간과 맞바꿉니다. 압축 후 살아남는 것은 요약본과 지침 파일이 다시 불러오는 내용입니다. 대화에서만 언급되고 요약되지 않은 내용은 사라집니다. 재개는 점심시간을 넘기는 다리로 생각하고, 팀의 기억으로 여기지 마세요.
계층 4: 작업 기록
앞의 세 계층 중 어느 것도 목요일에 동료가 던지는 질문에 답하지 못합니다. 화요일에 에이전트가 무엇을 했고, 왜 했으며, 누가 승인했을까? 지침 파일은 규칙을 담습니다. 자동 메모리는 한 사람의 선호도를 담습니다. 재개된 세션은 한 기기에서 한 사람의 대화를 담습니다. 결정과 실행, 승인에는 공유 기록이 필요하며, 그 기록이 바로 Task입니다.
Sharkly에서 Task 기반 실행에는 Task 제목과 설명, 최근 댓글과 실행을 촉발한 댓글, Agent의 지침과 Skills, Task에 구성된 저장소가 포함됩니다. 이것이 컨텍스트 핸드오프입니다. 다음 실행은 이전 세션의 기억이 아니라 Task에서 시작됩니다. 진행 상황, 추적 이벤트, 결과는 Task로 돌아가며, 실행 로그에는 실행이 대기열에 들어간 이유, 시작·종료 시각, 도구 호출, 트리거 출처, 실패 세부 정보가 기록됩니다.
제품 문서의 두 가지 규칙이 무엇을 어디에 둘지 결정하며, 둘 다 기능이라기보다 경계 규칙입니다. 독립형 Agent Chat 세션은 이를 생성한 사람의 것이며 다른 멤버는 접근 권한을 받지 못합니다. 팀에 결론이 필요하다면 Task 설명이나 댓글에 복사해 넣으세요. 그리고 Task의 Agent 채팅은 댓글이 아닙니다. Activity에 나타나지 않으므로 누군가 기록하지 않는 한 그곳에서 내린 결정은 보이지 않습니다. Claude Code 프로젝트 관리 워크스루에서는 이슈부터 리뷰까지 변경 사항을 담는 Task를 보여줍니다.
이 글이 다루는 함정과 정확히 맞닿아 있어 한 가지 구분을 더 짚어볼 만합니다. Crew는 공유 Task 디렉터리 재사용을 활성화할 수 있어, 나중에 실행되는 Agent 멤버가 같은 Computer에서 앞선 멤버의 로컬 변경 사항을 이어받습니다. 이 설정이 공유하는 것은 파일 시스템 상태이지 이전 Agent의 프로바이더 세션이 아닙니다. 파일은 이어지지만 모델의 대화는 이어지지 않습니다. 두 번째 Agent가 첫 번째 Agent의 추론을 필요로 한다면, 그것은 Task에 있어야 합니다.
컨텍스트 종류별로 제 계층에 넣기
| 컨텍스트 종류 | 계층 | 예시 |
|---|---|---|
| 모든 세션에 적용되는 규칙 | 지침 파일 | 커밋 전에 테스트 스위트 실행 |
| 수정 사항 또는 선호도 | 자동 메모리 | npm이 아니라 pnpm 사용 |
| 미완성 탐색 | 세션 재개 | 어제의 디버깅 스레드 |
| 여러 Agent가 공유하는 재사용 가능한 절차 | Skill | 릴리스 체크리스트 |
| 목표, 범위, 승인 기준 | Task 설명 | 구축 중인 요구 사항 |
| 결정, 근거, 리뷰 결과 | Task 댓글 | 옵션 B를 선택한 이유 |
| 무엇이 언제 실행되었고 어떻게 끝났는지 | 실행 로그 | 실패한 마이그레이션 실행 |
Skill은 별도의 행을 차지할 자격이 있습니다. Skill은 반복적으로 적용되어야 할 지침을 위해 재사용 가능한 지침과 지원 파일을 패키징하며, 로컬 Runtime 디렉터리에서 발견된 Skill은 조직으로 가져와 한 대의 노트북에만 머무르지 않게 할 수 있습니다. Skills in Sharkly 가이드에서는 범위와 바인딩을 다루고, 코딩 에이전트 스킬이란 무엇인가에서는 파일 형식을 다룹니다.
컨텍스트가 당신이 일하는 방식에 관한 것이라면 지침 파일과 자동 메모리를 사용하세요. 컨텍스트가 팀이 무엇을 만드는지에 관한 것이고 다른 사람이 읽어야 할 수도 있다면 Task를 사용하세요. Sharkly는 Claude Code, Codex 또는 다른 실행 도구를 대체하는 것이 아니라, 그런 도구들이 남기지 않는 공유 기록을 더해줍니다.
FAQ
/compact 명령이 내 CLAUDE.md를 잃어버리나요? 아니요. 프로젝트 루트의 CLAUDE.md는 압축 후 디스크에서 다시 읽혀집니다. 대화에서만 전달된 지침은 사라질 수 있으니, 그런 내용은 파일로 옮기세요.
자동 메모리는 팀과 공유되나요? 아니요. 홈 디렉터리 아래에 저장소별로 저장되며 동기화되지 않습니다. 팀이 볼 수 있어야 하는 컨텍스트는 저장소에 커밋된 지침 파일이나 Task에 속합니다.
Sharkly의 Agent가 이전 실행을 기억할 수 있나요? 매 실행마다 Task와 최근 댓글, 트리거 댓글을 받으며, 이것이 지속적인 형태의 기억입니다. 이전 실행의 비공개 대화는 받지 않습니다. 실행에 무엇이 포함되는지는 Agents in Sharkly를 참고하세요.
MCP 메모리 서버는 어떤가요? 모델이 질의할 수 있는 다섯 번째 저장소를 추가하며, 코드베이스의 구조적 회상에 유용합니다. 그래도 누가 변경을 승인했는지는 기록하지 않으므로, 작업 기록을 대체하기보다 함께 사용하세요.
