에이전트에게 지침을 미리 내려둘 수 있다? AGENTS.md
에이전트는 다양한 언어에 능한데 커서는 우리에게는 늘 한글로만 대답합니다. 어째서 그럴 수 있었을까요? 우리가 한글로 입력해서 한글로 대답한 것일까요? 그렇지 않습니다.
01 정말 그런지 확인해봅시다. 에이전트 채팅 창을 [Ask] 모드로 바꾸고 hi라고 입력해봅시다.
[나] : hi
[AI] : 안녕하세요! 글쓰기 앱이 잘 작동하고 있나요? 글 저장이 정상적으로 되는지, 또는 다른 도움이 필요하면 말씀해주세요.
그럼 놀랍게도 커서는 한글로 답을 해줄 겁니다. 분명 저는 영어로 인사를 했는데도 말이죠. 이럴 수 있는 이유는 이미 커서에 ‘항상 한글로 답할 것’이라는 커서 룰이 적용되었기 때문입니다.
02 그 내용은 어디에 있는 걸까요? 오른쪽 위의 [톱니바퀴] 버튼을 누르고 [Cursor Settings]에 들어가봅시다. 그럼 커서의 다양한 설정을 볼 수 있습니다.
[Note] 옵션의 위치는 달라질 수 있습니다. 옵션의 위치가 달라져도 당황하지 말고 최대한 Settings 옵션이 있을만한 메뉴를 찾아서 눌러보세요.
03 그중 [Rules, Skills, Subagents]라는 항목을 들어가봅니다. 미리 언급하지만 이 모든 기능이 에이전트를 보완하기 위한 방법입니다. 여기서 Rules가 바로 커서 룰입니다. 항목을 자세히 보면 항상 한글로 답하라는 문장이 적혀 있습니다. 이 문장은 처음에 여러분이 언어를 [Korean]으로 설정했기 때문에 들어가 있는 겁니다.
이제 의문이 풀립니다. hi라고 인사를 해도 커서가 한글로 대답했던 이유는 바로 이 커서 룰 때문이었습니다. 적용 범위도 [All]이네요. 그래서 커서의 창을 새로 열어도 항상 한글로 답할 수 있었던 겁니다. 이렇게 커서 룰을 사용하면 에이전트는 여러분이 입력한 프롬프트에 답할 때 룰을 고려합니다.
04 이 문장을 지우고 항상 영어로 답하라고 적으면 어떻게 될까요? 그러면 커서가 영어로 답하기 시작합니다. 한 번 해봅시다. Korean을 English로 수정하고 [Save]를 눌러 커서 룰을 저장합니다.
05 그런 다음 에이전트를 새로 만들고 채팅을 해봅시다. 안녕이라고 인사를 해보세요.
[나] : 안녕?
[AI] :
그럼 커서가 영어로 답을 합니다. 바로 이것이 커서 룰입니다. 이렇게 커서는 프롬프트를 읽기 전에 커서 룰을 확인하고 동작합니다. 이건 요즘 대부분의 바이브 코딩 도구의 특징입니다. 이름은 조금 다를 수 있지만요. 어쨌든 우리는 이 실습을 통해 커서에게 미리 지침을 내릴 수 있게 되었습니다.
06 다시 English를 Korean으로 돌리고 다음 실습으로 나아가봅시다.
AGENTS.md로 지침 등록하기
이제부터 실습에서는 웹 개발을 할 때는 항상 Next.js와 Shadcn을 사용하려고 합니다. 그래서 커서가 다른 방향으로 개발을 하지 않도록 미리 설정해두면 좋을 겁니다. 다만 이것을 영어로 적어야 하나 한글로 적어야 하나 헷갈립니다. 앞에서 본 대로면 영어로 적어야 할 것 같습니다. 그럴 때는 어떻게 해야 할까요? 커서에게 [Ask] 모드로 지침을 영어로 번역해달라고 한 다음 붙여넣어야 할까요? 그보다 간단한 방법이 하나 있습니다. 바로 AGENTS.md를 사용하는 방법입니다.
AGENTS.md 사이트 접속해보기
바로 실습을 통해 지침을 등록해보고 싶겠지만 AGENTS.md 사이트에 접속해서 이것이 무엇인지 알아봅시다. 다음은 AGENTS.md에 접속하면 처음 볼 수 있는 화면입니다.
‘Why AGENTS.md?’ 항목이 바로 이 문서를 사용해야 하는 이유를 적은 겁니다. 사이트까지 만들어가며 표준화하려는 노력을 볼 수 있습니다. 그리고 조금 더 아래로 스크롤바를 내려보면 이 표준화 문서를 지키기로 한 도구들이 지나가는 모습을 볼 수 있습니다. 우리에게 익숙한 커서도 있고 구글의 Jules 등 다양한 도구들이 보입니다.
결국 AGENTS.md는 ‘어떤 종류의 바이브 코딩 도구라고 하더라도 AGENTS.md 문서가 있다면 이것을 에이전트가 우선하여 읽고 동작할 수 있도록 하게 하자’라는 일종의 약속이 포함되어 있는 문서입니다. 그래서 AGENTS.md의 역할은 앞에서 설정 메뉴로 등록했던 커서 룰과 같습니다. 그래서 저는 앞으로 커서 룰이라는 표현을 쓰지 않고 AGENTS.md라는 표현을 사용하겠습니다.
[1:1 코칭] 클로드 코드는 AGENTS.md를 안 쓰나요? 이름이 안 보여요
사연을 이야기하자면 바이브 코딩 도구들이 막 등장했을 때는 ‘에이전트에게 미리 지침을 내리면 편하다.’라는 필요성에 모두 공감하고 있었습니다. 하지만 바이브 코딩 도구를 개발한 회사마다 이것을 다 다르게 불렀습니다. 예를 들어 클로드 코드는 CLAUDE.md라고 불렀고, 커서는 cursor rules라고 불렀습니다. 하지만 에이전트가 미리 알아야 할 지침에 대한 논의가 점점 보편화되면서 부르는 말, 지침을 쓰는 방식 등을 표준화하자는 이야기가 나왔고 이를 AGENTS.md라 칭하기 시작했습니다. 물론 클로드 코드는 여전히 CLAUDE.md를 사용하고 있습니다. 아마 시간이 지나면서 부르는 용어는 점차 통일될 거라 생각합니다.
[/1:1 코칭]
AGENTS.md 등록해서 사용해보기
01 그럼 커서에게 전역으로 AGENTS.md로 원하는 룰을 ‘영어’로 추가해달라고 하면 되겠네요. 한 번 그렇게 해봅시다.
[나] : 앞으로 웹 개발 관련 지시에는 모두 Next.js, Shadcn 기반으로 개발을 시작하라고 AGENTS.md를 등록하고 싶어. 이때 지침은 전역으로 등록해주고, 영어로 적어줘.
[AI] : 전역 AGENTS.md로 웹 개발 시 사용할 기술을 등록하겠습니다. ...생략...
커서가 전역으로 파일을 작성하고 등록하겠다고 합니다.
[Note] 여기서 ‘전역’이라는 건 커서에서 여는 모든 프로젝트에 이 규칙을 기본값으로 기억하고 작동하라는 말입니다. 반대로 프로젝트별로 규칙을 적용할 수도 있습니다.
02 잠시 기다렸다가 완료되면 커서 설정 파일의 Rules 항목을 확인해보세요. ➊ [AGENTS]라는 텍스트가 보입니다. 이것을 클릭하면 펼쳐지는데 커서가 작성한 영문 지침이 보입니다. 읽어보면 Next.js와 Shadcn이 보이네요. 이렇게 커서에 지침을 추가할 수 있습니다. ➋ 이때 [All], [User], [프로젝트 폴더 이름]을 선택하여 추가할 수 있습니다. 해당 탭은 Rules와 스킬, 서브에이전트가 영향을 끼칠 범위를 정할 수 있습니다. 이때 [All]은 전역 설정이 아닌 전역 설정과 프로젝트 설정을 함께 보는 탭입니다. 전역 설정이라고 오해하지 않기 바랍니다.
[User] : 전역으로 설정합니다.
[프로젝트 폴더 이름] : 해당 프로젝트 또는 폴더에만 설정합니다.
[All] : 전역, 프로젝트에 설정한 기능을 모두 살펴봅니다.
앞으로 커서와 작업하다가 언제나 그렇게 작업할 것 같다라고 예상되면 이렇게 AGENTS.md를 등록해서 사용하기 바랍니다.
AGENTS.md의 적용 범위 알아보기
앞에서 언급했듯 AGENTS.md는 적용 범위를 다음과 같이 2가지로 구분하여 등록할 수 있습니다. 다시 말하지만 [All]은 전역 설정이 아닌 전역 설정과 프로젝트 설정을 함께 보는 탭입니다. 전역 설정이라고 오해하지 않기 바랍니다.
적용 범위를 잘 활용하면 마크다운 문서 작업만 하는 폴더에서만 사용할 지침을 따로 만들어두고 효율적인 작업을 할 수도 있습니다. 다만 다양한 AGENTS.md의 활용 방식을 다루기에는 지면이 부족하므로 이 정도만 설명하고 넘어가겠습니다. 이 정도면 충분히 개념이 이해되었으리라 생각합니다.
다음은 정말로 지침대로 커서가 동작하는지 확인해본 화면입니다. 웹 기술로 테트리스 게임을 만들어보자고 했을 때 커서가 보여주는 답변을 보세요. 지침대로 잘 동작하네요. 이 내용은 따로 실습해볼 필요가 없으므로 눈으로만 보고 넘어갑시다.
결과를 보면 대부분의 UI를 Shadcn을 적용해서 만든 것을 볼 수 있습니다(검정색과 흰색 테마). 바이브 특유의 그라데이션, 보라색과 같은 것도 사용하지 말라고 했으면 더 좋았겠네요. 어쨌든 AGENTS.md는 잘 동작한다는 걸 확인했습니다.
AGENTS.md는 만능? 주의할 점도 있어요
그렇다면 AGENT.md는 아무렇게나 사용하면 될까요? 사실은 그렇지 않습니다. 왜냐하면 에이전트가 이 지침을 읽을 때에도 한계가 있기 때문입니다. 길게 설명할 수는 없지만 핵심적인 이유는 컨텍스트 윈도우 때문입니다. 컨텍스트 윈도우는 에이전트가 기억할 수 있는 기억 용량 같은 겁니다. 그런데 만약 여러분이 AGENTS.md를 너무 길게 적는다면 지침을 제대로 이행하지 못하거나, 지침을 보느라 여러분의 프롬프트를 제대로 이행하지 못하는 등의 문제가 생길 수 있습니다. 실제로 커서에서는 AGENTS.md에 대해 다음과 같이 안내하고 있습니다.
[Note] 설명은 cursor.com/docs/context/rules를 참고하여 최대한 쉬운 말로 작성했습니다.
이 말을 쉽게 해석하자면 AGENTS.md는 미리 입력하는 프롬프트 같은 거여서 너무 길어도 문제입니다. 그래서 다음 규칙을 지키는 것이 중요합니다.
규칙은 500줄 이하로 유지하세요. 너무 길면 관리하기 어렵습니다.
큰 규칙은 여러 개의 조합 가능한 규칙으로 분리하세요. 하나의 거대한 규칙보다 작고 재사용 가능한 규칙으로 나누는 게 좋습니다.
구체적인 예시나 참조 파일을 제공하세요. 추상적인 설명보다 실제 예가 이해에 도움이 됩니다.
모호한 안내는 피하세요. 명확한 내부 문서처럼 작성하세요. ‘잘 작성하세요’ 같은 애매한 표현 대신 구체적으로 작성해야 합니다.
반복되는 프롬프트는 규칙으로 만들어 재사용하세요. 훨씬 효율적으로 바이브 코딩할 수 있습니다.
파일 내용을 복사하지 말고 참조하세요. 내용을 직접 복사해넣으면 규칙이 길어지고, 원본 코드가 바뀔 때 자연스럽게 반영하려면 파일 경로만 참조하는 게 낫습니다.
바이브 코딩 입문 단계에서는 이것들을 모두 지킬 필요는 없고, 1, 2, 4 정도만 참고하면 됩니다. 이 내용의 핵심은 지침을 사용하려면 짧고, 구체적이고, 재사용할 수 있게 해라라는 겁니다.
정말 설명이 길었습니다. 바이브 코딩을 신나게 하다가 이런 공부를 하니 좀 머리가 아플 수도 있겠습니다. 하지만 이 내용은 바이브 코딩이 익숙해진 미래 여러분의 시간을 10배 이상은 줄여줄 팁입니다. 이후 난이도 있는 실습을 진행할 때 AGENTS.md를 자연스럽게 사용할 예정이므로 외우듯이 공부할 필요는 없습니다. 어떤 개념인지 알아두는 정도로 읽고 넘어가기 바랍니다.
[Note] 참고로 다음에 공부할 스킬이 Next.js와 Shadcn을 적용하기에 더 적절합니다. 만약 실습을 따라 하며 등록했다면 지워두기 바랍니다. 이유는 스킬을 공부하면 자연스럽게 알게 될 겁니다.
[마무리 요약]
AGENTS.md에 지침을 적어두면 에이전트가 대화할 때마다 이 규칙을 먼저 확인하고 행동합니다.
지침은 전역으로 적용할 수도 있고, 특정 프로젝트 폴더에만 적용할 수도 있습니다.
AGENTS.md는 500줄 이하로 짧고 구체적으로 작성해야 좋습니다.