2026년 9월 8일 기준

이 글에는 제휴 링크가 없습니다.

yml 파일이란 — AI가 유독 이 형식을 좋아하는 이유

AI 도구를 조금만 깊이 쓰기 시작하면 .yml이라는 확장자가 계속 나옵니다. Claude Code 설정도, 자동 배포도, MCP 서버 목록도 전부 이 파일이죠. 저도 처음엔 “개발자들이 쓰는 뭔가”로 넘겼습니다. 그런데 지금 이 블로그를 굴리는 저장소를 세어보니 yml 파일이 51개더군요. 글 한 편이 발행되는 데 최소 두 개가 관여합니다.

결론 요약

YAML은 사람이 읽고 쓰기 쉬운 설정·데이터 형식. 괄호 대신 들여쓰기로 구조를 만든다
.yml과 .yaml은 완전히 같다. 확장자를 3글자까지만 쓰던 시절의 흔적일 뿐
AI가 이걸 쓰는 이유: 사람이 읽는 문서인 동시에 기계가 파싱하는 데이터라서 — 규칙서와 작업기록을 한 파일로 겸한다
초보자가 밟는 지뢰는 4개: 탭 · yes/no · 소수점 끝의 0 · 콜론

🧩 1. YAML은 “괄호를 뺀 데이터 메모지”

이름부터 농담입니다. YAML은 “YAML Ain’t Markup Language”(YAML은 마크업 언어가 아니다)의 재귀 약자예요. 공식 명세는 스스로를 사람 친화적으로 설계된 데이터 직렬화 언어라고 소개합니다.

같은 내용을 JSON과 나란히 놓으면 차이가 바로 보입니다.

{ "채널": "네이버", "활성": true, "규칙": ["링크 금지", "사진 필수"] }

채널: 네이버
활성: true
규칙:
  - 링크 금지
  - 사진 필수

괄호도 따옴표도 쉼표도 없습니다. 들여쓰기가 곧 구조고, 나머지는 거의 다 그냥 글자예요. 그래서 개발을 모르는 사람도 파일을 열어 읽고 고칠 수 있습니다. 이게 이 형식의 전부이자 핵심입니다.

AI 규칙서와 작업기록을 사람·AI·스크립트가 함께 읽는 구조 (직접 제작)

📄 2. `.yml`과 `.yaml`, 뭐가 다른가 — 다르지 않습니다

제가 가장 오래 헷갈렸던 부분이라 먼저 털고 갑니다. 내용도 문법도 파서 동작도 완전히 동일합니다.

공식 권장 확장자는 .yaml이고 2006년부터 그랬습니다. .yml이 남아 있는 건 확장자를 3글자까지만 허용하던 옛 운영체제 시절의 관습 때문이에요. 지금은 어느 쪽을 써도 도구가 다 읽습니다.

실무 기준: 프로젝트가 이미 쓰는 쪽을 따라가세요. 한 저장소 안에서 섞이면 “왜 이 파일만 다르지?” 하고 매번 멈칫하게 됩니다. 저는 저장소 전체를 .yml로 통일했습니다.

🤖 3. AI는 yml을 어떻게 쓰는가 — 세 가지 역할

① AI에게 주는 규칙서

제 저장소의 config/channels.yml 일부입니다.

naver_review:
  label: 네이버 리뷰 블로그 (세차·클리닝 전문)
  active: true
  source_relation: restructure   # 복제 금지, 새로 재구성
  rules:
    - 쿠팡 파트너스 링크 금지 (저품질 위험 — 자체 사이트 전용)
    - 협찬 글은 공정위 표기 필수
    - 스토어 리뷰 복붙 금지 (유사문서)

이 파일은 AI가 작업 전에 읽는 규정집입니다. “네이버 리뷰 글에는 쿠팡 링크를 넣지 마라”를 매번 대화로 설명하는 대신, 한 번 적어두고 “channels.yml 규칙대로 변환해줘”라고 말하면 끝이죠.

프롬프트에 매번 붙여넣는 것과 뭐가 다르냐면 — 파일은 버전 관리가 되고, 사람도 고칠 수 있고, 스크립트도 읽을 수 있습니다. 대화창에 적은 규칙은 그 대화가 끝나면 사라지지만 파일은 남습니다. AI에게 부탁하지 말고 규칙으로 걸라는 원칙의 가장 가벼운 버전이기도 하고요.

② AI가 남기는 작업 기록

글 한 편당 하나씩 있는 상태 파일(content.yml)입니다. 지금 32개.

id: 20260907-claude-code-subagents
category: ai-automation
status: published
channels: [site, naver]
published:
  - channel: site
    url: https://happyvarious.com/posts/20260907-claude-code-subagents/
    date: 2026-09-07

어디에 발행됐는지, 언제 승인됐는지가 문장이 아니라 필드로 들어갑니다. “그 글 네이버에도 올렸던가?”를 기억에 의존하지 않게 되는 지점이죠.

③ AI와 스크립트가 함께 읽는 다리

가장 실용적인 쓰임은 여기입니다. 제 대시보드 생성기는 저 32개 파일을 전부 읽어 HTML을 자동으로 만듭니다.

import yaml
for f in glob.glob("content/*/content.yml"):
    d = yaml.safe_load(open(f, encoding="utf-8").read())

