도움말 — 이 대시보드를 읽는 법

1. 대시보드의 구조 — 3개 층위

• Layer 1 · 문제 개선 스코어카드 — 2026-04 기준선이 지적한 7대 구조 문제가 지금 얼마나 해결됐는지를 보여줍니다. 카드의 배지(개선/부분/미개선)는 전수 215개 관점을 롤업한 결과이며, 대표 포털에서만 개선이 확인된 경우에는 "부분"으로 표기합니다(예: 항상 200 문제는 게이트웨이 8/172만 개선되었으므로 "부분"입니다).
• Layer 2 · 등급 이동 — 포털별 사용자중심성(UF)·AI적합성(AI) 합산 점수가 2026-04에서 2026-08 사이에 어떻게 이동했는지를 보여줍니다. 점선과 "부분측정" 배지는 일부 지표를 측정하지 못해 잠정치라는 뜻으로, 점수가 내려갔더라도 실제 퇴보가 아니라 측정하지 못한 지표 때문일 수 있음을 알려줍니다.
• Layer 3 · AI/Agent 준비도 히트맵 — 215개 포털을 18개 지표로 교차한 표입니다. 셀 색은 0점(빨강)에서 2점(초록)까지를 나타내고, 회색은 측정하지 못한 지표입니다. 행을 클릭하면 지표별 판정과 측정 방식, 증거 링크가 펼쳐집니다.

2. 7대 문제 — 무엇이고, 왜 해결해야 하나

일곱 문제의 공통점은 모두 사람은 우회할 수 있지만 기계(에이전트)는 우회하지 못하는 종류라는 점입니다. 사람은 200 응답 안에 섞인 오류 메시지를 읽어 내고, HWP 파일을 열어 보고, 안 되면 전화로 문의합니다. 반면 에이전트는 그 각각의 지점에서 멈추거나 잘못된 호출을 반복합니다. 그래서 이 문제들이 곧 "AI 시대 준비도"를 재는 척도가 됩니다.

7대 문제 상세 — 왜 문제이고, 어떻게 해결하나

항상 200 반환 (오류도 HTTP 200)

왜 문제인가 — 오류가 발생해도 성공 코드(200)를 반환하면, 호출한 프로그램은 본문을 파싱해 보기 전까지 실패했다는 사실 자체를 알 수 없습니다. 재시도·폴백·알림 같은 모든 자동 복구 로직이 상태코드를 전제로 만들어지기 때문에, 이 문제 하나로 에이전트의 오류 처리 체계 전체가 무력화됩니다. 모니터링 도구도 '전부 성공'으로 기록해 장애가 숨겨집니다.

어떻게 해결하나 — 백엔드를 고치지 않아도 게이트웨이에서 오류 본문을 감지해 상태코드로 변환할 수 있습니다. 실제로 data.go.kr 게이트웨이가 이 방식으로 개선되어 8개 포털이 동시에 좋아졌습니다. 나머지 포털에도 같은 게이트웨이 정책을 확대하는 것이 가장 효과적인 한 수입니다. → 지표 개선 가이드

CORS 미지원

왜 문제인가 — 브라우저는 보안 정책상 CORS 허용 헤더가 없는 API를 웹 앱에서 직접 호출하지 못하게 막습니다. 그 결과 단순 날씨 조회 앱을 만들 때조차 중계용 프록시 서버를 별도로 구축·운영해야 하며, 이는 진입장벽이자 지속 비용이 됩니다.

어떻게 해결하나 — 공개 데이터 API라면 CORS를 전면 허용해도 안전합니다(접근 통제는 인증 키가 담당합니다). 게이트웨이나 웹서버 설정 한 줄이면 충분합니다. → 지표 개선 가이드

XML 기본 응답

왜 문제인가 — 기본 응답이 XML이면 JSON을 기본으로 가정하는 현대 개발 도구와 AI 에이전트 모두가 변환 계층을 얹어야 합니다. 같은 전환 비용을 모든 이용자가 각자 반복해서 지불하는 구조입니다.

