④ 헤르메스 엔지니어링

🖐 실무 따라하기 — 복붙해서 따라 하면 됩니다

1. 1막연한 요구 → 실행 가능한 명세로 번역 (의도→명세)

   /playground(또는 ChatGPT·Claude 웹)를 연다. 아래 프롬프트를 처음부터 끝까지 통째로 복사해 붙여넣어, 팀장의 구두 지시를 '입력/처리/출력/제약'이 명시된 작업명세서(spec)로 번역시킨다. 이 단계는 코드가 아니라 '무엇을 만들지 계약서'를 뽑는 단계다.

   프롬프트 (복사해서 AI에 입력)

   ⧉ 복사

   당신은 공공행정 업무를 실행 가능한 명세로 번역하는 분석가입니다. 아래 '막연한 지시'를 개발/실행이 가능한 작업명세서로 변환하세요.
   
   [막연한 지시]
   "요즘 밀린 도로 파손 민원들, 상황 좀 정리해서 위에 보고하고 민원인한테도 안내 나가게 해줘."
   
   [출력 형식] 아래 6개 항목을 표가 아닌 번호 목록으로 작성하세요:
   1. 목적(한 문장)
   2. 입력(무엇을 받는가: 데이터 항목을 구체적으로 나열 — 예: 접수번호, 위치, 민원 요지)
   3. 산출물(정확히 몇 종을 어떤 형태로 — 예: 보고용 요약 1건 + 민원인 안내문 N건)
   4. 각 산출물의 필수 필드(항목명 나열)
   5. 처리 규칙(우선순위·분류 기준 등. 지시에 근거가 없으면 항목 끝에 '(가정)'이라고 표시)
   6. 애매해서 팀장에게 되물어야 할 질문 정확히 3개
   
   [제약]
   - 실제 개인정보는 다루지 않고 합성 데이터만 가정한다.
   - 지시에 없는 사실(법조문·처리기한 숫자 등)은 지어내지 말고 '확인필요'로 남긴다.
   - 6개 항목을 빠짐없이 채우고, 5번의 각 규칙에는 근거 유무를 '(가정)' 표기로 구분한다.

   → 결과 6개 항목이 모두 채워진 명세서가 나온다. 특히 3번에 '보고용 요약 1건 + 민원인 안내문 N건'처럼 개수/형태가 명확해지고, 5번의 규칙에 '(가정)' 표기가 붙고, 6번에 되물을 질문 3개(예: 처리기한 며칠? 우선순위 기준은? 안내문 발송 방식은?)가 뜨는지 확인. 애매함이 질문으로 '밖으로 드러나는' 것이 이 단계의 핵심.

2. 2기계 인터페이스 설계 — JSON 스키마 확정 (스키마 설계)

   명세의 '필수 필드'를 기계가 검증할 수 있는 계약으로 고정한다. 아래 명령을 터미널에 통째로 붙여넣으면 스키마 파일이 저장되고 내용까지 화면에 출력된다(무설치자는 히어독 안의 JSON 텍스트만 메모장에 복사해 두면 됨). confidence(신뢰도)와 source(출처: 접수메모/AI추정)를 필드로 강제하는 것이 포인트 — 나중에 인간가독화 단계에서 그대로 표기로 이어진다.

   터미널 명령

   ⧉ 복사

   cat > /tmp/minwon.schema.json <<'JSON'
   {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "title": "도로파손 민원 정리 스키마",
     "type": "object",
     "required": ["generated_by", "cases"],
     "properties": {
       "generated_by": { "type": "string", "description": "AI 생성물 표기" },
       "cases": {
         "type": "array", "minItems": 1,
         "items": {
           "type": "object",
           "required": ["receipt_no", "location", "category", "priority", "confidence", "source", "citizen_notice"],
           "properties": {
             "receipt_no": { "type": "string", "pattern": "^MW-2026-[0-9]{4}$" },
             "location": { "type": "string" },
             "category": { "type": "string", "enum": ["포트홀", "균열", "침하", "기타"] },
             "priority": { "type": "string", "enum": ["상", "중", "하"] },
             "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
             "source": { "type": "string", "enum": ["접수메모", "AI추정"] },
             "citizen_notice": { "type": "string", "minLength": 20 }
           }
         }
       }
     }
   }
   JSON
   echo '--- 저장된 스키마 내용 ---'
   cat /tmp/minwon.schema.json

   → 결과 '--- 저장된 스키마 내용 ---' 아래로 방금 저장한 JSON 스키마 전문이 화면에 그대로 출력되면 성공(아무 출력이 없으면 히어독이 EOF까지 안 닫힌 것). 무설치자는 셸 대신 히어독 안의 JSON 텍스트만 보관. 핵심은 priority/category를 enum으로 가둬 AI가 임의 값을 못 넣게 하고, confidence·source·generated_by로 신뢰도/출처/AI표기를 스키마 차원에서 강제했다는 점.

