bpmnemonic은(는) 무엇을 하나요?
bpmnemonic — BPMN + mnemonic. 프로세스 다이어그램을 실제로 읽고, 검색하고, 버전 관리할 수 있는 문서로 변환합니다. 아무도 새벽 2시에 .bpmn 파일을 에디터로 열지 않지만, 모두가 마크다운을 읽기 때문입니다.
존재 이유
BPMN 파일은 액터, 결정, 예외 경로, 데이터 흐름, 메시지 교환 등 풍부한 의미를 담고 있지만, 뷰어가 열려 있어야만 확인할 수 있습니다. 다음과 같은 상황이 발생하면 다이어그램은 부담으로 변합니다:
- PR 리뷰에서 프로세스를 논의해야 할 때,
- 요구사항을 외주업체에 전달해야 할 때,
- 신규 엔지니어를 온보딩할 때,
- 또는 프로세스를 언어 모델에 입력해야 할 때.
이때는 산문 형식이 필요합니다. 다이어그램과 정확히 일치하는 산문이 필요합니다. 그리고 다이어그램이 변경될 때마다 수동으로 작성하고 싶지 않습니다.
이 스킬은 BPMN 구조를 다음 두 가지 마크다운 형식 중 하나로 변환합니다:
specs.md— 엔지니어를 위한 기술 명세서. 번호가 매겨진 단계, 완전한 흐름, 데이터 계약, 수락 기준.prd.md— 이해관계자를 위한 제품 요구사항 문서. 문제 진술, 액터, 사용자 여정, 성공 지표, 범위.
둘 다 동일한 다이어그램에서 파생됩니다. 대상 독자, 용어, 강조되는 BPMN 요소가 다릅니다.
호출
| 트리거 | 동작 |
|---|---|
/bpmnemonic 또는 /bpmn-to-spec 또는 /flow-to-doc | 기본값 — 파일 분석 후 생성할 형식을 묻고 생성 |
/bpmnemonic spec [path] | BPMN 파일에서 specs.md 생성 |
/bpmnemonic prd [path] | BPMN 파일에서 prd.md 생성 |
/bpmnemonic both [path] | 두 문서 모두 생성 |
/bpmnemonic analyze [path] | scripts/analyze-bpmn.sh를 실행하고 요소 수 + 복잡도 보고 |
| 자연어: "이 BPMN을 명세서로 변환해줘", "이 다이어그램에서 PRD를 만들어줘", "이 워크플로우를 문서화해줘" | 동일함 |
중지/비활성화
세션 기반이 아닙니다. 파일당 한 번 실행됩니다.
변환 플레이북 (5단계)
1단계: 파싱 및 인벤토리 작성
.bpmn 파일(XML)을 읽고 인벤토리를 작성합니다:
- 프로세스(Process) 이름, id, 문서화 내용
- 참여자(Participants)(
bpmn:participant) — "액터" 또는 "외부 시스템"이 됨 - 레인(Lanes)(
bpmn:laneSet내bpmn:lane) — "역할" 또는 "책임"이 됨 - 태스크(Tasks)(
bpmn:task,bpmn:userTask,bpmn:serviceTask,bpmn:sendTask,bpmn:receiveTask,bpmn:scriptTask,bpmn:businessRuleTask,bpmn:manualTask) — 번호가 매겨진 단계가 됨 - 이벤트(Events)(
bpmn:startEvent,bpmn:endEvent,bpmn:intermediateThrowEvent,bpmn:intermediateCatchEvent,bpmn:boundaryEvent) — 트리거, 종료, 오류 포착, 타임아웃 - 게이트웨이(Gateways)(
bpmn:exclusiveGateway,bpmn:parallelGateway,bpmn:inclusiveGateway,bpmn:eventBasedGateway) — 분기점 - 시퀀스 흐름(Sequence flows)(
bpmn:sequenceFlow) — 화살표 - 메시지 흐름(Message flows)(
bpmn:messageFlow) — 풀 간 통신, 통합 지점 - 데이터 객체(Data objects)(
bpmn:dataObject,bpmn:dataObjectReference) — 문서, 레코드, 페이로드 - 서브프로세스(Subprocesses)(
bpmn:subProcess,bpmn:callActivity) — 중첩된 복잡성
scripts/analyze-bpmn.sh가 실행되면 이 인벤토리를 자동으로 생성합니다.
2단계: 선형 내러티브 구축 (해피 패스)
각 시작 이벤트에서 각 종료 이벤트까지 시퀀스 흐름을 따라가며, 게이트웨이에서 벗어나지 않는 경로(가장 가능성 높은 성공 경로)를 선택합니다. 이것이 "해피 패스"이며, 명세서와 PRD 모두의 중심축이 됩니다.
번호가 매겨진 단계로 포맷합니다. 각 단계는 액터(레인에서)와 액션(태스크 이름에서)을 명명합니다.
3단계: 분기 (대체 흐름)
해피 패스에서 만나는 각 게이트웨이에 대해, 다른 분기는 명세서의 대체 흐름 또는 PRD의 에지 케이스가 됩니다. 주 흐름 뒤에 번호를 매깁니다.
4단계: 예외 포착
태스크에 연결된 경계 이벤트(bpmn:boundaryEvent) — 오류 이벤트, 타이머 이벤트, 에스컬레이션 이벤트 — 는 예외 흐름이 됩니다. 이는 일반적으로 PRD에서 누락되지만 명세서에서는 중요합니다.
5단계: 풀 간 통신 식별
풀 간 메시지 흐름은 통합 지점이 됩니다. 명세서에서는 외부 API 계약입니다. PRD에서는 "이것은 다음에 의존함" 섹션입니다.
출력 형식 선택
사용자가 지정하지 않으면 물어보십시오. 그렇지 않으면 다음 휴리스틱을 사용합니다:
| 다이어그램에... | 추천 |
|---|---|
| 풀 1개, 주로 사용자 태스크, 총 요소 10개 미만 | PRD — 기능 설명으로 충분히 작음 |
| 여러 풀, 메시지 흐름, 오류 이벤트 | specs.md — 엔지니어링에 세부 사항 필요 |
| 서브프로세스 또는 호출 활동 | specs.md + 각 서브프로세스 별도 변환 권장 |
| "결정 테이블" 게이트웨이(DMN) | both — PRD는 규칙을 설명, 명세서는 테이블을 캡처 |
| 확실하지 않을 때 | both — 서로 참조 |
실행 흐름 (Claude의 작업)
.bpmn파일을 읽습니다(XML — Read 도구 사용 후 정신적으로 파싱하거나scripts/parse-bpmn.sh를 통해 파싱).- 1단계에 따라 요소 인벤토리를 작성합니다.
- 지정되지 않은 경우 형식을 제안합니다. 확인을 받습니다.
- 해피 패스를 따라가며 선형 내러티브를 구축합니다.
- 대체 흐름(게이트웨이 분기), 예외 흐름(경계 이벤트), 통합 지점(메시지 흐름)을 식별합니다.
playbook/templates.md에서 선택한 템플릿을 렌더링하고 실제 내용으로 채웁니다.- 파일을 쓰기 전에 사용자에게 미리보기를 보여줍니다. 확인을 요청합니다.
./specs.md및/또는./prd.md에 씁니다. 파일이 이미 존재하면 차이점을 비교하고 덮어쓰기 전에 확인합니다.
안전 장치
- 소스 파일 읽기 전용.
.bpmn파일을 절대 수정하지 마십시오. 마크다운만 출력합니다. - 원래 ID 보존. 생성된 마크다운에 BPMN 요소 ID를 주석으로 참조하여 향후 업데이트 시 상호 참조할 수 있도록 합니다. (
<!-- from bpmn:userTask id="UserTask_1a2b3c" -->) - 흐름을 절대 발명하지 마십시오. 다이어그램에 경로가 표시되지 않으면 작성하지 마십시오. 모호한 내용이 있으면 추측하지 말고 문서에 미해결 질문으로 표시하십시오.
- 매우 작은 경우가 아니라면 DMN 테이블을 인라인으로 변환하지 마십시오. 참조하고 규칙을 요약한 후 별도의 결정 테이블 문서를 권장합니다.
- 이름 없는 요소 표시.
name속성이 없는bpmn:task id="Task_42"는 다이어그램 버그입니다. 이름을 발명하지 말고 출력에[이름 없는 태스크 — 레이블 필요]로 표시하십시오. - 미리보기 및 확인 없이 기존 specs.md / prd.md를 절대 덮어쓰지 마십시오. 수동 추가 내용이 포함될 수 있습니다.
이 스킬의 파일
SKILL.md— 이 파일playbook/elements.md— BPMN 요소 참조 (각 태그의 의미)playbook/extraction.md—.bpmnXML 파일 읽는 방법: 태그 이름, 속성, 흐름 추적playbook/templates.md—specs.md및prd.md의 대상 구조playbook/pitfalls.md— 프로세스 다이어그램을 서술할 때 흔한 실수examples/01-approval.md— 소규모 비용 승인 흐름 → 두 출력 모두examples/02-loan.md— 여러 레인과 게이트웨이가 포함된 대출 신청 → 명세서examples/03-errors.md— 타이머/오류 이벤트가 포함된 주문 처리 → 명세서scripts/analyze-bpmn.sh— BPMN 요소 개수 세기, 복잡도 점수 부여scripts/parse-bpmn.sh—.bpmn파일에서 구조화된 정보 추출 (최선 노력, xmlstarlet 사용 가능한 경우)README.md— 설치 및 빠른 시작