어떻게 해결하나 — 기본값을 JSON으로 바꾸고 XML은 옵션 파라미터로 유지하면 기존 이용자와의 호환을 지키며 전환할 수 있습니다. 6개월 병행 공지 후 기본값을 바꾸는 방식이 안전합니다. → 지표 개선 가이드

OpenAPI 미제공

왜 문제인가 — 기계가독 명세가 없으면 에이전트는 HWP 문서나 웹 화면을 읽어 호출법을 추론해야 합니다. 이용 절차 분석에서 실측했듯 이 차이가 토큰 비용을 수십 배로 벌립니다. 2026-08 전수 조사에서 공식 스펙을 관용 경로에 공개한 포털은 한 곳도 없었습니다.

어떻게 해결하나 — 기존 문서를 OpenAPI 3.x로 옮겨 /openapi.json 경로에 게시하면 됩니다. 명세가 생기면 Swagger 문서·SDK·MCP 서버가 모두 자동으로 따라옵니다 — 한 번의 작업으로 네 가지가 개선됩니다. → 지표 개선 가이드

RateLimit 헤더 없음

왜 문제인가 — 남은 호출량을 알 수 없으면 에이전트는 한도 초과를 실패를 겪고 나서야 알게 됩니다. 안정적인 자동화는 사전에 속도를 조절할 수 있어야 가능합니다.

어떻게 해결하나 — IETF 표준 RateLimit 헤더 3종(Limit·Remaining·Reset)을 게이트웨이에서 부착하면 됩니다. Kong이나 nginx의 플러그인 설정 수준의 작업입니다. → 지표 개선 가이드

정부 MCP 서버 없음

왜 문제인가 — 에이전트가 화면이 아닌 도구 호출로 데이터에 접근하는 시대에 공식 MCP가 없으면, 그 수요는 품질과 보안이 제각각인 비공식 래퍼 79종으로 흘러갑니다. 프랑스·미국·영국은 이미 정부가 운영하는 MCP를 제공하고 있습니다.

어떻게 해결하나 — OpenAPI 명세가 있으면 MCP 서버는 얇은 래퍼에 불과합니다. 공개 소스인 프랑스 datagouv-mcp를 참고해 대표 API 10종으로 파일럿을 시작하고, 서울시 파일럿의 교훈(자체 인프라 부재·정원 제한)을 보완하면 됩니다. → 지표 개선 가이드

API Key in URL (쿼리 파라미터 노출)

왜 문제인가 — URL에 실린 키는 웹서버 로그·프록시·Referer 헤더에 평문으로 남습니다. 키가 2년간 유효한데 회전(교체)용 API도 없어, 한 번의 유출이 곧 장기 노출로 이어집니다.

어떻게 해결하나 — 키를 Authorization 헤더로 옮기면 이 유출 경로가 사라지고 표준 클라이언트와도 호환됩니다. 쿼리 방식은 유예기간을 두고 병행하면 됩니다. → 지표 개선 가이드

3. AI/Agent 준비도 18개 지표 — 의미·점수 기준·측정 방법

두 개의 합산 점수 — UF와 AI는 무엇을 재는가