3. 3합성 민원 원자료를 스키마에 맞춰 구조화 (기계출력 생성)

   아래 프롬프트를 처음부터 끝까지 통째로 복사해 /playground(또는 Claude·ChatGPT 웹)에 붙여넣는다. [스키마] 자리에는 step2 히어독 안의 JSON 스키마 전문을 그대로 붙여 넣는다(요약하지 말 것). 합성 접수메모 5건은 프롬프트 안에 이미 포함되어 있다. AI는 스키마를 100% 만족하는 JSON'만' 출력해야 하며, 원문에 없어 추정한 값은 source를 'AI추정', confidence를 낮게 매긴다.

   프롬프트 (복사해서 AI에 입력)

   ⧉ 복사

   아래 [스키마]를 100% 만족하는 JSON 하나만 출력하세요. 설명·마크다운 코드펜스(```) 없이 JSON 본문만 출력합니다.
   
   [규칙]
   - generated_by 값은 정확히 "AI생성물(모델보조) — 담당자 검토 전"로 넣는다.
   - 접수메모에 적힌 사실은 source="접수메모", confidence는 0.9 이상.
   - 메모에 없어 네가 추정한 값(category/priority 등)은 source="AI추정", confidence는 0.6 이하로 낮춘다.
   - category는 반드시 ["포트홀","균열","침하","기타"] 중 하나, priority는 ["상","중","하"] 중 하나만 쓴다.
   - citizen_notice는 민원인에게 보낼 존댓말 안내문(20자 이상). 처리기한 등 확인 안 된 숫자는 지어내지 말고 '확인 후 별도 안내'로 표현한다.
   - receipt_no는 반드시 MW-2026-000x 형식으로 쓴다.
   
   [스키마]
   (여기에 step2의 JSON 스키마 전문을 그대로 붙여넣기)
   
   [합성 접수메모 5건]
   1. MW-2026-0001 / 홍길동 010-0000-0000 / 경북대로 12 앞 / "차선 가운데 구멍 나서 타이어 터질 뻔"
   2. MW-2026-0002 / 김영희 010-0000-0000 / 안동시 서동문로 사거리 / "바닥 쩍쩍 갈라짐, 밤에 안 보임"
   3. MW-2026-0003 / 이철수 010-0000-0000 / 포항 죽도시장 입구 / "도로가 푹 꺼져서 물 고임"
   4. MW-2026-0004 / 박민수 010-0000-0000 / 구미 인동로 / "맨홀 주변 울퉁불퉁"
   5. MW-2026-0005 / 최지은 010-0000-0000 / 경산 하양읍 / "과속방지턱 페인트 벗겨짐" (도로파손 아닐 수도)

   → 결과 코드펜스 없는 순수 JSON이 출력된다. cases 5개, 각 항목에 receipt_no(MW-2026-0001~0005), category(enum 중 하나), source가 접수메모/AI추정으로 구분되고, 추정 항목(예: 5번 과속방지턱은 category='기타'·confidence 0.6 이하)이 실제로 낮은 confidence를 갖는지 눈으로 확인. 이 JSON 출력 전체를 다음 step에서 /tmp/minwon.json 으로 저장한다.

4. 4기계 검증 — 스키마 위반 자동 적발 (도구/함수 인터페이스)

   AI 출력을 사람이 믿기 전에 기계로 검증한다. 먼저 step3의 JSON 전체를 /tmp/minwon.json 에 저장한다: 아래 첫 명령(`cat > /tmp/minwon.json`)을 실행하고 step3 JSON을 붙여넣은 뒤 Enter, Ctrl-D로 저장한다. 그 다음 두 번째 블록(검증 스크립트)을 통째로 붙여넣어 실행한다. 무설치·망분리자는 jsonschemavalidator.net 에 왼쪽=step2 스키마, 오른쪽=step3 JSON을 각각 붙여넣어 'valid'가 뜨는지로 동일하게 검증한다.

   터미널 명령

   ⧉ 복사

   # (1) step3의 JSON을 저장 — 아래 실행 후 step3 JSON을 붙여넣고 Enter, 그다음 Ctrl-D
   cat > /tmp/minwon.json
   
   # (2) 저장했으면 아래 블록을 통째로 붙여넣어 검증 실행
   python3 -m pip install --quiet jsonschema 2>/dev/null
   python3 - <<'PY'
   import json, sys
   from jsonschema import Draft202012Validator
   schema = json.load(open('/tmp/minwon.schema.json'))
   data   = json.load(open('/tmp/minwon.json'))
   errs = sorted(Draft202012Validator(schema).iter_errors(data), key=lambda e: list(e.path))
   if not errs:
       n = len(data['cases'])
       low = [c['receipt_no'] for c in data['cases'] if c['confidence'] < 0.6]
       print(f'PASS: 스키마 통과, 민원 {n}건.')
       print('저신뢰(검토 우선) 건:', low or '없음')
   else:
       print(f'FAIL: {len(errs)}개 위반')
       for e in errs[:10]:
           print(' -', list(e.path), e.message)
       sys.exit(1)
   PY

   → 결과 정상이면 'PASS: 스키마 통과, 민원 5건.'과 '저신뢰(검토 우선) 건: [...]'가 출력된다. AI가 enum 밖 값(예: priority="긴급")이나 필드 누락을 냈다면 'FAIL: N개 위반'과 함께 위반 경로(예: ['cases', 4, 'priority'])가 찍힌다 — 이때 step3로 돌아가 재생성. 이 검증기가 바로 사람↔기계 경계의 '민원창구 심사' 역할이다. 온라인 검증기 사용 시엔 'valid' 표시가 곧 PASS.

5. 5인간가독화 — 보고 요약 + 민원인 안내문 (기계출력의 인간가독화·표기)

   검증 통과한 JSON을 사람이 읽을 두 산출물로 변환한다. 아래 프롬프트를 통째로 붙여넣고, [JSON] 자리에 /tmp/minwon.json 내용(step3 출력) 전체를 붙여 넣는다. 신뢰도·출처를 문장 안에 자연스럽게 표기하고, AI생성물 고지문을 하단에 넣게 한다. 처리기한 등 미확인 수치는 지어내지 않는다.

   프롬프트 (복사해서 AI에 입력)

   ⧉ 복사

   아래 검증완료 JSON을 두 개의 사람이 읽을 문서로 변환하세요.
   
   [문서 A: 팀장 보고용 요약] (한 화면 분량)
   - 첫 줄에 총 건수, 우선순위 '상' 건수, 카테고리 분포(예: 포트홀 O·균열 O·침하 O·기타 O)를 요약.
   - 그 아래 표: 접수번호 | 위치 | 분류 | 우선순위 | 신뢰도(%) | 출처.
   - confidence 0.6 미만 건은 위치 뒤에 (담당자 재확인 필요) 표시.
   - category가 '기타'인 건은 '도로파손 아닐 수 있음'을 명시.
   
   [문서 B: 민원인 안내문] (건별, 존댓말)
   - 각 건의 citizen_notice를 다듬어 실제 발송 가능한 안내문으로.
   - 상단 제목: "[접수번호] 도로 파손 민원 처리 안내"
   - 확인 안 된 처리기한/보상 등은 절대 숫자로 지어내지 말고 "확인 후 개별 안내드리겠습니다"로.
   
   [공통] 두 문서 맨 아래에 정확히 이 고지문을 넣으세요:
   "※ 본 문서는 AI 보조로 초안 작성되었으며 담당 공무원 검토 전입니다. 개인정보는 합성 데이터입니다."
   
   [JSON]
   (여기에 /tmp/minwon.json 전체를 붙여넣기)

   → 결과 문서 A(요약: 첫 줄에 '총 5건, 우선순위 상 O건, 포트홀 O·균열 O…', 저신뢰 건에 '(담당자 재확인 필요)', 표 6열)와 문서 B(접수번호별 존댓말 안내문 5개)가 나온다. 두 문서 하단에 지정한 AI생성물·합성데이터 고지문이 그대로 붙는지, 처리기한이 '확인 후 개별 안내'로 남아 지어낸 숫자가 없는지 확인. 이 상태로 담당자 최종검토만 거치면 실제 업무 흐름에 투입 가능.