Back to Details

gitlab-flow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GitLab Flow (Jira → Code → MR → Merge)

GitLab 工作流（Jira → 代码 → MR → 合并）

Quy trình chuẩn cho một feature/bugfix mới. Có 2 vai trò: Developer (người làm task) và Reviewer (người review MR). Skill này hướng dẫn Claude thực hiện đúng từng bước theo prompt mà user gọi.
这是针对新功能/缺陷修复的标准流程，包含两个角色：Developer（任务执行者）和Reviewer（MR评审者）。本Skill指导Claude根据用户的提示准确执行每一步操作。

Conventions

约定规范

Branch naming

分支命名

  • Default: mọi branch dùng 
    feature/
     — bất kể task là feature, bug fix, hay hotfix.
  • Format: 
    feature/<TASK-ID>-<short-desc>
  • Bug-fix branches dưới 
    feature/
    : mô tả trạng thái bug bằng direction marker (
    Duplicate
    , 
    Stale
    , 
    Missing
    , 
    Broken
    , 
    Wrong
    , 
    Slow
    ) thay vì verb "Fix" — vd 
    feature/HNCW-311-Duplicate-survey-log
  • Override: user chủ động gõ 
    bugfix/...
    hoặc 
    hotfix/...
    trong prompt (Mode A) → skill respect và tạo đúng prefix đó. Skill KHÔNG tự động chọn 
    bugfix/
    hay 
    hotfix/
    dựa trên nội dung task.
Quy tắc 
<short-desc>
 (đủ để hiểu task ở first glance, chi tiết để Jira giữ):
RuleDetail
Độ dài tổng≤ 50 ký tự cả branch (target ≤ 40). Vượt → rút thêm
Số từ2-4 từ key. Filler bị drop
Ngôn ngữTiếng Việt không dấu, kebab-case (
-
ngăn cách)
CapitalizationSentence case STRICT: chỉ chữ cái đầu của từ đầu tiên trong description viết hoa. Mọi từ sau (KỂ CẢ viết tắt như 
NVKD
, 
VAT
, 
API
, 
JWT
) đều lowercase. Vd 
Bao-cao-ngay-nvkd
(KHÔNG 
Bao-cao-ngay-NVKD
), 
Vat-discount
(KHÔNG 
VAT-discount
), 
Gioi-han-domain-account
. TASK-ID giữ nguyên uppercase per Jira convention
Drop type filler"Cai-tien", "Update", "Improve", "Fix", "Sua", "Sua-loi", "Them", "Tao", "Add", "Create", "Bo-sung" — đều bỏ. Với bug fix, mô tả trạng thái bug (
Duplicate
, 
Stale
, 
Missing
, 
Broken
) thay vì verb "Fix"
KEEP direction marker"Cho-phep"/"Allow", "Khong-cho-phep"/"Disallow", "Validate", "Block", "Restrict", "Enforce" — chúng nói WHAT behavior. Không có chúng → ambiguous (allow? disallow? validate?)
KEEP context marker"Show"/"Display"/"Hide" (UI layer), "Filter"/"Sort"/"Search"/"Calculate" (logic layer), "Sync"/"Migrate"/"Schedule"/"Export"/"Import" (system layer) — chúng nói TẦNG/CÁCH THỨC của feature, mà 
feature/
prefix không cover. Vd 
Show-order-info
rõ hơn 
Order-info
(display? backend? API?)
Drop scope markerTag dạng 
[Supermarket - AU]
ở đầu task title KHÔNG đưa vào branch (giữ cho commit scope)
Drop constraint phụImplementation detail như "áp dụng cho sp non-weight" — bỏ. Đó thuộc commit body / Jira description
Ưu tiên giữDirection/Context + Action/Object + Phạm vi (vd 
Allow-qty-0-checkin-checkout
, 
Show-order-info-uber-doordash
). Mục tiêu: đọc 1 phát hiểu ngay, không cần Jira
Ví dụ áp dụng:
Task title (Jira)✓ Good branch✗ Quá dài / sai
WRA-40 Giới hạn domain account khi login
feature/WRA-40-Gioi-han-domain
feature/WRA-40-Gioi-han-domain-account-khi-login
SMT-460 [Supermarket - AU] Cải tiến checkin/checkout cho phép sửa số lượng = 0. Áp dụng cho sp KHÔNG phải hàng đổi trọng lượng
feature/SMT-460-Allow-qty-0-checkin-checkout
feature/SMT-460-Cai-tien-cho-phep-sua-so-luong-0-checkin-checkout-non-weight
WRA-334 Bug: tính sai VAT đơn có discount
feature/WRA-334-Wrong-vat-discount
bugfix/WRA-334-Fix-tinh-sai-VAT-don-co-discount
WRA-501 Hotfix: timeout khi gọi Jira
feature/WRA-501-Jira-timeout
hotfix/WRA-501-Fix-timeout-khi-goi-Jira-API
HNCW-311 Sửa lỗi ghi log survey 2 lần
feature/HNCW-311-Duplicate-survey-log
bugfix/HNCW-311-Fix-log-survey-2-lan
SMT-516 [Supermarket - AU] Bổ sung "Mã tham chiếu", "Mã đơn hàng", "Tổng giá trị đơn" trong chi tiết đơn hàng checkout Uber & Doordash
feature/SMT-516-Show-order-info-uber-doordash
feature/SMT-516-Order-info-uber-doordash
(thiếu context marker — không rõ display hay backend)
  • 默认规则：所有分支均使用
    feature/
    前缀    ——无论任务是功能开发、缺陷修复还是紧急修复（hotfix）。
  • 格式：
    feature/<TASK-ID>-<short-desc>
  • 缺陷修复分支仍使用
    feature/
    前缀：用方向标记词（
    Duplicate
    、
    Stale
    、
    Missing
    、
    Broken
    、
    Wrong
    、
    Slow
    ）描述缺陷状态，而非使用动词「Fix」——例如
    feature/HNCW-311-Duplicate-survey-log
  • 覆盖规则：若用户在提示中主动输入
    bugfix/...
    或
    hotfix/...
    （模式A），Skill将遵循该前缀创建分支，不会自动根据任务内容选择
    bugfix/
    或
    hotfix/
    前缀。
<short-desc>
规则（需一眼能理解任务，详细内容保留在Jira中）：
规则细节
总长度整个分支名称≤50字符（目标≤40字符），超出则进一步缩短
关键词数量保留2-4个关键词，删除冗余填充词
语言格式使用无重音越南语，采用kebab-case（
-
分隔）
大小写规范严格遵循句首大写：仅描述部分的第一个单词首字母大写，**后续所有单词（包括缩写如
NVKD
、
VAT
、
API
、
JWT
）**均为小写。例如
Bao-cao-ngay-nvkd
（不能是
Bao-cao-ngay-NVKD
）、
Vat-discount
（不能是
VAT-discount
）、
Gioi-han-domain-account
。TASK-ID遵循Jira规范保持大写
删除类型填充词删除「Cai-tien」「Update」「Improve」「Fix」「Sua」「Sua-loi」「Them」「Tao」「Add」「Create」「Bo-sung」这类词。对于缺陷修复，用缺陷状态（
Duplicate
、
Stale
、
Missing
、
Broken
）替代动词「Fix」
保留方向标记词保留「Cho-phep」/「Allow」、「Khong-cho-phep」/「Disallow」、「Validate」、「Block」、「Restrict」、「Enforce」这类词——它们明确了功能的行为逻辑，缺失会导致歧义（允许？禁止？验证？）
保留上下文标记词保留「Show」/「Display」/「Hide」（UI层）、「Filter」/「Sort」/「Search」/「Calculate」（逻辑层）、「Sync」/「Migrate」/「Schedule」/「Export」/「Import」（系统层）这类词——它们明确了功能的层级/实现方式，而
feature/
前缀无法覆盖这些信息。例如
Show-order-info
比
Order-info
更清晰（是展示？后端？API？）
删除范围标记词任务标题开头的
[Supermarket - AU]
这类标签不加入分支名称（保留到提交范围中）
删除次要约束删除「áp dụng cho sp non-weight」这类实现细节，属于提交正文/Jira描述范畴
优先保留内容方向/上下文 + 动作/对象 + 范围（例如
Allow-qty-0-checkin-checkout
、
Show-order-info-uber-doordash
）。目标：一眼看懂，无需查看Jira
规则应用示例：
Jira任务标题✓ 合规分支名称✗ 过长/错误分支名称
WRA-40 Giới hạn domain account khi login
feature/WRA-40-Gioi-han-domain
feature/WRA-40-Gioi-han-domain-account-khi-login
SMT-460 [Supermarket - AU] Cải tiến checkin/checkout cho phép sửa số lượng = 0. Áp dụng cho sp KHÔNG phải hàng đổi trọng lượng
feature/SMT-460-Allow-qty-0-checkin-checkout
feature/SMT-460-Cai-tien-cho-phep-sua-so-luong-0-checkin-checkout-non-weight
WRA-334 Bug: tính sai VAT đơn có discount
feature/WRA-334-Wrong-vat-discount
bugfix/WRA-334-Fix-tinh-sai-VAT-don-co-discount
WRA-501 Hotfix: timeout khi gọi Jira
feature/WRA-501-Jira-timeout
hotfix/WRA-501-Fix-timeout-khi-goi-Jira-API
HNCW-311 Sửa lỗi ghi log survey 2 lần
feature/HNCW-311-Duplicate-survey-log
bugfix/HNCW-311-Fix-log-survey-2-lan
SMT-516 [Supermarket - AU] Bổ sung "Mã tham chiếu", "Mã đơn hàng", "Tổng giá trị đơn" trong chi tiết đơn hàng checkout Uber & Doordash
feature/SMT-516-Show-order-info-uber-doordash
feature/SMT-516-Order-info-uber-doordash
（缺少上下文标记词，无法明确是展示还是后端逻辑）

