{
“title”: “.claude/ 폴더 해부: AI 코딩 어시스턴트 완벽 제어”,
“summary”: “최근 해커뉴스에서 큰 화제가 된 .claude/ 폴더는 AI 코딩 어시스턴트에게 프로젝트의 맥락과 규칙을 주입하는 핵심 공간입니다. 이 폴더를 제대로 구성하면 AI의 환각(Hallucination) 현상을 줄이고 팀의 코딩 컨벤션에 정확히 맞는 코드를 생성할 수 있습니다. 본 글에서는 .claude/ 폴더의 내부 구조와 실무에서 AI의 생산성을 극대화하기 위한 설정 방법을 깊이 있게 파헤쳐 봅니다.”,
“html”: “
도입부 — 왜 중요한가
\n
최근 해커뉴스(Hacker News)에서 334점이라는 높은 점수를 기록하며 개발자들의 이목을 끈 주제가 있습니다. 바로 .claude/ 폴더의 해부(Anatomy)에 관한 내용입니다. 우리는 이미 .github/ 폴더를 통해 CI/CD 파이프라인을 관리하고, .vscode/ 폴더로 에디터 설정을 팀원들과 공유하는 데 익숙합니다. 이제 AI 코딩 어시스턴트의 시대가 본격화되면서, AI에게 우리 프로젝트의 ‘맥락(Context)’을 이해시키기 위한 전용 디렉토리인 .claude/ 폴더가 새로운 표준으로 자리 잡고 있습니다.
\n
기존에 ChatGPT나 Claude 웹 인터페이스를 사용할 때 가장 큰 불만은 매번 프로젝트의 아키텍처, 사용 중인 라이브러리 버전, 팀의 코딩 컨벤션을 반복해서 설명해야 한다는 점이었습니다. 이를 생략하면 AI는 구식 라이브러리 문법을 사용하거나, 프로젝트 구조와 전혀 맞지 않는 코드를 뱉어내는 이른바 ‘환각(Hallucination)’ 현상을 보입니다. .claude/ 폴더는 프로젝트 최상단(Root)에 위치하여 AI 에이전트(예: Claude Code CLI)가 코드를 작성하거나 리뷰할 때 반드시 참고해야 하는 ‘두뇌’이자 ‘규칙서’ 역할을 합니다. 이를 통해 AI는 단순한 코드 생성기를 넘어, 프로젝트의 맥락을 완벽히 이해하는 시니어 개발자 수준의 페어 프로그래밍 파트너로 진화하게 됩니다.
\n\n
핵심 개념 설명
\n
.claude/ 폴더는 단순한 텍스트 파일의 모음이 아닙니다. AI 모델이 프로젝트를 분석하고 코드를 생성할 때 System Prompt로 주입되는 고도로 구조화된 메타데이터