• 사용자중심성 UF (0~14점) — 사람 개발자가 겪는 마찰의 총량을 재는 점수입니다. 가입 용이성 → 승인 속도 → 기본 포맷 → 문서 품질 → 호출 한도 → 오류 처리 → SDK·샘플, 즉 "가입부터 첫 성공 호출까지"의 7단계를 각각 0~2점으로 평가해 합산합니다. 한국 전수 평균은 5.74(D)입니다.
• AI 적합성 AI (0~14점) — 기계(에이전트)가 사람의 개입 없이 스스로 쓸 수 있는지를 재는 점수입니다. 기계가독 스키마 → HTTP 상태코드 → JSON 네이티브 → 오류 자기설명 → 프로그램 인증 → 한도 투명성 → CORS·HTTPS, 즉 "사람의 도움 없이 발견하고 호출하고 복구"하기 위한 7가지 전제를 평가합니다. 한국 전수 평균은 2.35(E)로 UF보다 낮은데, 사람이 쓰던 우회로(전화·게시판·HWP 열람)가 기계에게는 없기 때문입니다.
• 평가 방법 — 지표마다 0점(없음/비표준)·1점(부분)·2점(표준 충족)의 3단 척도로 채점한 뒤 단순 합산합니다. 측정불가 지표는 0점으로 처리하지 않고 합산과 분모에서 모두 제외하며, 7개 지표 중 일부만 측정된 포털에는 "부분측정 (n/7)" 배지를 붙여 잠정치임을 밝힙니다. 등급 구간은 A(12~14) B(9~11) C(6~8) D(3~5) E(0~2)입니다. †가 붙은 4개 지표(도구 네이티브·llms.txt·데이터 제품화·통합 계정)는 2026-08에 새로 만든 실험 지표여서 합산에서 제외하고 별도로 추적합니다.
• Before→After 비교 — 2026-04 기준선(문서·구성 조사)과 2026-08 재측정을 같은 지표 체계로 대조합니다. 측정 방식이 달라진 지표(문서 조사에서 실측으로 전환)는 판정 주석에 그 사실을 밝혀, "측정 교정"과 "실제 변화"를 구분할 수 있게 했습니다.

5. 지표별 개선 가이드 — 무엇을 어떻게 바꾸나

API를 제공하는 기관의 실무자를 위한 처방입니다. 대부분은 게이트웨이 설정이나 반나절이면 끝나는 작업 수준이며, 예제는 그대로 가져다 응용할 수 있는 형태로 실었습니다. 위 지표 표의 "개선 →" 링크를 누르면 해당 항목으로 바로 이동합니다.

HTTP 상태코드 http_semantics AI 적합성

게이트웨이나 컨트롤러에서 오류를 상태코드로 매핑하세요. 백엔드를 고치지 않고 게이트웨이의 응답 변환만으로도 가능합니다(data.go.kr이 실제로 이 방식으로 개선했습니다).

# 잘못된 키 → 401, 없는 자원 → 404, 파라미터 오류 → 400
HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

{"type":"/errors/invalid-key","title":"등록되지 않은 인증키","status":401}

JSON 네이티브 json_native AI 적합성

기본 응답을 JSON으로 바꾸고 XML은 &type=xml 옵션으로 남겨 두세요. 기존 이용자와의 호환을 위해 6개월 동안 두 형식을 함께 제공한다고 공지한 뒤 기본값을 전환하는 방식이 안전합니다.

GET /api/forecast?region=서울          → JSON (기본)
GET /api/forecast?region=서울&type=xml → XML (호환)

오류 자기설명 error_self_desc AI 적합성

RFC 7807(application/problem+json)을 채택하세요. 오류 코드표를 HWP로 배포하는 대신, 응답 자체가 원인과 해결 방법을 설명하도록 만드는 것이 핵심입니다.

{"type":"https://api.example.go.kr/errors/quota",
 "title":"일일 호출 한도 초과","status":429,
 "detail":"한도 1000회를 초과했습니다. 09:00(KST)에 초기화됩니다.",
 "instance":"/req/12345"}

기계가독 스키마 machine_schema AI 적합성

기존 문서를 OpenAPI 3.x YAML로 옮기고 /openapi.json 관용 경로에 게시하세요. Swagger Editor로 시작하면 반나절이면 끝나는 작업입니다. 새로 만드는 API는 스펙 우선(spec-first) 방식으로 설계하시기 바랍니다.

# https://api.example.go.kr/openapi.json 에 게시
openapi: 3.0.3
info: {title: 단기예보 조회, version: 2.0.0}
paths:
  /getVilageFcst:
    get:
      parameters: [{name: nx, in: query, required: true, schema: {type: integer}}]

프로그램 인증 programmatic_auth AI 적합성

키를 URL 쿼리에서 Authorization 헤더로 옮기세요. 로그와 Referer 헤더를 통한 유출이 사라지고 표준 클라이언트와도 호환됩니다. 기존 쿼리 방식은 유예기간 동안 함께 지원하면 됩니다.

