Files

Ho Ngoc Hai 393c2afc6b feat: Add agent execution guidelines and revise filename convention to use identical English filenames for both English and Vietnamese documentation.

2026-01-18 23:27:43 +07:00

13 KiB

Raw Blame History

description

description
Workflows chỉnh sửa và cập nhật docs của microservices theo chuẩn EN/VI

Workflow: Microservices Documentation Update

Mục Đích / Purpose

Workflow này giúp Agent cập nhật và duy trì documentation của microservices theo cấu trúc chuẩn:

docs/
  en/
    ARCHITECTURE.md
    README.md
    API.md (optional)
    ... (other docs)
  vi/
    ARCHITECTURE.md
    README.md
    API.md (optional)
    ... (other docs)
README.md (service root)

Khi Nào Sử Dụng / When to Use

Tạo mới hoặc cập nhật documentation cho microservices
Tách bilingual docs thành separate EN/VI files
Đảm bảo docs đồng bộ giữa EN và VI versions
Chuẩn hóa Mermaid diagrams và color palettes

⚠️ AGENT EXECUTION GUIDELINES (CRITICAL)

Đọc phần này TRƯỚC KHI thực thi workflow!

Quy Trình Thực Thi Đúng

LUÔN tuân theo các bước sau theo thứ tự:

Đọc TOÀN BỘ workflow specification từ đầu đến cuối
Kiểm tra current state của service documentation
So sánh current state với workflow requirements (đặc biệt chú ý Bước 2 về filename convention)
Xác định gaps/issues dựa trên workflow - KHÔNG dựa trên assumption hay kinh nghiệm từ project khác
Thực hiện changes theo đúng workflow specification
Validate theo workflow checklist (Bước 7)

❌ Common Mistakes to Avoid

Mistake #1: Không đọc kỹ workflow trước khi thực thi

❌ BAD: Thấy files KIEN-TRUC.md → Giả định sai → Đổi tên thành kien-truc.md
✅ GOOD: Đọc Bước 2 → Thấy "cùng tên file tiếng Anh" → Giữ nguyên ARCHITECTURE.md

Mistake #2: Dựa vào assumptions từ các workflows/projects khác

❌ BAD: "Tôi nghĩ Vietnamese files nên dùng Vietnamese filenames"
✅ GOOD: "Workflow nói rõ: Both EN/VI use SAME English filenames"

Mistake #3: Bỏ qua validation checklist

❌ BAD: Làm xong → Notify user ngay
✅ GOOD: Làm xong → Check Bước 7 → Đảm bảo đúng spec → Notify user

✅ Pre-Flight Checklist

Trước khi bắt đầu thực thi, hãy xác nhận:

Đã đọc toàn bộ workflow specification?
Đã hiểu rõ filename convention ở Bước 2?
Đã kiểm tra current state của documentation?
Đã so sánh current state với workflow requirements?
Đã xác định chính xác những gì CẦN thay đổi (không phải GIẢ ĐỊNH)?

Nếu có bất kỳ câu trả lời "No" nào → Quay lại đọc workflow!

Bước 1: Xác Định Cấu Trúc Hiện Tại / Identify Current Structure

Actions:

Kiểm tra cấu trúc docs/ folder của service
Xác định xem có bilingual files hay đã tách riêng EN/VI
List tất cả các files cần xử lý

Expected Output:

Danh sách files hiện tại
Xác định files nào cần tách/cập nhật

Bước 2: Tạo Cấu Trúc Thư Mục Chuẩn / Create Standard Structure

Actions:

Tạo docs/en/ nếu chưa có
Tạo docs/vi/ nếu chưa có
Đảm bảo có README.md tại service root
Sử dụng cùng tên file tiếng Anh cho cả EN và VI

Commands:

mkdir -p docs/en docs/vi

IMPORTANT - Filename Convention:

✅ Cả docs/en/ và docs/vi/ dùng CÙNG tên file tiếng Anh
✅ Ví dụ: ARCHITECTURE.md, README.md, API.md trong cả 2 folders
✅ Lợi ích: Dễ tìm file tương ứng, không cần nhớ 2 bộ tên khác nhau

Example Structure:

docs/
├── en/
│   ├── README.md           # English content
│   ├── ARCHITECTURE.md     # English content
│   └── API.md              # English content
└── vi/
    ├── README.md           # Vietnamese content (same filename!)
    ├── ARCHITECTURE.md     # Vietnamese content (same filename!)
    └── API.md              # Vietnamese content (same filename!)

Bước 3: Tách Nội Dung EN/VI / Separate EN/VI Content

