AI 코딩 컨벤션 시대, 컨벤션 문서의 독자가 바뀌었다

 

AI 코딩 컨벤션이라는 말이 낯설게 들릴 수 있습니다. 코드 컨벤션은 원래 사람 팀원끼리 지키던 약속이었는데, 요즘은 그 규칙 문서를 읽는 쪽이 AI로 바뀌었습니다. CLAUDE.md, AGENTS.md 같은 파일이 저장소마다 생겨나는 이유가 여기에 있습니다. 이 글에서는 탭과 스페이스로 싸우던 시절부터 AI에게 팀 규칙을 가르치는 지금까지, 코드 컨벤션이 어떻게 변해왔는지 정리해 봤습니다.

"팀 컨벤션 문서 있긴 한데, 솔직히 아무도 안 읽지 않나요?" "AI가 짜준 코드가 우리 프로젝트 스타일이랑 계속 어긋나요" "CLAUDE.md랑 AGENTS.md랑 뭐가 다른 건가요? 둘 다 만들어야 하나요?"

저도 신입 때는 코드리뷰에서 중괄호 위치를 지적받던 사람이었습니다. 그 뒤로 린터가 논쟁을 끝내는 시대를 지나, 이제는 AI에게 "우리 프로젝트에서는 이렇게 해"라고 문서로 가르치는 시대까지 왔습니다. 세 시대를 전부 겪어보니, 규칙 자체보다 규칙을 읽는 대상이 바뀌었다는 점이 재미있더라고요.

AI 코딩 도구를 쓰는데 결과물이 자꾸 프로젝트 스타일과 어긋나서 답답한 분, 그리고 CLAUDE.md나 AGENTS.md 같은 파일이 왜 필요한지 궁금한 분께 도움이 될 겁니다.

목차

1. 탭 vs 스페이스, 사람끼리 싸우던 시대
2. 린터와 포매터가 컨벤션 논쟁을 끝낸 이유
3. AI가 코드를 쓰기 시작하면서 생긴 새로운 문제
4. AI 코딩 컨벤션의 시작, CLAUDE.md
5. AGENTS.md, AI 컨벤션의 표준이 되다
6. AI 규칙 파일 종류 비교
7. 사람 컨벤션과 AI 컨벤션, 쓰는 법이 다릅니다
8. 독자는 바뀌어도 컨벤션의 목적은 그대로

1. 탭 vs 스페이스, 사람끼리 싸우던 시대

2012년에 신입으로 들어갔을 때, 첫 코드리뷰에서 로직이 아니라 중괄호 위치를 지적받았습니다. 함수 선언 옆에 여는 중괄호를 붙이느냐, 다음 줄에 내리느냐. 지금 생각하면 별것도 아닌데, 그때는 그게 리뷰 코멘트의 절반을 차지했어요.

사내 위키에 코드 컨벤션 문서가 있긴 했습니다. 들여쓰기는 4칸, 변수명은 카멜케이스, 상수는 대문자 스네이크케이스. 문제는 그 문서를 입사 첫 주에 한 번 읽고 나면 아무도 다시 안 열어본다는 거였죠. 컨벤션은 문서가 아니라 선배들의 리뷰 코멘트로 전수됐습니다. 사람이 쓰고, 사람이 읽고, 사람이 어기고, 사람이 지적하는 구조였습니다.

이 시대 컨벤션의 특징은 강제력이 없다는 점이었습니다. 문서는 존재하지만 지키는 건 개인의 성실함에 달려 있었고, 그래서 팀마다 스타일이 미묘하게 달랐어요. 이직하면 컨벤션부터 다시 배워야 했습니다.

2. 린터와 포매터가 컨벤션 논쟁을 끝낸 이유

변화는 도구에서 왔습니다. Go 언어가 2009년에 나오면서 gofmt라는 공식 포매터를 아예 언어에 포함시켰고, JavaScript 진영에서는 2013년 ESLint, 2017년 Prettier가 나왔습니다. 특히 Prettier의 접근이 인상적이었는데, "설정 옵션을 최소화한다"는 철학이었어요. 논쟁할 여지 자체를 없애버린 거죠.

