gitlab-flow

GitLab Flow（Jira → Code → MR → Merge）

新しい機能／バグ修正の標準的なワークフローです。役割は Developer（タスクの担当者）と Reviewer（MR のレビュー担当者）の 2 つです。このスキルでは、ユーザーが呼び出したプロンプトに従って Claude が各手順を正しく実行できるよう案内します。

Conventions

ブランチの命名

• デフォルト：すべてのブランチで feature/ を使用します — タスクが機能追加、バグ修正、ホットフィックスのいずれであっても同じです。
• 形式：feature/<TASK-ID>-<short-desc>
• feature/ 以下のバグ修正ブランチでは、「Fix」という動詞ではなく、方向性を示すマーカー（Duplicate、Stale、Missing、Broken、Wrong、Slow）を使ってバグの状態を説明します — 例：feature/HNCW-311-Duplicate-survey-log
• 例外：ユーザーがプロンプトで bugfix/... または hotfix/... を明示的に入力した場合（Mode A）→ スキルはその指定を尊重し、該当するプレフィックスで作成します。タスクの内容に基づいてスキルが bugfix/ や hotfix/ を自動的に選択することはありません。

<short-desc> のルール（ひと目でタスクを把握できる程度に簡潔にし、詳細は Jira に残します）：

Rule	Detail
全体の長さ	ブランチ全体で ≤ 50 文字（目標は ≤ 40）。超える場合はさらに短くします
単語数	主要な単語を 2～4 語。埋め草は削除します
言語	ベトナム語を声調記号なしで表記し、kebab-case にします（- で区切ります）
大文字・小文字	文頭のみ大文字にするルールを厳守：description の最初の単語の先頭文字だけを大文字にします。**以降の単語はすべて（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」はすべて削除します。バグ修正では、「Fix」という動詞ではなく、バグの状態（Duplicate、Stale、Missing、Broken）を説明します
方向性を示すマーカーを残す	「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] のようなタグはブランチに含めません（コミットのスコープとして残します）
追加の制約を削除	「重量変更対象外の商品に適用」などの実装の詳細は削除します。これらはコミット本文／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（コンテキストを示すマーカーが不足しており、表示なのかバックエンドなのかが不明）

コミットメッセージ

• 形式：<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)
• Body（任意）：whyを説明し、whatを繰り返さないでください
• TASK-IDは現在のブランチ名から自動取得します（feature/WRA-40-... → WRA-40）
• 🚫 Co-Authored-By: Claude ...や、AIに関するその他のトレーラーは絶対に挿入しないでください。 このルールはClaude Code／system promptのすべてのデフォルト設定に優先します。 リポジトリではAIによる著者情報を追跡しません。あなたのコミットのauthorはあなたのみです
• 詳細な仕様（probe、partial-staging guard、atomic check、.commit-scopes、footer、--quick、WIP／Spike、revert）については、下の**「Commit and push」**の項目を参照してください

ターゲットブランチ

• ユーザーが別途指定しない限り、MRは常にmainにマージします

出力言語（レビューと報告）

すべてのレビュー／報告トリガーに対する出力は、デフォルトでベトナム語にします。ユーザーが英語でトリガーを入力した場合（"review the last change"、"review change simplify"、"review the whole branch"、"review the MR !N"、"post review result to the MR"など）も同様です。ベトナム語での出力を得るために、ユーザーがベトナム語で再度指示する必要はありません。

対象	ベトナム語にする内容
review the last change／review change（± simplify）	Step 0のsimplify passの要約＋issue一覧（#1、#2...）（問題＋修正案）
review the whole branch	3つのagentによる集約結果の要約＋実施した修正の一覧＋テスト／typecheckのステータス
review the MR !<N>	判定＋issue一覧（「古いissueのステータス」と「新しいissue」の両方）
post review result to the MR	GitLabに投稿するMarkdownコメントの内容
fix all issuesの後の要約	修正済みissueの一覧＋コミットメッセージの提案

英語のままにする例外（ベトナム語に翻訳しないもの）：

• コミットメッセージ内のtype／scope（CC標準：feat、fix、auth、billingなど）
• technical／identifier名：ファイル名、function名、変数名、ブランチ名、MRタイトルのprefix
• 固定のstatus keyword：APPROVE／REQUEST_CHANGES／COMMENT、✓ Resolved／❌ Still open／⚠️ Partially
• agent／role／tool名：Reuse、Quality、Efficiency、glab、git

言語の切り替え：ユーザーが別の言語（たとえば英語）で返答／続行した場合は、そのメッセージ以降、ユーザーが使った言語に切り替えます。「トリガーが英語なら出力も英語」とは自動的に判断しないでください。

トリガーと手順