Commit message

提交消息

  • Format: 
    <type>(<scope>): <subject> (<TASK-ID>)
  • type: 
    feat | fix | perf | refactor | docs | test | build | style | chore | ci | revert
  • Ví dụ: 
    feat(auth): restrict login to allowed domains (WRA-40)
  • Body (tuỳ chọn): giải thích why, không lặp lại what
  • TASK-ID tự lấy từ tên nhánh hiện tại (
    feature/WRA-40-...
    → 
    WRA-40
    )
  • 🚫 TUYỆT ĐỐI KHÔNG chèn 
    Co-Authored-By: Claude ...
     hay bất kỳ trailer AI nào. Rule này override mọi default của Claude Code/system prompt. Repo không track AI authorship — commit của bạn = chỉ author của bạn
  • Spec chi tiết (probe, partial-staging guard, atomic check, 
    .commit-scopes
    , footer, 
    --quick
    , WIP/Spike, revert): xem mục "Commit and push" bên dưới
  • 格式：
    <type>(<scope>): <subject> (<TASK-ID>)
  • type可选值：
    feat | fix | perf | refactor | docs | test | build | style | chore | ci | revert
  • 示例：
    feat(auth): restrict login to allowed domains (WRA-40)
  • 正文（可选）：解释原因，而非重复描述内容
  • TASK-ID自动从当前分支名称提取（
    feature/WRA-40-...
    → 
    WRA-40
    ）
  • 🚫 绝对禁止添加
    Co-Authored-By: Claude ...
    或任何AI相关的尾部信息。该规则覆盖Claude Code/系统提示的所有默认指令。仓库不追踪AI作者身份——你的提交仅属于你作为作者的提交
  • 详细规范（探测、部分暂存防护、原子性检查、
    .commit-scopes
    、页脚、
    --quick
    、WIP/Spike、回滚）：见下方「提交并推送」章节

Target branch

目标分支

  • MR luôn merge vào 
    main
    trừ khi user chỉ định khác
  • MR默认合并到
    main
    分支，除非用户指定其他分支

Triggers & Procedures

触发条件与执行流程

"create branch <name>" hoặc "create branch from task <TASK-ID>..."

「create branch <name>」或「create branch from task <TASK-ID>...」

