SP 작성 방법론

1. 이 문서의 목적

SP 평가 방법론이 "이미 쓰인 SP가 얼마나 잘 되어 있는가"를 재는 잣대라면, 이 문서는 "새 SP를 쓸 때 무엇을 지켜야 그 잣대에서 높은 점수를 받을 수 있는가"를 규정한다. 혼디의 SP는 한 장짜리 독립 문서가 아니라, 2,011개가 상속·참조·데이터 공백 로그로 서로 얽혀 있는 하나의 트리다. 이 문서는 그 트리 구조와 SP끼리 주고받는 실제 메커니즘(SP-TREE-REGISTRY, GOV-TREE-PROTOCOL, GWP 레지스트리 등)을 근거로, SP 작성자가 지켜야 할 규칙을 정리한 것이지 새로운 원칙을 발명한 것이 아니다.

2. 최우선 원칙 — 목적 실현이 먼저다

모든 SP는 자신이 대표하는 대상의 목적을 실현하는 것이 존재 이유다. 의사 SP는 의사의 목적(환자의 증상을 듣고 의학적 판단을 돕는 것)을, 변호사 SP는 변호사의 목적(의뢰인을 위한 법률 자문·대리)을, 법무부 SP는 법무부의 목적(법무 행정 집행)을, 법원 SP는 법원의 목적(중립적 재판)을 달성하는 데 초점을 둔다. 이 원칙은 기관·부서·직책·개인을 가리지 않고 동일하게 적용된다 — 어느 부서의 SP든, 어느 직책의 SP든, 심지어 한 개인을 대표하는 SP든, 그 대상이 실제로 수행하는 일을 정확히 실현하도록 기능을 설계·구현하는 것이 먼저다. K-Law가 "가상판결 시뮬레이션"이라는 사법부의 목적에 맞춰 공리 체계를 설계했듯, STEPI SP가 "정책연구기관 안내"라는 자신의 목적에 맞춰 입출력 스키마를 설계했듯이, 모든 SP는 이 순서를 따른다: 먼저 이 대상이 무엇을 하는 존재인지 규정하고, 그 다음 그 목적을 실현할 기능을 설계·구현한다.

그러나 이 목적 실현은 혼자 이루어지지 않는다. 목적에 맞는 기능을 설계·구현할 때는 반드시 상위 SP의 상속(3장)과 다른 SP와의 소통 메커니즘(4장)을 함께 고려해야 한다. 자신의 목적 달성에만 매몰되어 상위 SP가 이미 정의한 원칙을 다시 정의하거나, 데이터 공백 로그·체인 조립 태그 같은 SP 간 소통 규약을 무시하면 그 SP 하나는 목적을 달성한 것처럼 보여도 SP 트리 전체의 일관성이 깨진다. 정리하면 —

• 무엇을 해야 하는가는 그 SP가 대표하는 기관·부서·직책·개인 자신의 목적이 결정한다.
• 그것을 SP 트리 안에서 어떻게 안전하게 구현하는가는 계층 상속 원칙(3장)과 SP 간 소통 메커니즘(4장)이 결정한다.

이 두 축은 어느 한쪽만으로는 완성되지 않으며, 새 SP를 쓰거나 고칠 때 항상 함께 적용한다.

3. 계층 원칙 — 상위 SP를 상속하는 법

2-1. 단일출처원칙 — 같은 규정을 두 곳에 쓰지 않는다

상위 SP가 이미 정의한 원칙·기준·절차를 하위 SP가 다시 풀어쓰지 않는다. 동일 내용이 두 곳에 있으면 더 상위·일반적인 위치가 단일 출처가 되고, 나머지는 참조로 대체한다. 실제로 도(道) 트리는 "정직성·능동적 역량·요청처리 파이프라인" 같은 원칙을 독자 정의했다가, kgov(K-Public)가 이미 같은 개념을 공리 체계로 더 정교하게 정의해두었다는 것이 드러나 폐기되고 다시 쓰인 전례가 있다. 새 SP를 쓰기 전에 상위 SP(들)를 먼저 읽고, 이미 정의된 개념을 다시 정의하고 있지 않은지 확인한다.

2-2. 상위 원칙을 재정의·완화하지 않는다

하위 SP는 상위 SP의 원칙에 추가할 수는 있어도, 그것을 약화시키거나 다시 정의할 수 없다. 도 트리 계열 문서들은 "정체성·활성화조건·법적지위고지·정직성·요청처리절차·PDV동의·위험등급 에스컬레이션의 원칙 그 자체는 kgov의 서문·공리·STEP을 그대로 따른다. 이 문서와 하위 트리 전체는 이를 재정의하거나 완화하지 않는다"라고 스스로 명시한다. 새 SP도 이 원칙을 따른다 — 상위가 이미 강하게 규정한 것을 하위에서 느슨하게 다시 쓰면 안 된다.

2-3. 상속 선언 헤더를 명시하고, 이름만 쓰고 버전은 쓰지 않는다

