본문으로 건너뛰기

Claude Code context, memory, MCP, Context7: 먼저 고장 난 레이어를 고치기

Claude Code가 규칙을 잊었을 때는 새 세션에서도 빠지는지 먼저 확인합니다. Context7 오류는 메모리를 늘리는 대신 설치 방식, 인증과 실제 문서 조회 결과를 차례로 점검해야 합니다.

LaoZhang AI Team게시업데이트 8 분 소요
목차
Claude Code의 현재 대화, 지속 메모리와 외부 도구를 구분하는 진단 도식

Claude Code가 앞서 정한 규칙을 잊었다면 긴 대화에서 흐름이 꼬였는지, 새 세션에 필요한 지침이 들어오지 않았는지부터 구분합니다. 전자는 /context를 보고 작업을 압축하거나 분리합니다. 후자는 /context의 Memory files에서 실제로 로드된 파일을 확인한 뒤 /memory로 수정할 위치를 찾습니다. Context7이 연결되지 않거나 엉뚱한 문서를 가져오는 경우에는 MCP 설정과 문서 조회를 점검합니다.

컨텍스트는 지금 모델이 처리하는 대화와 자료입니다. 지속 지침과 자동 메모리도 읽히면 이 컨텍스트의 일부가 됩니다. MCP는 외부 도구에 접근하는 연결 방식이고, Context7은 라이브러리 문서를 조회하는 서비스입니다. 따라서 Context7을 추가했다고 프로젝트의 결정을 장기 기억하게 되지는 않습니다.

문제가 생긴 시점으로 점검 시작하기

지금 겪는 증상첫 확인확인 뒤 할 일
같은 세션 후반에 폐기한 계획을 다시 제안한다/context에서 대화·파일·도구 결과의 비중현재 결정과 다음 작업을 남기고 /compact; 불필요하게 큰 조회는 범위를 줄이기
새 세션마다 테스트 명령이나 수정 금지 규칙이 빠진다/context → Memory files필요한 지침의 로드 여부 확인, /memory에서 올바른 파일 수정
압축 직후 진행 중이던 작업의 세부 사항이 사라진다압축 전후의 목표·완료 사항·미완료 사항대화에만 있던 작업 상태를 짧게 인계하고 필요한 원본 파일 다시 읽기
Context7이 목록에 없거나 인증을 요구한다/mcp, 수동 서버라면 claude mcp list와 get설치 방식과 실제 적용 범위 확인, 해당 경로의 인증 완료
연결은 됐지만 다른 라이브러리 문서로 답한다호출한 도구의 입력과 반환된 문서라이브러리 ID·버전·질문을 좁혀 다시 조회

긴 대화, 새 세션의 지침 누락과 Context7 연결 오류에 맞는 명령을 구분한 그림

그림은 점검 대상을 구분하는 데 사용합니다. 파일이 로드됐다는 근거는 /context에서 확인합니다. /memory에 경로가 표시된다는 사실만으로 해당 파일이 읽혔다고 판단하지 않습니다. 현재 공식 문서도 두 명령의 역할을 이렇게 구분합니다. Claude Code 메모리 문서

긴 세션에서 답변이 흔들리면 작업 상태부터 정리하기

/context를 실행해 무엇이 현재 컨텍스트를 차지하는지 봅니다. 많은 파일을 읽었거나 같은 로그를 반복해서 붙였다면, 외부 메모리 서버를 추가하기보다 다음 조회에서 필요한 부분만 가져오도록 바꾸는 편이 직접적인 조치입니다. 예를 들어 로그 전체 대신 오류가 발생한 구간, 데이터 전체 대신 필요한 필드와 한 페이지를 요청합니다.

압축하기 전에는 현재 작업을 다음처럼 정리합니다. 아래는 실제 실행 결과가 아닌 인계 메모 예시입니다.

목표: 로그인 후 설정 페이지가 열리지 않는 문제 수정
확정: 로그인 요청은 성공하며 이후 라우팅에서 오류가 발생함
완료: 오류가 발생한 파일과 재현 조건을 찾음
미완료: 라우팅 수정과 회귀 확인
유지할 조건: 인증 방식과 공개 API는 변경하지 않음
다음 작업: 오류 구간만 읽고 최소 수정안 제시

그다음 Claude Code 안에서 압축 범위를 지정합니다.