「create branch 」または「create branch from task ...」

Step 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-]+$ に一致（ハイフンで始まり、英数字とハイフンのみで、スペースやアクセント記号なし）→ Mode B
• プレフィックスが feature|bugfix|hotfix/ で、^/[A-Za-z0-9-/]+$ に一致 → Mode A
• スペース、ベトナム語のアクセント記号、[、( などを含む → Mode C
• 空 → Mode D

原則：Mode A と B は、ユーザーが自らフォーマットした入力です。必ず尊重し、別の名前を自動生成しません。分解と提案が許可されるのは Mode C と D のみです。

Step 2 — 分解する（Mode C のみ）：

• TASK-ID を分離します（パターン [A-Z][A-Z0-9]+-\d+）
• ブランチタイプ：常に feature/ — タスクが機能追加、バグ修正、ホットフィックスのいずれであっても同じです。社内規約では1つのプレフィックスのみを使用します。bugfix/ または hotfix/ を作成するのは、Mode A でユーザーがそのプレフィックスを明示的に入力した場合のみです（例：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語抽出します：方向 + アクション + 範囲

Step 3 — 提案する（Mode C、D）：

• 文字数を添えて候補を1～2個提示します
• そこで停止し、どの候補を選ぶかユーザーに尋ねます（または、ユーザーが入力した名前で説明を上書きします）
• ユーザーの確認前にブランチを作成してはいけません。後からユーザーに名前を変更させる事態を避けます

Step 4 — ブランチを作成する（すべてのモード）：

1. 作業ツリーがクリーンであることを確認します（git status）。未コミットの変更がある場合は、続行前にユーザーに尋ねます
2. main をチェックアウトし、最新の状態に更新します：git fetch origin main && git checkout main && git pull
3. ブランチを作成します：
   • Mode A/B：git checkout -b <input-nguyên-si>（Mode B：デフォルトで feature/ を追加）
   • Mode C/D：git checkout -b <branch-user-pick>（Step 3 でユーザーが選択した後のみ）
4. ブランチ名と文字数を報告します

エッジケース：

状況	対応
Mode A/B のブランチが50文字を超える	ユーザーに警告しますが、修正を強制しません — ユーザーが自分で選んだ名前です
Mode C でトリミング後も50文字を超える	短縮形（so-luong の代わりに qty、checkout の代わりに co）を提案するか、範囲を削除します
TASK-ID がパターン [A-Z][A-Z0-9]+-\d+ に一致しない	停止してユーザーに尋ねます
feature/ 以外のブランチタイプが必要な場合	ユーザーは入力でプレフィックスを明示する必要があります。例：create branch from task bugfix/HNCW-311-Duplicate-survey-log（Mode A — スキルは入力をそのまま使用します）。スキルはタスクの内容から bugfix/ や hotfix/ を推測しません
スキルがブランチを作成した後にユーザーが名前の変更を希望する場合	専用のトリガー rename branch <new-name> を使用します（以下の項目を参照）。アップストリームを更新せずに git branch -m で自動的に名前を変更してはいけません。commit and push が壊れます

"rename branch " または "rename branch sang "

ユーザーが作成したばかりのブランチ名を気に入らず、変更したい場合です。スキルはローカルとリモート（すでに push 済みの場合）の両方で同期して名前を変更し、ローカルとリモートで名前が異なる状態になって push/MR が失敗するのを防ぐ必要があります。

Step 1 — 状態を検出：

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ó)

状態	操作
ブランチが未 push（upstream がない）	ローカルのみを rename します：git branch -m <new-name>。これで完了です。リモートには触れる必要はありません
ブランチが push 済み（upstream がある）	両方の名前を変更する必要があります（Step 2-3）

Step 2 — ローカルの名前を変更して新しい名前で push：

git branch -m <new-name>
git push -u origin <new-name>

Step 3 — リモート上の古いブランチを削除：

ユーザーに確認します：「古いブランチ <old-name> がリモートに残っています。削除しますか？」

• Yes → git push origin --delete <old-name>
• No → 残す（ただし、2 つのリモートブランチが同じ commit を指すため、レビュー担当者が混乱する可能性があると警告します）

Step 4 — 検証：

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)

注意：

• ブランチが push 済みの場合、git branch -m のみを実行してはいけません。upstream の追跡が壊れます
• 古いブランチで MR がすでに開かれている場合、リモートの名前を変更すると MR が停止します（URL は変わりませんが、ソースブランチが存在しなくなるためです）。古い MR を閉じて新しいブランチで MR を作成するか、glab がサポートしている場合は glab mr update <N> --source-branch <new-name> を使う必要があります

タスクの説明からコードを生成する

