수정 이력(1건, 최종 수정 2026년 09월 01일)
이 글에 적용한 변경 사항의 기록입니다. 보관해 둔 수정 전 버전은 DOI가 부여된 고정 URL에서 읽을 수 있습니다.
- 일본어 원문의 완역으로 다시 번역했습니다. 기존 한국어판은 원문의 일부만 옮긴 축약본이라 절, 표, Mermaid 그림, 그림 설명, FAQ가 빠져 있었습니다. 일본어 원문에 맞춰 이들을 모두 복원했고, 기술적인 주장은 일본어판과 같습니다. 수정 전 버전 보기 (DOI: 10.5281/zenodo.21635083)
- 최초 공개
이 글을 인용하기(DOI: 10.5281/zenodo.21635082)
이 글은 Zenodo에 보관되어 있습니다. 항상 최신 버전으로 연결되는 DOI와 지금 보고 있는 버전에 고정된 DOI를 아래에 함께 제시합니다.
小村 豪 (2026). 「HCP 차트란 무엇인가 - HCP-DSL을 결정론적 SVG로 변환하는 MakingHCPChartSkill 사용법」. 합동회사 코무라소프트. https://doi.org/10.5281/zenodo.21635082 https://comcomponent.com/ko/blog/2026/02/22/000-what-is-hcp-chart-and-making-hcp-chart-skill/
- DOI(최신 버전)
- 10.5281/zenodo.21635082
- DOI(이 버전)
- 10.5281/zenodo.22217406
목차
- HCP 차트란 무엇인가
- 이 리포지토리가 해결하는 과제
- 리포지토리 구성을 최단으로 파악하기
- 10분 핸즈온(GCD 샘플)
- 샘플 2례 읽는 법
- 안에서 무엇을 하고 있는가(HCP 차트)
- 정리
HCP 차트를 「사양으로 읽을 수 있는 도면」으로 만들고 싶을 때, 손으로 그린 도면만으로는 운용이 어려워집니다.
MakingHCPChartSkill은 HCP-DSL(텍스트)을 사양에 따라 해석하고, 결정론적인 SVG(같은 입력에서는 항상 같은 SVG가 나온다는 뜻입니다)를 돌려주기 위한 스킬 리포지토리입니다.
이 글에서는 HCP 차트의 기본부터 시작해, 실제로 동작시키는 데까지를 한 번에 확인합니다.
이 글의 지식 맵
HCP 차트는 일본전신전화공사(현 NTT)의 요코스카 전기통신연구소에서 만들어진 계층적인 도법으로, MakingHCPChartSkill은 이를 텍스트로 쓰기 위한 HCP-DSL과, 이를 검증·렌더링하는 Python 스크립트 hcp_render_svg.py를 제공합니다. hcp_render_svg.py는 deprecated 상태가 된 옛 스크립트 hcp_xml_to_svg.py의 후계이며, 표준 라이브러리에만 의존하는 Python 3으로 동작하고, renderAllModules와 module은 동시에 지정할 수 없다는 제약을 가집니다. HCP-DSL의 기술에서는 최상위에 목적 라벨만 쓴다는 서술 세분성 규약이 필수 규칙으로 정해져 있습니다. OpenAI Codex 같은 코딩 에이전트는 이 스킬을 홈 디렉터리 아래의 skills 폴더로 배치함으로써 호출할 수 있습니다.
flowchart LR
accTitle: HCP 차트와 MakingHCPChartSkill의 지식 맵
accDescr: HCP 차트라는 도법과 이를 구현하는 HCP-DSL·서술 세분성 규약의 관계, MakingHCPChartSkill이 hcp_render_svg.py로 HCP-DSL을 SVG로 변환하고 옛 스크립트 hcp_xml_to_svg.py를 대체한 것, Codex로부터의 이용 형태, renderAllModules와 module 파라미터의 배타 관계를 보여주는 그림
hcp_chart["HCP 차트"]
making_hcp_chart_skill["MakingHCPChartSkill"]
hcp_dsl["HCP-DSL"]
hcp_render_svg["hcp_render_svg.py"]
hcp_xml_to_svg["hcp_xml_to_svg.py"]
description_granularity_convention["서술 수준 규칙"]
codex["Codex"]
render_all_modules_option["renderAllModules"]
module_parameter["module 파라미터"]
python["Python"]
diagnostics_output["diagnostics(진단 결과)"]
hcp_dsl -->|"구현을 담당한다"| hcp_chart
hcp_render_svg -->|"구현을 담당한다"| hcp_chart
making_hcp_chart_skill -->|"이용한다"| hcp_dsl
making_hcp_chart_skill -->|"이용한다"| hcp_render_svg
hcp_render_svg -->|"구현을 담당한다"| hcp_dsl
hcp_render_svg -->|"의 후속"| hcp_xml_to_svg
hcp_dsl -->|"전제로 한다"| description_granularity_convention
making_hcp_chart_skill -->|"전제로 한다"| description_granularity_convention
codex -.->|"이용한다"| making_hcp_chart_skill
render_all_modules_option -->|"양립하지 않는다"| module_parameter
hcp_render_svg -->|"이용한다"| render_all_modules_option
hcp_render_svg -->|"이용한다"| module_parameter
hcp_render_svg -->|"전제로 한다"| python
hcp_render_svg -->|"구현을 담당한다"| diagnostics_output
그림의 실선은 항상 성립하는 관계, 점선은 조건이 붙는 관계입니다(성립 조건은 상세 페이지의 관계별 설명에 적혀 있습니다). 관계 전체 목록(총 14건, 근거와 확신도 포함)과 주요 개념의 정의는 지식 맵 상세 페이지에 정리되어 있습니다(일본어). 데이터: JSON-LD / Turtle
1. HCP 차트란 무엇인가
HCP 차트는 처리를 계층적으로 기술하기 위한 표현입니다. 이 리포지토리에서는 다음 작성법이 필수 규칙으로 다뤄지고 있습니다.
- 왼쪽은 「무엇을 달성할지(목적)」
- 오른쪽(더 깊은 들여쓰기)은 「어떻게 달성할지(수단·상세)」
- 최상위(레벨 0)에는 목적 라벨을 쓴다
이 규칙에 따라 텍스트를 작성하면, 설계 의도와 구현 상세의 대응을 읽어내기 쉬워집니다.
flowchart TB
accTitle: HCP 차트 기술의 기본 규칙
accDescr: 최상위 레벨 0에는 목적 라벨을 쓰고, 왼쪽에 무엇을 달성할지라는 목적을, 오른쪽의 더 깊은 들여쓰기에 어떻게 달성할지라는 수단을 씀으로써 설계 의도와 구현 상세의 대응을 읽어낼 수 있다.
l0["레벨 0은 목적 라벨만"] --> goal["왼쪽은 목적(무엇을 달성할지)"]
goal --> means["오른쪽은 수단(어떻게 달성할지)"]
means -.-> effect["설계 의도와 구현 상세의 대응을 읽을 수 있다"]
그림 1: HCP 차트는 「왼쪽이 목적, 오른쪽 들여쓰기가 수단」이라는 대응으로 처리를 계층적으로 기술한다.
1.1. HCP의 유래와 다른 도법과의 차이
HCP는 Hierarchical ComPact description chart의 약자로, 일본전신전화공사(현 NTT)의 요코스카 전기통신연구소에서 만들어진 도법입니다. 즉 이 글이나 리포지토리에서 만든 조어가 아니라, 예전부터 일본에서 쓰여 온 기법입니다. 특징으로는 처리를 계층적으로 쓸 수 있다는 점, 데이터와 처리의 관계를 덧붙여 쓰기 쉽다는 점, 프리핸드로도 쓰기 쉽다는 점, 그리고 설명을 테두리 안이 아니라 기호 가까이에 두기 때문에 한 장에 많은 내용이 들어간다는 점을 들 수 있습니다.
다른 도법과 나란히 놓으면 위치가 더 잘 보입니다.
| 도법 | 구조를 나타내는 방법 | HCP 차트와의 차이 |
|---|---|---|
| 플로차트 | 처리를 상자로 나열하고 선으로 흐름을 따라간다 | 「어느 처리가 어느 처리의 상세인가」라는 계층은 나타낼 수 없습니다. 분기가 늘어나면 선이 교차하기 쉬워집니다 |
| NS 차트(구조화 차트) | 중첩된 직사각형으로 구조를 나타낸다 | 설명을 상자 안에 쓰기 때문에, 깊은 계층이나 긴 설명에서는 가로 폭이 부족해지기 쉽습니다 |
| PAD | 트리 구조로, 왼쪽에서 오른쪽으로 상세화해 간다 | 「왼쪽이 목적, 오른쪽이 수단」이라는 방향은 HCP와 비슷한 사고방식입니다. HCP는 기호가 원 중심이고, 설명을 기호 오른쪽에 붙입니다 |
그런 다음, 이 글에서 다루는 MakingHCPChartSkill 고유의 것은 표기법 자체가 아니라 다음 두 가지입니다.
- HCP 차트를 텍스트로 쓰기 위한 HCP-DSL과 그 해석 사양(
references/hcpchartspec.md) - 「레벨 0에는 목적 라벨만 쓰고, 대입이나 비교 같은 코드풍 기술은 자식 노드로 내린다」는 서술 세분성 규약. 이는 리포지토리 쪽이 필수 규칙으로 정한 것으로, HCP 차트 일반의 규칙이 아닙니다
flowchart TB
accTitle: 표기법 일반과 리포지토리 고유 부분의 구분
accDescr: HCP 차트라는 도법 자체는 요코스카 전기통신연구소에서 만들어진 기존 표기법이며, 이 리포지토리 고유의 것은 HCP-DSL과 그 해석 사양, 그리고 서술 세분성 규약 두 가지뿐이다.
general["HCP 차트(기존 도법)"] --> repo["MakingHCPChartSkill 고유 부분"]
repo --> dsl["HCP-DSL과 해석 사양"]
repo --> conv["서술 세분성 규약"]
conv -.-> rule["레벨 0은 목적 라벨만"]
그림 2: 표기법 자체는 예전부터 있던 도법이고, 이 리포지토리 고유의 것은 HCP-DSL과 서술 세분성 규약 두 가지뿐이다.
1.2. HCP-DSL 작성법(구문 요약표)
작성법의 전체상은 다음 표로 대략 충분합니다. 상세한 사양은 references/hcpchartspec.md, 요점만이라면 references/hcp-chart-schema.md에 정리되어 있습니다.
행의 종류
| 행의 형태 | 취급 |
|---|---|
| 빈 행 | 무시됩니다 |
앞머리(공백을 제외)가 #인 행 |
주석으로 무시됩니다 |
앞머리(공백을 제외)가 \ 또는 ¥인 행 |
명령행. 명령 이름은 첫 반각 스페이스까지이며, 그 이후가 인수입니다 |
| 그 밖 | 통상 처리 노드(원)로 그려집니다 |
들여쓰기(계층)
| 규칙 | 내용 |
|---|---|
| 1레벨의 단위 | 탭 1개, 또는 반각 스페이스 4개 |
| 어중간한 들여쓰기 | 스페이스 2개 같은 단위는 error가 됩니다 |
| 단숨에 깊게 하기 | 앞 행보다 2단 이상 깊게 하면 error가 됩니다. 한 단씩 내립니다 |
명령
| 명령 | 의미 | 주의 |
|---|---|---|
\title / \author / \date / \version |
헤더 정보 | \module보다 앞에 쓰면 전체 모듈 공통, 뒤에 쓰면 그 모듈만 덮어써집니다 |
\module <이름> |
모듈의 시작 | 필수. 레벨 0에서만 쓸 수 있습니다. 같은 이름 모듈은 error입니다 |
\mod <라벨> |
모듈·함수 호출 | 도면에서는 이중 원으로 그려집니다 |
\repeat <라벨> |
반복 | 반복하는 내용은 한 단 아래에 씁니다 |
\fork <라벨> |
분기(갈래 나누기)의 부모 | 분기 대상은 바로 아래에 둡니다 |
\true <라벨> / \false <라벨> |
참거짓 2분기의 가지 | \fork 바로 아래(한 단만 깊은 위치)에만 둘 수 있습니다. 조상에 \fork가 없으면 error입니다 |
\branch <조건> |
참거짓 이외의 다분기 가지 | 위와 동일 |
\return [n] |
탈출 | n은 생략 가능한 정수입니다 |
\ec <라벨> / \ex <라벨> |
오류 체크 / 오류 출구 | 현행 버전에서는 그리기만 하며, 제어의 의미는 갖지 않습니다 |
\data <이름> |
데이터 정의 | 이름에 공백과 .을 포함할 수 없습니다(포함하면 error) |
\in <이름> / \out <이름> |
입출력 데이터의 주석 | 한 단 위의 부모 노드에 대한 주석으로 취급됩니다 |
가장 단순한 예는 다음과 같습니다. \module에서 시작해, 목적을 왼쪽에, 수단을 오른쪽에 두는 것뿐입니다.
\module main
입력을 받고 전제를 확인한다
값이 양의 정수임을 확인한다
\fork 입력이 타당한가
\true 예
본처리를 실행한다
\false 아니오
오류로 호출자에게 반환한다
\return
결과를 반환한다
flowchart TB
accTitle: 최소 예시 DSL이 나타내는 처리 흐름
accDescr: module에서 시작해 입력의 전제를 확인하고, fork로 입력이 타당한지를 분기시켜, 타당하면 본처리를 실행하고 결과를 반환하며, 타당하지 않으면 오류로 호출자에게 반환하는 흐름을 나타낸다.
m["module main의 시작"] --> pre["입력을 받고 전제를 확인한다"]
pre --> fork{"입력이 타당한가"}
fork -->|"예"| main["본처리를 실행한다"]
fork -->|"아니오"| err["오류로 반환한다(return)"]
main --> ret["결과를 반환한다"]
그림 3: 최소 예시의 흐름. module에서 시작해 목적을 왼쪽에 두고, fork 바로 아래에 true와 false 분기를 나란히 놓는다.
2. 이 리포지토리가 해결하는 과제
도면만을 사람 손으로 관리하면 다음과 같은 문제가 일어나기 쉽습니다.
- 도면과 사양 텍스트가 어긋난다
- 분기나 계층의 제약이 애매해진다
- 차분 리뷰가 어렵다
MakingHCPChartSkill에서는 HCP-DSL을 JSON 리퀘스트로 건네고, hcp_render_svg.py가 검증과 묘화를 수행합니다.
같은 입력이면 같은 출력이 되므로, 도면을 CI나 리뷰에 넣기 쉬운 구성입니다.
flowchart TB
accTitle: 손으로 그린 도면의 과제와 텍스트 관리에 의한 해결
accDescr: 도면만을 사람 손으로 관리하면 사양 텍스트와의 어긋남이나 차분 리뷰의 어려움이 생기는 데 비해, HCP-DSL을 JSON 리퀘스트로 건네면 hcp_render_svg.py가 검증과 묘화를 수행하고, 같은 입력에서는 같은 SVG를 얻을 수 있다.
hand["도면만을 사람 손으로 관리"] -.-> issue["어긋남·애매함·차분 리뷰 곤란"]
dsl["HCP-DSL을 JSON 리퀘스트로 전달"] --> render["hcp_render_svg.py가 검증과 묘화"]
render --> svg["결정론적인 SVG가 반환된다"]
svg --> ci["CI나 리뷰에 넣을 수 있다"]
그림 4: 도면을 손으로 그리는 대신 텍스트인 HCP-DSL로부터 결정론적으로 SVG를 생성하므로, 차분 리뷰나 CI에 실을 수 있다.
3. 리포지토리 구성을 최단으로 파악하기
대상 리포지토리: https://github.com/gomurin0428/MakingHCPChartSkill
hcp-chart-svg-v2/SKILL.md스킬의 사용법과 제약(renderAllModules와module의 동시 지정 금지 등).hcp-chart-svg-v2/scripts/hcp_render_svg.pyJSON 입력을 검증하고, HCP-DSL을 해석해 SVG 응답을 돌려주는 본체.hcp-chart-svg-v2/references/사양 레퍼런스, 샘플 request/response, 샘플 SVG.hcp-chart-svg-v2/scripts/hcp_xml_to_svg.pydeprecated. 현재는hcp_render_svg.py를 사용.
flowchart TB
accTitle: 리포지토리의 주요 파일 구성
accDescr: hcp-chart-svg-v2 아래에 스킬의 사용법과 제약을 적은 SKILL.md, 본체 스크립트 hcp_render_svg.py, 사양 레퍼런스와 샘플을 담은 references가 있으며, 옛 스크립트 hcp_xml_to_svg.py는 deprecated 상태이다.
root["hcp-chart-svg-v2"] --> skill["SKILL.md(사용법과 제약)"]
root --> script["scripts 아래의 hcp_render_svg.py"]
root --> refs["references(사양과 샘플)"]
script -.-> old["hcp_xml_to_svg.py는 deprecated"]
그림 5: 입구는 SKILL.md, 본체는 hcp_render_svg.py, 사양과 샘플은 references 아래에 정리되어 있다.
4. 10분 핸즈온(GCD 샘플)
전제 환경
| 항목 | 내용 |
|---|---|
| Python | hcp_render_svg.py는 Python 3으로 실행합니다. 리포지토리에 최소 버전이 명시되어 있지는 않지만, dataclasses와 from __future__ import annotations를 사용하고 있으므로 3.7 이후라면 동작합니다 |
| 추가 패키지 | 필요 없습니다. 사용하고 있는 것은 argparse / json / logging / math / re / sys / dataclasses / pathlib / typing / xml.sax.saxutils로, 모두 표준 라이브러리입니다 |
| 셸 | 아래 명령어는 Windows의 PowerShell을 전제로 작성했습니다. 문자가 깨지는 경우, 실행 전에 $env:PYTHONUTF8 = "1"과 chcp 65001로 UTF-8을 명시해 주세요 |
| Codex | 4.2에서 스킬로 배치할 경우에만 필요합니다. Codex를 사용하지 않는다면 4.2는 건너뛰어도 됩니다(4.3 이후는 스크립트 단독으로 동작합니다) |
4.1. 리포지토리를 취득한다
git clone https://github.com/gomurin0428/MakingHCPChartSkill.git
cd .\MakingHCPChartSkill
4.2. 스킬을 로컬 Codex에 배치한다
여기서 말하는 Codex는 OpenAI의 코딩 에이전트를 가리킵니다. $HOME\.codex(Windows라면 C:\Users\<사용자명>\.codex)가 그 설정 디렉터리이며, 리포지토리의 README에서는 그 아래의 skills\<스킬명>으로 디렉터리째 복사하는 절차가 안내되어 있습니다. 이렇게 해 두면, 에이전트에게 「HCP 차트를 그려줘」라고 부탁했을 때 이 SKILL.md의 절차대로 렌더러를 호출해 줍니다.
Copy-Item -Recurse -Force .\hcp-chart-svg-v2 "$HOME\.codex\skills\hcp-chart-svg-v2"
이 절차는 필수가 아닙니다. 렌더러는 --input과 --output을 받는 단독 스크립트이므로, Codex를 사용하지 않는 분은 4.3으로 진행해 주세요.
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
flowchart TB
accTitle: 핸즈온에서 SVG를 얻기까지의 흐름
accDescr: 샘플 리퀘스트 JSON을 hcp_render_svg.py에 건네 응답 JSON을 생성하고, 그 svg 속성을 꺼내 SVG 파일로 저장하기까지의 일련의 흐름을 나타낸다.
req["샘플 리퀘스트 JSON"] --> py["hcp_render_svg.py를 실행"]
py --> res["응답 JSON이 출력된다"]
res --> ext["svg 속성을 꺼낸다"]
ext --> file["SVG 파일로 저장"]
그림 6: 핸즈온의 흐름. 리퀘스트 JSON을 스크립트에 건네고, 응답의 svg를 파일로 써낸다.
4.5. 보충(입력 제약)
renderAllModules=true일 때는module을 지정할 수 없습니다.diagnostics에error가 있는 경우,svg또는svgs는 비워집니다.
5. 샘플 2례 읽는 법
도면을 열었을 때, 다음 순서로 시선을 옮기면 읽을 수 있습니다.
- 맨 왼쪽 열만 위에서 아래로 읽는다. 여기에 나열된 것이 「무엇을 달성할지(목적)」이며, 처리 전체의 줄거리가 됩니다
- 눈에 띈 행에서 오른쪽으로 따라간다. 오른쪽 들여쓰기에 나열된 것이, 그 목적을 「어떻게 달성할지(수단·상세)」입니다
- 세로선(줄기)으로 부모·자식을 확인한다. 줄기는 같은 깊이의 처리를 이어 주며, 깊이가 얕은 행을 뚫고 지나가지 않도록 그려집니다
flowchart TB
accTitle: HCP 차트를 읽을 때 시선을 옮기는 방법
accDescr: 먼저 왼쪽 끝의 열을 위에서 아래로 읽어 처리 전체의 줄거리를 파악하고, 눈에 띈 행에서 오른쪽으로 따라가 수단과 상세를 확인하며, 세로선인 줄기로 부모자식 관계를 확인한다는 3단계의 읽는 법을 나타낸다.
s1["왼쪽 끝 열을 위에서 아래로 읽는다"] --> a1["처리 전체의 줄거리를 파악한다"]
a1 --> s2["눈에 띈 행에서 오른쪽으로 따라간다"]
s2 --> a2["수단·상세를 확인한다"]
a2 --> s3["세로선(줄기)으로 부모자식을 확인한다"]
그림 7: 먼저 왼쪽 끝의 목적 열에서 줄거리를 파악하고, 필요한 행만 오른쪽 수단으로 내려가는 것이 읽는 법의 기본이다.
기호의 의미는 다음과 같습니다.
| 기호 | 의미 |
|---|---|
| ○(원) | 통상 처리 |
| 이중 원 | 모듈·함수 호출(\mod) |
| ○ 안에 순환 화살표 | 반복(\repeat) |
| ○ 안에 오른쪽 방향 삼각형 | 분기의 부모(\fork) |
| 줄기에서 오른쪽으로 나가는 화살표 | 분기의 가지(\branch / \true / \false). 화살표 오른쪽에 조건이 적힙니다 |
| 아래 방향 삼각형 | 탈출(\return) |
| ○ 안에 × | 오류 체크(\ec) |
| 작은 원 2개 | 오류 출구(\ex) |
5.1. 유클리드 호제법(GCD)
- 입력 예:
example-gcd-request.json - 출력 예:
example-gcd-response.json
「입력의 수취」, 「반복」, 「반환」이 계층으로 분리되어 있어, 처리의 목적과 수단을 따라가기 쉬운 구성입니다.
왼쪽 끝 열만 읽으면 「입력값을 받아 계산 준비를 한다 → 나머지가 남아 있는 동안 최대공약수에 다가간다 → 결과를 이용자에게 반환한다」의 3행으로, 이것만으로도 알고리즘의 줄거리를 알 수 있습니다. r <- a mod b 같은 구체적인 계산은 반복 안쪽의 「다음으로 넘겨줄 값을 정한다」에서 다시 오른쪽 들여쓰기로 내려가 있습니다. 이 위치 관계가 바로 「목적(왼쪽)과 수단(오른쪽)」의 대응입니다. 왼쪽 끝에 갑자기 r <- a mod b가 나온다면, 서술 세분성 규약(1.1)을 위반했다는 신호입니다.
flowchart TB
accTitle: GCD 샘플의 왼쪽 끝 열이 보여주는 줄거리
accDescr: GCD 샘플의 왼쪽 끝 열은 입력값을 받아 계산 준비를 한다, 나머지가 남아 있는 동안 최대공약수에 다가간다, 결과를 이용자에게 반환한다의 3행이며, 구체적인 계산은 다시 오른쪽 들여쓰기로 내려가 있다.
g1["입력값을 받아 준비를 한다"] --> g2["나머지가 남아 있는 동안 다가간다"]
g2 --> g3["결과를 이용자에게 반환한다"]
g2 -.-> d1["구체적인 계산은 다시 오른쪽 계층으로"]
그림 8: GCD 샘플의 왼쪽 끝 열. 3행만으로 알고리즘의 줄거리를 알 수 있고, 계산의 상세는 오른쪽으로 내려간다.
도면 상단의 Data: 행과, 노드 아래에 붙는 in: / out: 주석도 읽는 법의 실마리입니다. 이 도면에서는 in: a, b와 out: a가 붙어 있어, 어디가 입구이고 어디가 출구인지 도면만으로 알 수 있습니다.
5.2. 수주 승인 플로우
- 입력 예:
example-order-approval-request.json - 출력 예:
example-order-approval-response.json
업무 플로우에서도 fork와 true/false를 사용해 분기의 의도를 명확하게 기술할 수 있습니다.
이쪽도 왼쪽 끝 열은 「수주 내용을 접수한다 → 출하 가부를 판정한다 → 처리 결과를 반환한다」의 3행뿐입니다. 재고 조회, 승인 신청, 출하 등록 같은 구현에 가까운 조작은 모두 오른쪽 들여쓰기에 들어가 있습니다. 분기는 줄기에서 오른쪽으로 나가는 화살표로, (예) / (아니오) 아래에 각각의 처리가 매달리는 형태입니다. 「결품이면 반려, 승인 완료면 출하 준비, 그렇지 않으면 보류」라는 업무 판단이, 두 곳의 분기에서 나오는 화살표를 따라가는 것만으로 파악됩니다.
flowchart TB
accTitle: 수주 승인 샘플의 업무 판단 분기
accDescr: 수주 내용을 접수해 출하 가부를 판정하고, 결품이면 반려, 승인 완료면 출하 준비, 그렇지 않으면 보류라는 업무 판단이 두 곳의 분기로 표현되어 있음을 나타낸다.
o1["수주 내용을 접수한다"] --> o2["출하 가부를 판정한다"]
o2 --> f1{"결품인가"}
f1 -->|"예"| back["반려"]
f1 -->|"아니오"| f2{"승인 완료인가"}
f2 -->|"예"| ship["출하 준비"]
f2 -->|"아니오"| hold["보류"]
그림 9: 수주 승인 샘플의 업무 판단. 두 곳의 분기를 따라가는 것만으로 반려·출하 준비·보류의 행선지를 파악할 수 있다.
업무 사양 리뷰에서는 이 왼쪽 끝 열을 관계자와 함께 맞춰 읽고, 오른쪽의 상세는 구현 담당자와 조율하는 식의 역할 분담이 쉬워집니다.
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를 보면서 정형해 나가면 도입 효과를 실감하기 쉽습니다.
참고 자료
관련 기사
같은 태그를 공유하는 최신 기사입니다. 더 가까운 주제로 지식을 넓힐 수 있습니다.
멀티스레드 실무 베스트 프랙티스 Java 편 ── 가상 스레드 시대의 정석
Java의 멀티스레드는 스레드를 직접 만들지 않고 ExecutorService와 가상 스레드에 올라타는 것이 정석입니다. synchronized와 ReentrantLock의 구분, 인터럽트에 의한 협조적 정지, ConcurrentHashMap의 ...
멀티스레드 실무 베스트 프랙티스 C 언어 편 ── Win32 API의 방식으로 안전하게 작성하기
C 언어 × Win32의 멀티스레드는 _beginthreadex를 이용한 스레드 생성, SRW 잠금과 조건 변수, Interlocked, 정지 이벤트+WaitForMultipleObjects의 정지 설계가 정석입니다. TerminateThread...
멀티스레드 실무 베스트 프랙티스 C++ 편 ── RAII와 jthread로 사고를 구조적으로 없애기
C++의 멀티스레드는 데이터 경쟁이 미정의 동작이 되는 세계입니다. std::thread 소멸자의 함정, jthread와 stop_token에 의한 정지 설계, scoped_lock의 데드락 회피, atomic의 올바른 위치, Win32 동기화 ...
멀티스레드 실무 베스트 프랙티스 .NET 편 ── 스레드를 늘리기 전에 정해둘 것
「스레드를 만들면 가끔 죽거나 멈춘다」를 막는 설계의 정석을 .NET/C# 대상으로 정리합니다. 스레드를 직접 만들지 않고 Task에 올라타기, 공유 가변 상태 줄이기, 락의 규율, CancellationToken을 통한 정지 설계, UI 스레드...
QR코드 판독값을 그대로 사용해서는 안 된다 ── 오류 정정이 통과해도 값은 보장되지 않는다
QR코드의 오류 정정은 정정이 통과한다고 해서 값이 올바르다고 보장하는 구조가 아닙니다. 샘플 이미지와 두 종류의 디코더를 이용한 실측을 바탕으로, 손상이 발생하는 위치에 따라 다른 값으로 읽혀 버리는 이유와 업무 시스템 측에 필요한 검증을 설명...
관련 토픽
이 기사와 가까운 토픽 페이지입니다. 기사를 출발점 삼아 관련 서비스와 다른 기사로 이어집니다.
Windows 기술 토픽
Windows 개발, 장애 조사, 기존 자산 활용에 관한 KomuraSoft LLC 기사를 모은 토픽 허브입니다.
이 주제와 연결되는 서비스
이 기사는 다음 서비스 페이지로 이어집니다. 가까운 입구부터 확인해 주세요.
기술 상담 & 설계 리뷰
설계 방향, 아키텍처 경계, 수명 관리, 기존 Windows 자산 처리 방법을 정리하는 데 도움을 드립니다.
자주 묻는 질문
이 기사 주제에 대해 상담 시 자주 나오는 질문을 모았습니다.
- HCP 차트란 무엇인가요?
- 처리를 계층적으로 기술하기 위한 표현입니다. 왼쪽에는 「무엇을 달성할지(목적)」를 쓰고, 오른쪽의 더 깊은 들여쓰기에는 「어떻게 달성할지(수단·상세)」를 쓰며, 최상위(레벨 0)에는 목적 라벨을 씁니다. 이 규칙에 따라 텍스트를 작성하면 설계 의도와 구현 상세의 대응을 읽어내기 쉬워집니다.
- MakingHCPChartSkill은 무엇을 하는 도구인가요?
- HCP-DSL(텍스트)을 사양에 따라 해석하고 결정론적인 SVG를 돌려주기 위한 스킬 리포지토리입니다. HCP-DSL을 JSON 리퀘스트로 건네면 hcp_render_svg.py가 검증과 묘화를 수행합니다. 같은 입력이면 같은 출력이 되므로, 도면을 CI나 리뷰에 넣기 쉬운 구성입니다.
- 도면을 손으로 관리하는 경우와 무엇이 다른가요?
- 도면만을 사람 손으로 관리하면 도면과 사양 텍스트가 어긋나거나, 분기나 계층의 제약이 애매해지거나, 차분 리뷰가 어려워지는 문제가 일어나기 쉽습니다. HCP-DSL이라는 텍스트로부터 결정론적으로 SVG를 생성하는 방식이라면, 도면을 사양으로서 다룰 수 있는 형태로 관리할 수 있고, diagnostics를 보면서 정형해 나갈 수 있습니다.
- 사용할 때 제약이 있나요?
- renderAllModules=true일 때는 module을 동시에 지정할 수 없습니다. 또한 diagnostics에 error가 있는 경우, svg 또는 svgs는 비워집니다. 스크립트는 hcp_xml_to_svg.py가 deprecated 상태이며, 현재는 hcp_render_svg.py를 사용합니다.