3.1 Xử Lý Bilingual Files (Nếu Có)

Pattern 1: Side-by-side format

# Title / Tiêu Đề
Description in English.
Mô tả bằng tiếng Việt.

→ Split into separate files

Pattern 2: Sections format

# English Section
...
---
# Phần Tiếng Việt
...

→ Extract each section to corresponding file

Pattern 3: Comments

# EN: English comment
# VI: Vietnamese comment

→ Remove VI comments from EN files, EN comments from VI files

3.2 Làm Sạch Nội Dung / Clean Content

For EN files:

✅ Keep: # EN: comments (optional)
❌ Remove: # VI: comments
❌ Remove: Vietnamese inline translations (after slashes)
❌ Remove: > **Lưu ý**: Vietnamese notes

For VI files:

✅ Keep: # VI: comments (optional)
❌ Remove: # EN: comments
❌ Remove: English inline translations
❌ Remove: > **Note**: English notes

Example:

❌ BAD (in EN file):
## Configuration / Cấu Hình
> **Note**: This is important
> **Lưu ý**: Điều này rất quan trọng

✅ GOOD (in EN file):
## Configuration
> **Note**: This is important

✅ GOOD (in VI file):
## Cấu Hình
> **Lưu ý**: Điều này rất quan trọng

Bước 4: Chuẩn Hóa Mermaid Diagrams / Standardize Mermaid Diagrams

4.1 Syntax Check

Common Issues Checklist:

Có xuống dòng sau flowchart TD / graph TD?
Arrow sử dụng --> không phải ->?
Không có Node ID trùng lặp?
Labels có ký tự đặc biệt được quote? ["Label (with parens)"]
Subgraph format: subgraph ID["Label"]?

4.2 Apply Dark Color Palette

LUÔN sử dụng bảng màu tối:

Node Type	Fill Color	Border	Stroke Width
Start	`#2C3E50`	`#34495E`	`3px`
End/Success	`#27AE60`	`#229954`	`3px`
Decision	`#E67E22`	`#D35400`	`2px`
Error	`#C0392B`	`#A93226`	`2px`
Process	`#8E44AD`	`#7D3C98`	`2px`
Database/Cache	`#34495E`	`#2C3E50`	`2px`
Gateway/API	`#3498DB`	`#2980B9`	`3px`
Neutral	`#7F8C8D`	`#5D6D7E`	`2px`

Text Color: #ECF0F1 (light text cho contrast)

Style Template:

style NodeName fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:3px

4.3 Example: Before/After

❌ BEFORE (no styling):

graph TD
    A[Start] --> B[Process]
    B --> C{Decision}
    C -->|Yes| D[Success]
    C -->|No| E[Error]

✅ AFTER (with dark palette):

graph TD
    A[Start] --> B[Process]
    B --> C{Decision}
    C -->|Yes| D[Success]
    C -->|No| E[Error]
    
    style A fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:3px
    style B fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
    style C fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
    style D fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:3px
    style E fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:2px

4.4 Visual Indicators (Optional)

Có thể thêm emoji cho clarity:

🚀 Start/Launch
✅ Success/Done
❌ Error/Failed
⚠️ Warning/Decision
🔐 Security/Auth
💾 Database
⚙️ Processing
🌐 API/Network

Bước 5: Đảm Bảo Đồng Bộ EN/VI / Ensure EN/VI Consistency

Checklist:

Cả EN và VI đều có cùng sections (headings)
Mermaid diagrams có cùng structure (chỉ khác labels)
Code examples giống nhau (chỉ khác comments)
File names khớp: en/ARCHITECTURE.md ↔ vi/ARCHITECTURE.md

EN Diagram Example:

graph TD
    A[Request] --> B{Valid?}
    B -->|Yes| C[Process]
    B -->|No| D[Error]

VI Diagram Example (same structure, Vietnamese labels):

graph TD
    A[Yêu cầu] --> B{Hợp lệ?}
    B -->|Có| C[Xử lý]
    B -->|Không| D[Lỗi]

Bước 6: Cập Nhật Service Root README / Update Service README

Service root README.md phải link đến EN/VI docs:

Template:

# Service Name

> **EN**: [English Documentation](docs/en/README.md)  
> **VI**: [Tài liệu Tiếng Việt](docs/vi/README.md)

## Quick Links