/compact 현재 목표, 확인된 원인, 완료한 수정, 미완료 검증과 변경 금지 조건을 남겨 주세요.

압축 후 Claude에게 목표와 다음 작업을 다시 말하게 하고 원본 파일과 대조합니다. 잘못된 요약이 남았다면 바로잡고 필요한 구간을 다시 읽습니다. 새로운 작업으로 넘어간다면 인계 메모를 저장한 뒤 /clear로 대화를 비울 수 있습니다. 아직 저장하지 않은 결정이 필요한 상태에서 먼저 지우지는 않습니다.

프로젝트의 시작 지침은 압축 뒤 다시 들어오지만, 대화에만 있던 세부 사항이 모두 보존되는 것은 아닙니다. 중첩 폴더의 지침이나 경로에 따라 적용되는 규칙은 해당 작업 때 다시 읽힐 수 있습니다. 압축 직후 자료를 다시 대량으로 읽어 컨텍스트를 채운다면, 압축을 반복하기보다 읽는 범위와 작업 단위를 바꿔야 합니다. 컨텍스트 윈도우와 압축

확인 기준은 빈 공간이 늘었다는 사실만이 아닙니다. 현재 목표와 제약을 정확히 유지하고, 이미 폐기한 방법을 다시 끌고 오지 않는지를 확인합니다. 코드 변경이 있었다면 그 변경에 맞는 테스트도 별도로 필요합니다.

새 세션에서 규칙을 잊으면 로드 여부와 저장 위치를 따로 확인하기

새 세션을 프로젝트에서 시작한 뒤 /context의 Memory files를 확인합니다. 필요한 파일이 없다면 시작한 디렉터리, 상위 디렉터리의 지침, 가져온 파일의 경로를 점검합니다. 그다음 /memory에서 해당 위치를 열거나 만듭니다. /memory에는 아직 존재하지 않는 위치도 표시될 수 있습니다.

지속 지침에는 매번 따라야 하는 규칙을 씁니다. 예를 들어 프로젝트의 지침 파일에 다음 내용을 짧게 넣을 수 있습니다. 실제 테스트 명령과 금지 범위는 자신의 저장소에 맞게 바꿉니다.

markdown
## 작업 규칙
- 코드 변경 후 npm test로 관련 테스트를 실행한다.
- 생성된 파일은 직접 수정하지 않고 원본을 수정한다.
- 인증 정책 변경이 필요하면 구현 전에 영향 범위를 설명한다.

저장한 뒤 새 세션에서 파일이 실제로 로드되는지 확인합니다. 이어 작은 작업을 요청해 규칙이 적용되는지 봅니다. 로드와 준수는 다른 문제입니다. 파일이 읽혀도 모호하거나 서로 충돌하는 지침은 기대한 행동을 보장하지 못하므로, 무엇을 언제 해야 하는지 명확하게 적습니다.

자동 메모리는 경험에서 남길 만한 정보를 선택적으로 저장하는 기능입니다. 매 대화 전체를 보관하는 기록 시스템은 아닙니다. MEMORY.md는 시작 시 앞부분 200줄 또는 25KB 중 먼저 도달하는 범위가 읽히며, 별도 주제 파일은 필요할 때 읽힙니다. 이 숫자를 모든 CLAUDE.md 파일의 강제 길이 제한으로 해석하면 안 됩니다. 긴 조사 기록은 원본에 보관하고 메모리에는 유효한 사실과 다시 찾을 위치를 남기는 편이 관리하기 쉽습니다. 같은 기기의 같은 Git 저장소에 속한 worktree들은 자동 메모리를 공유하지만, 다른 기기로 자동 동기화되는 것은 아닙니다. 자동 메모리의 로드와 저장 범위

AGENTS.md만 사용하는 저장소라면 버전 조건도 확인합니다. 직접 지원은 Claude Code 2.1.277 이상에서 제공됩니다. 기본 동작은 시작 디렉터리와 그 상위 경로에 프로젝트 CLAUDE.md나 CLAUDE.local.md가 없을 때 직접 읽는 방식입니다. 사용자 전역 CLAUDE.md는 이 조건에서 제외됩니다. /config의 Project instructions에서 함께 읽도록 선택할 수도 있습니다. 실제 적용은 /context에서 확인합니다. 프로젝트 지침 선택 조건

Context7 설치 방법에 맞는 인증 경로 선택하기

