Incomex AI Portal
KB-4539

dev process

4 min read Revision 1

Quy trình Phát triển (Dev Process)

QUY TRÌNH PHÁT TRIỂN (DEV PROCESS)

Hiệu lực: 2026-02-08 Phê duyệt: User (Commander) Đồng thuận: Claude (Opus), Gemini, GPT

⚡ CÁC NGUYÊN TẮC TỐI THƯỢNG (SUPREME PRINCIPLES)

  1. Local First: Mọi logic BẮT BUỘC chạy thành công trên Local trước. Cloud chỉ để deploy, không để debug. Mục tiêu: tốc độ tối đa, chi phí bằng 0.

  2. Assembly First: Lắp ghép trước khi chế tạo. Tận dụng tối đa Block/Flow/Module đã có. Chỉ viết code mới khi không còn mảnh ghép phù hợp.

  3. Evidence-Based Verification: Không chấp nhận báo cáo miệng. Mọi Commit/Merge phải có bằng chứng: script test PASS, log thành công, hoặc screenshot. "Chưa thấy Bằng chứng = Chưa làm xong."

QUY TRÌNH 2 NHỊP

Nhịp 1 — Phát triển (liên tục, nhanh)

  • Agent sửa code → test local → commit vào feature branch
  • Gom nhiều thay đổi liên quan vào cùng 1 branch
  • KHÔNG push mỗi commit nhỏ, KHÔNG trigger CI liên tục
  • Local verify đủ tiêu chí mới chuyển sang nhịp 2

Chốt chặn Nhịp 1 — Luật "Commit Xanh"

  • Trước mỗi commit: bắt buộc chạy bash scripts/test_mcp_e2e.sh --target=local
  • Test đỏ → sửa ngay. Chỉ commit khi test xanh.
  • Không gom code lỗi vào batch chờ lên Cloud sửa.

Nhịp 2 — Đồng bộ (theo batch, linh hoạt)

  • Gom tất cả commits → push 1 lần → tạo PR
  • CI chạy 1 lần duy nhất cho cả batch
  • Review (mũ Kỹ sư trưởng) → merge → Cloud Run deploy 1 lần
  • Batch size linh hoạt, do Claude (điều phối) quyết định

Tiêu chí chuyển Nhịp 1 → Nhịp 2

  1. Hoàn thành 1 mission trọn vẹn
  2. Tích lũy đủ 5-10+ commits liên quan
  3. Cuối ngày làm việc (GH luôn có bản mới nhất)
  4. Cần production verify cho feature quan trọng

3 CHỐT CHẶN CƯỠNG CHẾ

Agents không cần "nhớ" — hệ thống tự chặn.

Chốt Thời điểm Cơ chế Chặn gì
Pre-commit Hook Trước commit Git hook chạy test --quick Code lỗi logic
CI Pipeline Sau push GitHub Actions chạy test --full Lỗi tương thích, lint
Branch Protection Trước merge Require CI pass Code chưa chuẩn vào main

TIÊU CHUẨN RESILIENT CALLER (Hiệu lực 2026-02-08)

Mọi cuộc gọi đến Cloud Run services và external APIs PHẢI tuân thủ:

  • Async-only: Dùng httpx (async), CẤM dùng requests (blocking)
  • Retry: Dùng tenacity — 3 retries, exponential backoff 1s/2s/4s, timeout 30s
  • Phonebook Pattern: KHÔNG hardcode URLs — đọc từ env vars (SERVICE_{NAME}_URL)
  • Health endpoint: Mọi Cloud Run service PHẢI có /health trả chi tiết per-service
  • Startup Probe: Mọi Cloud Run service PHẢI cấu hình startup probe gọi /health
  • Graceful degradation: Service lỗi → status=degraded, không crash container

Chi tiết: xem Playbook docs/playbooks/resilient-caller-standard.md

LUẬT BỔ SUNG

  • Code đi kèm Test: Thêm tính năng = thêm test case
  • Cấm deploy thủ công: gcloud run deploy trực tiếp = VI PHẠM
  • Sai project = dừng ngay: Chỉ dùng github-chatgpt-ggcloud
  • Mission phải có checkpoint: CI xanh → báo cáo → chờ User phê duyệt → mới merge

CÔNG CỤ

Script scripts/test_mcp_e2e.sh:

  • --target=local (localhost:8000) | --target=cloud (Cloud Run)
  • --quick (< 1 phút, cho pre-commit) | --full (cho CI)

Quy trình merge theo repo

  • agent-data-test: 3 bước UNGATE → MERGE → REGATE
  • web-test: CI-as-reviewer, gh pr merge --squash --delete-branch