AI 코딩 어시스턴트를 쓰다 보면 반드시 한 번쯤 겪는 순간이 있다. 작은 버그 하나를 고쳐달라고 했을 뿐인데, 세션이 끝날 즈음엔 API 레이어 전체가 재작성되어 있고, 새 패키지 세 개가 설치되어 있고, 데이터 페칭 패턴이 통째로 바뀌어 있다. 모델이 이상한 게 아니다. 컨텍스트가 없었던 것이다.
dev.to에 올라온 한 현장 글이 이 문제를 정확하게 짚었다. Cursor, Claude Code, Windsurf 같은 도구들은 새 세션을 열 때마다 제로에서 시작한다. 어제 내가 설명한 스택 구조도, 절대 건드리지 말아야 할 파일도, 우리 팀의 컨벤션도—모두 사라진다. 그래서 매번 첫 10분을 재설명에 쓰고, 마지막 한 시간을 되돌리는 데 쓴다. 이건 프롬프트 실력의 문제가 아니라, 세션 지속성의 구조적 부재가 만드는 문제다.
해결책은 생각보다 단순하다. .cursorrules(Windsurf라면 .windsurfrules)와 CLAUDE.md—두 파일을 프로젝트 루트에 두면 된다. 이 파일들은 세션이 시작될 때 자동으로 로드되어, AI가 첫 줄부터 내 프로젝트의 맥락 안에서 동작하게 만든다. 핵심은 내용의 구체성이다. "TypeScript를 사용하고 클린 코드를 작성하라"는 너무 모호해서 모델 행동을 실질적으로 바꾸지 못한다. 실제로 효과가 있는 설정은 훨씬 구체적이다—어떤 라우터를 쓰는지(Next.js 14 App Router, Pages Router 아님), 어떤 상태 관리를, 어떤 임포트 alias를 쓰는지까지.
그 중에서도 가장 ROI가 높은 부분은 DO NOT 섹션이다. AI 어시스턴트는 본질적으로 최적화를 지향한다. 명시적 금지가 없으면 '개선'이라는 이름으로 작동 중인 코드를 건드린다. pages/ 디렉토리를 만들지 말 것, 관련 없는 파일을 드라이브바이 리팩토링하지 말 것, 이유 없이 npm 패키지를 추가하지 말 것, Server Components로 처리 가능한 데이터를 useEffect에서 페칭하지 말 것—이런 구체적인 안티패턴 목록이 "조심해라"는 막연한 지시보다 훨씬 강력하게 작동한다. 프로젝트를 하면서 AI가 저질렀던 최악의 실수 다섯 가지를 떠올려 보라. 그게 당신의 DO NOT 섹션 초안이다.
그런데 설정 파일로 해결되는 문제가 있고, 그것만으로는 부족한 문제가 있다. 대규모 프로덕션 코드베이스에서 AI 에이전트가 틀리는 이유는 단순히 컨텍스트를 몰라서가 아니다. 찾을 수가 없어서다. 8만 줄이 넘는 코드베이스에서 "유저 인풋 유효성 검사는 어디서 하나요?"라고 물으면, 에이전트는 파일을 하나씩 읽다가 컨텍스트 한도에 부딪히고, 그럴듯하지만 틀린 파일 경로를 자신 있게 반환한다. 이 문제를 해결하려고 등장한 것이 MCP(Model Context Protocol) 기반 툴킷이다.
dev.to에서 공개된 오픈소스 프로젝트 mcp-server-toolkit은 이 문제를 네 가지 서버로 접근한다. mcp-code-search는 저장소 전체를 대상으로 코드를 검색해 파일 경로와 줄 번호를 돌려준다. mcp-database는 자연어 질문을 읽기 전용 SQL로 변환해 실행한다—기본값이 읽기 전용이라는 점이 중요하다. mcp-docs는 마크다운 문서를 인덱싱해 로컬에서 검색 가능하게 만들고, mcp-git은 git blame과 커밋 히스토리를 통해 코드가 '왜' 바뀌었는지까지 추적한다. 기존 AI 에이전트의 워크플로우가 '파일 랜덤 읽기 → 추측 → 어쩌면 맞는 답변'이었다면, MCP 툴킷 이후는 '적절한 도구로 검색 → 관련 결과 확인 → 근거 있는 답변'으로 바뀐다.
이 두 흐름을 함께 놓고 보면 하나의 결론이 보인다. 설정 파일이 '이 AI가 내 프로젝트의 규칙을 알게 하는 것'이라면, MCP는 'AI가 내 프로젝트의 실체에 접근하게 하는 것'이다. 전자가 규범적 컨텍스트라면, 후자는 검색 가능한 컨텍스트다. 둘 다 없으면 AI는 매 세션마다 백지에서 시작하는 유능한 외부인이고, 둘 다 있으면 프로젝트를 정말로 아는 팀원처럼 동작한다. AI 도구의 품질은 모델 성능보다 컨텍스트 설계에 달려 있다는 말이 점점 더 현실이 되고 있다.
더 넓은 시각에서 보면, 이 흐름은 단순한 설정 팁의 문제가 아니다. Agentic Design Patterns를 다룬 velog의 글이 정리하듯, AI가 실제로 일하는 시스템이 되려면 프롬프트 하나가 아니라 구조가 필요하다. 컨텍스트 설정 파일은 그 구조의 최소 단위다. 세션마다 규칙을 재설명하는 것은 AI에게 메모리를 만들어주는 게 아니라, 메모리가 없는 시스템에 반복 입력을 넣는 것에 불과하다. 반면 .cursorrules와 CLAUDE.md는 AI가 '이 환경에서 어떻게 행동해야 하는가'를 처음부터 알고 시작하게 만드는 최소한의 장치다.
실전 적용은 이렇게 시작하면 된다. 먼저 프로젝트 루트에 .cursorrules 또는 CLAUDE.md를 만든다. 스택과 버전, 주요 디렉토리 구조, 실행 명령어를 명시한다. 그리고 지금까지 AI가 저질렀던 최악의 실수들을 DO NOT 섹션에 구체적으로 나열한다. 여기까지가 컨텍스트 설계의 1단계다. 2단계는 대규모 코드베이스라면 MCP 서버를 붙여 검색 가능성을 확보하는 것이다. npx mcp-server-toolkit@latest init 한 줄로 시작할 수 있다. 과도하게 정교하게 만들려고 하지 않아도 된다. 3줄 커스터마이즈로 시작해서, AI가 다시 같은 실수를 할 때마다 규칙을 추가하면 된다.
앞으로 AI 코딩 도구는 더 강력해질 것이다. 모델은 계속 좋아지고, MCP처럼 도구와 에이전트를 연결하는 표준도 빠르게 성숙해지고 있다. 하지만 도구가 강력해질수록 컨텍스트 설계의 중요성도 같이 올라간다. 아무것도 모르는 상태에서 강력한 에이전트를 실행하면, 빠르게 많은 것을 망가뜨릴 수 있다. 결국 AI를 잘 쓰는 개발자와 그렇지 않은 개발자의 차이는 프롬프트 실력보다 컨텍스트를 얼마나 잘 설계하느냐로 갈릴 것이다. 세션이 시작되기 전에 이미 절반은 결정된다.