Hướng Dẫn Quy trình Phát Triển tiêu chuẩn

Version: 1.6.1 | Last reviewed: 2026-03-24

Tổng Quan

PARA Workspace tổ chức quy trình phát triển thành 4 luồng workflow chính:

┌──────────────────────────────────────────────────────────────────────┐
│                                                                      │
│  0. PLANNING          1. DAILY DEV        2. RELEASE      3. OPS    │
│  ────────────         ──────────          ──────────      ────────  │
│  /brainstorm          /open               /release        /retro    │
│     ↓                    ↓                   ↓            /inbox    │
│  /docs (strategy)     [coding + hot lane]                           │
│     ↓                    ↓                                          │
│  /plan create         /push                                         │
│     ↓                    ↓                                          │
│  /backlog sync        /end (sync + plan check)                      │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

0. Planning Flow (Dự án mới)

Luồng này chạy 1 lần khi khởi tạo dự án có quy mô lớn (>5 tasks).

/new-project [name]
    ↓
/brainstorm           → Động não, ghi nhận quyết định (tùy chọn)
    ↓
/docs new (strategy)  → Tạo docs/strategy/strategy.md (v1.6.1, tùy chọn)
    ↓
/plan create          → Chọn loại: 🗺️ Roadmap hoặc 📐 Detail Plan (v1.6.1)
    ↓                    (set active_plan nếu là Detail Plan)
/backlog sync         → Tạo backlog items từ các phase trong plan
    ↓
/open [project]       → Chuyển sang luồng Daily Dev Flow

Mô hình 3 tầng (v1.6.1): Strategy → Roadmap → Detail Plan. Số tầng sử dụng tùy thuộc vào quy mô dự án. Xem chi tiết tại Strategy Plan Flow Guide. Không phải mọi dự án đều cần Plan. Xem tiêu chí quyết định tại Planning Guide.

1. Daily Development Flow

Luồng này diễn ra hằng ngày khi developer làm việc.

/open [project]
    │
    │  📋 Đọc session log + backlog summary (~10 dòng)
    │  🔥 Đọc Hot Lane (sprint-current.md)
    │  📐 Xem phase hiện tại (nếu có active_plan)
    │  💡 Nhận đề xuất công việc ưu tiên
    │
    ▼
[Coding & Testing]
    │
    │  🔧 Phát triển features
    │  🧪 Kiểm thử cục bộ (local test)
    │  🔥 Task phát sinh? → Ghi `- [ ]` vào sprint-current.md
    │  ✅ Xong task nhanh? → Đánh dấu `[x]` ngay
    │
    ▼
/push ["message"]
    │
    │  📝 Cập nhật CHANGELOG
    │  ⬆️ Push lên GitHub
    │
    ▼
/end [project] [done]
    │
    │  💾 Lưu session log
    │  🔥 Hot Lane Sync: [x] → done.md (#session), [ ] → hỏi giữ/promote
    │  💡 Smart Suggest: gợi ý đánh dấu Done cho các task chiến lược
    │  📐 Kiểm tra tiến độ plan phase
    │  🧹 Tự động gỡ active_plan (nếu đã hoàn thành)

⚠️ KHÔNG CẦN chạy /backlog update giữa phiên. /end là điểm đồng bộ duy nhất.

Hot Lane: Task phát sinh

sprint-current.md là Hot Lane — vùng đệm agent-writable dành cho các task ad-hoc phát sinh khi đang code. Đây KHÔNG phải sprint board.

## Quick Tasks

- [x] Fix typo trong README ← hoàn thành trong phiên
- [ ] Thêm error handling cho API ← chưa xử lý

## Notes

Trọng tâm phiên: Phase 2 tasks

Khi chạy /end:

• Items [x] → chuyển vào done.md với tag #session
• Items [ ] → Agent hỏi: giữ lại cho phiên sau hoặc promote lên backlog

2. Release Cycle Flow

Luồng này thực hiện khi phát hành version mới.

/plan review          → Tổng quan tiến độ theo phase
    ↓
/backlog review       → Kiểm tra trạng thái task cho phase hiện tại
    ↓
[Development Sprint]  → 1-2 ngày/phase
    ↓
/release [project]    → Tạo CHANGELOG, Git tag, push
    ↓
/deploy               → Xác minh trên production

Plan Archiving

Khi tất cả phases đạt 100%, /plan review tự động thực hiện:

1. Di chuyển plan sang artifacts/plans/done/[plan-name].md
2. Tạo completion review tại artifacts/plans/done/[plan-name]-review.md
3. Xóa active_plan khỏi project.md
4. Gợi ý chạy /retro để tổng kết dự án

Plan và review nằm cùng thư mục done/. /retro chỉ cần đọc một nơi duy nhất.

3. Operations Flow

Chạy khi cần (không hằng ngày).

Quan hệ giữa các Artifacts

project.md (active_plan, agent)
    │
    │ trỏ tới
    ▼
Plan (artifacts/plans/)              ← HOW & ORDER
    │                                   lưu kho: plans/done/ (+ review)
    │ ánh xạ tới
    ▼
Backlog (artifacts/tasks/backlog.md) ← WHAT & STATUS (chiến lược)
    │
    │ task nhanh phát sinh trong phiên
    ▼
Hot Lane (sprint-current.md)         ← BUFFER (ad-hoc, agent-writable)
    │
    │ /end đồng bộ cả hai xuống
    ▼
Done (artifacts/tasks/done.md)       ← RECORD (#backlog + #session tags)
    │
    │ bằng chứng phiên làm việc
    ▼
Session Log (sessions/YYYY-MM-DD.md) ← EVIDENCE
    │
    │ khi phát hành
    ▼
CHANGELOG → GitHub Release           ← PUBLIC RECORD

CLI: update vs install

⚠️ Lệnh install KHÔNG kéo dữ liệu từ GitHub. Luôn dùng update khi cần phiên bản mới nhất.

Thực hành tốt (Best Practices)

✅ NÊN

• Luôn bắt đầu với /open để có đầy đủ context và phase hiện tại
• Commit thường xuyên với /push (nhiều commit nhỏ tốt hơn 1 commit lớn)
• Task phát sinh → ghi - [ ] vào sprint-current.md TRƯỚC khi bắt tay code
• Kết thúc phiên bằng /end — điểm đồng bộ duy nhất (Hot Lane Sync + Smart Suggest)
• Dùng ./para update khi cần đồng bộ workspace từ GitHub

❌ KHÔNG NÊN

• Bỏ qua /open và code trực tiếp không context
• Quên chạy /end dẫn đến mất context cho ngày hôm sau
• Chạy /backlog update giữa phiên — /end đã xử lý đồng bộ
• Đọc toàn bộ backlog/plan trong /open — chỉ cần grep summary
• Dùng ./para install --force khi thực chất cần pull mới từ GitHub

Tài liệu liên quan

• Strategy Plan Flow Guide — Mô hình 3 tầng Strategy → Roadmap → Plan (v1.6.1)
• Planning Guide — Hướng dẫn chi tiết Plan + Backlog
• Workflows Reference — Danh mục và bảng version workflows
• Glossary — Thuật ngữ và bản đồ ảnh hưởng

Cập nhật trong v1.6.1 (Mô hình 3 tầng Strategy, Planning Flow cải tiến)