- 📖 [Architecture Documentation](docs/en/ARCHITECTURE.md) / [Tài liệu Kiến trúc](docs/vi/ARCHITECTURE.md)
- 🚀 [Quick Start](docs/en/README.md#quick-start)
- 🔧 [Configuration](docs/en/README.md#configuration)

## Tech Stack

- .NET 8
- PostgreSQL
- Redis
- RabbitMQ

## Development

\`\`\`bash
dotnet build
dotnet run
\`\`\`

See detailed documentation in [docs/en/](docs/en/) or [docs/vi/](docs/vi/).

Bước 7: Validation / Kiểm Tra Chất Lượng

7.1 Content Checklist

For each EN file:

No Vietnamese text (except code comments if needed)
No bilingual patterns (Text / Chữ)
All Mermaid diagrams have dark color palette
No syntax errors in Mermaid
Links work correctly

For each VI file:

No English text (except technical terms)
No bilingual patterns
All Mermaid diagrams have dark color palette
Mermaid structure matches EN version
Links work correctly

7.2 Structure Checklist

docs/en/ exists with all required files
docs/vi/ exists with mirror files (same count)
Service root README.md links to both EN/VI
Both EN and VI folders use SAME English filenames (e.g., ARCHITECTURE.md in both)
File count matches between EN/VI directories (e.g., 4 files in EN = 4 files in VI)

7.3 Filename Convention Validation

✅ CORRECT Convention (as per Bước 2):

Both docs/en/ and docs/vi/ use SAME English filenames:

docs/en/ARCHITECTURE.md   ↔ docs/vi/ARCHITECTURE.md  ✅
docs/en/API.md            ↔ docs/vi/API.md           ✅
docs/en/README.md         ↔ docs/vi/README.md        ✅
docs/en/TWITTER_SETUP.md  ↔ docs/vi/TWITTER_SETUP.md ✅

❌ INCORRECT (Common mistakes):

# Mistake 1: Using Vietnamese filenames in VI folder
docs/en/ARCHITECTURE.md   ↔ docs/vi/kien-truc.md     ❌ WRONG!
docs/en/TWITTER_SETUP.md  ↔ docs/vi/cai-dat-twitter.md ❌ WRONG!

# Mistake 2: Case inconsistency
docs/en/ARCHITECTURE.md   ↔ docs/vi/architecture.md  ❌ WRONG!

# Correct approach
docs/en/ARCHITECTURE.md   ↔ docs/vi/ARCHITECTURE.md  ✅ CORRECT!

Why this convention?

✅ Easier to find corresponding files
✅ No need to remember two naming schemes
✅ Better cross-reference in documentation
✅ Simpler maintenance

7.4 Mermaid Validation

# Optional: validate Mermaid syntax using mermaid-cli
mmdc -i docs/en/ARCHITECTURE.md -o /tmp/test.svg

Resources / Tài Nguyên

Related Skills:

Documentation Skill - Documentation guidelines
Mermaid Diagrams Skill - Diagram patterns
Skill Authoring - How to write skills

Tools:

Mermaid Live Editor - Test diagrams
Mermaid Documentation

Example: Complete Workflow Execution

# 1. Create structure
mkdir -p services/my-service-net/docs/{en,vi}

# 2. Split bilingual ARCHITECTURE.md into EN/VI
# (Agent processes content, removes cross-language text)

# 3. Apply Mermaid formatting
# (Agent adds dark color palette to all diagrams)

# 4. Update root README.md
# (Agent creates bilingual link structure)

# 5. Validate
# Check all files exist, links work, diagrams render

Result:

services/my-service-net/
├── README.md               (links to docs/en and docs/vi)
└── docs/
    ├── en/
    │   ├── README.md        (English content)
    │   ├── ARCHITECTURE.md  (English content)
    │   └── API.md           (English content)
    └── vi/
        ├── README.md        (Vietnamese content, same filename!)
        ├── ARCHITECTURE.md  (Vietnamese content, same filename!)
        └── API.md           (Vietnamese content, same filename!)

Quick Tips / Mẹo Nhanh

Mermaid Common Issues

Missing line break after flowchart TD → Add newline
Single dash in arrow -> → Change to -->
Duplicate node IDs → Rename nodes (A, B, C, etc.)
Missing quotes on special chars → Wrap in ["label"]

Color Pattern Quick Reference

🟦 Start = #2C3E50 / #34495E
🟩 Success = #27AE60 / #229954  
🟧 Decision = #E67E22 / #D35400
🟥 Error = #C0392B / #A93226
🟪 Process = #8E44AD / #7D3C98
⬛ Database = #34495E / #2C3E50
🔷 API = #3498DB / #2980B9

Visual Indicators

Use emojis consistently: 🚀 ✅ ❌ ⚠️ 🔐 💾 ⚙️ 🌐
Dark palette mandatory for all diagrams
Light text color #ECF0F1 for contrast

13 KiB Raw Blame History