สถาปนิกเมอร์เมด: ทักษะไดอะแกรมและเอกสารประกอบ

เมอร์เมด อาร์คิเทค - ทักษะไดอะแกรมและเอกสารประกอบที่ครอบคลุม

รุ่น 2.0 - สถาปัตยกรรมแบบลำดับชั้นพร้อมการประสานงานอัจฉริยะ

ทักษะ Claude Code อันทรงพลังสำหรับการสร้างไดอะแกรม Mermaid และเอกสารออกแบบ โดยใช้การโหลดคู่มือตามความต้องการ การสร้างไดอะแกรมจากโค้ด และยูทิลิตี้ Python

การติดตั้ง

ติดตั้งด้วยคลิกเดียวผ่าน Skilz Marketplace

ติดตั้งทักษะนี้ทันทีจาก Skilz Marketplace:

skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid

การติดตั้งด้วยตนเอง

โคลนโดยตรงลงในไดเรกทอรีทักษะ Claude Code ของคุณ:

# Navigate to your skills directory
cd ~/.claude/skills

# Clone the repository
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git

ตรวจสอบการติดตั้ง

หลังการติดตั้ง ตรวจสอบว่าทักษะพร้อมใช้งาน:

# List installed skills
ls ~/.claude/skills/design-doc-mermaid

# Or ask Claude Code
# "List my installed skills"

ทักษะนี้ทำอะไรได้บ้าง

การสร้างไดอะแกรมอัจฉริยะ:

• ไดอะแกรมกิจกรรม (ขั้นตอนการทำงาน, กระบวนการ, ตรรกะทางธุรกิจ)
• ไดอะแกรมการปรับใช้ (โครงสร้างพื้นฐานคลาวด์, K8s, ไร้เซิร์ฟเวอร์)
• ไดอะแกรมสถาปัตยกรรม (องค์ประกอบระบบ, ไมโครเซอร์วิส)
• ไดอะแกรมลำดับ (การไหลของ API, การโต้ตอบของบริการ)
• เอกสารออกแบบที่สมบูรณ์พร้อมไดอะแกรมที่ฝังอยู่

การแปลงโค้ดเป็นไดอะแกรม:

• แยกสถาปัตยกรรมจากแอปพลิเคชัน Spring Boot
• สร้างไดอะแกรมการปรับใช้จากไฟล์การกำหนดค่า
• สร้างไดอะแกรมลำดับจากการเรียกใช้เมธอด
• จัดทำเอกสารไปป์ไลน์ ETL และการไหลของข้อมูล

การจัดการไดอะแกรม:

• แยกไดอะแกรม Mermaid จากไฟล์ Markdown
• ตรวจสอบความถูกต้องของไวยากรณ์ไดอะแกรมด้วย mermaid-cli
• แปลงไดอะแกรมเป็นรูปภาพ PNG/SVG
• ประมวลผลทั้งไดเรกทอรีเป็นชุด

เริ่มต้นอย่างรวดเร็ว

สร้างไดอะแกรมกิจกรรม

User: "Create an activity diagram for user registration with email verification"

ทักษะนี้จะ:

1. โหลด references/guides/diagrams/activity-diagrams.md
2. ใช้เทมเพลตรูปแบบการลงทะเบียน
3. เพิ่มสัญลักษณ์ Unicode (🔐 สำหรับความปลอดภัย, 📧 สำหรับอีเมล, ✅ สำหรับความสำเร็จ)
4. ใช้การจัดรูปแบบที่มีคอนทราสต์สูง
5. ส่งออกไดอะแกรม Mermaid ที่สมบูรณ์

สร้างจากโค้ด

User: "Here's my Spring Boot application.yml - generate a deployment diagram"

ทักษะนี้จะ:

1. วิเคราะห์การกำหนดค่า (แหล่งข้อมูล, แคช, ความปลอดภัย)
2. โหลด references/guides/diagrams/deployment-diagrams.md
3. โหลด examples/spring-boot/README.md
4. แมปการกำหนดค่าไปยังทรัพยากรคลาวด์
5. สร้างไดอะแกรมการปรับใช้พร้อมข้อกำหนดของทรัพยากร

