수정 이력(6건, 최종 수정 2026년 09월 03일)
이 글에 적용한 변경 사항의 기록입니다. 보관해 둔 수정 전 버전은 DOI가 부여된 고정 URL에서 읽을 수 있습니다.
- permalink·저자 표기·지식 맵 래퍼·깨진 내부 링크 등 CI가 지적한 표시용 수정을 반영했습니다. 본문의 기술적인 주장은 바꾸지 않았습니다.
- 일본어 원문의 완역으로 다시 번역했습니다. 기존 한국어판은 원문의 일부만 옮긴 축약본이라 절, 표, Mermaid 그림, 그림 설명, FAQ가 빠져 있었습니다. 일본어 원문에 맞춰 이들을 모두 복원했고, 기술적인 주장은 일본어판과 같습니다. 수정 전 버전 보기 (DOI: 10.5281/zenodo.21635083)
- 본문의 흐름·구조를 그림으로도 따라갈 수 있도록 Mermaid 그림을 9개 추가했습니다(본문 500〜750자당 1그림 규약에 맞춘 것입니다). 본문 문장은 바꾸지 않았습니다.
- 글 맨 앞에 「이 글의 지식 맵」 절을 추가했습니다. 본문에서 다루는 개념과 그 관계를 요약·그림·상세 페이지 링크로 정리한 것입니다. 본문의 주장은 바꾸지 않았습니다.
- 외부 리뷰(1283건)에 대한 대응으로 본문을 업데이트했습니다. 개별 변경 내용은 아래 이력을 참고하세요.
- HCP 차트의 유래(Hierarchical ComPact description chart, 일본전신전화공사 요코스카 전기통신연구소에서 개발)를 밝히고, 독자 용어가 아님을 명시한 뒤, 이 리포지토리에 고유한 것은 HCP-DSL과 서술 입도 규약 두 가지라고 구분했습니다. DSL 구문 빠른 참조, 전제 환경 표, 그림에서 어디를 볼지의 절차와 기호 범례를 추가했습니다.
- 최초 공개
이 글을 인용하기(DOI: 10.5281/zenodo.21635082)
이 글은 Zenodo에 보관되어 있습니다. 항상 최신 버전으로 연결되는 DOI와 지금 보고 있는 버전에 고정된 DOI를 아래에 함께 제시합니다.
Go Komura (2026). 「HCP 차트와 MakingHCPChartSkill 입문」. 합동회사 코무라소프트. https://doi.org/10.5281/zenodo.21635082 https://comcomponent.com/ko/blog/what-is-hcp-chart-and-making-hcp-chart-skill/
- DOI(최신 버전)
- 10.5281/zenodo.21635082
- DOI(이 버전)
- 10.5281/zenodo.22217406
목차
- HCP 차트란 무엇인가
- 이 리포지토리가 해결하는 과제
- 리포지토리 구성을 빠르게 파악하기
- 10분 핸즈온(GCD 샘플)
- 샘플 두 가지를 읽는 법
- 안에서 무엇을 하는가(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가 됩니다. 1단씩 내립니다 |
명령
| 명령 | 의미 | 주의 |
|---|---|---|
\title / \author / \date / \version |
헤더 정보 | \module보다 앞에 쓰면 모든 모듈 공통, 뒤에 쓰면 그 모듈만 덮어씁니다 |
\module <이름> |
모듈의 시작 | 필수. 레벨 0에서만 쓸 수 있습니다. 같은 이름 모듈은 error입니다 |
\mod <라벨> |
모듈·함수 호출 | 그림에서는 이중 원으로 그려집니다 |
\repeat <라벨> |
반복 | 반복할 내용은 1단 아래에 씁니다 |
\fork <라벨> |
분기(배분)의 부모 | 분기 대상은 바로 아래에 둡니다 |
\true <라벨> / \false <라벨> |
참·거짓 2분기의 가지 | \fork의 바로 아래(1단만 깊은 위치)에만 둘 수 있습니다. 조상에 \fork가 없으면 error입니다 |
\branch <조건> |
참·거짓 이외의 다분기 가지 | 위와 같음 |
\return [n] |
탈출 | n은 생략 가능한 정수입니다 |
\ec <라벨> / \ex <라벨> |
오류 검사 / 오류 출구 | 현행 버전에서는 그리기만 하며, 제어의 의미는 갖지 않습니다 |
\data <이름> |
데이터 정의 | 이름에 공백과 .을 넣을 수 없습니다(넣으면 error) |
\in <이름> / \out <이름> |
입출력 데이터의 주석 | 1단 위 부모 노드에 대한 주석으로 다뤄집니다 |
최소 예는 다음과 같습니다. \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. 이 리포지토리가 해결하는 과제
그림만 사람이 관리하면 이런 문제가 일어나기 쉽습니다.
- 그림과 사양 텍스트가 어긋난다
- 분기나 계층의 제약이 모호해진다
- diff 리뷰가 어렵다
MakingHCPChartSkill에서는 HCP-DSL을 JSON 요청으로 넘기고, hcp_render_svg.py가 검증과 렌더링을 수행합니다.
같은 입력이면 같은 출력이 되므로, 그림을 CI나 리뷰에 넣기 쉬운 구성입니다.
flowchart TB
accTitle: 손그림의 과제와 텍스트 관리에 의한 해결
accDescr: 그림만 사람이 관리하면 사양 텍스트와의 어긋남이나 diff 리뷰의 어려움이 생기는 반면, HCP-DSL을 JSON 요청으로 넘기면 hcp_render_svg.py가 검증과 렌더링을 수행하고, 같은 입력에서는 같은 SVG를 얻는다.
hand["그림만 사람이 관리"] -.-> issue["어긋남·모호함·diff 리뷰 곤란"]
dsl["HCP-DSL을 JSON 요청으로 넘긴다"] --> render["hcp_render_svg.py가 검증과 렌더링"]
render --> svg["결정적인 SVG가 돌아온다"]
svg --> ci["CI나 리뷰에 넣을 수 있다"]
그림 4: 그림을 손으로 그리는 대신 텍스트 HCP-DSL에서 결정적으로 SVG를 생성하므로, diff 리뷰나 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는 비권장이다.
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는 비권장"]
그림 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. 샘플 두 가지를 읽는 법
그림을 열었을 때, 다음 순서로 눈을 움직이면 읽을 수 있습니다.
- 맨 왼쪽 열만 위에서 아래로 읽는다. 여기에 늘어선 것이 「무엇을 달성할지(목적)」이며, 처리 전체의 줄거리가 됩니다
- 관심 있는 행에서 오른쪽으로 따라간다. 오른쪽 들여쓰기에 늘어선 것이 그 목적을 「어떻게 달성할지(수단·상세)」입니다
- 세로선(줄기)으로 부모·자식을 확인한다. 줄기는 같은 깊이의 처리를 잇고 있으며, 깊이가 얕은 행을 뚫고 지나가지 않도록 그려집니다
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의 구분, interrupt를 통한 협력적 중단, ConcurrentHashMa...
멀티스레드 실무 베스트 프랙티스 C 언어 편 ── Win32 API의 방식으로 안전하게 작성하기
C 언어 × Win32의 멀티스레드는 _beginthreadex로 스레드를 만들고, SRW 락과 조건 변수, Interlocked, 정지 이벤트+WaitForMultipleObjects로 정지를 설계하는 것이 정석입니다. TerminateThre...
멀티스레드 실무 베스트 프랙티스 C++ 편 ── RAII와 jthread로 사고를 구조적으로 없애기
C++ 멀티스레드는 data race가 곧 undefined behavior가 되는 세계입니다. std::thread 소멸자의 함정, jthread와 stop_token으로 멈추는 설계, scoped_lock의 deadlock 회피, atomic...
멀티스레드 실무 베스트 프랙티스 .NET 편 ── 스레드를 늘리기 전에 정해 둘 것
「스레드를 만들었더니 가끔 죽거나 멈춘다」를 막는 설계의 정석을 .NET/C# 대상으로 정리합니다. 스레드를 직접 만들지 않고 Task에 맡기기, 공유 가변 상태 줄이기, 락의 규율, CancellationToken으로 정지 설계하기, UI 스레...
QR 코드를 읽은 값을 그대로 쓰면 안 됩니다 ── 오류 정정이 통과해도 값은 보장되지 않습니다
QR 코드의 오류 정정은, 정정이 통과하면 값이 맞다고 보장하는 장치가 아닙니다. 샘플 이미지와 decoder 2종으로 측정한 결과에서, 오염이 어디에 걸리느냐에 따라 다른 값으로 읽힐 수 있는 이유와 업무 시스템 쪽에 필요한 검증을 설명합니다.
관련 토픽
이 기사와 가까운 토픽 페이지입니다. 기사를 출발점 삼아 관련 서비스와 다른 기사로 이어집니다.
Windows 기술 토픽
Windows 개발, 장애 조사, 기존 자산 활용에 관한 KomuraSoft LLC 기사를 모은 토픽 허브입니다.
이 주제와 연결되는 서비스
이 기사는 다음 서비스 페이지로 이어집니다. 가까운 입구부터 확인해 주세요.
기술 상담 & 설계 리뷰
설계나 처리 흐름을 눈에 보이는 형태로 정리하고 싶은 주제라서, 기술 상담·설계 리뷰 맥락에서 쓰기 쉬운 글입니다.
자주 묻는 질문
이 기사 주제에 대해 상담 시 자주 나오는 질문을 모았습니다.
- HCP 차트란 무엇인가요?
- 처리를 계층적으로 기술하기 위한 표현입니다. 왼쪽에는 「무엇을 달성할지(목적)」를 쓰고, 오른쪽의 깊은 들여쓰기에는 「어떻게 달성할지(수단·상세)」를 쓰며, 최상위(레벨 0)에는 목적 라벨을 씁니다. 이 규칙에 따라 텍스트를 쓰면 설계 의도와 구현 상세의 대응을 읽기 쉬워집니다.
- MakingHCPChartSkill은 무엇을 하는 도구인가요?
- HCP-DSL(텍스트)을 사양에 따라 해석하고, 결정적인 SVG를 돌려주기 위한 스킬 리포지토리입니다. HCP-DSL을 JSON 요청으로 넘기면 hcp_render_svg.py가 검증과 렌더링을 수행합니다. 같은 입력이면 같은 출력이 되므로, 그림을 CI나 리뷰에 넣기 쉬운 구성입니다.
- 그림을 손으로 관리하는 경우와 무엇이 다른가요?
- 그림만 사람이 관리하면 그림과 사양 텍스트가 어긋나고, 분기나 계층의 제약이 모호해지며, diff 리뷰가 어려워지는 문제가 일어나기 쉽습니다. HCP-DSL이라는 텍스트에서 결정적으로 SVG를 생성하는 방식이면 그림을 사양으로 다루는 형태로 관리할 수 있고, diagnostics를 보면서 다듬어 갈 수 있습니다.
- 사용할 때 제약이 있나요?
- renderAllModules=true일 때는 module을 동시에 지정할 수 없습니다. 또한 diagnostics에 error가 있으면 svg 또는 svgs는 비어 있게 됩니다. 스크립트는 hcp_xml_to_svg.py가 deprecated이며, 지금은 hcp_render_svg.py를 사용합니다.