From rkit
Mermaid v8.8.0 다이어그램 작성 규칙. subgraph ID 필수, flowchart/direction/& 금지. Triggers: mermaid, diagram, 다이어그램, ダイアグラム
npx claudepluginhub solitasroh/rkit --plugin rkitThis skill is limited to using the following tools:
가이드 문서에서 Mermaid 다이어그램 생성 시 **반드시** 따른다.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
가이드 문서에서 Mermaid 다이어그램 생성 시 반드시 따른다. 아래 규칙을 하나라도 어기면 렌더링이 실패한다.
flowchart 금지 → 반드시 graph를 사용한다 (8.8.0에서 flowchart는 에러)direction 금지 → subgraph 내 direction TB/LR 사용 불가 (9.3+ 기능)subgraph ID["라벨"] 형식만 허용& 연산자 금지 → A --> B & C 불가, 반드시 각각 별도 라인으로[""] 필수좋은 예:
graph TD
A["ApplicationContext"]
B["Observable<br/>Filter 특수화"]
C["ILocator · IDataService"]
나쁜 예 (신택스 에러 발생):
A[ApplicationContext<br/>Composition Root] %% 따옴표 없이 <br/> → 에러
B[ILocator · IDataService] %% 따옴표 없이 가운뎃점 → 에러
[""]가 필요한 경우:
<br/>, <i>, <b> 등 HTML 태그·, ↔, (), <>, /, +, - 등 특수문자단순 영문 한 단어만 → 따옴표 없이 [] 가능
형식: subgraph 영문ID["표시 라벨"]
모든 subgraph에 예외 없이 적용한다. 중첩 subgraph도 동일.
subgraph 안에 direction 키워드를 쓰지 않는다 (8.8.0 미지원).
좋은 예:
graph TD
subgraph APP["apps/ui (namespace ui)"]
subgraph MVVM["MVVM"]
subgraph VIEW["View (QML)"]
A["main.qml"]
end
subgraph VM["ViewModel"]
B["AppViewModel"]
end
end
subgraph TYPES["Types"]
C["DataTypes.h"]
end
end
나쁜 예 (전부 신택스 에러):
flowchart TD %% flowchart → 에러, graph를 써야 함
subgraph APP["apps/ui"]
direction TB %% direction → 에러, 8.8.0 미지원
end
subgraph "apps/ui (namespace ui)" %% ID 없이 문자열만 → 에러
subgraph "MVVM" %% ID 없이 따옴표 문자열 → 에러
subgraph "View (QML)" %% ID 없이 따옴표 문자열 → 에러
subgraph 체크리스트:
subgraph ID["라벨"] 형식인가?direction 키워드가 없는가?& 연산자 절대 금지좋은 예:
graph TD
CTX --> LOC
CTX --> SVC
CTX --> DSP
CTX --> PROV
나쁜 예 (& 연산자 에러):
CTX --> LOC & SVC & DSP & PROV
&를 쓰고 싶은 충동이 들면 반드시 별도 라인으로 풀어 쓴다.
추가 연결선 문법:
-.->, 라벨 점선: -. 텍스트 .-> 또는 -.->|텍스트|==>, 라벨: ==>|텍스트|graph TD
A["Component A"]
B["Component B"]
A --> B
style A fill:#f9f,stroke:#333,color:#000
style B fill:#bbf,stroke:#333,color:#000
classDef로 재사용:
graph TD
A["Component A"]
B["Component B"]
A --> B
classDef interface fill:#bbf,stroke:#333,color:#000
class A,B interface
규칙:
style은 다이어그램 맨 아래에 배치한다classDef + class를 사용한다fill 지정 시 color도 함께 지정한다 (가독성)한 다이어그램에 노드 15개를 넘기지 않는다. 넘으면 노드가 축소되어 텍스트를 읽을 수 없다.
하나의 거대한 다이어그램 대신 레이어별/역할별로 나눠서 여러 개의 작은 다이어그램을 만든다.
### 전체 레이어 구조
(graph TD — 레이어 3~5개만, 각 레이어에 대표 컴포넌트 1~2개)
### View 레이어 상세
(graph LR — View 내부 컴포넌트만)
### ViewModel ↔ Service 연결
(graph LR — ViewModel과 Service 간 의존성만)
나쁜 예: 전체 프로젝트의 모든 클래스를 하나의 다이어그램에 넣는 것
| 상황 | 분할 방법 |
|---|---|
| 레이어가 3개 이상 | 오버뷰 1개 + 레이어별 상세 다이어그램 |
| subgraph가 3단계 중첩 | 상위 구조 1개 + 하위 상세 분리 |
| 노드가 15개 초과 | 역할별로 나누어 별도 다이어그램 |
| 연결선이 교차 | 관련 노드끼리 묶어 별도 다이어그램 |
좋은 예 (오버뷰 — 레이어만):
graph TD
subgraph UI["UI Layer"]
QML["QML Views"]
VM["ViewModels"]
end
subgraph CORE["Core Layer"]
SVC["Services"]
REPO["Repositories"]
end
subgraph INFRA["Infrastructure"]
NET["Network"]
DB["Database"]
end
QML --> VM
VM --> SVC
SVC --> REPO
REPO --> NET
REPO --> DB
나쁜 예 (모든 클래스를 한 다이어그램에 — 15개 초과):
graph TD
subgraph UI["UI Layer"]
subgraph VIEWS["Views"]
A["main.qml"]
B["FullLayout"]
C["PageA.qml"]
D["PageB.qml"]
E["PageC.qml"]
end
subgraph VMS["ViewModels"]
F["AppViewModel"]
G["PageAViewModel"]
H["PageBViewModel"]
I["PageCViewModel"]
end
end
subgraph CORE["Core"]
J["ServiceLocator"]
K["LogService"]
L["DataService"]
M["CrashHandler"]
N["ExternalDataService"]
end
%% ... 이미 15개 초과, 읽을 수 없음
| 용도 | 유형 | 예시 |
|---|---|---|
| 모듈/레이어 구조 | graph TD | 아키텍처 오버뷰 |
| 호출 관계 (좌→우) | graph LR | reference 의존성 |
| 시퀀스/시나리오 | sequenceDiagram | API 호출 흐름 |
| 클래스 관계 | classDiagram | 상속/구현 관계 |
| 상태 전이 | stateDiagram-v2 | 라이프사이클 |
API 호출 흐름, 시나리오 묘사에 사용한다.
sequenceDiagram
participant C as Client
participant S as Server
participant DB as Database
C->>S: POST /login
activate S
S->>DB: SELECT user
DB-->>S: user row
S-->>C: 200 OK + token
deactivate S
| 문법 | 의미 |
|---|---|
->> | 실선 화살표 (동기 요청) |
-->> | 점선 화살표 (응답) |
-x | 실선 + X (실패/취소) |
--x | 점선 + X |
sequenceDiagram
participant A as ServiceA
participant B as ServiceB
alt 성공
A->>B: request
B-->>A: 200 OK
else 실패
A->>B: request
B-->>A: 500 Error
end
loop 매 5초
A->>B: health check
end
opt 캐시 있으면
A->>A: 캐시 반환
end
participant 선언 순서가 좌→우 배치 순서를 결정한다as 별칭을 사용하면 이후 별칭으로만 참조한다Note over A,B: 텍스트 로 노트를 추가한다activate/deactivate 또는 +/- 접미사로 활성화 표시: A->>+B: req / B-->>-A: res: 뒤 텍스트를 쓴다 (따옴표 불필요)클래스 관계, 상속/구현 구조 묘사에 사용한다.
classDiagram
class IService {
<<interface>>
+start() void
+stop() void
}
class LogService {
-logger: Logger
+start() void
+stop() void
+log(msg: string) void
}
class DataService {
-repo: Repository
+start() void
+stop() void
+fetch(id: int) Data
}
IService <|.. LogService : implements
IService <|.. DataService : implements
DataService --> Repository : uses
| 문법 | 의미 |
|---|---|
<|-- | 상속 (extends) |
<|.. | 구현 (implements) |
--> | 의존 (uses) |
--* | 합성 (composition) |
--o | 집합 (aggregation) |
..> | 점선 의존 |
| 기호 | 의미 |
|---|---|
+ | public |
- | private |
# | protected |
~ | package/internal |
<<interface>>, <<abstract>>, <<enumeration>> 으로 스테레오타입 표기+methodName(param: Type) ReturnType 형식+fieldName: Type 형식: 라벨 로 끝에 추가상태 전이, 라이프사이클 묘사에 사용한다. 반드시 stateDiagram-v2를 쓴다 (stateDiagram은 구버전).
stateDiagram-v2
[*] --> Idle
Idle --> Running : start()
Running --> Paused : pause()
Paused --> Running : resume()
Running --> Stopped : stop()
Paused --> Stopped : stop()
Stopped --> [*]
stateDiagram-v2
[*] --> Active
state Active {
[*] --> Idle
Idle --> Processing : request
Processing --> Idle : done
}
Active --> Error : fault
Error --> Active : recover
Error --> [*] : fatal
[*]은 시작/종료 상태 (위치에 따라 자동 구분)StateA --> StateB : 이벤트/조건state "표시 라벨" as S1 으로 한글 라벨을 별칭 지정state ParentState { ... } 블록으로note right of StateA: 설명 으로 노트 추가subgraph ID끼리 직접 연결(YAML --> FILES)은 렌더러에 따라 깨질 수 있다.
subgraph 내부의 노드끼리 연결하는 것이 안전하다.
나쁜 예 (subgraph ID 간 직접 연결 — 렌더러 호환성 문제):
graph TD
subgraph A["Group A"]
A1["Node 1"]
end
subgraph B["Group B"]
B1["Node 2"]
end
A --> B
좋은 예 (내부 노드 간 연결):
graph TD
subgraph GA["Group A"]
A1["Node 1"]
end
subgraph GB["Group B"]
B1["Node 2"]
end
A1 --> B1
_) 사용 금지 — 일부 렌더러에서 파싱 오류InProgress, inProgress (O)in_progress (X)state "진행 중" as InProgress나쁜 예:
stateDiagram-v2
[*] --> in_progress
in_progress --> build_failed
좋은 예:
stateDiagram-v2
[*] --> InProgress
InProgress --> BuildFailed
생성한 Mermaid 코드를 아래 체크리스트로 반드시 검증한다:
flowchart 키워드가 없는가? → graph로 교체direction 키워드가 없는가? → 삭제subgraph에 영문 ID가 붙어있는가? → subgraph ID["라벨"]& 연산자가 없는가? → 별도 라인으로 분리[""]로 감싸져 있는가?stateDiagram-v2에서 상태 ID에 underscore(_)가 없는가? → PascalCase 사용