PyYAML의 safe_load가 YAML을 읽는 데 성공해도 description이 문자열이라는 보장은 없다. 이 예제에서는 같은 설명을 따옴표로 감싸면 str이 됐지만, 다음 줄에 들여쓴 입력은 dict가 됐다. 문자열을 받는 프로그램이라면 파싱 성공 뒤에 값의 타입도 따로 검사해야 한다.
가상의 스킬 이름 log-reader와 설명 Read logs: keep timestamps로 이 차이를 확인했다. Python 3.11.18과 PyYAML 6.0.3의 safe_load에 작은 YAML 본문을 넣고, 파싱 성공 여부와 description 값의 타입을 확인했다. 여기서 프로그램이 요구한다고 정한 형식은 ‘description은 문자열’이다.
name: log-reader
description: "Read logs: keep timestamps"
설명 전체를 따옴표로 감싼 입력은 성공했다. description의 타입은 str이었고 값은 Read logs: keep timestamps였다. 설명의 뜻은 그대로 두고 YAML에서 문자열로 읽히도록 표기한 경우다.
name: log-reader
description:
Read logs: keep timestamps
다음 줄에 설명을 들여쓴 위 입력도 파싱에 성공했다. 그러나 description은 dict가 됐다. 안에는 Read logs라는 키와 keep timestamps라는 값이 들어 있었다. YAML 구문으로는 읽을 수 있어도, 설명문 자리에 문자열을 기대하는 프로그램의 형식과는 맞지 않았다.
name: log-reader
description: Read logs: keep timestamps
따옴표와 줄바꿈을 모두 없앤 이 입력은 ScannerError로 실패했다. 오류 메시지는 mapping values are not allowed here였고, 설명문 안의 두 번째 콜론을 가리켰다. 콜론 뒤에 공백이 붙은 logs: keep 구문을 이 위치에 그대로 쓴 입력에서 오류가 난 것이다. 따라서 같은 문장을 놓고도 구문 오류, 문자열, 사전이라는 서로 다른 결과를 구별해야 했다.
여러 줄 표기가 모두 사전을 만드는 것은 아니다. description: > 아래에 같은 문장을 들여쓴 접힌 블록 표기는 이 실행에서 문자열이 됐다. 다만 값 끝에 줄바꿈이 하나 남았다. 따옴표로 감싼 값과 타입은 같아도 바이트까지 같다고 할 수는 없다. 이번 확인은 타입과 실제 값만 비교했으며, 그 끝 줄바꿈이 특정 스킬 로더에서 문제를 일으키는지는 시험하지 않았다.
검사를 붙인다면 두 질문을 나눌 수 있다. 먼저 YAML 파서가 읽을 수 있는가. 그다음 필요한 키가 있고 각 값이 프로그램이 요구한 타입인가. 이 예에서는 파싱에 성공한 사전 값이 두 번째 검사에서 탈락한다. 사람이 보기 좋은 설명을 쓰는 일과 그 설명이 문자열로 전달되는 일을 같은 검사에 맡기면 이 차이가 빠진다.
확인 범위는 Python 3.11.18과 PyYAML 6.0.3에서 읽은 작은 합성 YAML 본문이다. 실제 Markdown frontmatter 추출, 스킬 설치와 에이전트 로딩은 시험하지 않았다.