สร้างเอกสารออกแบบ

User: "Create an API design document for the contacts API"

ทักษะนี้จะ:

1. โหลด assets/api-design-template.md
2. โหลดคู่มือไดอะแกรมที่เกี่ยวข้อง (ลำดับ, ER, สถาปัตยกรรม)
3. สร้างเอกสารที่สมบูรณ์พร้อมไดอะแกรมที่ฝังอยู่
4. บันทึกไปยัง docs/design/api-contacts-v1-2025-01-13.md

โครงสร้าง

การจัดระเบียบแบบลำดับชั้น

mermaid-architect/
├── SKILL.md                          # Main orchestrator with decision tree
├── README.md                         # This file
├── CLAUDE.md                         # Claude Code instructions
│
├── references/                       # Reference materials
│   ├── mermaid-diagram-guide.md     # Legacy general guide
│   └── guides/                       # Specialized guides (load on-demand)
│       ├── diagrams/
│       │   ├── activity-diagrams.md      # ✅ Complete
│       │   ├── deployment-diagrams.md    # ✅ Complete
│       │   ├── architecture-diagrams.md  # ✅ Complete
│       │   └── sequence-diagrams.md      # ✅ Complete
│       ├── code-to-diagram/
│       │   └── README.md                 # ✅ Complete (master guide)
│       ├── unicode-symbols/
│       │   └── guide.md                  # ✅ Complete (100+ symbols)
│       └── troubleshooting.md        # ✅ Complete (28 common errors)
│
├── scripts/                          # Python utilities
│   ├── extract_mermaid.py           # ✅ Extract & validate diagrams
│   └── mermaid_to_image.py          # ✅ Convert to PNG/SVG
│
├── examples/                         # Language-specific patterns
│   ├── spring-boot/                 # ✅ Complete
│   ├── fastapi/                     # ✅ Complete
│   ├── react/                       # ✅ Complete
│   ├── python-etl/                  # ✅ Complete
│   ├── node-webapp/                 # ✅ Complete
│   └── java-webapp/                 # ✅ Complete
│
└── assets/                           # Design document templates
    ├── architecture-design-template.md
    ├── api-design-template.md
    ├── feature-design-template.md
    ├── database-design-template.md
    └── system-design-template.md

คุณสมบัติหลัก

1. สัญลักษณ์ Unicode เชิงความหมาย

ทุกไดอะแกรมใช้สัญลักษณ์ Unicode ที่มีความหมาย:

graph TB
    User[👤 Client] --> Gateway[🌐 API Gateway]
    Gateway --> Auth[🔐 Auth Service]
    Gateway --> API[⚙️ API Service]
    API --> DB[(💾 Database)]
    API --> Cache[(⚡ Redis)]
    API --> Queue[📬 Message Queue]
    Queue --> Worker[⚙️ Background Worker]

หมวดหมู่สัญลักษณ์:

• โครงสร้างพื้นฐาน: ☁️ 🌐 🔌 📡 🗄️
• การประมวลผล: ⚙️ ⚡ 🔄 🚀 💨
• ข้อมูล: 💾 📦 📊 📈 🗃️
• การรับส่งข้อความ: 📨 📬 📤 📥 🐰
• ความปลอดภัย: 🔐 🔑 🛡️ 🚪 👤
• การตรวจสอบ: 📝 📊 🚨 ⚠️ ✅ ❌

2. การจัดรูปแบบที่มีคอนทราสต์สูง

ไดอะแกรมทั้งหมดใช้สีที่เข้าถึงได้และมีคอนทราสต์สูง - ดูรายละเอียดทั้งหมดใน SKILL.md

3. ยูทิลิตี้ Python

แยกไดอะแกรม

# List all diagrams in a file
python scripts/extract_mermaid.py document.md --list-only

# Extract to separate .mmd files
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# Validate all diagrams
python scripts/extract_mermaid.py document.md --validate