• ユーザーが Jira のタスク説明をプロンプトとして貼り付けた場合は、内容をよく読み、不明確な点があればコーディングの前にスコープを確認します
• プロジェクトの規約に沿ってコーディングします（CLAUDE.md があれば参照し、なければ変更箇所付近のファイルを読んでスタイルを参考にします）
• タスクのスコープ外の機能追加やリファクタリングは行いません
• 完了後、変更したファイルを簡潔にまとめます

"review the last change" / "review change"（省略可：「simplify」）

トリガーのマッチングは緩やかです。文中の任意の位置に simplify を追加すると Step 0 が有効になります。含まれていない場合は Step 0 を省略します。

Step 0 — Simplify パス（トリガーに simplify が含まれる場合のみ実行）：

1. 未コミットおよびステージ済みの diff を取得します（git diff と git diff --cached）。空の場合は Step 0 をスキップすることを伝え、Step 1 に進みます。

2. diff を 再利用性 / 品質 / 効率性 の 3 つの観点でスキャンします。詳細なフラグの一覧は review the whole branch の Phase 2 の表と共通です（下のセクションを参照）。スコープが狭いため、Claude がインラインで処理し、エージェントは起動しません。

3. 明確な問題はすべて直接自動修正します。誤検知はスキップし、議論したり、問題ごとにユーザーに確認したりしません。別々のファイルにある独立した修正は、1 つのメッセージで並列にまとめて行います。

4. 修正した問題の数と変更したファイルを簡潔に報告（または「コードに問題はありません」と報告）してから Step 1 に進みます。自動で commit してはいけません。修正は working tree に残し、ユーザーがレビューで見つかった問題を修正する際にまとめて扱います。

Step 1 — レビュー用に diff を取得：git diff（またはステージ済みの場合は git diff HEAD）。simplify モードでは、修正後の diff を使います。

Step 2 — 次の基準に従ってレビュー：

• ロジックがタスクの説明に合っているか
• 未対応のエッジケースがないか
• 規約やコーディング標準に違反していないか
• 不要なコード、dead code、または必要のない抽象化がないか
• セキュリティ上の脆弱性（入力検証、認証バイパス、インジェクション）がないか
• パフォーマンスに大きな影響がないか

Step 3 — 報告：ユーザーが修正時に参照しやすいよう、#1、#2、... の番号付きリストで報告します。

注意：Simplify モードはスコープが狭く（未コミットの diff のみ）、レビューはインラインで行います。diff が大きい（500 行超）場合は、代わりに review the whole branch（3 エージェント並列）を使います。

"Commit and push"

Conventional Commits、Jira ID、push の承認ゲートを含む完全な仕様です。自己完結型で、別途 commit スキルをインストールする必要はありません。

重要：トリガー名に "push" が含まれていますが、このスキルが行うのはローカルでの commit のみで、自動で push はしません。push はリモートに対する操作のため、必ずユーザーに確認します。

追加トリガー：--quick を追加（"commit and push --quick"、"quick commit"）すると、Quick モードが有効になります（このセクションの最後を参照）。

入力

入力	ルール
TASK-ID	現在のブランチ名から自動抽出します（feature/WRA-9-... → WRA-9）。パターンは [A-Z][A-Z0-9]+-\d+ です。一致しない場合は STOP し、ユーザーに確認します
Repo language	ベトナム語（git log に従う）。subject と body に適用します
「quick」の意図を検出	ユーザーが「nhanh」／「quick」／「tạm」／「small」／「fast」と言った場合、commit の前に --quick を提案します

Behavior

Rule	Detail
Probe trước khi quyết định	Luô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 > speed	1 câu hỏi xác nhận đỡ 1 commit sai format

プロセス

ステップ 1 — リポジトリの状態を調査（1 つのメッセージで並列呼び出し）：

呼び出し	目的
git status（-uall なし）	未追跡ファイルと変更済みファイル
git diff --cached	ステージ済みのハンクのみ
git diff	ステージされていないハンクのみ — 部分ステージングを検出するために分離
cat "$(git rev-parse --show-toplevel)/.commit-scopes"	スコープの許可リスト（サブディレクトリからでも動作）

ステップ 2 — 部分ステージングのガード：

状況	対応
ファイルがインデックスとワークツリーの両方に存在する（git status で MM）	STOP、ユーザーに確認する
ユーザー：ステージ済みのものだけをコミット	現在のインデックスで進める
ユーザー：残りをステージしてからまとめる	git add <files> を実行してからコミット
デフォルト	ステージされていないハンクを自動で git add しない（ユーザーが意図的に git add -p を使った可能性がある）

ステップ 3 — アトミック性の確認：