저희 팀에 Prettier를 도입했을 때가 기억납니다. 처음엔 반발이 있었어요. 자기 스타일이 뭉개진다고요. 그런데 한 달쯤 지나니까 아무도 코드 스타일 얘기를 안 하더라고요. 저장하면 알아서 정리되니까 싸울 거리가 사라진 겁니다. 코드리뷰가 로직과 설계 얘기로 채워지기 시작한 게 이때부터였습니다.

💡 이 시대의 교훈 기계가 판정할 수 있는 규칙은 문서가 아니라 도구로 강제하는 게 낫습니다. 사람의 성실함에 기대는 규칙은 언젠가 무너집니다. 이 교훈은 뒤에 나올 AI 컨벤션 작성법에서도 그대로 이어집니다.

이 시기를 지나며 컨벤션 문서에서 스타일 규칙이 빠져나갔습니다. 들여쓰기, 세미콜론, 따옴표 같은 건 설정 파일이 담당하고, 문서에는 아키텍처 원칙이나 네이밍 철학 같은 것만 남았죠. 그런데 그 문서조차 여전히 아무도 안 읽는다는 문제는 그대로였습니다.

3. AI가 코드를 쓰기 시작하면서 생긴 새로운 문제

AI 코딩 도구를 처음 실무에 붙여보면 공통적으로 겪는 일이 있습니다. 코드 자체는 돌아가는데, 우리 프로젝트 같지가 않아요. 저희가 만들어둔 공통 응답 포맷 대신 자기 방식대로 에러를 던지고, 이미 있는 유틸 함수를 놔두고 비슷한 걸 새로 만들고, 폐기하기로 한 옛날 패턴을 아무렇지 않게 다시 씁니다.

이건 AI가 멍청해서가 아니라 맥락이 없어서 생기는 문제입니다. AI 모델은 세션이 새로 시작될 때마다 기억이 초기화됩니다. 어제 열 번을 설명했어도 오늘 새 창을 열면 처음 보는 프로젝트예요. 신입사원이 매일 아침 기억을 잃고 출근하는 셈인데, 그 신입에게 매번 말로 온보딩을 다시 해줄 수는 없잖아요.

그래서 자연스럽게 답이 나왔습니다. 매번 말로 하지 말고, AI가 매번 읽고 시작하는 문서를 만들자. 사람은 안 읽던 그 컨벤션 문서를, AI는 세션마다 빠짐없이 읽게 하자는 거죠. 여기서 AI 코딩 컨벤션이라는 개념이 출발합니다.

4. AI 코딩 컨벤션의 시작, CLAUDE.md

마크다운으로 AI 에이전트에게 지시를 남기는 방식은 여러 도구별 관례를 통해 퍼졌는데, 그중에서도 Anthropic의 Claude Code가 쓰는 CLAUDE.md가 이 개념을 대중화한 대표 사례로 꼽힙니다. 저장소 루트에 CLAUDE.md라는 파일을 두면, Claude Code가 작업을 시작할 때마다 그 내용을 먼저 읽고 들어가는 구조입니다.

내용은 사람용 컨벤션 문서와 크게 다르지 않습니다. 프로젝트 구조, 빌드와 테스트 명령어, 따라야 할 패턴, 하지 말아야 할 것들. 차이는 딱 하나, 이 독자는 문서를 100% 읽는다는 점입니다. 13년 동안 사내 위키에 문서를 써오면서 처음 만나보는 독자 유형이었어요.

저도 블로그 스킨을 직접 만들면서 이걸 체감했습니다. 티스토리 에디터는 기본 모드로 전환할 때 특정 HTML 구조를 깨뜨리는 버릇이 있어서, "콜아웃 박스는 반드시 1행 1열 table로 만들 것" 같은 규칙을 문서로 정리해 뒀거든요. 그 뒤로는 같은 실수를 반복해서 바로잡을 일이 사라졌습니다. 사람 후임에게 인수인계하는 문서와 하는 일이 똑같은데, 지켜지는 확률만 다릅니다.

5. AGENTS.md, AI 컨벤션의 표준이 되다

도구마다 자기 파일을 요구하면서 잠깐 혼란기가 있었습니다. Claude Code는 CLAUDE.md, Cursor는 자체 규칙 파일, Gemini CLI는 GEMINI.md, Copilot은 또 다른 파일. 같은 내용을 파일명만 바꿔 복사해두는 웃지 못할 상황이 벌어졌죠.