모든 SP는 헤더에 # 상위 상속 항목으로 자신이 무엇을 상속하는지 선언한다. 다른 SP를 본문에서 언급할 때는 이름만 쓰고 버전 번호는 절대 적지 않는다(예: K-Public_common(SP-TREE-REGISTRY 참조)). 버전이 바뀔 때마다 참조하는 쪽 전부를 손으로 찾아 고쳐야 하는 문제가 2026-07-29 감사에서 16개 파일·33건 발견된 바 있다. 최신 버전이 필요하면 사람은 SP-TREE-REGISTRY_v1_0.md(관계 정보)를, 코드/런타임은 prompts/sp-catalog.json(이름→최신 파일명 매핑)을 본다.

kgov(SP-10_kpublic, 전국 공통) → <PROVINCE>-GOV-COMMON-OVERLAY(도별 사실)
  → GOV-TREE-PROTOCOL(다단 체인 기술 프로토콜) → DO-SP → { L2 | L3 | L4 }

새로운 상속 관계가 생기면 SP-TREE-REGISTRY_v1_0.md의 F 섹션(CHILD_PATTERN -> PARENT_NAME 형식의 edges 블록)에 반드시 줄을 추가한다 — 이 파일을 갱신하지 않으면 CI(check_no_undeclared_inheritance.py)가 관계를 인식하지 못한다.

2-4. 형제 관계와 부모-자식 관계를 구분해서 선언한다

같은 부모를 상속한다고 해서 자동으로 서로 부모-자식은 아니다. 예를 들어 국세청·관세청 등 7개 기관은 SP-NAT-POLICY-{CODE}(전국 단일 본청)와 SP-NAT-{NAME}-TEMPLATE(도별 지사)가 둘 다 kgov를 직접 상속하는 형제 관계이며, 어느 쪽이 응답할지는 발화 성격(정책 문의 vs 접수·처리)으로 갈린다. 이런 관계를 만들 때는 "A가 B를 상속한다"인지 "A와 B가 같은 부모의 형제다"인지를 SP 헤더와 SP-TREE-REGISTRY 양쪽에 명확히 구분해서 적는다.

2-5. 자동검증이 가능하도록 필수 공통 섹션을 유지한다

kgov를 상속하는 기관 SP는 최소한 다음 섹션을 갖춰야 CI(check_sp_inheritance.py)의 자동 검증을 통과한다. 이 섹션 이름과 순서를 임의로 바꾸지 않는다.

섹션	내용
§LEGAL-BASIS	페르소나 유형, 설립·운영 근거 법령, 출처와 검증일
§1	기관 정체성 및 조직 개요, disclaimer
§CAPABILITIES	할 수 있는 일과 수행 방식(직접 수행 / 안내만 수행)
§5	유의사항 — 미검증 항목·초안 여부 등 한계 고지

4. SP 간 소통 메커니즘을 반영하는 법

3-1. 데이터 공백은 구조화된 로그로 남긴다 (DATA_REQUIREMENT / GAP_LOG)

SP가 다수로 쪼개져 서로 데이터를 주고받는 구조(도 트리 등)에서는, "이 정보가 왜 없는지"를 사람이 읽는 산문이 아니라 다른 SP·라우터가 기계적으로 읽을 수 있는 표로 선언한다. 원인은 두 가지로 나뉜다.

Type	의미
no_internal_data	애초에 이 기관 소관이 아니어서 데이터가 없음
no_interagency_access	데이터는 있지만 기관 간 연동이 안 되어 있음

STEPI SP의 §3. DATA_REQUIREMENT 선언이 이 형식을 따른 실제 사례다 — field / owner_agency / connected / unavailable_reason / fallback 열로 데이터 공백을 구조화했다. 새 SP도 "모른다"고 말할 때 이 표 형식을 따른다.

3-2. 다단 체인은 라우터가 읽을 수 있는 태그 문법으로 조립한다

SP가 여러 단계(도 → 부서 → 세부기관 등)로 이어질 때는 사람이 산문으로 설명하는 대신, 라우터가 파싱 가능한 태그로 체인 순서를 명시한다(예: [JEJU_CHAIN: SP-DO-000 > {L2코드} > {L3코드}? > {L4코드}?]). 이 태그는 어떤 단계가 고정이고 어떤 단계가 가변인지도 함께 규정해야, 라우터 코드와 SP 문서가 서로 다른 이해를 갖지 않는다.

3-3. 실행형 서비스는 GWP 레지스트리에 등록하고, URL을 하드코딩하지 않는다

사용자가 실제로 호출하는 SP(긴급신고, 전문가 상담 등)는 gwp-registry.js에 type(inline/tab/tool), sp_key, threshold(매칭 임계값)로 등록한다. SP 파일의 실제 경로(sp_url)는 직접 적지 않고, 빌드 시 자동 생성되는 prompts/sp-catalog.json을 런타임에 조회해 채운다(resolveSpUrls()) — 파일명이 바뀔 때마다 등록 코드를 손으로 고치다 깨지는 사고(SP-16_kinsurance 사례)를 막기 위해서다.

3-4. 개인정보가 SP 경계를 넘을 때는 PDV 프로토콜을 그대로 따른다

