arrow_back Trở về Quy tắc
rules Rule

Quản lý Phiên bản (VCS)

Quy tắc an toàn Git: atomic commit, bảo vệ secrets, phân tách scope, và giao thức Branch & Merge Safety dành cho AI Agent.

Quy tắc Quản lý Phiên bản (VCS)

Các quy tắc này điều chỉnh cách AI Agent tương tác với Git trong PARA Workspace. Chúng đảm bảo thực hành commit an toàn, bảo vệ secrets, tách biệt dữ liệu workspace khỏi repo dự án, và định nghĩa giao thức Branch & Merge nghiêm ngặt.

1. Nguyên tắc Vàng

  • BẮT BUỘC KHÔNG thực hiện git commit hoặc git push khi chưa có sự đồng ý rõ ràng từ người dùng.
  • Ngoại lệ: Các workflow có xác nhận tích hợp (/push, /release).

2. Kiểm tra Ignore trước khi Commit

BẮT BUỘC xác minh .gitignore tồn tại và bao phủ các pattern bắt buộc trước mọi thao tác git.

Các pattern bắt buộc

# Dependencies
node_modules/

# Build output
dist/
build/
.next/
.astro/

# Platform-specific
.vercel/
.wrangler/

# Environment files (QUAN TRỌNG - secrets)
.env
.env.local
.env.*.local
*.local

# IDE & Editor
.vscode/
.idea/
*.swp
*.swo
*~
.DS_Store
Thumbs.db

3. Cấm Secrets

  • TUYỆT ĐỐI KHÔNG tạo .env.local hoặc bất kỳ file .env nào chứa thông tin xác thực thật.
  • NÊN dùng env.example.txt làm template.
  • BẮT BUỘC hướng dẫn người dùng tự cấu hình secrets.

Các file nguy hiểm (TUYỆT ĐỐI KHÔNG commit)

  • .env* (API keys, credentials)
  • *.pem, *.key (Khóa riêng tư)
  • id_rsa* (SSH keys)
  • *.sqlite, *.db (Cơ sở dữ liệu)
  • credentials.json (Service accounts)

4. Phân tách Scope Git

  • BẮT BUỘC KHÔNG git add dữ liệu workspace (sessions/, _inbox/, Archive/) vào repo của dự án.
  • BẮT BUỘC xác minh Cwd nằm trong Projects/[project-name]/repo/ trước khi chạy lệnh git.

5. Tích hợp Workflow

Khi chạy /push hoặc /release, BẮT BUỘC:

  1. Kiểm tra .gitignore tồn tại.
  2. Quét các file nhạy cảm đang được track.
  3. Cảnh báo người dùng nếu phát hiện file nhạy cảm.
  4. DỪNG LẠI nếu phát hiện secrets quan trọng — không bao giờ force-push.

6. An toàn Branch & Merge

Thêm vào từ v1.5.3. Phần này định nghĩa giao thức đầy đủ cho branching, Pull Request, và merge an toàn.

6a. Tạo Branch

  • BẮT BUỘC đề xuất tạo branch và được người dùng chấp thuận trước khi thực hiện.
  • BẮT BUỘC KHÔNG tự động tạo branch — đây là quyết định của người dùng.

6b. Cấm Merge cục bộ

  • BẮT BUỘC KHÔNG thực hiện git merge vào main (hoặc nhánh chính) tại local.
  • BẮT BUỘC sử dụng Pull Request (PR) cho mọi merge vào main.
  • Ngoại lệ: Khi người dùng yêu cầu merge cục bộ rõ ràng.

6c. Pull Request

  • BẮT BUỘC KHÔNG tạo Pull Request (gh pr create) khi chưa được người dùng cho phép.
  • NÊN đề xuất tiêu đề và nội dung PR, sau đó hỏi người dùng xác nhận.

6d. Sau khi Merge

  • Sau khi PR được merge, BẮT BUỘC yêu cầu người dùng test trước khi đánh tag release.
  • BẮT BUỘC KHÔNG tự động đánh tag version — đây là quyết định của người dùng.

Quy trình tóm tắt

Branch:  đề xuất → người dùng đồng ý → tạo branch
Code:    phát triển trên branch → push branch
PR:      đề xuất → người dùng đồng ý → tạo PR
Merge:   người dùng merge trên GitHub (không merge local)
Tag:     người dùng test → đề xuất tag → người dùng đồng ý

Tham khảo

  • Workflow: /push — Commit và push nhanh với kiểm tra an toàn
  • Workflow: /release — Cổng kiểm soát chất lượng trước phát hành
  • Rule: governance.md — Bảo vệ file hệ thống
  • Learn: Rule Layers & Trigger Index — Cách rules được tải progressive

→ Trở về Rules Catalog → Learn: Rule Layers & Trigger Index