이 파편화를 정리한 게 AGENTS.md입니다. 2025년 8월 OpenAI가 주도하고 Google, Cursor, Factory 등이 참여해 공개 표준으로 공식화했고, 2025년 12월에는 Linux Foundation 산하 Agentic AI Foundation에 기증됐습니다. Linux나 Kubernetes를 관리하는 그 재단이 맡게 되면서, 특정 회사가 마음대로 바꾸거나 버릴 수 없는 중립 표준이 된 셈입니다.

채택 속도도 빨랐습니다. 2025년 8월 시점에 이미 GitHub에서 2만 개 이상의 저장소가 채택했고, 같은 해 12월에는 6만 개를 넘어섰으며 20개 이상의 AI 코딩 도구가 이 형식을 지원합니다. 스펙이 단순한 것도 한몫했다고 봅니다. 저장소 루트에 놓인 평범한 마크다운 파일 하나, 필수 구조도 프론트매터도 없습니다. 마크다운 파일 하나가 표준이 될 수 있었던 건, 역설적이게도 아무것도 강제하지 않았기 때문이라고 생각해요.

📌 README.md와 AGENTS.md의 관계 README는 사람 개발자를 위한 소개와 퀵스타트, AGENTS.md는 AI 에이전트를 위한 빌드 명령·테스트 절차·코딩 규칙을 담습니다. 같은 저장소에 사람용 안내서와 AI용 안내서가 나란히 놓이는 구조입니다.

6. AI 규칙 파일 종류 비교

2026년 현재 실무에서 마주치는 규칙 파일들을 정리하면 이렇습니다. 주의할 점 하나, Cursor는 CLAUDE.md를 읽지 않고 Claude Code는 Cursor 규칙 파일을 읽지 않습니다. 자동으로 호환되는 게 아니라서, 여러 도구를 쓰는 팀은 연결 방법을 알아야 합니다.

반응형

