AI한테 요청 시 필수로 읽는 .md파일 관리하기

새 채팅을 열 때마다 AI에게 프로젝트를 처음부터 다시 설명하고 있다면, 이 글이 그 반복을 끊는 데 도움이 될 거예요. AI 코딩 도구는 대화를 새로 시작할 때마다 앞 대화를 기억하지 못해요. "우리 폴더 구조는 이렇고", "이 라이브러리를 써 줘", "말투는 이렇게" 같은 설명을 매번 다시 해야 하죠. 이 반복을 파일 하나로 대신하게 만드는 게 '규칙 파일'이에요. 그런데 규칙 파일은 만들어두면 끝이 아니라, 오히려 거기서부터 관리가 시작돼요.

AI는 왜 매번 처음 만난 사람처럼 굴까

AI 코딩 도구는 새 세션을 시작할 때마다 컨텍스트가 비워져요. 컨텍스트(context)는 AI가 지금 대화에서 기억하고 있는 내용의 범위예요. 새 대화를 열면 이 기억이 리셋돼서, 어제 알려준 프로젝트 사정을 오늘은 모르는 채로 시작해요.

규칙 파일은 이 빈자리를 메우는 장치예요. "우리 프로젝트는 이렇게 해 줘"라고 미리 적어두는 메모장이고, 확장자가 .md인 마크다운(서식이 단순한 텍스트 문서) 형식을 주로 써요. 예를 들어 Claude Code는 세션을 열 때마다 CLAUDE.md라는 파일을 자동으로 다시 읽어요. 사람이 매번 설명하던 걸 파일이 대신하는 거죠.

기준은 간단해요. 같은 설명을 두 번째로 하고 있다면, 그건 규칙 파일에 적을 때가 됐다는 신호예요. 맥락이 빠진 채로 코드를 맡기면 파일 하나를 고쳤을 때 엉뚱한 곳이 깨지기도 하는데, 규칙 파일은 바로 그 맥락을 붙잡아두는 역할을 해요. 비슷한 고민은 코딩을 못하는 비개발자가 Cursor를 선택한 진짜 이유는?에서도 다룬 적이 있어요.

도구마다 파일 이름도 위치도 다르다

규칙 파일은 도구마다 이름과 위치, 그리고 글자 수 한도가 달라요. 지금 쓰는 도구가 어떤 파일을 읽는지부터 알아야 엉뚱한 데 적어두는 실수를 피할 수 있어요.

특히 한도를 조심해야 해요. Windsurf는 전역 규칙 6,000자, 워크스페이스 규칙은 파일당 12,000자로 제한하는데, 이 한도를 넘으면 초과된 부분이 조용히 잘려요. 경고 없이 사라지니까, 뒤쪽에 적어둔 중요한 규칙이 통째로 무시돼도 눈치채기 어렵죠. GitHub Copilot은 저장소 전체 지시를 .github/copilot-instructions.md 한 파일에 두고, 특정 폴더에만 적용할 지시는 .github/instructions 폴더에 따로 나눠 둬요.

도구마다 이렇게 제각각이면, 여러 도구를 오가는 사람은 같은 규칙을 몇 번씩 복붙하게 돼요. 그 피로를 줄이려는 움직임이 바로 다음 이야기예요.

여러 AI가 같은 규칙을 읽게 하는 AGENTS.md

AGENTS.md는 도구마다 파일을 따로 만드는 번거로움을 없애려고 만든 공통 표준이에요. 특정 회사 하나의 규격이 아니라, 여러 AI 코딩 도구가 함께 읽도록 약속한 형식이죠.

AGENTS.md 공식 사이트 기준으로, 이 표준은 6만 개가 넘는 오픈소스 프로젝트에서 쓰이고 20여 개 도구가 지원해요. 시작은 2025년 8월이었어요. OpenAI가 주도하고 구글(Jules)·Cursor·Factory 등이 함께 참여해 공개했죠. 이후 2025년 12월에는 리눅스 재단이 Agentic AI Foundation을 출범시키면서 AGENTS.md를 그 산하로 옮겼어요. 표준 문서가 공개된 시점(2025년 8월)과 이를 관리할 재단이 생긴 시점(2025년 12월)은 이렇게 서로 다르니 헷갈리지 않는 게 좋아요.

