workflow-erd

Generate ERDs from functional specs, PRDs, or domain descriptions. A solid ERD design leads to better UI design and more reliable API implementation. This is a Layer 2 skill (optional harness).

Why ERD matters in the workflow

/workflow-idea → PRD + Functional Spec
       ↓
/workflow-erd → ERD (data relationships become concrete)
       ↓
  Better understanding of domains → better UI design, better API design

The functional spec tells you "what to build". The ERD tells you "what data exists and how it connects". This concreteness cascades into everything downstream.

Prerequisites

#	Check	On failure
1	.wiki symlink exists	"Run /wiki-init first"

ERD Levels

Level	Entities	Attributes	Types	PK/FK	Indexes	Labels
Conceptual	O	X	X	X	X	Korean verbs
Logical	O	Korean	Abstract (Long, String, Enum)	O	X	Korean verbs
Physical	O	English snake_case	DB-specific (BIGINT, VARCHAR)	O	O	English verbs

Abstract types (Logical): Long, String, Int, Float, Boolean, Date, DateTime, Text, Enum

Workflow

1. Input analysis

Accept input from:

• Functional spec (SPEC file from /workflow-idea)
• PRD
• Natural language description
• Existing ERD file (for modification)

If the functional spec exists in Wiki Focus, read it to understand domains and features. This gives the ERD a strong foundation.

2. Choose ERD level

If not specified, ask via AskUserQuestion:

• A) Conceptual — entities and relationships only
• B) Logical — with Korean attributes and abstract types
• C) Physical — with DB column names, types, and indexes

3. Determine save location

1. Read .wiki/CONTRIBUTING.md to understand the wiki structure
2. Suggest location via AskUserQuestion
3. Filename: {project-name}-{level}-erd.mmd

4. Data modeling

1. Identify domains — group related business areas
2. Extract entities — core nouns become entities
3. Define relationships — cardinality (1:1, 1:N, N:M) and relationship verbs
4. Define attributes (Logical/Physical only) — properties, types, constraints

5. Generate .mmd file

Read the appropriate reference file from references/ to match the exact structure, syntax, and styling:

• references/conceptual-erd-example.md
• references/logical-erd-example.md
• references/physical-erd-example.md

Read the .md file to understand the structure and styling, then generate the output as a .mmd file (pure Mermaid, no markdown wrapper).

File structure

---
config:
  theme: dark
  look: handDrawn
  layout: elk
---
erDiagram
  direction BT

  [Entity definitions]

  [Relationships]

  [Entity:::class applications]

  [classDef definitions]

Order matters: Entities → Relationships → Class applications → classDef definitions.

Attribute syntax (Logical/Physical)

type name [PK|FK|UK] ["comment"]

Example (Logical):

Long 직원ID PK ""
String 이름 "NN"
Enum 재직상태 "NN"

Example (Physical):

BIGINT employee_id PK "AUTO_INCREMENT"
VARCHAR(50) name "NN"

Conceptual ERDs have empty entity blocks:

직원 :::blue {

}

Relationship syntax

엔티티A||--o{엔티티B:"관계동사"

Cardinality	Notation
1:1	||--||
1:N	||--o{
N:1	}o--||
N:M	}o--o{
0..1	||--o|

Color palette (15 colors)

Assign unique colors per entity. Use the classDef palette from the reference files. Colors are designed for dark theme + handDrawn.

6. Add to Wiki Focus

Edit AGENTS.md to add the ERD file to ### Wiki Focus.

7. Review and refine

Guide user to preview in VS Code with Mermaid extension. Accept feedback and modify:

• Add/remove/rename entities
• Add/remove/change attributes or types
• Change relationships or cardinality
• Change colors

8. Level conversion

User can request conversion between levels:

• Conceptual → Logical: Add Korean attributes + abstract types
• Logical → Physical: Convert to English snake_case + DB types + indexes
• Physical → Logical: Reverse conversion
• Logical → Conceptual: Remove attribute blocks

Reference

• references/conceptual-erd-example.md — Conceptual ERD example
• references/logical-erd-example.md — Logical ERD example
• references/physical-erd-example.md — Physical ERD example