# Replace diagrams with image references (for Confluence)
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md

แปลงเป็นรูปภาพ

# Single file
python scripts/mermaid_to_image.py diagram.mmd output.png

# Custom theme and size
python scripts/mermaid_to_image.py diagram.mmd output.svg \
  --theme dark --background white --width 1200

# Batch convert directory
python scripts/mermaid_to_image.py diagrams/ output/ \
  --format png --recursive

# From stdin
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png

ข้อกำหนด

สำหรับการสร้างไดอะแกรม

• ระบบทักษะ Claude Code (อัตโนมัติ)
• คู่มือและเทมเพลต (รวมอยู่ในทักษะนี้)

สำหรับการตรวจสอบและแปลงรูปภาพ

# Install mermaid-cli globally
npm install -g @mermaid-js/mermaid-cli

# Verify installation
mmdc --version

สำหรับสคริปต์ Python

• Python 3.7+
• ไม่จำเป็นต้องใช้แพ็คเกจเพิ่มเติม (ใช้เฉพาะไลบรารีมาตรฐาน)

เส้นทางการเรียนรู้

ยังใหม่กับไดอะแกรม Mermaid?

1. เริ่มต้นด้วยไดอะแกรมกิจกรรม - อ่าน references/guides/diagrams/activity-diagrams.md
2. เรียนรู้สัญลักษณ์ Unicode - อ่าน references/guides/unicode-symbols/guide.md
3. ลองตัวอย่าง - ใช้รูปแบบจาก examples/spring-boot/
4. ตรวจสอบงานของคุณ - รัน python scripts/extract_mermaid.py --validate

ต้องการจัดทำเอกสารโค้ดที่มีอยู่?

1. ระบุเฟรมเวิร์ก - Spring Boot, FastAPI, React, ฯลฯ
2. โหลดคู่มือตัวอย่าง - อ่าน examples/{your-framework}/README.md
3. จับคู่รูปแบบ - ค้นหารูปแบบโค้ดที่คล้ายกันในตัวอย่าง
4. สร้างไดอะแกรม - ใช้เทมเพลตจากคู่มือ
5. ตรวจสอบ - ใช้สคริปต์ตรวจสอบความถูกต้อง

กำลังสร้างเอกสารออกแบบ?

1. เลือกประเภทเทมเพลต - สถาปัตยกรรม, API, ฟีเจอร์, ฐานข้อมูล, หรือระบบ
2. โหลดเทมเพลต - อ่านจาก assets/{type}-design-template.md
3. กรอกส่วนต่างๆ - แทนที่ตัวยึดด้วยเนื้อหาจริง
4. เพิ่มไดอะแกรม - โหลดคู่มือไดอะแกรมตามความจำเป็นสำหรับแต่ละส่วน
5. ใช้สัญลักษณ์ - ปรับปรุงด้วยสัญลักษณ์ Unicode ตลอดทั้งเอกสาร
6. บันทึก - วางใน docs/design/ พร้อมตราประทับเวลา

วิธีการทำงานของระบบลำดับชั้น

แนวทางแบบดั้งเดิม (ไม่มีประสิทธิภาพ)

• โหลดเอกสารทักษะทั้งหมด (~50KB)
• AI ประมวลผลเทมเพลตและตัวอย่างทั้งหมด
• การใช้โทเค็นสูง
• เวลาตอบสนองช้า

แนวทางแบบลำดับชั้น (มีประสิทธิภาพ)

1. ผู้ใช้ส่งคำขอ → AI วิเคราะห์เจตนา
2. ต้นไม้ตัดสินใจทำงาน → กำหนดคู่มือที่จำเป็น
3. โหลดเฉพาะสิ่งที่จำเป็น → อ่านคู่มือเฉพาะ (~2-5KB)
4. สร้างผลลัพธ์ → ใช้เทมเพลตที่ตรงเป้าหมาย
5. มีประสิทธิภาพด้านโทเค็น → ใช้บริบทน้อยกว่า 10 เท่า

