Skill 決策流程圖生成器
SKILL.md 파일을 읽어 구조화된 데이터 nodes.json을 추출하고, 스크립트가 결정론적으로 순서도 HTML을 생성합니다.
분업
| 단계 | 담당자 | 이유 |
|---|---|---|
| SKILL.md → nodes.json | AI | SKILL.md는 자연어로, 의미가 불안정하므로 AI가 문맥을 이해해야 함 |
| nodes.json → HTML | 스크립트 | 좌표 계산은 결정론적이고 재현 가능하며 픽셀 정렬이 필요함 |
AI는 오직 구조화된 데이터만 출력하며, 좌표나 SVG를 절대 생성하지 않습니다. 스크립트는 오직 기하학만 수행하며, 의미를 절대 추측하지 않습니다.
실행 단계
1. SKILL.md 읽기
사용자가 지정한 SKILL.md 파일을 읽습니다. 파일을 찾을 수 없는 경우 사용자에게 경로를 입력하도록 요청합니다.
2. AI가 nodes.json 추출
다음 스키마에 따라 JSON을 출력합니다. 각 출력 엣지에는 반드시 명시적으로 side 필드가 있어야 합니다. 이는 AI의 의미적 판단이며, 스크립트는 추측하지 않습니다.
최상위 구조
{
"title": "스킬 이름",
"subtitle": "선택적 설명",
"nodes": [ ... ],
"edges": [ ... ],
"loops": [ ... ],
"legend": [ ... ]
}
nodes: 필수, 노드 배열edges: 필수, 방향성 엣지 배열loops: 선택 사항, 되돌림 점선 (아래 참조)legend: 일반적으로 빈 배열[]로 두고, 기본 범례 사용
노드 type
| type | 의미 | 모양 |
|---|---|---|
entry | 흐름 시작점 | 둥근 사각형 |
decision | 결정 지점 (예/아니오, 있음/없음) | 다이아몬드 |
process | 처리 단계 | 둥근 사각형 |
output | 보고서/파일 출력 | 둥근 사각형 |
terminal | 종료/오류 종료 | 둥근 사각형 |
노드 role (색상)
| role | 의미 | fill / stroke |
|---|---|---|
ai | AI 추론 / LLM 호출 | #E6F1FB / #185FA5 |
output | 보고서 / 파일 출력 | #EEEDFE / #534AB7 |
decision | 결정 지점 | #FAEEDA / #854F0B |
script | 스크립트 실행 | #E1F5EE / #0F6E56 |
terminal | 종료 / 오류 | #FCEBEB / #A32D2D |
각 노드는 하나의 role만 가질 수 있습니다. 한 단계가 여러 가지 성격의 작업(다른 role에 해당)을 포함하는 경우, 반드시 여러 개의 노드로 분할해야 합니다. 예를 들어 '스크립트로 기준선 가져오기 + AI 보충 분석'은 role=script와 role=ai 두 개의 노드로 분할되어야 합니다.
엣지 side (중요!)
| side | 의미 | 레이아웃 동작 |
|---|---|---|
bottom | 메인 흐름 아래로 | target은 from의 다음 레이어, cx는 from 상속 |
left | 결정 왼쪽 분기 / 분기 왼쪽 | 결정 → 동일 레이어 수평 연결; 일반 → 다음 레이어 직교 꺾임선 |
right | 결정 오른쪽 분기 / 분기 오른쪽 | 위와 동일, 방향만 반대 |
side의 의미적 판단은 AI가 수행합니다:
- 결정 다이아몬드(type=decision)의
left/right→ 결정과 동일 레이어, 수평 연결선 - 일반 사각형(type=process/output)의
left/right→ 다음 레이어, 직교 꺾임선 (수직→수평→수직, 대각선 없음)
loops (되돌림, 선택 사항, 점선)
흐름에 '이전 단계로 돌아가는' 로직이 있을 때 사용합니다. 예를 들어:
- 수정 후 재검토 (
apply_fix → entry) - 재시도 (
retry → checkpoint) - 조건 충족까지 반복 (
recheck → validate)
{ "from": "apply_fix", "to": "entry", "label": "수정 후 재검토", "path": "left_edge" }
필드 설명:
from: 되돌림 시작 노드 id (보통 마지막 단계)to: 되돌림 종료 노드 id (보통 흐름 시작점 또는 검사 지점)label: 되돌림 레이블, 점선 옆에 표시path: 고정값"left_edge"(그래프 왼쪽 가장자리를 따라 경로 지정)
참고:
- 되돌림 시작점과 종료점 사이에 edges에 중복 엣지를 그리지 마십시오. 그렇지 않으면 중복 렌더링됩니다.
- loops의 from/to 노드는 depth 계산에 참여하지 않습니다.
legend
일반적으로 빈 배열 []로 두면, 스크립트가 기본 5색 범례를 사용합니다. 필요시 사용자 지정:
[
{ "label": "AI 실행", "fill": "#E6F1FB", "stroke": "#185FA5" },
{ "label": "출력/보고서", "fill": "#EEEDFE", "stroke": "#534AB7" },
{ "label": "결정 지점", "fill": "#FAEEDA", "stroke": "#854F0B" },
{ "label": "스크립트", "fill": "#E1F5EE", "stroke": "#0F6E56" },
{ "label": "종료", "fill": "#FCEBEB", "stroke": "#A32D2D" }
]
3. 스크립트 호출하여 HTML 생성
python3 <skill_dir>/scripts/flowchart.py <nodes.json> --out docs/decision-flowchart.html
스크립트는 다음을 수행합니다:
- id 고유성, side/type/role 유효성, from/to 참조 유효성 검증
- 레이어 자동 계산 (결정 측지는 동일 레이어 / 일반 분기는 하위 레이어 / 합류점 = max(들어오는 엣지)+1)
- x (side에 따라 결정) 및 y (레이어 + 노드 높이에 따라) 자동 계산
- 연결선 렌더링 (수평 측지 / 직교 꺾임선 / 수직 메인 흐름 / 합류점 3단 / 되돌림 점선)
- 자동 viewBox + 하단 범례
- 자체 포함 HTML 출력
nodes.json 예제
docs/halucatch-v2-nodes.json— 전체 예제 (loop 되돌림, 삼항 분기, 합류점 포함)docs/halucatch-nodes.json— 기본 예제docs/security-review-nodes.json— 다중 결정 지점 예제docs/self-nodes.json— 최소 예제 (9개 노드)
자체 점검 목록
- 진입 노드 type=entry가 최상단에 위치
- 각 엣지에 side 필드 존재 (bottom/left/right)
- 결정 다이아몬드의 side=left/right는 측지 (동일 레이어 수평 연결)
- 일반 사각형의 side=left/right는 분기 (하위 레이어 직교 꺾임선)
- 하나의 노드에 하나의 role, 혼합 단계는 분할됨
- 합류점 (여러 들어오는 엣지가 같은 노드로)은 특별 처리 불필요, 스크립트가 자동 인식
- 되돌림은 loops 필드 사용, edges에 중복 없음
- 모든 노드 id가 edges의 from/to에서 참조됨 (고립 노드 없음)
- 범례는 빈 배열
[]
자주 묻는 질문
Q: 노드가 겹칩니다. 어떻게 해야 하나요?
side 필드가 누락되었는지 확인하십시오. 결정 분기에는 side (left/right/bottom)가 반드시 있어야 합니다. 그렇지 않으면 두 대상 노드가 같은 위치를 상속받게 됩니다.
Q: 되돌림 점선이 그려지지 않습니다.
되돌림은 loops 배열로 선언해야 하며 (edges가 아님), from/to를 edges에 중복해서 넣지 마십시오. path는 고정값 "left_edge"입니다.
Q: 스크립트에서 JSON 형식 오류가 발생합니다. JSON은 주석과 작은따옴표를 지원하지 않습니다. 일반적인 문제: 쉼표 누락, 불필요한 쉼표 (배열 끝), 작은따옴표 사용.
더 많은 질문은 docs/FAQ.md를 참조하십시오.