전체 quest 의 마무리
이제 네 포맷을 다 알아. 마지막으로 남은 기술은 잘 고르는 거야. 아래 표가 어느 포맷이 언제 이기는지를 정리해줘.
청중과 흐름을 보고 골라
- Markdown — 주로 읽을 사람이 사람이고, 문서가 글맛이 중요할 만큼 길 때.
- JSON — 주로 읽을 쪽이 소프트웨어고, 오가는 통로가 네트워크나 저장소고, 기계가 왕복시켜야 할 때.
- YAML — 사람이 직접 파일을 고치고, 구조가 깊이 중첩되고, 들여쓰기 규율을 감당할 수 있을 때.
- TOML — 사람이 직접 고치고, 구조는 얕거나 중간이고, 짧게 쓰는 것보다 한 줄 한 줄이 분명한 게 더 중요할 때.
피할 안티패턴
- 사람이 고치는 config 에 JSON — 주석을 못 달고, trailing comma 함정이 있고, 깊어지면 괄호 죽처럼 읽혀.
- 네트워크로 오가는 데 YAML — 파싱이 느리고, 시스템을 옮겨 다니며 들여쓰기가 흔들리고, 안전하지 않은 파서를 쓰면 보안 구멍이 돼.
- 깊이 중첩된 데이터에 TOML — table 헤더가 겹겹이 쌓여. 네 단계를 넘으면 YAML 이나 JSON 이 나아.
- 구조화된 데이터를 Markdown 만으로 — 구조는 front matter 에, 글은 본문에 둬. 표 모양 데이터를 Markdown 본문만으로 담아보려고 하지 마.
얻은 fluency
넷을 다 읽고, 그 사이를 오가고, JSON Schema 를 한 번 써서 어디서든 검증하고, Norway 문제와 trailing comma 함정과 YAML 탭을 한눈에 알아보고, jq 를 꺼낼 때와 yq 를 꺼낼 때와 MDX component 를 꺼낼 때를 구분하게 됐어. 그게 markup literacy 야.
마무리 원칙: 포맷은 도구일 뿐이야. literacy 란 어느 도구가 어느 일에 맞는지 아는 것, 그리고 손에 엉뚱한 도구가 들려 있을 때 옮겨 담을 줄 아는 거야. 지금 손에 넣은 네 포맷 감각은 앞으로 만드는 모든 프로젝트에 계속 쌓여. README 든 API spec 이든 배포 manifest 든 빌드 manifest 든 학습 데이터든 전부.