파일	대상 도구	특징
AGENTS.md	20개 이상 도구 (Codex, Copilot, Cursor 등)	공개 표준, 가장 단순한 형식, 이식성 최고
CLAUDE.md	Claude Code	디렉터리 계층별 로딩, @경로 임포트 지원
.cursor/rules/*.mdc	Cursor	글롭 패턴으로 파일별 규칙 적용 가능
.cursorrules	Cursor (구버전)	폐기 예정, 신규 프로젝트는 사용 비권장
GEMINI.md	Gemini CLI	전역·프로젝트·하위 폴더 계층 탐색

여러 도구를 함께 쓴다면 AGENTS.md를 단일 원본으로 두고, Claude Code에는 CLAUDE.md 맨 위에 @AGENTS.md 임포트 한 줄을 넣거나 심볼릭 링크로 연결하는 방식이 무난합니다. 파일 하나만 관리하면 되니까요.

7. 사람 컨벤션과 AI 컨벤션, 쓰는 법이 다릅니다

여기가 개인적으로 제일 재미있는 부분입니다. 사람용 컨벤션 문서를 13년 써온 습관으로 AI 규칙 파일을 쓰면 잘 안 먹힙니다. 독자가 다르니 문체도 달라져야 하더라고요.

사람용 문서는 배경 설명과 정중한 권고체로 씁니다. "가급적 이런 방식을 지향합니다" 같은 식으로요. 그런데 AI 규칙은 반대입니다. "우리는 대체로 인라인 목을 피한다" 같은 서술형보다 "인라인 목을 절대 쓰지 말고 src/test/factories의 팩토리를 써라" 같은 직접 명령형이 권장되고, IMPORTANT나 NEVER 같은 강조 표기가 실제로 준수율을 높인다는 게 공식 문서에서도 확인됩니다. 사람 후임에게 저렇게 쓰면 퇴사 사유가 되겠지만, AI에게는 그게 친절인 셈입니다.

넣지 말아야 할 내용도 있습니다. 들여쓰기나 포매팅 같은 코드 스타일 규칙은 ESLint와 Prettier가 더 빠르고 확실하게 처리하니 규칙 파일에 넣지 말고, "클린 코드를 작성하라" 같은 당연한 말도 토큰만 낭비하니 빼라는 것이 공통된 조언입니다. 2절에서 얘기한 교훈이 그대로 돌아온 거죠. 기계가 판정할 수 있는 건 도구로, 문서에는 도구가 못 하는 맥락만.

💡 실무에서 체감한 요령 규칙 파일은 짧을수록 잘 지켜집니다. 저도 처음에 욕심내서 길게 썼다가, 정작 중요한 규칙이 묻히는 걸 겪고 절반 이하로 줄였습니다. 한 파일이 150~200줄을 넘으면 하위 디렉터리로 쪼개라는 가이드도 같은 맥락입니다. 그리고 낡은 규칙은 바로 지워야 합니다. 틀린 지시는 없는 것보다 나쁩니다.

8. 독자는 바뀌어도 컨벤션의 목적은 그대로

탭과 스페이스로 싸우던 시절이나, 린터가 논쟁을 끝낸 시절이나, AI에게 규칙 문서를 써주는 지금이나, 컨벤션의 목적은 한 번도 바뀐 적이 없다고 생각합니다. 코드를 쓰는 주체가 여럿이어도 결과물은 한 사람이 쓴 것처럼 보이게 하는 것. 다만 그 "여럿"에 이제 사람이 아닌 존재가 포함됐을 뿐입니다.

아이러니한 건, AI 덕분에 컨벤션 문서가 드디어 읽히는 문서가 됐다는 점입니다. 사람은 안 읽던 그 문서를 AI는 세션마다 읽습니다. 그리고 규칙 파일을 잘 쓰려고 고민하다 보면 결국 우리 프로젝트의 규칙이 뭔지 스스로 정리하게 되더라고요. AI에게 설명하지 못하는 규칙은 애초에 팀원에게도 설명 못 하던 규칙이었을 가능성이 큽니다.

확실하진 않지만, 몇 년 뒤에는 AGENTS.md가 README.md만큼 당연한 파일이 돼 있지 않을까 싶습니다. 지금 프로젝트에 규칙 파일이 없다면, 거창하게 말고 열 줄짜리부터 시작해 보세요. 신입에게 해줄 첫 온보딩 멘트를 파일로 옮긴다는 기분이면 충분합니다.

AI 코딩 컨벤션 자주 묻는 질문

AGENTS.md와 CLAUDE.md 중 무엇을 써야 하나요?

Claude Code만 쓴다면 CLAUDE.md 하나로 충분합니다. 여러 도구를 쓰거나 오픈소스처럼 불특정 다수가 참여하는 프로젝트라면 AGENTS.md를 원본으로 두고, CLAUDE.md에서 임포트하거나 심볼릭 링크로 연결하는 방식이 관리하기 편합니다.

.cursorrules 파일은 이제 못 쓰나요?

당장 동작이 멈추는 건 아니지만 폐기 수순입니다. Cursor가 루트의 .cursorrules를 여전히 읽기는 하나 글롭이나 프론트매터 같은 기능이 없어서, 새 프로젝트는 .cursor/rules 디렉터리의 mdc 파일을 쓰라는 게 공식 방향입니다. 기존 파일 내용은 마크다운 그대로라 AGENTS.md로 옮기기도 쉽습니다.

AI 규칙 파일에 코드 스타일 규칙도 넣어야 하나요?

들여쓰기, 따옴표, 세미콜론처럼 포매터가 판정할 수 있는 규칙은 넣지 않는 게 좋습니다. 그런 건 Prettier나 ESLint 설정이 담당하고, 규칙 파일에는 도구가 못 잡는 것들, 예를 들어 아키텍처 원칙이나 "이 유틸을 재사용하라" 같은 프로젝트 고유 맥락을 담는 게 효율적입니다.

규칙 파일은 어느 정도 길이가 적당한가요?

짧을수록 좋다는 게 중론입니다. 대략 150~200줄을 넘어가면 하위 디렉터리별 파일로 쪼개는 걸 권합니다. 길어질수록 개별 규칙의 준수율이 떨어지는 경향이 있어서, 모든 걸 담기보다 자주 어기는 것 위주로 추리는 편이 낫습니다.

🎲 추천 글 모음

하네스 엔지니어링 vs 루프 엔지니어링 - AI 에이전트 용어 정리 (2026)

좋은 코드란 무엇인가 - 13년 차 개발자의 대답이 네 번 바뀐 이야기

트레이드 오프 모르는 개발자가 신기술을 밀어붙일 때

MAS(멀티 에이전트 시스템)란 무엇인가 - 모놀리식부터 AI 에이전트까지, 분산 아키텍처의 역사

AI 개발 언어 1위는 왜 파이썬일까 - 느린데도 이긴 언어의 역설