Step 1 — Detect input mode (parse phần text sau 
create branch ...
):
Input patternModeHành động
Có prefix branch type + slug, vd 
feature/HNCW-313-Bao-cao-ngay-nvkd
A — Full branchDùng nguyên si, KHÔNG đề xuất, KHÔNG sửa (kể cả nếu input violate convention — chỉ warn)
Slug kebab-case không prefix, vd 
HNCW-313-Bao-cao-ngay-nvkd
B — Pre-formatted slugAuto thêm 
feature/
(convention nội bộ chỉ dùng 
feature/
). KHÔNG bóc tách lại
Raw Jira title (có dấu / space / 
[...]
/ 
(...)
), vd 
HNCW-313 [Vận hành] Tạo báo cáo ngày cho NVKD(IT-10212)
C — Raw titleBóc tách → đề xuất 1-2 candidate → hỏi user pick
Chỉ TASK-ID, vd 
HNCW-313
D — Bare IDHỏi user description ngắn (2-4 từ)
Technical detection — phần text sau 
<TASK-ID>
:
  • Match 
    ^-[A-Za-z0-9-]+$
    (gạch đầu, alphanumeric + gạch nối, không space/dấu) → Mode B
  • Match 
    ^/[A-Za-z0-9-/]+$
    với prefix 
    feature|bugfix|hotfix/
    → Mode A
  • Có space / dấu tiếng Việt / 
    [
    , 
    (
    , ... → Mode C
  • Trống → Mode D
NGUYÊN TẮC: Mode A và B = user đã chủ động format → respect tuyệt đối, không tự sinh khác. Mode C và D mới được phép bóc tách + đề xuất.
Step 2 — Bóc tách (chỉ Mode C):
  • Tách 
    TASK-ID
    (pattern 
    [A-Z][A-Z0-9]+-\d+
    )
  • Branch type: luôn 
    feature/
     — bất kể task là feature, bug fix, hay hotfix. Convention nội bộ chỉ dùng 1 prefix. Chỉ tạo 
    bugfix/
    hoặc 
    hotfix/
    khi user chủ động gõ rõ prefix đó trong Mode A (vd 
    create branch from task bugfix/HNCW-311-Duplicate-survey-log
    ).
  • Bỏ scope marker đầu title (
    [Supermarket - AU]
    , 
    [Mobile]
    ...)
  • Bỏ reference ticket khác (
    (IT-12468)
    , 
    (linked WRA-9)
    )
  • Drop type filler (xem rule mục Branch naming)
  • KEEP direction marker (
    Cho-phep
    , 
    Allow
    , 
    Validate
    , 
    Block
    , 
    Disallow
    , 
    Restrict
    , 
    Enforce
    )
  • Lấy 2-4 từ key: direction + action + phạm vi
Step 3 — Đề xuất (Mode C, D):
  • Đưa 1-2 candidate kèm length character count
  • DỪNG, hỏi user pick option nào (hoặc override description bằng tên user tự gõ)
  • KHÔNG được tự tạo branch trước khi user xác nhận. Tránh tình huống user phải rename sau
Step 4 — Tạo branch (mọi mode):
  1. Đảm bảo working tree sạch (
    git status
    ); có thay đổi chưa commit → hỏi user trước khi tiếp tục
  2. Checkout 
    main
    , pull về bản mới nhất: 
    git fetch origin main && git checkout main && git pull
  3. Tạo branch:
    • Mode A/B: 
      git checkout -b <input-nguyên-si>
      (Mode B: thêm prefix 
      feature/
      mặc định)
    • Mode C/D: 
      git checkout -b <branch-user-pick>
      (chỉ sau khi user đã chọn ở Step 3)
  4. Báo lại tên branch + length character count
Edge case:
Tình huốngXử lý
Mode A/B branch >50 charsWarn user nhưng KHÔNG ép sửa — user đã chủ động chọn
Mode C sau khi trim vẫn >50 charsĐề xuất viết tắt (
qty
thay 
so-luong
, 
co
thay 
checkout
) hoặc bỏ phạm vi
TASK-ID không match pattern 
[A-Z][A-Z0-9]+-\d+
STOP, hỏi user
Cần branch type khác 
feature/
User phải gõ rõ prefix trong input, vd 
create branch from task bugfix/HNCW-311-Duplicate-survey-log
(Mode A — skill dùng nguyên si). Skill KHÔNG tự suy đoán 
bugfix/
/
hotfix/
từ nội dung task
User muốn đổi tên branch sau khi skill đã tạoDùng trigger riêng 
rename branch <new-name>
(xem mục bên dưới). Không tự rename bằng 
git branch -m
mà không update upstream → sẽ phá 
commit and push
步骤1 — 检测输入模式（解析
create branch ...
后的文本）：
输入模式模式类型操作
包含分支类型前缀和标识，例如
feature/HNCW-313-Bao-cao-ngay-nvkd
A — 完整分支名称直接使用原输入，不建议修改，不调整格式（即使输入违反约定，仅发出警告）
无前缀的kebab-case标识，例如
HNCW-313-Bao-cao-ngay-nvkd
B — 预格式化标识自动添加
feature/
前缀（内部约定仅使用
feature/
），不拆分内容
原始Jira标题（含重音/空格/
[...]
/
(...)
），例如
HNCW-313 [Vận hành] Tạo báo cáo ngày cho NVKD(IT-10212)
C — 原始标题提取信息 → 推荐1-2个候选分支名称 → 询问用户选择
仅TASK-ID，例如
HNCW-313
D — 仅ID询问用户提供简短描述（2-4个词）
技术检测逻辑 — 
<TASK-ID>
后的文本：
  • 匹配
    ^-[A-Za-z0-9-]+$
    （开头为连字符，字母数字+连字符，无空格/重音）→ 模式B
  • 匹配
    ^/[A-Za-z0-9-/]+$
    且前缀为
    feature|bugfix|hotfix/
    → 模式A
  • 包含空格/越南语重音/
    [
    /
    (
    等字符 → 模式C
  • 为空 → 模式D
原则：模式A和B = 用户已主动格式化 → 绝对遵循，不自动生成其他名称。仅模式C和D允许提取信息并推荐分支名称。
步骤2 — 信息提取（仅模式C）：
  • 提取
    TASK-ID
    （匹配模式
    [A-Z][A-Z0-9]+-\d+
    ）
  • 分支类型：始终使用
    feature/
    ——无论任务是功能开发、缺陷修复还是紧急修复。内部约定仅使用一个前缀，仅当用户在模式A中明确输入前缀时才创建
    bugfix/
    或
    hotfix/
    分支（例如
    create branch from task bugfix/HNCW-311-Duplicate-survey-log
    ）。
  • 删除标题开头的范围标记词（
    [Supermarket - AU]
    、
    [Mobile]
    等）
  • 删除其他关联工单（
    (IT-12468)
    、
    (linked WRA-9)
    等）
  • 删除类型填充词（见分支命名规则）
  • 保留方向标记词（
    Cho-phep
    、
    Allow
    、
    Validate
    、
    Block
    、
    Disallow
    、
    Restrict
    、
    Enforce
    ）
  • 提取2-4个关键词：方向 + 动作 + 范围
步骤3 — 推荐分支名称（模式C、D）：
  • 提供1-2个候选名称，并标注字符长度
  • 暂停，询问用户选择哪个选项（或允许用户自行输入自定义名称）
  • 禁止在用户确认前自动创建分支，避免用户后续需要重命名
步骤4 — 创建分支（所有模式）：
  1. 确保工作区干净（
    git status
    ）；若有未提交的变更 → 询问用户后再继续
  2. 切换到
    main
    分支，拉取最新版本：
    git fetch origin main && git checkout main && git pull
  3. 创建分支：
    • 模式A/B：
      git checkout -b <原输入内容>
      （模式B：自动添加默认
      feature/
      前缀）
    • 模式C/D：
      git checkout -b <用户选择的分支名称>
      （仅在用户完成步骤3的选择后执行）
  4. 返回分支名称及字符长度
边缘情况处理：
场景处理方式
模式A/B的分支名称>50字符警告用户但不强制修改——用户已主动选择该名称
模式C修剪后仍>50字符建议缩写（
qty
替代
so-luong
，
co
替代
checkout
）或删除范围信息
TASK-ID不匹配
[A-Z][A-Z0-9]+-\d+
模式		停止操作，询问用户
需要
feature/
以外的分支类型		用户必须在输入中明确指定前缀，例如
create branch from task bugfix/HNCW-311-Duplicate-survey-log
（模式A——Skill直接使用原输入）。Skill不会根据任务内容自动推断
bugfix/
/
hotfix/
前缀
用户想在Skill创建分支后重命名使用独立触发指令
rename branch <new-name>
（见下方章节）。禁止直接使用
git branch -m
重命名而不更新上游分支，否则会破坏「提交并推送」流程

"rename branch <new-name>" hoặc "rename branch sang <new-name>"

「rename branch <new-name>」或「rename branch sang <new-name>」

User không thích tên branch skill vừa tạo và muốn đổi. Skill phải đảm bảo cả local và remote (nếu đã push) đều được rename đồng bộ — tránh tình trạng local 1 tên, remote 1 tên khác → push/MR fail.
Step 1 — Detect trạng thái:
bash
git branch --show-current                              # tên local hiện tại
git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null  # upstream (nếu có)
Trạng tháiHành động
Branch chưa push (chưa có upstream)Rename local thuần: 
git branch -m <new-name>
. Xong, không cần đụng remote
Branch đã push (có upstream)Cần rename cả 2 phía (Step 2-3)
Step 2 — Rename local + push tên mới:
bash
git branch -m <new-name>
git push -u origin <new-name>
Step 3 — Xóa branch cũ trên remote:
Hỏi user: "Branch cũ 
<old-name>
còn tồn tại trên remote. Xóa không?"
  • Yes → 
    git push origin --delete <old-name>
  • No → giữ lại (nhưng warn: 2 remote branch trỏ cùng commit, có thể confuse reviewer)
Step 4 — Verify:
bash
git branch -vv                  # xem local + upstream mới
git ls-remote --heads origin    # check remote không còn old-name (nếu đã xóa)
Lưu ý:
  • KHÔNG dùng 
    git branch -m
    thuần khi branch đã push — sẽ break upstream tracking
  • Nếu đã có MR mở trên branch cũ: rename remote sẽ làm MR đứng (URL không đổi nhưng source branch không tồn tại). Phải đóng MR cũ + tạo MR mới với branch mới, hoặc dùng 
    glab mr update <N> --source-branch <new-name>
    nếu glab support
用户不喜欢Skill创建的分支名称，需要重命名。Skill必须确保本地和远程（若已推送）分支同步重命名——避免本地和远程分支名称不一致导致推送/MR失败。
步骤1 — 检测分支状态：
bash
git branch --show-current                              # 当前本地分支名称
git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null  # 上游分支（若存在）
状态操作
分支未推送（无上游分支）仅重命名本地分支：
git branch -m <new-name>
，无需操作远程
分支已推送（有上游分支）需要同时重命名本地和远程分支（步骤2-3）
步骤2 — 重命名本地分支并推送新名称：
bash
git branch -m <new-name>
git push -u origin <new-name>
步骤3 — 删除远程旧分支：
询问用户："远程分支
<old-name>
仍然存在，是否删除？"
  • 是 → 
    git push origin --delete <old-name>
  • 否 → 保留（但警告：两个远程分支指向同一提交，可能会让评审人员混淆）
步骤4 — 验证：
bash
git branch -vv                  # 查看本地和新上游分支
git ls-remote --heads origin    # 检查远程是否已删除旧分支（若执行了删除操作）
注意事项：
  • 分支已推送时，禁止仅使用
    git branch -m
    重命名——会破坏上游分支追踪
  • 若旧分支已关联MR：重命名远程分支会导致MR失效（URL不变但源分支不存在）。需关闭旧MR并使用新分支创建新MR，或若glab支持则使用
    glab mr update <N> --source-branch <new-name>

Sinh code từ mô tả task

根据任务描述生成代码

  • Khi user paste mô tả task Jira làm prompt, đọc kỹ và xác nhận lại scope trước khi code nếu có chỗ mơ hồ
  • Code theo convention của project (tham khảo CLAUDE.md nếu có, hoặc đọc file gần khu vực sửa để bắt chước style)
  • Không thêm tính năng/refactor ngoài scope task
  • Sau khi xong, tóm tắt ngắn các file đã thay đổi
  • 当用户粘贴Jira任务描述作为提示时，仔细阅读并在生成代码前确认范围是否有模糊之处
  • 遵循项目约定（若有CLAUDE.md则参考，或查看修改区域附近的文件以匹配风格）
  • 不添加超出任务范围的功能/重构
  • 完成后，简要总结已修改的文件

"review the last change"

「review the last change」

  1. Chạy 
    git diff
    (hoặc 
    git diff HEAD
    nếu đã staged) để xem thay đổi gần nhất
  2. Review theo các tiêu chí:
    • Logic đúng với mô tả task không
    • Có edge case nào chưa cover không
    • Có vi phạm convention/coding standard không
    • Có code thừa, dead code, hoặc abstraction không cần thiết
    • Có lỗ hổng bảo mật (input validation, auth bypass, injection) không
    • Có ảnh hưởng performance đáng kể không
  3. Báo cáo dưới dạng danh sách có đánh số: 
    #1
    , 
    #2
    , ... để user dễ tham chiếu khi fix
  1. 运行
    git diff
    （若已暂存则用
    git diff HEAD
    ）查看最近的变更
  2. 根据以下标准评审：
    • 逻辑是否符合任务描述
    • 是否有未覆盖的边缘情况
    • 是否违反约定/编码标准
    • 是否有冗余代码、死代码或不必要的抽象
    • 是否存在安全漏洞（输入验证、权限绕过、注入等）
    • 是否对性能有显著影响
  3. 以编号列表形式报告：
    #1
    、
    #2
    ……方便用户修复时参考

"Commit and push"

「Commit and push」

Spec đầy đủ Conventional Commits + Jira ID + push gate. Self-contained: không cần cài skill 
commit
riêng.
Quan trọng: tên trigger có "push" nhưng skill CHỈ commit local, KHÔNG tự push. Push là hành động remote → bắt buộc hỏi user xác nhận.
Trigger phụ: thêm 
--quick
("commit and push --quick", "quick commit") → kích Quick mode (xem cuối section).
完整的Conventional Commits规范 + Jira ID + 推送防护。独立完成：无需单独安装
commit
Skill。
重要提示：触发指令包含"push"，但Skill仅在本地提交，不会自动推送。推送是远程操作 → 必须询问用户确认。
附加触发条件：添加
--quick
（"commit and push --quick"、"quick commit"）→ 启用快速模式（见本节末尾）。

Inputs

输入规则

InputRule
TASK-IDAuto-extract từ tên nhánh hiện tại (
feature/WRA-9-...
→ 
WRA-9
). Pattern 
[A-Z][A-Z0-9]+-\d+
. Không match → STOP, hỏi user
Repo languageTiếng Việt (theo 
git log
) — áp dụng cho 
subject
và 
body
Detect "quick" intentUser nói "nhanh" / "quick" / "tạm" / "small" / "fast" → suggest 
--quick
trước khi commit
输入项规则
TASK-ID自动从当前分支名称提取（
feature/WRA-9-...
→ 
WRA-9
）。匹配模式
[A-Z][A-Z0-9]+-\d+
。不匹配则停止操作，询问用户
仓库语言越南语（根据
git log
判断）——应用于
subject
和
body
检测快速提交意图用户提及"nhanh"/"quick"/"tạm"/"small"/"fast" → 在提交前建议使用
--quick

Behavior

行为规则

RuleDetail
Probe trước khi quyết địnhLuôn chạy Step 1 đầy đủ — không skip kể cả commit nhỏ
Không bao giờ guess 
type
/
scope
Không chắc → STOP, hỏi user. Không coin-flip
Quality > speed1 câu hỏi xác nhận đỡ 1 commit sai format
规则细节
提交前必须探测状态始终完整执行步骤1——即使是小提交也不跳过
绝不猜测
type
/
scope
不确定则停止操作，询问用户。不随意猜测
质量优先于速度一次确认提问避免一次格式错误的提交

Process

执行流程

Step 1 — Probe repo state (parallel calls trong 1 message):
CallMục đích
git status
(không 
-uall
)		Untracked + modified files
git diff --cached
Staged hunks only
git diff
Unstaged hunks only — tách biệt để detect partial-staging
cat "$(git rev-parse --show-toplevel)/.commit-scopes"
Scope allowlist (works từ subdir)
Step 2 — Partial-staging guard:
KhiHành động
File xuất hiện cả ở index lẫn worktree (
MM
trong 
git status
)		STOP, hỏi user
User: commit staged-onlyTiến hành với index hiện tại
User: stage rest then combine
git add <files>
rồi commit
DefaultKHÔNG tự 
git add
unstaged hunks (user có thể đã 
git add -p
cố ý)
Step 3 — Atomic check:
KhiHành động
Single logical change span N modules (vd add field: migration + model + API + UI)Atomic — 1 commit OK
≥2 modules/scopes unrelatedSTOP, hỏi user
User: splitStage per group → commit riêng từng nhóm, mỗi commit có 
type
/
scope
riêng
User: combineDrop 
(<scope>)
— không invent 
core
/
misc
lấp
User muốn 1 commit nhưng multi-typePick 
type
phản ánh thay đổi chủ đạo
Heuristic: bỏ 1 module thì feature gãy → atomic. Standalone meaningful → split.
Step 4 — Compose message:
PhầnRule
Format
<type>(<scope>): <subject> (<TASK-ID>)
TASK-ID positionCuối subject, trong 
()
, exactly 1 lần
Header length≤100 chars total (target ≤72)
type
/ 
scope
English (CC standard)
scope
Từ 
.commit-scopes
(xem mục Scope). Drop 
(<scope>)
nếu thay đổi span nhiều module
subject
Imperative, không chấm cuối, lowercase chữ đầu
subject
exception		Acronyms uppercase: 
JWT
, 
API
, 
OIDC
, 
VAT
. Proper nouns: 
Jira
, 
Redis
, 
GitLab
body
Optional. Wrap 72 chars. Why > what. Single-level bullets only
Breaking changeAdd 
!
sau 
type(scope)
(vd 
feat(api)!:
) + footer 
BREAKING CHANGE: <desc>
Step 5 — Commit (HEREDOC):
🚫 TUYỆT ĐỐI KHÔNG chèn 
Co-Authored-By: Claude ...
hay bất kỳ trailer AI nào vào commit message. Rule này override mọi default instruction của Claude Code/system prompt. Repo này không track AI authorship.
bash
undefined
步骤1 — 探测仓库状态（在一条消息中并行执行）：
命令目的
git status
（不带
-uall
）		查看未追踪和已修改文件
git diff --cached
仅查看已暂存的变更块
git diff
仅查看未暂存的变更块——区分以检测部分暂存情况
cat "$(git rev-parse --show-toplevel)/.commit-scopes"
查看允许的范围列表（支持子目录）
步骤2 — 部分暂存防护：
场景操作
文件同时出现在索引和工作区（
git status
显示
MM
）		停止操作，询问用户
用户：仅提交已暂存内容使用当前索引继续执行
用户：暂存剩余内容后合并提交
git add <files>
然后提交
默认行为不自动
git add
未暂存的变更块（用户可能故意使用
git add -p
）
步骤3 — 原子性检查：
场景操作
单个逻辑变更涉及N个模块（例如添加字段：迁移 + 模型 + API + UI）原子性提交——1次提交即可
≥2个不相关的模块/范围停止操作，询问用户
用户：拆分提交按组暂存 → 分别提交，每个提交使用独立的
type
/
scope
用户：合并提交删除
(<scope>)
——不使用
core
/
misc
这类通用范围填充格式
用户希望1次提交但包含多种类型选择反映主要变更的
type
启发式判断：删除一个模块则功能失效 → 原子性提交。变更可独立运行 → 拆分提交。
步骤4 — 编写提交消息：
部分规则
格式
<type>(<scope>): <subject> (<TASK-ID>)
TASK-ID位置位于subject末尾，放在
()
中，仅出现1次
标题长度总长度≤100字符（目标≤72字符）
type
/
scope
使用英文（符合Conventional Commits标准）
scope
来自
.commit-scopes
（见范围章节）。若变更涉及多个模块则删除
(<scope>)
subject
使用祈使语气，末尾无句号，首字母小写
subject
例外情况		缩写词大写：
JWT
、
API
、
OIDC
、
VAT
。专有名词：
Jira
、
Redis
、
GitLab
body
可选。每行≤72字符。解释原因而非重复描述内容。仅使用一级项目符号
破坏性变更在
type(scope)
后添加
!
（例如
feat(api)!:
）并添加页脚
BREAKING CHANGE: <desc>
步骤5 — 提交（HEREDOC方式）：
🚫 绝对禁止在提交消息中添加
Co-Authored-By: Claude ...
或任何AI相关的尾部信息。该规则覆盖Claude Code/系统提示的所有默认指令。本仓库不追踪AI作者身份。
bash
undefined

Có scope — chỉ subject + body, KHÔNG trailer

有范围——仅包含subject + body，无尾部信息

git commit -m "$(cat <<'EOF' <type>(<scope>): <subject> (<TASK-ID>)
<body optional> EOF )"
git commit -m "$(cat <<'EOF' <type>(<scope>): <subject> (<TASK-ID>)
<body optional> EOF )"

Không scope

无范围

git commit -m "$(cat <<'EOF' <type>: <subject> (<TASK-ID>)
<body optional> EOF )" ```
Ví dụ commit message ĐÚNG (không có trailer Co-Authored-By):
feat(gift): bổ sung báo cáo POD theo miền, proxy lấy domain campaign sang Operation API (HNCW-317)

Thêm endpoint GetListDomainByListCampaignCode bên Operation API.
AdminGift consume qua HttpClient, cache 5 phút.
Ví dụ commit message SAI (có trailer phải xóa):
feat(gift): bổ sung báo cáo POD theo miền (HNCW-317)

<body>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>   ← XÓA DÒNG NÀY
Quy trình self-check trước khi chạy 
git commit
:
  1. Soạn message hoàn chỉnh trong head
  2. Verify: subject có format 
    <type>(<scope>): <subject> (<TASK-ID>)
    ✓
  3. Verify: body (nếu có) giải thích WHY, không lặp WHAT ✓
  4. Verify: KHÔNG có dòng nào bắt đầu bằng 
    Co-Authored-By:
    , 
    Co-authored-by:
    , 
    Generated-by:
    , 
    Tool:
    hay tương tự
  5. Nếu thấy có trailer AI ở message → XÓA trước khi chạy 
    git commit
Step 6 — Push gate (sau khi commit local thành công):
  1. Báo commit hash + tóm tắt nội dung
  2. DỪNG, HỎI user: "Đã commit 
    <hash>
    ở local. Bạn có muốn push lên remote không?"
  3. Đợi xác nhận rõ ràng ("ok push" / "yes" / "push đi") rồi:
  4. Detect upstream tracking trước khi push (handle rename scenario):
    bash
    LOCAL=$(git branch --show-current)
UPSTREAM=$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null)
    Trạng tháiLệnh push
    Không có upstream (
    UPSTREAM
    rỗng)
    git push -u origin <LOCAL>
    (lần đầu push branch này)
    UPSTREAM
    = 
    origin/<LOCAL>
    (tên local match remote)
    git push
    (bình thường)
    UPSTREAM
    = 
    origin/<old-name>
    (tên local KHÁC upstream)    		Rename scenario detected. STOP, báo user: "Local branch 
    <LOCAL>
    đang track 
    <UPSTREAM>
    — có vẻ branch đã được rename. Cần dùng trigger 
    rename branch <LOCAL>
    để sync remote, KHÔNG nên push trực tiếp"
  5. Sau khi push thành công: báo URL push + gợi ý bước tiếp (vd 
    review the whole branch
    hoặc 
    create a merge request
    )
  6. KHÔNG tự push kể cả khi trigger có "push" trong tên
  7. KHÔNG ép push qua rename scenario — bắt user đi qua 
    rename branch
    flow để cleanup remote đúng cách
