.cursorrules / .windsurfrules

CLAUDE.md / AGENTS.md

프로젝트 루트 디렉토리에 배치하는 마크다운 파일로, AI 에이전트에게 프로젝트의 아키텍처, 코딩 컨벤션, 빌드·테스트 명령어, 기술 스택, 제약 조건 등을 알려주는 '프로젝트 지도(map)' 역할을 한다. Claude Code에서 /init 명령어로 자동 생성할 수 있으며, AI가 프로젝트를 처음 접할 때 가장 먼저 읽는 파일이다. 잘 작성된 CLAUDE.md는 AI 에이전트의 코드 생성 품질을 극적으로 향상시키며, 반대로 이 파일이 없으면 AI가 프로젝트의 패턴과 규칙을 이해하지 못해 일관성 없는 코드를 생성한다. Mitchell Hashimoto(하네스 엔지니어링 창시자)는 AGENTS.md를 반복적으로 개선하는 것을 하네스 엔지니어링의 핵심 활동으로 제안했다. 구체적 방법론은: AI 에이전트가 실수를 했을 때, 같은 실수를 반복하지 않도록 해당 규칙을 AGENTS.md에 추가하는 것이다. 시간이 지남에 따라 AGENTS.md는 프로젝트의 모든 '암묵적 규칙'이 명시화된 문서로 성장한다. CLAUDE.md는 Claude Code 전용이고, AGENTS.md는 도구 독립적인 범용 이름이며, 기능과 목적은 동일하다.

RAG (Retrieval-Augmented Generation)

외부 데이터 소스에서 관련 정보를 먼저 검색(Retrieval)한 뒤, 이 정보를 LLM의 컨텍스트에 포함시켜(Augmented) 응답을 생성(Generation)하는 기술이다. 2020년 Meta AI의 Patrick Lewis 등이 발표한 논문에서 처음 제안되었으며, AI의 환각(Hallucination) 문제를 해결하는 가장 효과적인 방법 중 하나로 자리잡았다. LLM은 훈련 데이터에 포함되지 않은 정보(사내 코드, 비공개 API 문서, 최신 라이브러리 변경사항 등)를 알 수 없지만, RAG를 통해 관련 문서를 실시간으로 검색하여 컨텍스트에 주입하면 최신·정확한 정보를 기반으로 코드를 생성할 수 있다. 바이브 코딩에서의 활용 예시: AI 코딩 에이전트가 사내 API 문서 데이터베이스를 RAG로 검색하여, 정확한 엔드포인트 URL, 인증 방식, 요청/응답 스키마를 확인한 후 코드를 생성한다. Grounding의 핵심 구현 방식이며, Corrective RAG(검색 결과의 관련성을 평가하여 재검색하는 변형) 등의 발전된 형태도 존재한다.

Codebase Indexing

AI 도구가 프로젝트의 전체 소스 코드를 분석·색인(index)하여, 특정 질문이나 작업 시 관련 코드를 빠르게 찾을 수 있도록 하는 사전 처리 과정이다. 도서관의 색인 카드가 원하는 책을 빠르게 찾게 해주는 것처럼, 코드베이스 인덱싱은 AI가 수만~수백만 줄의 코드에서 필요한 부분을 즉시 특정할 수 있게 한다. Windsurf는 프로젝트를 처음 열 때 전체 파일을 인덱싱하고, Augment Code는 심층 인덱싱(Deep Indexing)으로 코드 간 의존성과 아키텍처 패턴까지 분석한다. 인덱싱 깊이에 따라 AI 에이전트의 정확도가 크게 달라지며, 단순 텍스트 검색 수준의 인덱싱과 코드 의미론(semantics)까지 파악하는 심층 인덱싱은 결과물의 차이가 상당하다. Greptile 같은 코드베이스 인덱싱 전문 도구도 존재하며, 이들은 코드의 의미적 관계를 파악하여 '이 함수를 호출하는 모든 곳'이나 '이 데이터 구조를 사용하는 모든 패턴'을 찾아낸다. RAG의 코드 버전으로 이해할 수 있다.