Context7 연결 오류를 고칠 때는 먼저 설치 도우미, 호스팅 플러그인, 수동 MCP 중 무엇을 사용했는지 확인합니다. 서로 다른 경로의 인증 처방을 섞으면 설정을 바꿔도 효과가 없을 수 있습니다. 아래 명령은 독자가 자신의 환경에서 사용할 문서 예제입니다. 이 글에서는 실제 계정 로그인이나 서버 호출을 수행하지 않았습니다.

설치 도우미로 CLI 또는 MCP 구성하기

터미널에서 다음 명령을 실행하는 공식 경로가 있습니다.

bash
npx ctx7 setup --claude

도우미는 기기 인증 링크와 코드를 안내하고, 인증 후 API key를 생성하며 관련 skill을 설치합니다. CLI와 MCP 모드를 선택할 수 있습니다. 설치된 skill은 라이브러리 질문에 자동으로 작동하므로 매번 use context7을 붙일 필요는 없습니다. CLI 모드를 골랐다면 MCP 목록에 서버가 없다는 이유만으로 실패라고 판단하지 않습니다. Context7의 Claude Code 설치 안내

호스팅 플러그인 연결하기

Claude Code 안에서 각각 입력합니다.

/plugin marketplace add upstash/context7
/plugin install context7@context7-marketplace

설치 후 Claude Code를 재시작하고 /mcp에서 Context7을 선택해 브라우저 로그인을 완료합니다. 호스팅 플러그인은 로컬 Node.js나 npm을 요구하지 않으며 CONTEXT7_API_KEY를 읽지 않습니다. 플러그인의 인증이나 사용량 문제를 환경 변수 export만으로 고치려 하지 말고, 플러그인에 연결한 계정과 인증 상태부터 확인합니다. 플러그인 설치와 로그인

API key가 필요하면 수동 HTTP 구성 사용하기

기존 Context7 API key로 수동 MCP를 연결하려면 다음처럼 프로젝트 루트의 .mcp.json에 서버 항목을 둘 수 있습니다. 파일이 이미 있다면 다른 서버를 덮어쓰지 말고 mcpServers 안에 필요한 항목만 합칩니다.

json
{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "Bearer ${CONTEXT7_API_KEY}"
      }
    }
  }
}

여기서 ${CONTEXT7_API_KEY}는 실제 키가 아닌 환경 변수 참조입니다. Claude Code를 시작하는 프로세스에 그 변수가 있어야 합니다. 키 자체를 저장소에 넣지 말고, 현재 세션이 이전 환경에서 시작됐다면 올바른 환경으로 다시 시작합니다. 프로젝트 서버의 사용 승인도 확인합니다. Claude Code의 환경 변수 확장, Context7 수동 HTTP 인증

수동 OAuth는 HTTP의 /mcp/oauth 경로를 사용하는 별도 구성입니다. 로컬 stdio 서버는 API key 인증을 사용합니다. 위 API key 예제의 URL을 플러그인 내부 인증에 그대로 대입하거나, stdio에 HTTP OAuth 처방을 적용하지 않습니다. Context7 클라이언트별 인증

목록에 보이는데 연결되지 않을 때

수동으로 이름을 context7로 등록한 서버는 해당 프로젝트의 터미널에서 확인합니다. 플러그인 서버는 /mcp에서 표시되는 실제 이름과 설치 출처를 확인합니다.

bash
claude mcp list
claude mcp get context7

Added는 설정을 저장했다는 뜻입니다. 연결과 인증, 문서 조회 성공까지 증명하지는 않습니다. 상태를 읽고 해당 원인만 수정합니다.

표시되는 상태나 문제다음 조치
Pending approval프로젝트의 서버 구성을 검토하고 사용 승인
Disabled 또는 Rejected연결 재시도 전에 비활성화·거부한 설정 확인
Needs authentication선택한 설치 경로의 로그인 또는 API key 인증 완료
Failed to connectIssue의 HTTP 상태·오류 코드 확인; URL·헤더·전송 방식에서 원인 수정
cached … connects on first use캐시된 도구 목록일 수 있으므로 실제 호출 또는 Reconnect로 연결 확인

Issue의 자세한 오류 표시는 버전에 따라 다르며 현재 문서는 2.1.219 이상에서의 표시를 설명합니다. 헤더 값의 앞뒤 공백이나 type: "http" 누락도 확인합니다. MCP 상태와 구성 경고

