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

관련 기사

같은 태그를 공유하는 최신 기사입니다. 더 가까운 주제로 지식을 넓힐 수 있습니다.

관련 토픽

이 기사와 가까운 토픽 페이지입니다. 기사를 출발점 삼아 관련 서비스와 다른 기사로 이어집니다.

이 주제와 연결되는 서비스

이 기사는 다음 서비스 페이지로 이어집니다. 가까운 입구부터 확인해 주세요.

자주 묻는 질문

이 기사 주제에 대해 상담 시 자주 나오는 질문을 모았습니다.

HCP 차트란 무엇인가요?

HCP 차트는 처리를 계층적으로 기술하기 위한 표현입니다. 왼쪽에는 무엇을 달성할지(목적)를, 오른쪽의 더 깊은 들여쓰기에는 어떻게 달성할지(수단·상세)를 쓰고, 최상위(레벨 0)에는 목적 라벨을 씁니다. 이 규칙에 따라 텍스트를 작성하면 설계 의도와 구현 상세의 대응을 읽어내기 쉬워집니다.

MakingHCPChartSkill은 어떤 문제를 해결하나요?

도면만을 사람 손으로 관리하면 도면과 사양 텍스트가 어긋나거나, 분기나 계층의 제약이 애매해지거나, 차분 리뷰가 어려워지는 문제가 일어나기 쉽습니다. MakingHCPChartSkill에서는 HCP-DSL을 JSON 리퀘스트로 건네고 hcp_render_svg.py가 검증과 묘화를 수행합니다. 같은 입력이면 같은 출력이 되는 결정론적 구성이라 도면을 CI나 리뷰에 넣기 쉽습니다.

HCP-DSL에서 SVG를 생성하려면 어떻게 하나요?

GitHub의 MakingHCPChartSkill 리포지토리를 클론하고 hcp-chart-svg-v2 스킬을 배치한 뒤, hcp_render_svg.py에 --input으로 리퀘스트 JSON을, --output으로 출력 경로를 지정해 실행합니다. 응답 JSON의 svg 필드에서 SVG를 꺼내 파일로 저장하면 됩니다. renderAllModules=true일 때는 module을 동시에 지정할 수 없고, diagnostics에 error가 있으면 svg는 비워집니다.

HCP 차트를 도입하면 어떤 장점이 있나요?

HCP 차트는 도면으로서 보기 쉬울 뿐 아니라 사양으로서 다룰 수 있는 형태로 관리할 수 있다는 점이 강점입니다. 검증과 묘화가 자동화되어 있어 HCP-DSL을 검증하면서 SVG까지 일관되게 생성할 수 있습니다. 처음 시도한다면 평소의 처리 사양을 하나 HCP-DSL로 쓰고 diagnostics를 보면서 정형해 나가면 도입 효과를 실감하기 쉽습니다.

저자 프로필

기사 저자의 프로필 페이지입니다.

Go Komura

합동회사 코무라소프트 대표

Windows 소프트웨어 개발, 기술 상담, 장애 조사를 중심으로 재현이 어려운 장애 조사와 기존 자산이 남아 있는 프로젝트에 강점이 있습니다.