ตัวอย่างขั้นตอนการทำงาน

ผู้ใช้: "สร้างไดอะแกรมการปรับใช้สำหรับการตั้งค่า Docker Compose ของฉัน"

ต้นไม้ตัดสินใจ:

1. Analyze: "deployment diagram" + "Docker Compose"
2. Determine: deployment-diagrams.md needed
3. Load: references/guides/diagrams/deployment-diagrams.md (2KB)
4. Find pattern: Docker Compose template exists
5. Generate: Using template + Unicode symbols
6. Output: Complete diagram in <30 seconds

โทเค็นที่ใช้: ~2,000 (เทียบกับ ~10,000 ในแนวทางแบบดั้งเดิม)

สถานะความสมบูรณ์

✅ เสร็จสมบูรณ์:

• ตัวประสานต้นไม้ตัดสินใจแบบลำดับชั้น
• คู่มือไดอะแกรมกิจกรรมพร้อมเทมเพลต
• คู่มือไดอะแกรมการปรับใช้ (AWS, GCP, K8s, ไร้เซิร์ฟเวอร์, Docker)
• คู่มือสัญลักษณ์ Unicode (100+ สัญลักษณ์)
• สคริปต์แยก Mermaid พร้อมการตรวจสอบ
• สคริปต์แปลง Mermaid เป็นรูปภาพ
• ตัวอย่างการแปลงโค้ด Spring Boot เป็นไดอะแกรม
• เทมเพลตเอกสารออกแบบ (5 ประเภท)
• ระบบการจัดรูปแบบที่มีคอนทราสต์สูง

🚧 กำลังดำเนินการ:

• ตัวอย่าง FastAPI
• ตัวอย่างสถาปัตยกรรมคอมโพเนนต์ React
• ตัวอย่างไปป์ไลน์ Python ETL

📋 วางแผนไว้:

• คู่มือไดอะแกรมสถาปัตยกรรม
• คู่มือไดอะแกรมลำดับ
• คู่มือหลักการแปลงโค้ดเป็นไดอะแกรม
• ตัวอย่าง Node.js/Express
• ตัวอย่างเว็บแอป Java

การมีส่วนร่วม

ในการเพิ่มคู่มือประเภทไดอะแกรมใหม่:

1. สร้างคู่มือใน references/guides/diagrams/{type}-diagrams.md
2. รวมสิ่งต่อไปนี้:
   • เมื่อใดควรใช้
   • ไวยากรณ์พื้นฐาน
   • รูปแบบทั่วไป (3-5 เทมเพลต)
   • ตัวอย่างสัญลักษณ์ Unicode
   • แนวทางปฏิบัติที่ดีที่สุด
3. อัปเดตต้นไม้ตัดสินใจใน SKILL.md
4. เพิ่มตัวอย่างพร้อมการแมปโค้ด

ในการเพิ่มตัวอย่างภาษาใหม่:

1. สร้างไดเรกทอรีใน examples/{framework}/
2. เพิ่ม README.md พร้อมด้วย:
   • ภาพรวมเฟรมเวิร์ก
   • ไดอะแกรมสถาปัตยกรรมจากโครงสร้าง
   • ไดอะแกรมการปรับใช้จากการกำหนดค่า
   • ไดอะแกรมลำดับจากโค้ด
   • ไดอะแกรมกิจกรรมจากตรรกะ
3. อัปเดตตารางการแปลงโค้ดเป็นไดอะแกรมใน SKILL.md

ใบอนุญาต

ส่วนหนึ่งของ Claude Code Skills - ใบอนุญาต MIT

ทักษะที่เกี่ยวข้อง

• confluence - อัปโหลดไดอะแกรมไปยัง Confluence
• plantuml - รูปแบบไดอะแกรมทางเลือก

ลิงก์

• ที่เก็บ GitHub
• รายชื่อ Skilz Marketplace
• เอกสารทางการ Mermaid

รุ่น: 2.0.0 อัปเดต: 2025-01-13 ดูแลโดย: SpillwaveSolutions