# 이전: GET /api?serviceKey=abc123  (로그에 평문 잔존)
# 이후:
GET /api HTTP/1.1
Authorization: Bearer abc123

한도 투명성 rate_limit_transparency AI 적합성

IETF RateLimit 헤더 3종을 게이트웨이에서 응답에 붙여 주세요. Kong이나 nginx 플러그인 설정만으로 해결되는 수준의 작업입니다.

HTTP/1.1 200 OK
RateLimit-Limit: 1000
RateLimit-Remaining: 847
RateLimit-Reset: 3600

CORS·HTTPS cors_https AI 적합성

공개 데이터 API라면 CORS를 전면 허용해도 안전합니다(인증은 헤더에 담긴 키가 담당하기 때문입니다). 게이트웨이에 한 줄만 추가하면 됩니다.

# nginx
add_header Access-Control-Allow-Origin *;
add_header Access-Control-Allow-Headers Authorization;

가입 용이성 signup_ease UF 사용자중심성

조회성 API는 이메일 가입만으로, 위험이 낮은 API는 가입 없이 쓰는 공용 샌드박스 키로 개방하세요. 본인인증은 개인정보를 다루는 API에만 한정하는 것이 바람직합니다.

위험도 3단계 정책 예:
  공개 통계·날씨  → 가입 불요(샌드박스 키)
  일반 조회      → 이메일 인증
  개인정보 연계  → 본인인증 유지

승인 속도 approval_speed UF 사용자중심성

자동승인 기준(개인정보와 무관할 것, 출처를 표시할 것, 쿼터를 준수할 것)을 공개하고 이를 충족하면 즉시 키를 발급하세요. 심의는 예외적인 경우에만 적용하되, 그 사유와 처리 기한을 함께 알려야 합니다.

활용신청 → 기준 자동판정(1초) → 즉시 키 발급
         → 기준 미충족 시에만 심의(사유+최대 3일 기한 고지)

기본 포맷 data_format UF 사용자중심성

처방은 json_native와 같습니다. 새로 만드는 API는 JSON 전용으로 시작하고, 파일 중심으로 운영되는 포털이라면 최소한 카탈로그와 메타데이터만이라도 JSON API로 제공하세요.

GET /catalog/datasets?page=1  → {"datasets":[...], "total": 451}

문서 품질 doc_quality UF 사용자중심성

HWP 첨부 문서를 OpenAPI 스펙을 렌더링하는 Swagger UI로 대체하세요. 스펙(machine_schema)만 만들어 두면 문서는 자동으로 생성되므로, 한 번의 작업으로 두 지표를 함께 개선할 수 있습니다.

docs.example.go.kr → Swagger UI로 스펙 렌더
+ '지금 실행해보기(Try it out)' 버튼 = 샘플 코드 불필요

호출 한도 rate_limit UF 사용자중심성

기본 한도를 실제 서비스가 가능한 수준(하루 1만 회 이상)으로 올리고, 증량 요청은 신청 즉시 자동으로 처리하세요. 남용은 낮은 한도가 아니라 RateLimit 헤더와 429 응답으로 제어하는 것이 맞습니다.

기본 10,000/일 → 초과 시 429 + Retry-After → 증량 신청 API로 즉시 상향

오류 처리 error_handling UF 사용자중심성

오류 응답을 하나의 스키마로 통일하고 모든 API에 예외 없이 적용하세요(게이트웨이에서 응답을 검증하면 됩니다). error_self_desc에서 설명한 RFC 7807 채택이 그대로 해법이 됩니다.

모든 오류 = problem+json 단일 스키마
게이트웨이에서 스키마 위반 응답을 감지해 변환/경고

SDK·샘플 sdk_samples UF 사용자중심성

OpenAPI 스펙만 있으면 openapi-generator로 여러 언어의 SDK가 자동으로 생성됩니다. 이미 잘 만들어진 커뮤니티 SDK(예: PublicDataReader)를 공식으로 인정하는 것도 좋은 방법입니다.