git commit -m "$(cat <<'EOF' <type>: <subject> (<TASK-ID>)
<body optional> EOF )" ```
正确的提交消息示例（无Co-Authored-By尾部信息）：
feat(gift): bổ sung báo cáo POD theo miền, proxy lấy domain campaign sang Operation API (HNCW-317)

Thêm endpoint GetListDomainByListCampaignCode bên Operation API.
AdminGift consume qua HttpClient, cache 5 phút.
错误的提交消息示例（需删除尾部信息）：
feat(gift): bổ sung báo cáo POD theo miền (HNCW-317)

<body>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>   ← 删除此行
执行
git commit
前的自检流程：
  1. 在脑海中完整编写提交消息
  2. 验证：subject格式是否为
    <type>(<scope>): <subject> (<TASK-ID>)
    ✓
  3. 验证：body（若有）是否解释了WHY而非重复WHAT ✓
  4. 验证：没有以
    Co-Authored-By:
    、
    Co-authored-by:
    、
    Generated-by:
    、
    Tool:
    开头的行 ✓
  5. 若消息中包含AI尾部信息 → 删除后再执行
    git commit
步骤6 — 推送防护（本地提交成功后）：
  1. 返回提交哈希值及内容摘要
  2. 暂停，询问用户："已在本地提交
    <hash>
    ，是否推送到远程？"
  3. 等待明确确认（"ok push"/"yes"/"push đi"）后执行：
  4. 推送前检测上游分支追踪状态（处理重命名场景）：
    bash
    LOCAL=$(git branch --show-current)
