맞는 포맷 고르기 — 결정 매트릭스

전체 quest 의 마무리

이제 네 포맷 다 알아. 마지막 기술이 잘 고르기. 아래 매트릭스가 각 포맷이 이기는 시점 요약.

청중과 lifecycle 로 골라

Markdown — 주요 청중이 사람 reader 이고, 문서가 prose 가 중요할 만큼 길 때.
JSON — 주요 청중이 소프트웨어, 매체가 네트워크 또는 저장소, 기계 라운드트립 요구될 때.
YAML — 사람이 파일 편집, 구조가 깊이 중첩, 들여쓰기 규율 받아들일 만할 때.
TOML — 사람이 파일 편집, 구조가 얕은-에서-중간, 줄당 명확함이 compactness 이길 때.

피할 안티패턴

사람 config 에 JSON — 주석 없음, trailing comma 함정, 깊은 중첩이 알파벳 수프처럼 읽힘.
Wire 에 YAML — 파싱 느림, 시스템 가로지르는 들여쓰기 민감, 안전하지 않은 파서로 보안 위험.
깊이 중첩 데이터에 TOML — table 헤더 쌓임; 4 단계 넘으면 YAML 또는 JSON 이김.
구조화 데이터 단독에 Markdown — 구조엔 front matter, prose 엔 본문 사용. table-as-data 를 Markdown 본문 만으로 인코딩 시도하지 마.

얻은 fluency

넷 다 읽음. 그 사이 변환. JSON Schema 한 번 작성하고 어디서나 검증. 한 눈에 Norway 문제, trailing-comma 함정, YAML 탭 발견. jq 잡을 시점, yq 잡을 시점, MDX component 잡을 시점 앎. 그게 markup literacy.

마무리 원칙: 포맷은 도구. literacy 는 어느 도구가 어느 일에 맞는지 알기, 그리고 잘못된 도구가 손에 있을 때 번역하는 법 알기. 지금 든 네 포맷 fluency 가 모든 프로젝트 — README, API spec, 배포 manifest, 빌드 manifest, 학습 데이터 — 가로질러 평생 누적될 거.

Code

결정 매트릭스·text

                       │ 주석     │ 네이티브│ 깊은   │ Wire    │ 가장 좋은 주 사용
                       │ 허용?    │ 날짜?   │ 중첩   │ 포맷?   │
──────────────────────┼──────────┼────────┼────────┼─────────┼──────────────────
  Markdown             │   yes    │   no   │   no   │   no    │ 사람 prose +
  (front matter 가진)  │          │        │        │         │ 구조화 메타
  JSON                 │   no     │   no   │  yes   │  YES    │ 기계 wire
                       │          │        │        │         │ 포맷, API
  YAML                 │   yes    │  yes   │  YES   │ 드물게  │ 사람 config,
                       │          │        │        │         │ K8s, CI, Ansible
  TOML                 │   yes    │   YES  │ 중간   │   no    │ 사람 config,
                       │          │        │        │         │ pyproject, Cargo

의심되면 — 세 빠른 필터·text

1. 누가 이걸 가장 자주 편집하나?
   - prose 작성하는 사람              → Markdown
   - 구조 편집하는 사람              → YAML 또는 TOML
   - 소프트웨어                       → JSON (또는 스트림엔 JSONL)

2. 얼마나 중첩?
   - 1-3 단계                         → TOML 가 가장 깨끗하게 읽힘
   - 4+ 단계                          → YAML 가 TOML 이김
   - 다양함                          → 둘 다, + 강타입 config layer

3. 어디로 이동?
   - 디스크만                         → 사람이 선호하는 포맷
   - 네트워크 가로질러                → JSON
   - 둘 다                            → 디스크엔 사람 포맷, 경계에서 변환

마지막 exercise — 본인 일에 적용·text

현재 리포의 세 config / 데이터 파일 골라:
  - 현재 JSON 인 거 하나
  - 현재 YAML 인 거 하나
  - 현재 TOML 인 (또는 가능했을) 거 하나

각각 자문:
  - 청중에게 포맷이 맞나?
  - schema 가 데이터 옆 사나, 코드에 흩어져 있나?
  - 변환이 가독성 개선하거나 도구 깨뜨릴까?

이 리뷰가 파일당 10 분, 분기당 시간 절약.

Exercise

리포 하나 audit. 모든 config / 데이터 파일을 포맷별로 나열. 각각 자문: 청중에게 이 포맷이 맞나? 바뀌어야 할 거 표시. 그 후 하나 바꾸기 — 잘못된 포맷 파일 하나를 맞는 거로 변환하고 편집 편안함의 diff 알아채. quest 의 마지막 lesson 은 매트릭스 이해만 아니라 변경 실현.

맞는 포맷 고르기 — 결정 매트릭스

전체 quest 의 마무리

청중과 lifecycle 로 골라

피할 안티패턴

얻은 fluency

Code

External links

Exercise

Progress

댓글 0