다른 프로젝트에서는 작동하는데 여기서는 실패한다면 설정 범위를 확인합니다. local은 현재 프로젝트에서 개인용, project는 .mcp.json으로 팀 공유, user는 모든 프로젝트에서 개인용입니다. 같은 이름이 여러 범위에 있으면 상위 우선순위의 서버 항목 전체가 적용되므로 다른 범위의 헤더가 합쳐진다고 기대하면 안 됩니다. 기존 항목이 무엇인지 확인한 뒤 원하는 구성을 남깁니다. MCP 설정 범위

원인이 드러나지 않을 때는 현재 공식 CLI의 디버그 옵션을 사용할 수 있습니다.

bash
claude --debug='mcp,startup'

범주 필터에는 =를 사용합니다. 로그를 파일로 남기려면 --debug-file 옵션이 있습니다. 로그는 필요한 오류 부분만 확인하고 공유 전 토큰과 개인 정보를 제거합니다. 예전 글의 claude mcp logs context7을 공통 진단 명령으로 가정하는 대신 설치 버전의 공식 CLI 옵션을 따릅니다. CLI 디버그 옵션

연결 성공 뒤에는 문서를 실제로 조회했는지 확인하기

Context7의 현재 MCP 도구는 resolve-library-id와 query-docs입니다. 연결 상태와 도구 개수가 정상이어도 이번 답변이 문서 조회를 사용했다는 뜻은 아닙니다. 다음처럼 라이브러리, 버전과 필요한 기능을 함께 지정합니다.

이 프로젝트는 Next.js 15를 사용합니다.
Context7의 /vercel/next.js에서 15 버전의 App Router 문서를 조회해 주세요.
미들웨어 설정에 필요한 부분만 가져오고, 조회한 문서의 링크와
확인한 버전을 답변에 남겨 주세요. 다른 버전이면 차이를 밝혀 주세요.

/vercel/next.js는 공식 안내의 라이브러리 ID 예시입니다. 다른 라이브러리라면 먼저 resolve-library-id가 반환한 후보에서 목적에 맞는 ID를 고릅니다. 원하는 버전의 문서가 있는지도 반환 결과로 확인합니다. 특정 버전을 프롬프트에 썼다는 이유만으로 그 버전이 조회됐다고 단정하지 않습니다. Context7 라이브러리 ID 사용

성공 판단은 세 단계입니다. 실제 도구 호출이 있었는지, 입력이 원하는 라이브러리와 질문을 가리키는지, 반환된 문서가 요청한 버전과 기능을 뒷받침하는지 확인합니다. “문서를 확인했습니다”라는 답변만 남고 호출 결과가 없다면 조회의 증거가 부족합니다. 이때 메모리를 늘리기보다 조회 요청을 좁히고 원문 링크를 확인합니다.

증상, 컨텍스트 사용량, 메모리와 MCP 상태를 함께 기록하는 진단 자료 도식

공유할 진단 기록에는 발생 시점, 실제 로드된 지침 파일 이름, MCP 설치 방식과 범위, 오류 코드, 호출한 라이브러리 ID와 문서 링크를 남깁니다. 키나 전체 대화 기록은 문제를 설명하는 데 필요하지 않습니다.

외부 memory MCP를 검토할 시점

지속 규칙은 프로젝트 지침, 작업 중 결정은 인계 메모, 라이브러리 문서는 Context7처럼 용도에 맞는 곳에서 관리할 수 있습니다. 큰 조사는 별도 subagent로 맡기고 현재 작업에 필요한 결과만 받는 방법도 있습니다. 다만 새 subagent가 메인 세션의 자동 메모리를 그대로 알고 있다고 가정하지 말고, 필요한 목표와 제약을 입력으로 전달합니다. 컨텍스트를 분리하는 방법

여러 기기나 도구에서 같은 작업 상태를 조회해야 하거나 팀이 변경되는 사실을 함께 사용해야 한다면 외부 memory MCP가 후보가 됩니다. 이 경우 저장할 사실, 읽을 사람, 수정·삭제 방법을 먼저 정하고 한 프로젝트에서 작게 확인합니다. 이전에 정한 결정을 올바르게 찾아오는지, 폐기한 정보를 여전히 답하는지, 추가 도구 결과가 컨텍스트를 다시 크게 채우는지 비교합니다.

