HCP 차트란 무엇인가 - HCP-DSL을 결정론적 SVG로 변환하는 MakingHCPChartSkill 사용법

1. HCP 차트란 무엇인가

HCP 차트는 처리를 계층적으로 기술하기 위한 표현입니다.
이 리포지토리에서는 다음 작성법이 필수 규칙으로 다뤄지고 있습니다.

• 왼쪽은 「무엇을 달성할지(목적)」
• 오른쪽(더 깊은 들여쓰기)은 「어떻게 달성할지(수단·상세)」
• 최상위(레벨 0)에는 목적 라벨을 쓴다

이 규칙에 따라 텍스트를 작성함으로써, 설계 의도와 구현 상세의 대응을 읽어내기 쉬워집니다.

2. 이 리포지토리가 해결하는 과제

도면만을 사람 손으로 관리하면 다음과 같은 문제가 일어나기 쉽습니다.

• 도면과 사양 텍스트가 어긋난다
• 분기나 계층의 제약이 애매해진다
• 차분 리뷰가 어렵다

MakingHCPChartSkill에서는 HCP-DSL을 JSON 리퀘스트로 건네고, hcp_render_svg.py가 검증과 묘화를 수행합니다.
같은 입력이면 같은 출력이 되므로, 도면을 CI나 리뷰에 넣기 쉬운 구성입니다.

3. 리포지토리 구성을 최단으로 파악하기

대상 리포지토리: https://github.com/gomurin0428/MakingHCPChartSkill

• hcp-chart-svg-v2/SKILL.md
  스킬의 사용법과 제약(renderAllModules와 module의 동시 지정 금지 등).
• hcp-chart-svg-v2/scripts/hcp_render_svg.py
  JSON 입력을 검증하고, HCP-DSL을 해석해 SVG 응답을 돌려주는 본체.
• hcp-chart-svg-v2/references/
  사양 레퍼런스, 샘플 request/response, 샘플 SVG.
• hcp-chart-svg-v2/scripts/hcp_xml_to_svg.py
  deprecated. 현재는 hcp_render_svg.py를 사용.

4. 10분 핸즈온(GCD 샘플)

4.1. 리포지토리를 취득한다

git clone https://github.com/gomurin0428/MakingHCPChartSkill.git
cd .\MakingHCPChartSkill

4.2. 스킬을 로컬 Codex에 배치한다

Copy-Item -Recurse -Force .\hcp-chart-svg-v2 "$HOME\.codex\skills\hcp-chart-svg-v2"

4.3. 샘플 입력으로부터 SVG 응답을 생성한다

python .\hcp-chart-svg-v2\scripts\hcp_render_svg.py `
  --input .\hcp-chart-svg-v2\references\example-gcd-request.json `
  --output .\hcp-chart-svg-v2\references\example-gcd-response.json `
  --pretty

4.4. 응답 JSON에서 SVG를 꺼낸다

$r = Get-Content -Raw .\hcp-chart-svg-v2\references\example-gcd-response.json | ConvertFrom-Json
$r.svg | Set-Content -NoNewline -Encoding utf8 .\hcp-chart-svg-v2\references\example-gcd.svg

4.5. 보충(입력 제약)

• renderAllModules=true일 때는 module을 지정할 수 없습니다.
• diagnostics에 error가 있는 경우, svg 또는 svgs는 비워집니다.

5. 샘플 2례 읽는 법

5.1. 유클리드 호제법(GCD)

• 입력 예: example-gcd-request.json
• 출력 예: example-gcd-response.json

「입력의 수취」, 「반복」, 「반환」이 계층으로 분리되어 있어, 처리의 목적과 수단을 따라가기 쉬운 구성입니다.

5.2. 수주 승인 플로우

• 입력 예: example-order-approval-request.json
• 출력 예: example-order-approval-response.json

업무 플로우에서도 fork와 true/false를 사용해 분기의 의도를 명확하게 기술할 수 있습니다.

6. 안에서 무엇을 하고 있는가(HCP 차트)

execute_request의 처리 플로우를 HCP-DSL로 표현하면 다음과 같습니다.

\module main
리퀘스트를 받고 전제를 확인한다
    입력 JSON의 필수 항목을 검증한다
DSL을 파싱해 구조화한다
    모듈과 계층을 해석한다
    diagnostics를 수집한다
진단 결과에 따라 응답 경로를 선택한다
    \fork error가 존재하는가
        \true 예
            비어 있는 SVG 계 페이로드를 돌려준다
        \false 아니오
            묘화 대상 모듈을 결정한다
            \fork renderAllModules가 true인가
                \true 예
                    모든 모듈의 SVG를 생성한다
                    svgs를 포함한 응답 JSON을 조립한다
                \false 아니오
                    단일 모듈의 SVG를 생성한다
                    svg를 포함한 응답 JSON을 조립한다
결과를 호출 측으로 돌려준다

위의 DSL을 실제로 렌더링한 도면이 이것입니다.

7. 정리

HCP 차트는 도면으로서 보기 쉬울 뿐만 아니라, 사양으로서 다룰 수 있는 형태로 관리할 수 있다는 점이 강점입니다.
MakingHCPChartSkill을 쓰면 HCP-DSL을 검증하면서 SVG까지 일관되게 생성할 수 있습니다.

다음에 시도한다면, 평소의 처리 사양을 하나 HCP-DSL로 쓰고 diagnostics를 보면서 정형해 나가면 도입 효과를 실감하기 쉽습니다.

참고 자료

• MakingHCPChartSkill
• hcp-chart-svg-v2/SKILL.md
• hcp-chart-svg-v2/scripts/hcp_render_svg.py