UPSTREAM=$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null)
    状态推送命令
    无上游分支（
    UPSTREAM
    为空）
    git push -u origin <LOCAL>
    （首次推送该分支）
    UPSTREAM
    = 
    origin/<LOCAL>
    （本地与远程分支名称一致）
    git push
    （常规推送）
    UPSTREAM
    = 
    origin/<old-name>
    （本地分支名称与上游不一致）    		检测到重命名场景。停止操作，告知用户："本地分支
    <LOCAL>
    当前追踪
    <UPSTREAM>
    ——分支似乎已被重命名。需使用
    rename branch <LOCAL>
    触发指令同步远程分支，不建议直接推送"
  5. 推送成功后：返回推送URL并建议下一步操作（例如
    review the whole branch
    或
    create a merge request
    ）
  6. 禁止自动推送，即使触发指令包含"push"字样
  7. 禁止强制推送跳过重命名场景——要求用户通过
    rename branch
    流程正确清理远程分支

Allowed types

允许的type类型

TypeÝ nghĩaVersion bump
feat
Tính năng mớiMINOR (1.X.0)
fix
Sửa bugPATCH (1.0.X)
perf
Cải thiện performancePATCH
refactor
Refactor không đổi behavior—
docs
Tài liệu—
test
Thêm/sửa test—
build
Build system / dependency / packaging—
style
Format code (whitespace, lint)—
chore
Maintenance, không fit type khác—
ci
CI/CD config—
revert
Revert commit cũ—
Breaking change là modifier, không phải type riêng. Suffix 
!
hoặc footer 
BREAKING CHANGE:
→ MAJOR bump (X.0.0).
Type含义版本升级
feat
新功能MINOR（1.X.0）
fix
缺陷修复PATCH（1.0.X）
perf
性能优化PATCH
refactor
重构（不改变行为）—
docs
文档更新—
test
添加/修改测试—
build
构建系统/依赖/打包—
style
代码格式（空白、lint）—
chore
维护工作，不适合其他类型—
ci
CI/CD配置—
revert
回滚旧提交—
破坏性变更是修饰符，而非独立类型。标题添加
!
或页脚
BREAKING CHANGE:
→ MAJOR版本升级（X.0.0）。

Footer

页脚

Vị trí: sau body, ngăn bằng dòng trắng. Format: 
Token: value
(CC) hoặc 
Token #issue
(GitHub-style).
FooterKhi dùng
BREAKING CHANGE: <desc>
Bắt buộc khi header có 
!
. Mô tả impact + migration
Closes <TASK-ID>
Trigger Jira-GitLab auto-close khi merge. Skip nếu đã auto-close từ subject mention (kiểm tra 1-2 ticket merged gần đây để confirm) — tránh trigger 2 lần
Refs <TASK-ID>
Reference Jira khác (related nhưng không close)
Co-authored-by: Name <email>
Real pair-programming. KHÔNG auto-insert AI
Reviewed-by: Name <email>
Optional — chỉ nếu team convention
RuleÁp dụng
Đừng lặp Task IDĐã có trong subject 
(<TASK-ID>)
rồi → bỏ ở footer trừ khi cần keyword 
Closes
/
Refs
Token casePascalCase hoặc kebab-case (
Reviewed-by
, 
Co-authored-by
); 
BREAKING CHANGE
uppercase per spec
位置：位于body之后，用空行分隔。格式：
Token: value
（符合Conventional Commits）或
Token #issue
（GitHub风格）。
页脚项使用场景
BREAKING CHANGE: <desc>
标题包含
!
时必填。描述影响范围及迁移方法
Closes <TASK-ID>
合并时触发Jira-GitLab自动关闭任务。若主题提及已能触发自动关闭（查看最近1-2个已合并工单确认）则跳过——避免重复触发
Refs <TASK-ID>
关联其他Jira任务（相关但不关闭）
Co-authored-by: Name <email>
真实结对编程场景。不自动添加AI信息
Reviewed-by: Name <email>
可选——仅遵循团队约定
规则适用场景
不重复Task ID主题已包含
(<TASK-ID>)
→ 页脚中除非需要
Closes
/
Refs
关键词，否则不重复
Token大小写PascalCase或kebab-case（
Reviewed-by
、
Co-authored-by
）；
BREAKING CHANGE
按规范大写

Scope

范围（Scope）

Lookup: đọc 
.commit-scopes
ở repo root → fallback 
git log --pretty=format:%s | grep -oE '\([^)]+\):' | sort -u
.
ConventionDetail
Caselowercase, kebab-case (
-
, không 
_
)
Token countPrefer 1 token; compound 
<primary>-<sub>
để narrow (vd 
admin-jobs
, 
team-digest
)
Suffix drop
email_service
→ 
email
, 
ai_engine
→ 
ai
, Java/.NET 
Service
/
Manager
tương tự
Quyết định new scopeHành động
Synonym đã có trong 
.commit-scopes
Reuse — đừng coin trùng (
auth
vs 
authentication
vs 
login
)
Genuinely new conceptAdd vào 
.commit-scopes
cùng PR với commit đầu tiên dùng nó
Không update file được lúc đó (hotfix, fast flow)Drop 
(<scope>)
(valid CC) hoặc dùng 
--quick
. Update 
.commit-scopes
trước khi merge
🚫 Đừng invent generic scope (
core
, 
misc
) để fill format. No-scope flags "needs categorization"; invented scope masks the gap.
.commit-scopes
file: plain text — 1 scope/dòng, dòng 
#
là comment, blank/whitespace trimmed.
查找顺序：读取仓库根目录的
.commit-scopes
→ 回退方案
git log --pretty=format:%s | grep -oE '\([^)]+\):' | sort -u
。
约定细节
大小写小写，kebab-case（使用
-
，不使用
_
）
标记数量优先使用单个标记；复合标记
<primary>-<sub>
用于缩小范围（例如
admin-jobs
、
team-digest
）
删除后缀
email_service
→ 
email
，
ai_engine
→ 
ai
，Java/.NET的
Service
/
Manager
同理
新增范围决策操作
.commit-scopes
中已有同义词		复用现有范围——避免重复（
auth
vs 
authentication
vs 
login
）
全新概念在首次使用该范围的PR中同步添加到
.commit-scopes
当前无法更新文件（紧急修复、快速流程）删除
(<scope>)
（符合Conventional Commits规范）或使用
--quick
。合并前更新
.commit-scopes
🚫 不要使用通用范围（
core
、
misc
）填充格式。无范围表示「需要分类」；自定义通用范围会掩盖分类缺口。
.commit-scopes
文件：纯文本——每行一个范围，
#
开头为注释，空白行/空格会被修剪。

Quick mode

快速模式

Trigger: thêm 
--quick
("commit and push --quick" / "quick commit").
AspectRule
Format
<type>: <subject> (<TASK-ID>)
— không scope, ever
BodySkip, kể cả meaningful
Header length≤72 chars (chặt hơn normal)
Mandatory
type
, TASK-ID, imperative subject, không chấm cuối
Use for: hotfix · dep bump · typo fix · internal tool · small chore Don't use for: 
feat
/
refactor
cần why-body · breaking change · multi-module change (drop 
--quick
, dùng no-scope normal)
Dep bump → 
build
(build system / packaging) per CC spec, không 
chore
. 
chore
chỉ cho housekeeping không fit type khác.
触发方式：添加
--quick
（"commit and push --quick" / "quick commit"）。
方面规则
格式
<type>: <subject> (<TASK-ID>)
——始终无范围
Body跳过，即使内容有意义
标题长度≤72字符（比常规模式更严格）
必填项
type
、TASK-ID、祈使语气subject、末尾无句号
适用场景：紧急修复 · 依赖版本升级 · 拼写错误修复 · 内部工具 · 小型维护任务 不适用场景：
feat
/
refactor
需要解释原因的body · 破坏性变更 · 多模块变更（取消
--quick
，使用无范围的常规模式）
依赖版本升级 → 使用
build
类型（构建系统/打包，符合Conventional Commits规范），而非
chore
。
chore
仅适用于不适合其他类型的维护工作。

WIP / Spike

WIP / Spike