두 줄이면 끝입니다. AI가 yml을 쓰고, 파이썬이 그걸 읽고, 사람이 브라우저로 봅니다. 세 주체가 파일 하나를 공유하는 거죠. JSON도 되지만 사람이 직접 손보기엔 불편하고, 워드 문서는 기계가 못 읽습니다. YAML은 정확히 그 사이에 있습니다.

그리고 이미 매일 보고 계실 겁니다. Claude Code의 서브에이전트 정의, GitHub 자동 배포 설정, MCP 서버 구성이 전부 이 형식이에요. 마크다운 글 맨 위 --- 사이 영역(프론트매터)도 YAML입니다 — 지금 읽고 계신 이 글의 제목과 키워드도 거기 적혀서 그대로 사이트 메타태그가 됩니다.

💥 4. 실제로 이게 뭘 잡아냈나

이 글을 쓰기 직전에 있었던 일입니다. “지금 채널 라인 몇 개 굴리고 있지?”라고 물었더니, AI가 config/channels.yml(설정)과 content/*/content.yml(실제 발행 기록)을 대조하고 이렇게 답했습니다.

네이버 리뷰 채널이 설정에는 active: false인데, 실제로는 7건이 발행됐습니다.

설정이 현실보다 뒤처져 있었던 거죠. 채널을 만들고 글은 계속 올렸는데 설정 파일만 안 고친 겁니다. 눈으로는 못 잡습니다 — 두 파일이 다른 폴더에 있고, 한쪽은 32개로 흩어져 있으니까요. 구조화된 형식이었기 때문에 대조가 가능했습니다.

교훈은 두 개입니다. yml로 적어두면 AI가 감사(監査)를 대신 해줍니다. 동시에 yml은 스스로 갱신되지 않습니다 — 현실이 바뀌면 파일도 고쳐야 하고, 그 대조를 주기적으로 시켜야 합니다. AI 산출물은 검증까지가 한 세트라는 이야기의 연장이에요.

⚠️ 5. 함정 4가지 — 직접 돌려본 결과

말로만 하면 안 믿기니 이 저장소의 파이썬(PyYAML 6.0.3)으로 실제 실행한 결과입니다.

내가 쓴 것	실제로 읽히는 값	왜
`active: yes`	`True` (참/거짓)	yes·no·on·off가 불리언으로 변환됨
`country: NO`	`False`	노르웨이 국가코드 NO가 “거짓”이 됨
`version: 1.20`	`1.2`	숫자로 읽혀 끝의 0이 사라짐
`title: 제목: 부제`	에러	값 안의 콜론을 구조로 해석

해결은 전부 같습니다 — 헷갈릴 것 같으면 따옴표로 감싸세요. active: "yes", version: "1.20", title: "제목: 부제". 이 넷 중 셋은 에러도 안 나고 조용히 다른 값이 되기 때문에 더 위험합니다.

그리고 하나 더, 탭(Tab)으로 들여쓰기하면 무조건 깨집니다. 공식 명세가 못 박아 둔 규칙이에요 — “이식성을 위해, 탭 문자는 들여쓰기에 사용해서는 안 된다. 시스템마다 탭을 다르게 취급하기 때문이다.” 실제로 탭을 넣고 돌려보니 ScannerError가 났습니다. 에디터에서 Tab 키가 스페이스로 들어가도록 설정해두는 게 유일한 예방책입니다.

🎯 시작 코스 — 오늘 만들 수 있는 첫 yml

거창할 필요 없습니다. AI에게 매번 반복해서 설명하고 있는 것을 파일로 빼면 그게 첫 yml입니다. 이대로 복사해서 쓰세요.

# my-rules.yml — AI에게 매번 설명하던 것들 (2026-09-08 작성)

톤:
  - 존댓말, 과장 금지
  - 결론을 맨 앞에

금지:
  - 확인 안 된 수치를 확정해서 쓰기
  - 회사 이름·고객 정보 언급

형식:
  분량: "A4 1장 이내"      # 콜론이 있으니 따옴표
  마무리: 실행 항목 3개

그리고 대화 시작할 때 한 줄이면 됩니다. “my-rules.yml 규칙을 지켜서 써줘.”

만들 때 지킬 것 세 가지:

한 파일에 한 가지 주제. 규칙과 기록을 한 파일에 섞지 않습니다
필드 이름은 짧고 일관되게, 값은 한글도 괜찮습니다. 위 예시처럼 키까지 한글로 써도 파서는 읽습니다
날짜와 이유를 주석(#)으로 남기세요. 3주 뒤의 나는 왜 이렇게 정했는지 기억 못 합니다

AI 업무 자동화는 도구가 아니라 순서라고 썼는데, yml은 그 순서의 두 번째 칸쯤에 있습니다. 반복되는 지시를 파일로 굳히는 순간부터 AI에게 시키는 일의 결과가 눈에 띄게 일정해집니다.

기준: 2026-09-08. 문법 실험은 이 저장소의 PyYAML 6.0.3에서 직접 실행한 결과입니다. YAML 정의와 탭 규칙은 공식 명세 1.2.2(yaml.org/spec/1.2.2, 2021-10-01 개정), 확장자 권장 이력은 위키백과 YAML 문서를 확인했습니다. 다이어그램은 직접 제작했습니다.