개인정보(PDV)가 한 SP에서 다른 SP·다른 origin(탭)으로 이동해야 하는 경우, 그 SP가 새로 동의 절차를 발명하지 않는다. 같은 origin 안이면 kgov의 STEP 0-γ PDV 동의로 충분하고, 별도 origin(예: jeju.hondi.net처럼 새 탭으로 뜨는 서비스)이면 PDV-TRANSFER-PROTOCOL이 정의하는 window.opener 기반 탭 간 중개를 그대로 참조한다.

3-5. 안전장치는 재발명하지 않고 공통 게이트를 상속한다

민감정보 감지, 사용자 등급 분기, 위험 신호 태깅 같은 안전 로직은 각 SP가 새로 설계하지 않는다. SP_common_guardrails(사용자 등급 분기 C30~C34)와 SP_red_flag_registry (민감정보 태깅 정책)를 참조하기만 한다. 전문가 페르소나 SP 63개 전원이 이 원칙을 따른다.

5. 실행 규율 — 위험도에 맞춘 강제절차

K-Law류의 강제규칙·게이트웨이·확신도 출력 의무는 사법·의료·세무처럼 판단 오류의 대가가 큰 고위험 SP에 요구되는 수준이다. STEPI 같은 단순 안내형 SP까지 25개 강제규칙을 전부 이식할 필요는 없다. 그러나 SP의 위험도와 무관하게 다음 최소선은 모든 SP가 지킨다 — 이는 SP 평가 방법론의 "예외·경계상황 처리"· "자기검증 장치" 기준에서 낮은 SP일수록 확인해야 할 항목이다.

• 확신할 수 없는 사실은 확정적으로 말하지 않고 "미확인"으로 남긴다.
• 유사 기관·유사 SP와 혼동될 수 있는 지점을 최소 한 줄로 구분해 둔다.
• 범위 밖 요청이 들어왔을 때 침묵하거나 임의로 답하지 않고, 어디로 안내할지 명시한다.

6. 버전 관리·정직성 규율

• 버전 표기 — 파일명과 헤더에 v메이저.마이너를 일치시킨다.
• 개정이력 — 무엇이·왜 바뀌었는지 최소 한 줄을 남긴다. 폐기된 이전 버전은 사유를 명시하고 prompts/archive/로 옮긴다(K-Law v1.0의 처리 방식을 따른다).
• 정직성 — 초안이거나 미검증 항목이 있으면 숨기지 않고 §5(유의사항)에 명시한다. "TBD"로 남기는 것이 틀린 정보를 확정적으로 적는 것보다 낫다.

7. CI가 기계적으로 강제하는 것들

아래 도구들은 사람이 매번 검사하지 않아도 위반을 잡아낸다. 새 SP를 작성했다면 이 검증을 통과하는지 미리 확인한다.

도구	강제하는 것
check_no_hardcoded_sp_refs.py	다른 SP를 "이름_버전" 형태로 하드코딩하면 빌드 실패(변경이력 섹션 제외)
check_sp_inheritance.py	AGENT-SUPPLIER·SP-INDUSTRY-TRANSFORM·kgov 3개 공식 패밀리의 상속 선언·필수 섹션·복붙 여부 검증
check_no_undeclared_inheritance.py	SP-TREE-REGISTRY의 edges 블록에 없는 상속 관계를 "관습적으로" 만들지 못하게 차단
build_manifest.py	새 SP가 sp-catalog.json에서 누락되지 않도록 자기검증

prompts/gov-tree/ 하위(도청·부서 등)는 아직 informational 등급으로만 검증된다 — 헤더 형식이 파일마다 제각각이라 strict 적용 시 오탐이 나기 때문이다. 이 구간에 새 SP를 쓸 때는 특히 헤더 형식(# 상위 상속 문구)을 기존 파일과 통일해서 향후 strict 전환에 방해가 되지 않게 한다.

8. 작성 전 체크리스트

• 이 SP가 대표하는 기관·부서·직책·개인의 실제 목적이 무엇인지 먼저 규정했는가, 그리고 그 목적을 실현하는 기능을 설계했는가?
• 상위 SP(들)를 읽고, 이미 정의된 원칙을 다시 쓰고 있지 않은가?
• 헤더에 # 상위 상속 체인을 명시했는가?
• 다른 SP를 언급할 때 이름만 쓰고 버전 번호를 적지 않았는가?
• 새 상속/참조 관계를 SP-TREE-REGISTRY_v1_0.md의 edges 블록에 추가했는가?
• 형제 관계와 부모-자식 관계를 헷갈리지 않고 구분해 선언했는가?
• §LEGAL-BASIS·§1·§CAPABILITIES·§5 필수 섹션을 갖췄는가(kgov 계열인 경우)?
• 데이터 공백이 있다면 owner_agency / connected / unavailable_reason / fallback 표로 선언했는가?
• 실행형 서비스라면 GWP 레지스트리에 sp_key로 등록하고 URL을 하드코딩하지 않았는가?
• 안전 로직을 새로 만들지 않고 SP_common_guardrails/SP_red_flag_registry를 참조했는가?
• 미확인 사실을 확정적으로 적지 않고 정직하게 표시했는가?
• 버전과 개정이력을 기록했는가?

9. 변경 이력