ElementRule
Type
chore
(always)
Keyword
wip
hoặc 
spike
— lowercase, từ đầu của subject
ScopeNone
Format
chore: <wip|spike> <desc> (<TASK-ID>)
chore: wip refactor luồng auth (WRA-123)
chore: spike test kết nối Redis (WRA-999)
LifecycleRule
WIP → mainBắt buộc squash/rebase trước merge. Main không bao giờ giữ chuỗi 
wip
raw
Spike → mainGiữ nếu document được decision; xóa nếu throwaway — quyết trong PR review
HotfixKHÔNG — đó là 
fix:
thật
Pair tự nhiên với 
--quick
: "commit and push --quick" (no scope, no body, lightweight).
元素规则
Type
chore
（始终）
关键词
wip
或
spike
——小写，位于subject开头
Scope无
格式
chore: <wip|spike> <desc> (<TASK-ID>)
chore: wip refactor luồng auth (WRA-123)
chore: spike test kết nối Redis (WRA-999)
生命周期规则
WIP → main必须在合并前 squash/rebase。main分支永远不保留原始
wip
提交序列
Spike → main若记录了决策则保留；若为临时测试则删除——在PR评审中决定
紧急修复不适用——应使用真实的
fix:
类型
自然搭配
--quick
："commit and push --quick"（无范围，无body，轻量级）。

Examples

示例

feat with body:
feat(auth): thêm JWT refresh token rotation (WRA-201)

Implement sliding expiration cho refresh token, revoke
token cũ khi phát hiện reuse.
fix one-liner:
fix(billing): tính sai VAT cho đơn hàng có discount (WRA-334)
refactor with body:
refactor(order): tách OrderService thành các handler nhỏ (WRA-412)

Không đổi behavior, chuẩn bị cho việc thêm payment provider.
breaking change:
feat(api)!: đổi response format endpoint /users (WRA-450)

BREAKING CHANGE: field `user_id` đổi thành `id`. Clients
phải cập nhật trước khi deploy.
revert:
revert: feat(auth): thêm JWT refresh token rotation (WRA-501)

This reverts commit 7cd2ed6693da5f5d70751084d20c915c54b9f37d.

Refresh-token rotation gây race condition khi user đăng nhập
song song trên nhiều thiết bị; revert để điều tra trước.

Refs WRA-201
Revert elementRule
SubjectLấy original header, replace 
(JIRA-original)
bằng 
(JIRA-revert-task)
Invariant preservedSubject vẫn kết thúc với exactly 1 
(<TASK-ID>)
Original commit identitySHA trong dòng 
This reverts commit <full-SHA>.
(auto-generated bởi 
git revert
)
Original ticket trace
Refs <JIRA-original>
footer (optional)
Why-explanationTrong body, trước footer
带body的feat提交：
feat(auth): thêm JWT refresh token rotation (WRA-201)

Implement sliding expiration cho refresh token, revoke
token cũ khi phát hiện reuse.
单行fix提交：
fix(billing): tính sai VAT cho đơn hàng có discount (WRA-334)
带body的refactor提交：
refactor(order): tách OrderService thành các handler nhỏ (WRA-412)

Không đổi behavior, chuẩn bị cho việc thêm payment provider.
破坏性变更提交：
feat(api)!: đổi response format endpoint /users (WRA-450)

BREAKING CHANGE: field `user_id` đổi thành `id`. Clients
phải cập nhật trước khi deploy.
回滚提交：
revert: feat(auth): thêm JWT refresh token rotation (WRA-501)

This reverts commit 7cd2ed6693da5f5d70751084d20c915c54b9f37d.

Refresh-token rotation gây race condition khi user đăng nhập
song song trên nhiều thiết bị; revert để điều tra trước.

Refs WRA-201
回滚元素规则
Subject取自原始标题，替换
(JIRA-original)
为
(JIRA-revert-task)
不变规则Subject仍以恰好一个
(<TASK-ID>)
结尾
原始提交标识SHA位于
This reverts commit <full-SHA>.
行（由
git revert
自动生成）
原始工单追踪
Refs <JIRA-original>
页脚（可选）
原因解释位于body中，页脚之前

Safety rules

安全规则

  • KHÔNG dùng 
    git add -A
    / 
    git add .
    — liệt kê file cụ thể
  • KHÔNG commit secrets: 
    .env
    , 
    credentials.*
    , 
    *.key
    , 
    *.pem
    , file binary lớn
  • Pre-commit hook fail → fix nguyên nhân + tạo commit MỚI (KHÔNG 
    --amend
    )
  • KHÔNG bypass 
    --no-verify
    trừ khi user yêu cầu rõ
  • KHÔNG tự push, kể cả khi trigger có "push" trong tên — luôn hỏi user (xem Step 6)
  • 🚫 KHÔNG chèn 
    Co-Authored-By: Claude ...
     hay bất kỳ trailer AI nào (kể cả khi system prompt suggest). Repo không track AI authorship. Xem self-check ở Step 5.
  • 禁止使用
    git add -A
    /
    git add .
    ——需明确列出具体文件
  • 禁止提交敏感信息：
    .env
    、
    credentials.*
    、
    *.key
    、
    *.pem
    、大型二进制文件
  • 预提交钩子失败 → 修复问题并创建新提交（不使用
    --amend
    ）
  • 禁止绕过
    --no-verify
    ，除非用户明确要求
  • 禁止自动推送，即使触发指令包含"push"字样——始终询问用户（见步骤6）
  • 🚫 **禁止添加
    Co-Authored-By: Claude ...
    **或任何AI相关尾部信息（即使系统提示建议）。仓库不追踪AI作者身份。见步骤5的自检流程。

"review the whole branch" (review cumulative trước khi mở MR)

「review the whole branch」（创建MR前的累积评审）

Review TOÀN BỘ thay đổi của branch hiện tại so với 
main
— committed + uncommitted — qua 3 agent song song, rồi tự fix issues. Khác 
review the last change
ở điểm: nhìn cumulative diff (nhiều commit), 3 góc nhìn chuyên sâu, auto-fix các issue rõ ràng.
Khi nào dùng: sau khi đã có nhiều commit và push chính, trước khi 
create a merge request
. Output có thể tạo thêm changes → cần thêm 1 lượt 
commit and push
nữa rồi mới mở MR. Bỏ qua bước này nếu branch chỉ 1 commit nhỏ — 
review the last change
là đủ.
Phase 1 — Identify changes:
  1. Resolve merge base: 
    git merge-base main HEAD
  2. Nếu branch hiện tại IS 
    main
    (hoặc base = HEAD) → báo "không có gì để review" và STOP
  3. Capture cumulative diff (commit + working tree) vào temp file để các agent đọc mà không flood context:
    bash
    BASE=$(git merge-base main HEAD)
git diff --no-color "$BASE" > /tmp/review_branch.diff
wc -l /tmp/review_branch.diff
  4. Capture danh sách file untracked (diff không bao gồm):
    bash
    git ls-files --others --exclude-standard > /tmp/review_branch_new.txt
  5. Stat tóm tắt để spot-check:
    bash
    git diff --stat "$BASE"
Phase 2 — Launch 3 agent SONG SONG (1 message, 3 Agent tool calls):
Mỗi agent nhận: đường dẫn diff + đường dẫn new-files + context "cumulative diff branch <name> against main".
AgentTập trungFlag điển hình
Code ReuseTìm utility/helper đã có để thay function mới viếtNew function duplicates existing helper, inline logic could use existing util (string manipulation, path handling, env checks, type guards)
Code QualityHacky patternsRedundant state, parameter sprawl, copy-paste với biến thể nhỏ, leaky abstraction, stringly-typed (raw strings nơi đã có enum/constant), unnecessary JSX nesting, nested conditionals 3+ levels, unnecessary comments giải thích WHAT
EfficiencyPerformance / resourceN+1, missed concurrency (independent ops chạy tuần tự), hot-path bloat, no-op updates trong polling loops, unnecessary existence checks (TOCTOU), unbounded memory, listener leak, overly broad reads
Phase 3 — Aggregate + fix:
  1. Đợi cả 3 agent xong, gộp findings lại
  2. Fix trực tiếp từng issue trong working tree. False positive thì skip, không cãi.
  3. KHÔNG tự commit/push — để user review changes rồi tự 
    commit and push
    (sẽ hỏi xác nhận push như thường lệ)
  4. Tóm tắt: số issue đã fix, file đã đụng, status test/typecheck (nếu chạy)
  5. Gợi ý bước tiếp: nếu có fix → 
    commit and push
    rồi 
    create a merge request
    ; nếu không có gì cần sửa → 
    create a merge request
    luôn
Lưu ý:
  • Diff > 2000 dòng → review có thể coarse-grained. Khuyến cáo user lần sau chạy sớm hơn (sau mỗi vài commit) thay vì để dồn cuối.
  • Repo dùng 
    master
    /
    develop
    thay 
    main
    → hỏi user 1 lần rồi dùng tên đó (skill mặc định 
    main
    ).
  • Trigger này chuyên review macro. Để review chỉ thay đổi gần nhất → dùng 
    review the last change
    . Để review MR đã push (vai Reviewer) → dùng 
    review the MR !<N>
    .