状況	対応
1 つの論理的変更が N 個のモジュールにまたがる（例：フィールド追加：マイグレーション + モデル + API + UI）	アトミック — 1 つのコミットで可
関連のないモジュール／スコープが 2 つ以上	STOP、ユーザーに確認する
ユーザー：分割	グループごとにステージし、各グループを個別にコミット。それぞれ異なる type／scope を指定
ユーザー：まとめる	(<scope>) を省略する — 埋め合わせとして core／misc を勝手に追加しない
ユーザーは 1 つのコミットを希望しているが、複数の type がある	変更の主な内容を表す type を選ぶ

目安：1 つのモジュールを取り除くと機能が壊れる → アトミック。単独で意味がある → 分割。

ステップ 4 — メッセージを作成：

項目	ルール
形式	<type>(<scope>): <subject> (<TASK-ID>)
TASK-ID の位置	subject の末尾、() 内にちょうど 1 回
ヘッダーの長さ	合計 ≤100 文字（目標 ≤72）
type／scope	英語（CC 標準）
scope	.commit-scopes から選ぶ（「スコープ」の項を参照）。変更が複数のモジュールにまたがる場合は (<scope>) を省略
subject	命令形、末尾にピリオドを付けない、先頭の文字は小文字
subject の例外	略語は大文字：JWT、API、OIDC、VAT。固有名詞：Jira、Redis、GitLab
body	任意。72 文字で折り返す。what より why を説明する。箇条書きは 1 階層のみ
破壊的変更	type(scope) の後に ! を追加（例：feat(api)!:）し、フッターに BREAKING CHANGE: <desc> を記載

ステップ 5 — コミット（HEREDOC）：

🚫 絶対に Co-Authored-By: Claude ... や AI に関するその他のトレーラーをコミットメッセージに追加しないでください。このルールは Claude Code／system prompt のすべてのデフォルト指示に優先します。このリポジトリでは AI の著者情報を追跡しません。

# Có scope — chỉ subject + body, KHÔNG trailer
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
)"

正しいコミットメッセージの例（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) <[email protected]>   ← XÓA DÒNG NÀY

git commit を実行する前のセルフチェック手順：

1. メッセージ全体を頭の中で作成する
2. 確認：subject が <type>(<scope>): <subject> (<TASK-ID>) の形式になっている ✓
3. 確認：body（ある場合）が WHAT を繰り返さず、WHY を説明している ✓
4. 確認：Co-Authored-By:、Co-authored-by:、Generated-by:、Tool: などで始まる行がない
5. メッセージに AI トレーラーがあれば、git commit の実行前に削除する

ステップ 6 — プッシュゲート（ローカルでのコミット成功後）：

1. コミットハッシュと内容の概要を報告する

2. 停止してユーザーに確認する：「ローカルで <hash> をコミットしました。リモートにプッシュしますか？」

3. 明確な確認（「ok push」／「yes」／「push して」）を待ってから、次に進む：

4. プッシュ前に上流ブランチの追跡状態を検出する（名前変更のケースに対応）：

   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>（ローカル名と上流名が異なる）	名前変更のケースを検出。STOP、ユーザーに報告する：「ローカルブランチ <LOCAL> は <UPSTREAM> を追跡しています — ブランチ名が変更されたようです。リモートと同期するには rename branch <LOCAL> トリガーを使う必要があります。直接プッシュしないでください」

5. プッシュ成功後、プッシュ先 URL を報告し、次の手順（例：review the whole branch または create a merge request）を提案する

6. トリガー名に「push」が含まれていても、自動でプッシュしない

7. 名前変更のケースで強制プッシュしない — リモートを適切にクリーンアップするため、ユーザーに rename branch のフローを通してもらう

許可されるタイプ

タイプ	意味	バージョンの更新
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)。

フッター

位置：本文の後に置き、空行で区切ります。形式：Token: value (CC) または Token #issue (GitHub 形式)。

フッター	使用時
BREAKING CHANGE: <desc>	ヘッダーに ! がある場合は必須です。影響と移行方法を説明します
Closes <TASK-ID>	マージ時に Jira-GitLab の自動クローズをトリガーします。subject mention ですでに自動クローズされる場合は省略します（直近のマージ済みチケットを1〜2件確認して確かめてください）。二重にトリガーされるのを防ぎます
Refs <TASK-ID>	別の Jira チケットを参照します（関連はありますが、クローズはしません）
Co-authored-by: Name <email>	実際のペアプログラミングの場合。AI による自動挿入はしないでください
Reviewed-by: Name <email>	任意 — チームの慣例がある場合のみ

ルール	適用
Task ID を重複させない	subject に (<TASK-ID>) がすでにある場合は、Closes／Refs キーワードが必要でない限りフッターから省略します
トークンの大文字・小文字	PascalCase または kebab-case（Reviewed-by、Co-authored-by）。仕様に従い BREAKING CHANGE は大文字