한 가지 알아둘 점은, 도구마다 인식하는 파일이 여전히 조금씩 다르다는 거예요. 예를 들어 Claude Code는 AGENTS.md를 직접 읽지 않고 CLAUDE.md만 읽어요. 그래서 이미 AGENTS.md가 있다면, CLAUDE.md 안에 `@AGENTS.md` 한 줄을 넣어 불러오거나 심볼릭 링크(파일 하나를 다른 이름으로도 가리키게 하는 연결)를 걸어두면 돼요. 그러면 규칙은 한 곳에서만 관리하면서 여러 도구가 같은 내용을 보게 되죠.

파일은 짧을수록 잘 지켜진다

규칙 파일은 길게 쓸수록 오히려 잘 안 지켜져요. 많이 적어둘수록 AI가 더 똑똑해질 것 같지만 반대예요.

Claude Code 공식 문서는 CLAUDE.md 한 파일을 200줄 미만으로 유지하라고 권해요. 파일이 길어지면 그만큼 컨텍스트를 많이 차지하고, 지시를 지키는 비율도 떨어지거든요. 여기서 컨텍스트를 차지한다는 건 토큰을 먹는다는 뜻이에요. 토큰(token)은 AI가 글을 읽고 쓸 때 세는 단위인데, 규칙을 많이 넣을수록 토큰을 더 쓰고 정작 중요한 지시가 묻히기 쉬워요.

그래서 파일이 커지면 한 곳에 다 몰아넣지 말고 주제별로 쪼개는 게 좋아요. Claude Code는 .claude/rules 폴더에 주제별 파일을 나눠 두면 알아서 찾아 읽어요. 규칙을 "필요한 만큼만, 짧게" 두는 게 핵심이에요.

전부 켜두지 말고 언제 켤지를 정한다

규칙을 전부 '항상 켜짐'으로 두면 매 요청마다 그 규칙들이 다 따라붙어요. 편하지만 토큰을 계속 먹어서, 대화가 본격적으로 시작되기도 전에 예산을 다 써버릴 수 있어요. 그래서 규칙마다 '언제 켜질지'를 정해두는 게 좋아요.

가장 쉬운 방법은 계층으로 나누는 거예요. 내 개인 취향은 전역 규칙에, 팀이 함께 쓸 규칙은 프로젝트 규칙에, 특정 폴더에서만 필요한 규칙은 그 범위에만 걸어두는 식이죠. Cursor의 프로젝트 규칙은 이 '언제 켜지는가'를 네 가지로 나눠요.

1. 항상 켜기 — 모든 대화에 무조건 포함
2. AI가 알아서 판단 — 규칙 설명을 보고 관련 있을 때만 불러옴
3. 특정 파일 패턴일 때 — 지정한 파일을 열면 자동으로 붙음
4. 직접 호출 — 필요할 때 이름을 불러 적용

여기서 '특정 파일 패턴'은 glob(글롭) 패턴으로 지정해요. glob은 "src 폴더 안 모든 파일"처럼 파일 묶음을 별표로 나타내는 표기예요. 항상 필요한 규칙만 '항상 켜기'로 두고, 가끔 쓰는 규칙은 나머지 방식으로 돌리면 토큰도 아끼고 지시도 더 잘 지켜져요. 참고로 내 로컬 테스트 주소나 개인 설정처럼 팀과 공유하면 안 되는 내용은 공용 파일 대신 개인용 파일(예: Claude Code의 CLAUDE.local.md)에 따로 두는 게 안전해요.

규칙만 고치고 코드는 그대로 두면 어긋난다