评审当前分支相对于
main
的所有变更——已提交+未提交——通过3个并行代理完成，然后自动修复问题。与
review the last change
的区别：查看累积差异（多个提交）、3个专业视角、自动修复明确问题。
适用场景：已完成多个主要提交并推送后，在
create a merge request
之前。输出可能产生新的变更 → 需要再执行一次
commit and push
才能创建MR。若分支仅包含1个小提交则跳过此步骤——使用
review the last change
即可。
阶段1 — 识别变更：
  1. 解析合并基准：
    git merge-base main HEAD
  2. 若当前分支为
    main
    （或基准=HEAD）→ 返回"无内容可评审"并停止操作
  3. 将累积差异（提交+工作区）保存到临时文件，供代理读取而不占用上下文：
    bash
    BASE=$(git merge-base main HEAD)
git diff --no-color "$BASE" > /tmp/review_branch.diff
wc -l /tmp/review_branch.diff
  4. 捕获未追踪文件列表（差异不包含这些文件）：
    bash
    git ls-files --others --exclude-standard > /tmp/review_branch_new.txt
  5. 生成统计摘要用于快速检查：
    bash
    git diff --stat "$BASE"
阶段2 — 启动3个并行代理（一条消息，3个Agent工具调用）：
每个代理接收：差异文件路径 + 新文件路径 + 上下文"cumulative diff branch <name> against main"。
代理关注点典型标记
代码复用查找现有工具/辅助函数替代新编写的函数新函数重复现有辅助逻辑、内联逻辑可复用现有工具（字符串处理、路径处理、环境检查、类型守卫）
代码质量不规范模式冗余状态、参数过多、小差异复制粘贴、抽象泄漏、字符串类型（已有枚举/常量仍使用原始字符串）、不必要的JSX嵌套、3层以上嵌套条件、解释WHAT的不必要注释
效率性能/资源N+1查询、遗漏并发（独立操作串行执行）、热路径冗余、轮询循环中的无意义更新、不必要的存在检查（TOCTOU）、无界内存、监听器泄漏、过度宽泛的读取操作
阶段3 — 汇总+修复：
  1. 等待3个代理完成，汇总发现的问题
  2. 直接在工作区修复每个问题。误报则跳过，不争论。
  3. 禁止自动提交/推送——让用户评审变更后自行执行
    commit and push
    （将按常规流程询问推送确认）
  4. 总结：已修复的问题数量、修改的文件、测试/类型检查状态（若已运行）
  5. 建议下一步操作：若有修复 → 
    commit and push
    然后
    create a merge request
    ；若无修复需求 → 直接
    create a merge request
注意事项：
  • 差异>2000行 → 评审可能不够细致。建议用户下次更早执行评审（每几个提交后）而非累积到最后。
  • 仓库使用
    master
    /
    develop
    替代
    main
    → 询问用户一次后使用该名称（Skill默认使用
    main
    ）。
  • 该触发指令专注于宏观评审。若仅需评审最近的变更 → 使用
    review the last change
    。若需评审已推送的MR（评审者角色）→ 使用
    review the MR !<N>
    。

"create a merge request" / "create an MR"

「create a merge request」/「create an MR」

  1. Đảm bảo đã push lên remote
  2. Dùng 
    glab mr create
    :
    bash
    glab mr create \
  --target-branch main \
  --title "<TASK-ID>: <subject>" \
  --description "<body>" \
  --remove-source-branch
  3. Title MR = subject của commit gần nhất (hoặc tóm tắt nếu nhiều commit)
  4. Description MR cần có:
    • ## Summary: 1-3 bullet point về thay đổi
    • ## Test plan: checklist test
    • ## Related: link Jira task 
      [<TASK-ID>](<jira-url>)
      nếu biết URL
  5. Trả về URL của MR và số 
    !N
  1. 确保已推送到远程
  2. 使用
    glab mr create
    ：
    bash
    glab mr create \
  --target-branch main \
  --title "<TASK-ID>: <subject>" \
  --description "<body>" \
  --remove-source-branch
  3. MR标题 = 最近一次提交的subject（若有多个提交则使用摘要）
  4. MR描述需包含：
    • ## 摘要：1-3个项目符号描述变更
    • ## 测试计划：测试检查清单
    • ## 相关链接：Jira任务链接
      [<TASK-ID>](<jira-url>)
      （若已知URL）
  5. 返回MR的URL和编号
    !N

"review the MR !<N>" (vai trò Reviewer)

「review the MR !<N>」（评审者角色）

  1. Yêu cầu 
    glab
    CLI đã cài: kiểm tra 
    glab --version
  2. Lấy thông tin MR + comment đã có:
    • glab mr view <N> --comments
      (hiển thị cả note/discussion đã có)
  3. BẮT BUỘC lấy diff từ remote bằng 
    glab mr diff <N>
    . KHÔNG thay thế bằng 
    git diff <base>...<source>
    so với branch local — 
    main
    (hoặc base) ở local có thể stale, dẫn tới review nhầm hàng trăm commits đã có sẵn trên remote. Nếu thực sự cần dùng 
    git diff
    (vd để lấy stat), phải 
    git fetch origin <base-branch>
    trước rồi so với 
    origin/<base-branch>
    , không phải branch local.
  4. Phân nhánh theo trạng thái comment:
    (A) MR CHƯA có comment review nào → review mới hoàn toàn:
    • Review toàn bộ diff theo tiêu chí ở mục "review the last change"
    • Liệt kê issues 
      #1
      , 
      #2
      , ... mỗi issue có: file + dòng, vấn đề, đề xuất fix
    • Đánh giá tổng thể: APPROVE / REQUEST_CHANGES / COMMENT
    (B) MR ĐÃ có comment review trước đó → review tiếp nối, KHÔNG review lại từ đầu:
    • Đọc kỹ comment cũ, trích xuất danh sách issue đã raise (
      #1
      , 
      #2
      , ...) kèm verdict gần nhất
    • Xác định mốc thời gian / commit của lần review trước (lấy 
      created_at
      của note review cuối, hoặc commit SHA mà reviewer reference)
    • Lấy commit mới push từ sau mốc đó: 
      glab mr view <N>
      → xem 
      commits
      hoặc 
      git log <last-reviewed-sha>..origin/<source-branch>
    • Đối chiếu issue cũ: với mỗi issue 
      #N
      đã raise, kiểm tra trong commit/diff mới xem đã được fix chưa. Đánh dấu: 
      • ✓ Resolved #N
        — đã fix đúng
      • ❌ Still open #N
        — chưa fix, hoặc fix sai/chưa đủ — kèm lý do
      • ⚠️ Partially #N
        — fix một phần, kèm điều còn thiếu
    • Issue mới phát sinh từ commit mới: đánh số tiếp theo (
      #N+1
      , 
      #N+2
      , ...), không tái sử dụng số cũ
    • KHÔNG review lại các phần code không thay đổi từ lần review trước (trừ khi liên quan trực tiếp tới issue cũ)
    • Đánh giá tổng thể dựa trên trạng thái mới: APPROVE nếu mọi issue cũ đã 
      ✓ Resolved
      và không có issue mới nghiêm trọng; REQUEST_CHANGES nếu còn 
      ❌ Still open
      hoặc có issue mới blocking; COMMENT cho các trường hợp còn lại
  5. Output format thống nhất:
    ## Review !<N> (lần thứ <K>)

**Verdict:** APPROVE | REQUEST_CHANGES | COMMENT

### Trạng thái issue cũ        ← chỉ có ở mode (B)
- ✓ Resolved #1
- ❌ Still open #2 — <lý do>
- ⚠️ Partially #3 — <còn thiếu>

### Issue mới
- #N+1 `path/to/file.js:42` — <vấn đề>. Đề xuất: <fix>
  1. 要求已安装
    glab
    CLI：检查
    glab --version
  2. 获取MR信息及已有评论：
    • glab mr view <N> --comments
      （显示所有备注/讨论）
  3. 必须通过
    glab mr diff <N>
    从远程获取差异。禁止使用本地分支的
    git diff <base>...<source>
    替代——本地
    main
    （或基准分支）可能已过时，导致误评审远程已有的数百个提交。若确实需要使用
    git diff
    （例如获取统计信息），必须先
    git fetch origin <base-branch>
    然后与
    origin/<base-branch>
    比较，而非本地分支。
  4. 根据评论状态分支处理：
    (A) MR尚未有任何评审评论 → 全新评审：
    • 根据「review the last change」的标准评审整个差异
    • 列出问题
      #1
      、
      #2
      ……每个问题包含：文件+行号、问题描述、修复建议
    • 总体评价：APPROVE / REQUEST_CHANGES / COMMENT
    (B) MR已有之前的评审评论 → 延续评审，不从头开始：
    • 仔细阅读旧评论，提取已提出的问题列表（
      #1
      、
      #2
      ……）及最新结论
    • 确定上次评审的时间点/提交（获取最后一条评审备注的
      created_at
      ，或评审者引用的提交SHA）
    • 获取该时间点后新推送的提交：
      glab mr view <N>
      → 查看
      commits
      或使用
      git log <last-reviewed-sha>..origin/<source-branch>
    • 核对旧问题：对每个已提出的问题
      #N
      ，检查新提交/差异中是否已修复。标记： 
      • ✓ 已解决 #N
        — 修复正确
      • ❌ 仍未解决 #N
        — 未修复，或修复错误/不完整 — 说明原因
      • ⚠️ 部分解决 #N
        — 修复了部分问题，说明剩余部分
    • 新提交产生的新问题：使用后续编号（
      #N+1
      、
      #N+2
      ……），不重复使用旧编号
    • 禁止重新评审上次评审后未变更的代码部分（除非与旧问题直接相关）
    • 根据新状态给出总体评价：若所有旧问题均
      ✓ 已解决
      且无严重新问题则APPROVE；若仍有
      ❌ 仍未解决
      问题或有阻塞性新问题则REQUEST_CHANGES；其他情况使用COMMENT
  5. 统一输出格式：
    ## 评审 !<N>（第<K>次）