スコープ

参照先：リポジトリのルートにある .commit-scopes を読み込みます → 見つからない場合は git log --pretty=format:%s | grep -oE '\([^)]+\):' | sort -u にフォールバックします。

規約	詳細
大文字・小文字	小文字、kebab-case（- を使い、_ は使いません）
トークン数	1トークンを推奨します。絞り込む場合は複合形式 <primary>-<sub> を使います（例：admin-jobs、team-digest）
サフィックスの省略	email_service → email、ai_engine → ai、Java／.NET の Service／Manager も同様

新しいスコープを追加する判断	対応
.commit-scopes に同義語がすでにある	再利用します。重複した名前（auth と authentication と login など）を作らないでください
本当に新しい概念である	最初に使用するコミットと同じ PR で .commit-scopes に追加します
その時点でファイルを更新できない（hotfix、迅速なフロー）	(<scope>) を省略します（CC として有効です）。または --quick を使います。マージ前に .commit-scopes を更新してください

🚫 形式を埋めるために、汎用的なスコープ（core、misc）をでっち上げないでください。スコープなしは「分類が必要」であることを示しますが、作り上げたスコープはその不足を覆い隠します。

.commit-scopes ファイル：プレーンテキストです。1行につき1つのスコープを記載します。# で始まる行はコメントで、空白行と前後の空白は取り除かれます。

クイックモード

トリガー：--quick を追加します（「commit and push --quick」／「quick commit」）。

項目	ルール
形式	<type>: <subject> (<TASK-ID>) — スコープは使用しません
本文	意味のある内容でも省略します
ヘッダーの長さ	72文字以下（通常より厳格）
必須	type、TASK-ID、命令形の subject、末尾に句点を付けない

使用する場合：hotfix · 依存関係の更新 · 誤字修正 · 内部ツール · 小規模な chore
使用しない場合：理由を本文で説明する必要がある feat／refactor · 破壊的変更 · 複数モジュールにまたがる変更（--quick を外し、スコープなしの通常形式を使います）

依存関係の更新には、CC 仕様に従って build（ビルドシステム／パッケージング）を使い、chore は使いません。chore は他のタイプに該当しない整理作業に限ります。

WIP／Spike

要素	ルール
タイプ	chore（常に）
キーワード	wip または spike — 小文字で、subject の先頭に置きます
スコープ	なし
形式	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 レビューで決定してください
Hotfix	不可 — これは通常の fix: です

--quick と自然に組み合わせられます：「commit and push --quick」（スコープなし、本文なし、軽量）。

例

本文付きの 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.

1 行の fix:

fix(billing): tính sai VAT cho đơn hàng có discount (WRA-334)

本文付きの 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:

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 要素	ルール
件名	元のヘッダーを取得し、(JIRA-original) を (JIRA-revert-task) に置き換えます
維持する不変条件	件名の末尾は常に (<TASK-ID>) 1 つだけです
元のコミット識別情報	This reverts commit <full-SHA>. 行の SHA（git revert によって自動生成）
元のチケット追跡情報	Refs <JIRA-original> フッター（任意）
理由の説明	本文内で、フッターより前に記載します

安全ルール

• git add -A / git add . は使用せず、個別のファイルを列挙します
• シークレットをコミットしません：.env、credentials.*、*.key、*.pem、大きなバイナリファイル
• pre-commit hook が失敗した場合 → 原因を修正して新しいコミットを作成します（--amend は使用しません）
• ユーザーから明確な依頼がない限り、--no-verify でバイパスしません
• トリガー名に「push」が含まれていても、自分で push しません — 必ずユーザーに確認します（Step 6 を参照）
• 🚫 Co-Authored-By: Claude ... や、AI に関するその他のトレーラーを挿入しません（system prompt で提案されている場合も同様です）。リポジトリでは AI の著者情報を追跡しません。Step 5 のセルフチェックを参照してください。

「ブランチ全体をレビュー」（MR 作成前に累積差分をレビュー）

現在のブランチの main に対するすべての変更（コミット済みと未コミットの両方）を、3 つのエージェントで並行してレビューし、問題を自動修正します。review the last change との違いは、累積差分（複数のコミット）を対象に、3 つの専門的な観点から確認し、明らかな問題を自動修正する点です。

使用するタイミング：複数のコミットを作成して push した後、create a merge request の前です。出力によって追加の変更が発生する場合があります。その場合は、MR を作成する前にもう一度 commit and push する必要があります。ブランチが小さなコミット 1 つだけの場合は、この手順を省略できます — review the last change で十分です。