openapi-generator generate -i openapi.json -g python -o sdk-python
# python/js/java SDK를 CI에서 자동 배포

도구 네이티브(MCP) tool_native 실험 †

OpenAPI 스펙이 갖춰져 있으면 MCP 서버는 그 위에 얹는 얇은 래퍼에 지나지 않습니다. 소스가 공개된 프랑스의 datagouv-mcp를 참고해 대표 API 10종으로 파일럿을 시작해 보세요.

# fastmcp 예시
@mcp.tool()
def get_forecast(region: str) -> dict:
    """단기예보 조회"""
    return api.call('/getVilageFcst', region=region)

llms.txt llms_txt 실험 †

사이트 루트에 llms.txt 텍스트 파일 하나를 두는 것으로 충분합니다. API 목록과 스펙 위치, 인증 방법을 AI가 읽을 수 있게 적어 두기만 하면 됩니다.

# https://api.example.go.kr/llms.txt
# 단기예보 API
> 기상청 단기예보 조회 서비스
- 스펙: /openapi.json
- 인증: Authorization 헤더 (발급: /signup)

데이터 제품화 data_product 실험 †

데이터셋 메타데이터에 버전, 갱신주기, 최종갱신 시점, SLA를 DCAT 표준 필드로 명시하세요.

{"dct:modified":"2026-08-01","dct:accrualPeriodicity":"P1D",
 "version":"2.1","sla":"가용성 99.5%, 지연 최대 1시간"}

통합 계정 unified_identity 실험 †

새로 만드는 포털은 자체 가입 절차 대신 data.go.kr 키 위임 방식(E-GEN 모델: 'data.go.kr 회원가입은 필수, 별도 계정은 없음')을 채택하세요. 장기적으로는 정부 통합 개발자 ID로 나아가야 합니다.

E-GEN 방식: 자체 회원DB 없음 → data.go.kr serviceKey 그대로 수용
→ 이용자 추가 가입 0회, 포털은 회원관리 비용 0

4. 측정 방법론 — 판정을 신뢰할 수 있는 이유

• 측정 방식 3계층 — live 는 실제로 HTTP를 호출해 확인한 결과입니다(잘못된 키를 일부러 넣어 상태코드가 정직한지 검증하는 식이며, 실제 키는 절대 노출하지 않고 더미 키만 사용합니다). browser 는 실제 브라우저에서 렌더링된 화면을 관측한 결과이고, doc 은 공식 문서와 구성 정보를 근거로 판정한 결과입니다. 상세 패널의 "측정방식" 배지에서 셋을 구분할 수 있습니다.
• 측정불가는 0점이 아닙니다 — 인증키가 없는 등의 이유로 검증하지 못한 지표는 평균을 낼 때 분모에서 제외해, 점수를 인위적으로 끌어내리지 않습니다.
• 판정 규칙 — 개선(점수 상승), 유지(만점 유지), 미개선(변화 없음), 후퇴(점수 하락), 신규(2026-04 기준값이 없음), 측정불가의 여섯 가지로 판정합니다. "후퇴"로 표시된 사례 상당수는 문서를 근거로 낙관적으로 매겼던 값이 실측으로 교정된 결과일 수 있어, 그런 경우에는 별도 주석을 답니다.
• 오탐 교정 의무 — 자동 탐지 결과는 반드시 표본을 뽑아 사람이 다시 검증합니다(실제 사례로, 자동 탐지된 llms.txt 3건이 모두 HTML 오류 페이지로 확인되어 판정을 바로잡았고 그 교정 이력도 공개했습니다).
• 재현 가능성 — 모든 live 판정에는 그대로 재현할 수 있는 curl 명령과 응답 샘플을 증거로 링크했으며, serviceKey는 게시 전에 마스킹합니다.
• 전체 정본 명세는 루브릭 명세 v1.0(저장소 output/expert_review_2026-08.md 부록 A)을 참조하시기 바랍니다.