규칙 파일 관리에서 가장 자주 놓치는 부분이 여기예요. 규칙 파일도 결국 코드처럼 다뤄야 해요. git(변경 이력을 저장·공유하는 시스템)에 함께 커밋해서 팀원 모두가 같은 규칙을 쓰게 하고, 규칙이 바뀌면 그 규칙을 참조하는 코드나 자동화도 같은 작업에서 함께 손봐야 해요.

이걸 놓치면 조용한 사고가 나요. 규칙 문서를 사람만 읽는 게 아니라 자동화 스크립트나 다른 AI도 함께 읽는 구조라면, 문서만 고치고 넘어갔을 때 자동화는 여전히 옛 규칙대로 돌아요. 겉으로는 규칙을 바꾼 것 같지만 실제 동작은 그대로인, 이른바 '부분 동기화' 상태가 되는 거죠.

옛 형식을 방치하는 것도 비슷한 실수예요. 예를 들어 Cursor의 단일 .cursorrules 파일은 0.45 무렵 .cursor/rules 폴더 방식이 도입되면서 사실상 옛 방식(deprecated, 이제 안 쓰기로 한 방식)이 됐어요. 하위 호환으로 아직 동작은 하지만, 공식 문서에서는 안내가 사라졌으니 새 방식으로 옮기는 게 좋아요.

규칙이 잘 지켜지지 않는 것처럼 보일 때는, 규칙을 더 세게 쓰기 전에 그 파일이 실제로 읽혔는지부터 확인하는 게 순서예요. Claude Code라면 /memory 명령으로 지금 어떤 규칙 파일이 로드됐는지 볼 수 있어요. 변경 이력은 git으로 추적하고 프로젝트 규칙은 .md로 관리한다는 원칙은, AI가 코드를 써주지만 이제 비개발자도 Git을 알아야해요에서 이야기한 '직접 챙겨야 할 안전장치'와 같은 결이에요.

규칙 파일을 만드는 데는 5분이면 충분해요. 승부는 그다음, 짧게 유지하고 언제 켤지 나누고 코드와 함께 갱신하는 관리에서 갈려요. AI에게 좋은 결과를 얻고 싶다면 파일을 늘리기보다, 있는 규칙을 자주 다듬는 쪽이 훨씬 효과가 커요.

한 번 더, 빠르게 짚고 갈게요

Q. Cursor를 쓰는데 예전에 만든 .cursorrules 파일을 그대로 둬도 되나요?

A. 지금도 하위 호환으로 읽히긴 해요. 다만 .cursorrules는 사실상 옛 방식이 됐고 공식 문서에서도 안내가 빠졌어요. .cursor/rules 폴더의 .mdc 파일 방식으로 옮기는 걸 권해요.

Q. CLAUDE.md랑 AGENTS.md를 둘 다 만들어야 하나요?

A. 꼭 둘 다 관리할 필요는 없어요. Claude Code는 AGENTS.md를 직접 읽지 않으니, AGENTS.md를 두고 CLAUDE.md 안에서 `@AGENTS.md`로 불러오거나 심볼릭 링크를 걸면 한 곳만 관리하면서 여러 도구가 같은 규칙을 봐요.

Q. 규칙을 적었는데 AI가 안 지켜요. 왜 그럴까요?

A. 규칙을 더 세게 쓰기 전에, 그 파일이 실제로 로드됐는지부터 확인해 보세요. 하위 폴더의 규칙은 그 폴더를 열 때만 읽히기도 하고, 여러 규칙이 서로 모순되면 AI가 아무거나 고르기도 해요. Claude Code에서는 /memory로 로드 상태를 확인할 수 있어요.

Q. 규칙 파일은 얼마나 길어도 되나요?

A. 짧을수록 좋아요. Claude Code는 한 파일 200줄 미만을 권하고, Windsurf는 전역 6,000자·파일당 12,000자 한도가 있어요. 길어지면 주제별로 파일을 쪼개고, 항상 필요한 규칙만 남기는 게 좋아요.