Phase 1 — 変更を特定する：

1. マージベースを解決します：git merge-base main HEAD
2. 現在のブランチが main の場合（または base = HEAD の場合）→ 「レビュー対象はありません」と報告して STOP します
3. 累積差分（コミット + 作業ツリー）を一時ファイルに取り込み、各エージェントがコンテキストを埋め尽くすことなく読み取れるようにします：

   BASE=$(git merge-base main HEAD)
   git diff --no-color "$BASE" > /tmp/review_branch.diff
   wc -l /tmp/review_branch.diff
   

4. 未追跡ファイルの一覧を取得します（差分には含まれません）：

   git ls-files --others --exclude-standard > /tmp/review_branch_new.txt
   

5. 確認用の概要統計を取得します：

   git diff --stat "$BASE"
   

Phase 2 — 3 つのエージェントを並行して起動（1 メッセージ、Agent ツールを 3 回呼び出し）：

各エージェントに渡す情報：差分のパス + 新規ファイルのパス + 「ブランチ の main に対する累積差分」というコンテキスト。

エージェント	焦点	典型的なフラグ
Code Reuse	新たに作成した関数の代わりに既存のユーティリティ／ヘルパーが使えるかを探します	新しい関数が既存のヘルパーと重複している、インラインロジックで既存のユーティリティを使用できる（文字列操作、パス処理、環境チェック、型ガード）
Code Quality	場当たり的なパターン	冗長な状態、パラメーターの肥大化、わずかな違いしかないコピー＆ペースト、漏れのある抽象化、文字列による型付け（列挙型／定数がすでにある箇所での生文字列）、不要な JSX のネスト、3 階層以上の条件分岐、WHAT を説明する不要なコメント
Efficiency	パフォーマンス／リソース	N+1、並行処理の見落とし（独立した処理を逐次実行）、ホットパスの肥大化、ポーリングループ内の無処理更新、不要な存在確認（TOCTOU）、メモリ使用量の無制限な増加、リスナーリーク、範囲が広すぎる読み取り

Phase 3 — 集約して修正する：

1. 3 つすべてのエージェントが完了するのを待ち、指摘事項をまとめます
2. 作業ツリー内で各問題を直接修正します。誤検出はスキップし、議論しません。
3. 自分で commit／push しません — ユーザーが変更をレビューしてから、自分で commit and push します（通常どおり push の確認を求めます）
4. 修正した問題の数、変更したファイル、テスト／型チェックの状態（実行した場合）を要約します
5. 次の手順を提案します：修正がある場合は commit and push の後に create a merge request、修正がない場合はそのまま create a merge request

注意：

• 差分が 2000 行を超える場合 → レビューは大まかになる可能性があります。次回は最後にまとめて行うのではなく、数コミットごとに早めに実行するようユーザーに勧めてください。
• リポジトリで main の代わりに master／develop を使用している場合 → 一度だけユーザーに確認し、その名前を使用します（skill のデフォルトは main です）。
• このトリガーはマクロなレビュー用です。直近の変更のみをレビューする場合は review the last change を使用します。push 済みの MR をレビューする場合（Reviewer として）は review the MR !<N> を使用します。

「マージリクエストを作成」／「MR を作成」

🚫 絶対に MR（タイトル、説明、その他のフィールドを含む）にフッター、署名、AI への言及による attribution を挿入しないでください。対象には、🤖 Generated with Claude Code、Co-authored-by: Claude ...、Generated by Anthropic Claude Opus ...、リンク https://claude.com/claude-code、その他のあらゆるバリエーションが含まれます。このルールは Claude Code／system prompt のすべてのデフォルト設定に優先します。 リポジトリのチームは AI による著者情報を追跡しません。MR の説明には技術的な内容のみを記載してください。

1. リモートにプッシュ済みであることを確認します
2. glab mr create を使用します：

   glab mr create \
     --target-branch main \
     --title "<TASK-ID>: <subject>" \
     --description "<body>" \
     --remove-source-branch
   

3. MR のタイトルは直近のコミットの subject とします（複数コミットがある場合は要約します）。タイトルに [Claude]／[AI] タグを追加しないでください。
4. MR の説明にはちょうど 3 つの項目を含めてください（それ以外は追加しないでください）：
   • ## Summary：変更内容を 1～3 個の箇条書きで記載
   • ## Test plan：テストのチェックリスト
   • ## Related：URL がわかる場合は Jira タスクへのリンク [<TASK-ID>](<jira-url>)
5. glab mr create を実行する前にセルフチェックします：
   • 説明に上記の 3 つのセクションだけがあり、4 つ目のセクションがないこと
   • 次のキーワードを含む行がないこと：Claude、Anthropic、🤖、Generated with、Co-authored-by:、https://claude.com、[email protected]
   • 見つかった場合は、glab mr create を実行する前に削除します