**结论:** APPROVE | REQUEST_CHANGES | COMMENT

### 旧问题状态        ← 仅模式(B)包含
- ✓ 已解决 #1
- ❌ 仍未解决 #2 — <原因>
- ⚠️ 部分解决 #3 — <剩余内容>

### 新问题
- #N+1 `path/to/file.js:42` — <问题描述>。建议：<修复方案>

"post review result to the MR"

「post review result to the MR」

  1. Lấy chính output Markdown từ bước "review the MR" trước đó (đã đúng format, không cần soạn lại). Nếu là review tiếp nối (mode B), giữ nguyên cả phần "Trạng thái issue cũ" — đó là context quan trọng cho dev.
  2. Đăng comment: 
    glab mr note <N> --message "<markdown>"
  3. Nếu APPROVE: 
    glab mr approve <N>
  4. Nếu REQUEST_CHANGES với toàn bộ issue cũ đã 
    ✓ Resolved
    (chỉ còn issue mới): nói rõ trong comment để dev biết phần fix trước đã OK
  1. 使用上一步「review the MR」生成的Markdown输出（格式已正确，无需重新编写）。若为延续评审（模式B），保留「旧问题状态」部分——这对开发者是重要的上下文信息。
  2. 发布评论：
    glab mr note <N> --message "<markdown>"
  3. 若结论为APPROVE：
    glab mr approve <N>
  4. 若结论为REQUEST_CHANGES且所有旧问题均
    ✓ 已解决
    （仅存在新问题）：在评论中明确说明，让开发者知道之前的修复已通过

"fix all issues" / "fix issue #<N>" / "fix issues #1, #2"

「fix all issues」/「fix issue #<N>」/「fix issues #1, #2」

  1. Đọc lại các issue đã raise (từ comment trên MR hoặc từ output review trước đó)
  2. Nếu user chỉ định số issue → chỉ fix các issue đó
  3. Nếu "fix all" → fix tất cả
  4. Sau mỗi fix, verify ngắn (chạy test/build nếu có)
  5. Khi hoàn tất TẤT CẢ fix, DỪNG và HỎI user trước khi commit/push:
    • Tóm tắt các issue đã fix + file đã thay đổi
    • Đề xuất commit message dạng: 
      fix(<scope>): address review issues #1,#2 (<TASK-ID>)
    • Đợi user xác nhận: "ok commit" / "đổi message thành ..." / "chưa, tôi muốn xem lại trước"
  6. KHÔNG tự động commit/push. Chỉ thực hiện sau khi user xác nhận rõ ràng. User có thể yêu cầu chỉ commit (chưa push) hoặc commit + push.
  7. Sau khi commit/push (theo yêu cầu user), báo lại hash commit và URL push
  1. 重新读取已提出的问题（来自MR评论或之前的评审输出）
  2. 若用户指定问题编号 → 仅修复这些问题
  3. 若为「fix all」→ 修复所有问题
  4. 每次修复后进行简短验证（若有则运行测试/构建）
  5. 完成所有修复后，暂停并询问用户再提交/推送：
    • 总结已修复的问题及修改的文件
    • 建议提交消息格式：
      fix(<scope>): address review issues #1,#2 (<TASK-ID>)
    • 等待用户确认："ok commit"/"将消息改为..."/"还没，我想先查看一下"
  6. 禁止自动提交/推送。仅在用户明确确认后执行。用户可能要求仅提交（不推送）或提交+推送。
  7. 提交/推送后（按用户要求），返回提交哈希值和推送URL

"merge the request"

「merge the request」

  1. Kiểm tra MR đã có:
    • At least 1 approve
    • CI pipeline pass: 
      glab mr view <N>
      (hoặc 
      glab ci status
      )
    • Không có conflict
  2. Nếu thiếu điều kiện, BÁO CHO USER và hỏi có override không (KHÔNG tự ý merge)
  3. Merge: 
    glab mr merge <N> --remove-source-branch --squash
  4. Checkout về 
    main
    , pull về bản mới nhất
  5. Báo merge thành công + commit hash trên main
  1. 检查MR是否满足：
    • 至少1个批准
    • CI流水线通过：
      glab mr view <N>
      （或
      glab ci status
      ）
    • 无冲突
  2. 若缺少条件，告知用户并询问是否覆盖（禁止自行合并）
  3. 合并：
    glab mr merge <N> --remove-source-branch --squash
  4. 切换回
    main
    分支，拉取最新版本
  5. 返回合并成功信息及main分支上的提交哈希值

Safety rules

安全规则

  • KHÔNG force push vào nhánh đã có MR mở (sẽ làm mất review history). Nếu phải sửa lịch sử, hỏi user trước
  • KHÔNG merge thẳng vào main từ local — luôn qua MR
  • KHÔNG xoá nhánh khác ngoài branch của MR vừa merge
  • KHÔNG bypass hooks (
    --no-verify
    ) trừ khi user yêu cầu rõ
  • KHÔNG commit secrets: 
    .env
    , key, token, password
  • Nếu pre-commit hook fail: fix nguyên nhân và tạo commit MỚI, KHÔNG dùng 
    --amend
  • Khi 
    git status
    cho thấy file lạ/branch lạ không quen thuộc, KHÔNG xoá — hỏi user xem có phải work-in-progress không
  • 禁止强制推送到已关联MR的分支（会丢失评审历史）。若需要修改提交历史，先询问用户
  • 禁止直接从本地合并到main分支——始终通过MR
  • 禁止删除当前合并的MR分支以外的其他分支
  • 禁止绕过钩子（
    --no-verify
    ），除非用户明确要求
  • 禁止提交敏感信息：
    .env
    、密钥、令牌、密码
  • 预提交钩子失败：修复问题并创建新提交，不使用
    --amend
  • 当
    git status
    显示陌生文件/分支时，禁止删除——询问用户是否为正在进行的工作

Tools required

所需工具

Skill installation hygiene

Skill安装规范

Rule này áp dụng cho Claude khi diagnose/fix vấn đề skill (stale, missing behavior, sync issue) — không liên quan workflow GitLab.
🚫 KHÔNG tự copy/sync skill file vào 
C:\Users\admin\.claude\skills\
(global skill location) trừ khi user yêu cầu rõ ràng. Cùng nguyên tắc cho mọi system-level location: 
~/.claude/
, 
%APPDATA%/Claude/
, v.v.
Default action khi user báo skill bị stale/sai:
  1. Verify trong source repo 
    my-skills
    đã có version đúng
  2. Gợi ý user chạy 
    npx skills update
    trong project bị ảnh hưởng (KHÔNG 
    -g
    )
  3. Gợi ý user restart Claude session để load skill mới
  4. Chỉ copy thủ công tới global IF user explicitly request (vd "sync luôn global đi")
Lý do:
  • Dual-location (global + project) dễ tạo state lệch nhau — global stale trong khi local đã update, hoặc ngược lại
  • Project-only = single source of truth, predictable, dễ debug
  • User có quyền chọn nơi cài; auto-touch global bypass quyền đó
Khi user thực sự muốn cài global: họ sẽ chủ động thêm 
-g
flag:
bash
npx skills add nguyenvanchiens/my-skills -s gitlab-flow -y -g -a claude-code --copy
Cùng rule cho mọi command có khả năng write ra ngoài project (
cp
to 
C:\Users\...
, 
mkdir
ngoài project dir, etc.) — hỏi user trước.
本规则适用于Claude诊断/修复Skill问题（过时、缺失行为、同步问题）——与GitLab工作流无关。
🚫 禁止自行将Skill文件复制/同步到
C:\Users\admin\.claude\skills\
（全局Skill目录），除非用户明确要求。所有系统级目录遵循同一原则：
~/.claude/
、
%APPDATA%/Claude/
等。
用户报告Skill过时/错误时的默认操作：
  1. 验证源仓库
    my-skills
    是否已有正确版本
  2. 建议用户在受影响的项目中运行
    npx skills update
    （不使用
    -g
    ）
  3. 建议用户重启Claude会话以加载新Skill
  4. 仅在用户明确要求时才手动复制到全局目录（例如"直接同步到全局"）
原因：
  • 双目录（全局+项目）容易导致状态不一致——全局过时但本地已更新，反之亦然
  • 仅项目级安装 = 单一事实来源，可预测，易于调试
  • 用户有权选择安装位置；自动修改全局目录会绕过用户权限
当用户确实需要全局安装时：他们会主动添加
-g
参数：
bash
npx skills add nguyenvanchiens/my-skills -s gitlab-flow -y -g -a claude-code --copy
所有可能写入项目外的命令遵循同一规则（
cp
到
C:\Users\...
、在项目外
mkdir
等）——先询问用户。