이것은 외부 메모리 도입을 위한 판단 기준입니다. 특정 서버를 설치하면 컨텍스트 혼선과 연결 오류가 함께 해결된다는 보장은 아닙니다. 앞에서 확인한 원인이 이미 해결됐다면 새 서버를 추가할 이유도 다시 검토할 수 있습니다.

자주 묻는 질문

/memory에 파일이 보이면 로드된 것인가요?

경로가 표시되는 것만으로는 확인할 수 없습니다. /memory는 위치를 찾고 파일을 열거나 만드는 관리 화면이고, 실제로 읽힌 지침은 /context의 Memory files에서 확인합니다. 메모리 관리와 로드 확인

/compact를 하면 프로젝트 규칙도 사라지나요?

시작 시 적용되는 프로젝트 지침은 다시 들어옵니다. 대화에서만 합의한 세부 사항은 요약에서 빠질 수 있으므로 목표, 현재 결정과 미완료 작업을 명시적으로 남깁니다. 경로별 규칙은 해당 파일을 다룰 때 적용될 수 있습니다. 압축 이후의 컨텍스트

Context7 플러그인에 API key 환경 변수를 설정해야 하나요?

현재 호스팅 플러그인은 CONTEXT7_API_KEY를 읽지 않습니다. /mcp에서 브라우저 로그인으로 인증합니다. API key를 사용하려면 설치 도우미나 수동 MCP 구성을 선택합니다. Context7 인증 경로

Tool Search를 켜면 MCP가 컨텍스트를 차지하지 않나요?

도구 정의를 처음부터 모두 올리는 부담을 줄일 수 있지만, 실제 호출 결과는 여전히 컨텍스트에 들어옵니다. 큰 출력은 조회 범위와 필드를 줄여야 합니다. 사용 가능 여부도 모델과 API 제공 환경에 따라 다르므로 프록시에서 설정만 강제로 켜면 된다고 가정하지 않습니다. MCP Tool Search

코드 위치와 긴 로그도 자동 메모리에 넣어야 하나요?

코드 위치는 현재 파일 검색으로, 긴 로그는 원본 기록으로 확인하는 편이 적합합니다. 자동 메모리를 전체 세션의 백업처럼 쓰기보다 사용자 선호, 유효한 결정과 참고 자료의 위치를 남깁니다. 항상 따라야 하는 지침은 자동 저장을 기다리지 말고 프로젝트 지침에 명시합니다. 지침과 자동 메모리의 역할

참고 자료6

이 글이 링크한 외부 페이지를 본문에 나온 순서대로 정리했습니다. 마지막 업데이트: 2026년 10월 7일.

  1. 1.Claude Code 메모리 문서code.claude.com/docs/en/memory
  2. 2.컨텍스트 윈도우와 압축code.claude.com/docs/en/context-window
  3. 3.Context7의 Claude Code 설치 안내context7.com/docs/clients/claude-code
  4. 4.Claude Code의 환경 변수 확장code.claude.com/docs/en/mcp
  5. 5.Context7 수동 HTTP 인증context7.com/docs/resources/all-clients
  6. 6.CLI 디버그 옵션code.claude.com/docs/en/cli-reference
Claude Code에서 작업에 맞는 첫 MCP를 선택하는 경로
Claude Code

Claude Code MCP 추천: 용도별 첫 서버 선택과 설치 확인

PR과 이슈가 필요하면 GitHub, 버전별 문서가 필요하면 Context7, 브라우저 동작 확인은 Playwright, 운영 오류 조사는 Sentry가 첫 후보입니다. 이미 쓰는 도구로 충분한지 확인한 뒤, 필요한 서버 하나를 연결하고 실제 조회 결과까지 확인하세요.

10 분
Claude Code에서 MCP 도구 정의와 호출 결과에 컨텍스트 공간을 나누는 개념도
Claude Code

Claude Code MCP 컨텍스트 과부하: 원인 찾기와 큰 출력 줄이기

MCP 서버 수를 줄이기 전에 컨텍스트가 언제 늘어나는지 확인하세요. 도구 검색은 정의 로딩을 늦추고, 필터링과 분할 조회는 큰 반환값을 줄입니다. 정리한 뒤에도 같은 기록에 접근하고 필요한 작업을 끝낼 수 있어야 합니다.

8 분