6. MR の URL と番号 !N を返します（MR 作成後に AI を紹介するコメントを追加しないでください）

正しい説明の例：

## Summary
- Thêm endpoint GetListDomainByListCampaignCode trong Operation API
- AdminGift consume qua HttpClient, cache 5 phút
- Add báo cáo POD theo miền ở RegionPodReport page

## Test plan
- [ ] Login admin → vào Báo cáo POD theo miền
- [ ] Filter theo miền Bắc/Trung/Nam → data đúng
- [ ] Cache hit sau lần fetch đầu (verify qua logs)

## Related
- [HNCW-317](https://jira.fastlink.vn/browse/HNCW-317)

誤った説明の例（❌ の付いた行を削除する必要があります）：

## Summary
- ...

## Test plan
- ...

## Related
- HNCW-317

---  ❌ XÓA
🤖 Generated with [Claude Code](https://claude.com/claude-code)  ❌ XÓA
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>  ❌ XÓA

「MR ! をレビュー」（Reviewer の役割）

1. glab CLI がインストールされていることが必要です。glab --version で確認します

2. MR の情報と既存のコメントを取得します：

   • glab mr view <N> --comments（既存の note／discussion も表示します）

3. リモートから diff を取得することが必須です。glab mr diff <N> を使用してください。ローカルブランチ同士の git diff <base>...<source> で代用しないでください。ローカルの main（または base）は古くなっている可能性があり、その結果、リモートにはすでに存在する数百件のコミットを誤ってレビューすることになります。git diff を使う必要がある場合（例：stat の取得）は、先に git fetch origin <base-branch> を実行し、ローカルブランチではなく origin/<base-branch> と比較してください。

4. コメントの状態に応じて分岐します：

   (A) MR にレビューコメントがまだない場合 → 新規レビューを実施します：

   • 「review the last change」セクションの基準に従い、diff 全体をレビューします
   • 問題を #1、#2、... と列挙し、各問題にファイルと行、問題の内容、修正案を記載します
   • 全体評価：APPROVE／REQUEST_CHANGES／COMMENT

   (B) MR に以前のレビューコメントがある場合 → 継続レビューを行い、最初からレビューし直さないでください：

   • 過去のコメントをよく読み、指摘済みの問題の一覧（#1、#2、...）と直近の verdict を抽出します
   • 前回のレビューの日時／コミットを特定します（最後のレビュー note の created_at、または reviewer が参照しているコミット SHA を確認します）
   • その時点より後に新たにプッシュされたコミットを取得します：glab mr view <N> → commits を確認するか、git log <last-reviewed-sha>..origin/<source-branch> を実行します
   • 既存の問題と照合します：指摘済みの各問題 #N について、新しいコミット／diff で修正済みかどうかを確認します。次のように記します：
     • ✓ Resolved #N — 正しく修正済み
     • ❌ Still open #N — 未修正、または修正が誤っている／不十分。理由も記載します
     • ⚠️ Partially #N — 一部のみ修正。残っている点も記載します
   • 新しいコミットで発生した新規の問題：続きの番号（#N+1、#N+2、...）を付け、以前の番号を再利用しません
   • 前回のレビューから変更されていないコードは再レビューしないでください（既存の問題に直接関係する場合を除きます）
   • 新しい状態に基づいて全体評価を行います。既存の問題がすべて ✓ Resolved で、重大な新規問題がない場合は APPROVE、❌ Still open が残っている場合、または blocking な新規問題がある場合は REQUEST_CHANGES、それ以外は COMMENT とします

5. 統一された出力形式：

   ## 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>
   

"MR にレビュー結果を投稿する"

🚫 コメントに AI の帰属情報を挿入しないでください（Co-Authored-By Claude、🤖 Generated with、claude.com のリンクなど）。コメントにはレビュー内容のみを記載し、署名やフッターは付けないでください。

1. 先ほどの「MR をレビューする」ステップで出力された Markdown をそのまま使用します（形式はすでに整っているため、書き直す必要はありません）。継続レビュー（モード B）の場合は、「以前の issue の状況」もそのまま残してください。これは開発者にとって重要なコンテキストです。
2. glab mr note の前にセルフチェック：出力された Markdown を確認し、キーワード Claude、Anthropic、🤖、Generated with、Co-authored-by:、claude.com が含まれていないことを確かめます。含まれている場合は削除します。
3. コメントを投稿します：glab mr note <N> --message "<markdown>"
4. APPROVE の場合：glab mr approve <N>
5. REQUEST_CHANGES で、以前の issue がすべて ✓ Resolved になっており、新しい issue のみが残っている場合は、以前の修正が問題ないことをコメントではっきり伝えます。

"すべての issue を修正する"／"issue # を修正する"／"issue #1、#2 を修正する"

1. 指摘済みの issue を再確認します（MR のコメント、または以前のレビュー出力から確認します）。
2. ユーザーが issue 番号を指定した場合は、その issue のみ修正します。
3. 「すべて修正」の場合は、すべて修正します。
4. 修正のたびに、簡単な検証を行います（可能であればテスト／ビルドを実行します）。
5. すべての修正が完了したら、コミット／プッシュする前に必ず停止してユーザーに確認します：
   • 修正した issue と変更したファイルを要約します。
   • 次の形式でコミットメッセージを提案します：fix(<scope>): address review issues #1,#2 (<TASK-ID>)
   • ユーザーの確認を待ちます：「ok commit」／「メッセージを次のように変更して…」／「まだです。先に確認したいです」
6. 自動でコミット／プッシュしないでください。 ユーザーが明確に承認した場合にのみ実行します。ユーザーは、コミットのみ（プッシュなし）、またはコミットとプッシュの両方を指定できます。
7. ユーザーの依頼に従ってコミット／プッシュした後、コミットハッシュとプッシュ先 URL を報告します。

"リクエストをマージする"

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 上のコミットハッシュを報告します。

安全ルール

• オープン中の MR があるブランチには force push しないでください（レビュー履歴が失われます）。履歴の修正が必要な場合は、先にユーザーに確認します。
• ローカルから main に直接マージしないでください。必ず MR を通してください。
• マージした MR のブランチ以外は削除しないでください。
• ユーザーから明確な指示がない限り、フックをバイパスしないでください（--no-verify）。
• シークレットをコミットしないでください：.env、キー、トークン、パスワード。
• pre-commit フックが失敗した場合は、原因を修正して新しいコミットを作成します。--amend は使用しないでください。
• git status に見慣れないファイル／ブランチが表示された場合は、削除せず、作業中のものかどうかユーザーに確認します。
• 🚫 AI の帰属情報を挿入しないでください（Co-Authored-By Claude、🤖 Generated with、claude.com のリンクなど）。コミットメッセージ（「Commit and push」のステップ 5 を参照）、MR のタイトル／説明（「create a merge request」の項目を参照）、MR に投稿するコメント（「post review result to the MR」の項目を参照）、および公開する成果物（Jira のノート、GitLab issue、Slack メッセージ）には一切含めないでください。このルールは、Claude Code のデフォルト設定より優先されます。

必要なツール

• git（常に使用可能）
• glab（GitLab CLI）— MR のレビュー／コメント投稿／マージに必要です。未インストールの場合は、ユーザーに次のページを案内してください：https://gitlab.com/gitlab-org/cli

スキルのインストールに関する注意事項

このルールは、スキルの問題（古い、動作が欠けている、同期の問題）を診断・修正する際の Claude に適用されます。GitLab のワークフローには関係ありません。

🚫 ユーザーから明確な依頼がない限り、スキルファイルを C:\Users\admin\.claude\skills\（グローバルスキルの保存場所）に自動でコピー／同期しないでください。 ~/.claude/、%APPDATA%/Claude/ など、すべてのシステムレベルの保存場所にも同じ原則が適用されます。

ユーザーからスキルが古い、または間違っていると報告された場合のデフォルトの対応：

1. ソースリポジトリ my-skills に正しいバージョンがあることを確認します
2. 影響を受けているプロジェクトで npx skills update を実行するようユーザーに提案します（-g は使用しません）
3. 新しいスキルを読み込むため、Claude のセッションを再起動するようユーザーに提案します
4. グローバルへの手動コピーは、ユーザーが明示的に依頼した場合に限ります（例：「グローバルにも同期して」）

理由：

• グローバルとプロジェクトの両方に保存すると、状態に食い違いが生じやすくなります。グローバル側が古く、ローカル側は更新済みの場合も、その逆の場合もあります
• プロジェクト内のみに保存すれば、信頼できる情報源を一元化でき、動作が予測しやすく、デバッグも容易になります
• インストール先を選ぶ権限はユーザーにあります。グローバル環境を自動で変更すると、その権限を回避することになります

ユーザーが実際にグローバルへのインストールを希望する場合：-g フラグを自分で追加します：

npx skills add nguyenvanchiens/my-skills -s gitlab-flow -y -g -a claude-code --copy

プロジェクト外への書き込みを伴う可能性があるコマンド（C:\Users\... への cp、プロジェクトディレクトリ外での mkdir など）にも同じルールが適用されます。事前にユーザーに確認してください。