Community程式設計與開發github.com

gitmoji

程式碼編寫技能。使用 Gitmoji Triangle 慣例(表情符號配對、票號、範圍、摘要)撰寫 Git 提交,並將暫存的工作拆分為每次提交一個決策。

gitmoji 是什麼?

Gitmoji 是一款專為開發者和 AI 代理設計的進階 Git 提交技能,強制採用結構化的「Triangle」提交訊息格式。每個提交訊息開頭必須包含一對表情符號(例如 🧩👔),後方依序接上票號(如 #412)、範圍(如 server)和摘要(如「allow an appeal within 30 days of refusal」)。此格式確保每次提交都代表一個可由審查者獨立接受的決策,特別適合在開始編寫程式碼前先規劃提交清單,以及在執行 `git commit` 之前驗證訊息格式。該技能支援 Claude Code、Cursor 和 Codex 等主流 AI 代理平台,並提供詳細的指令指南、暫存檢查(`gitmoji staged`)以及提交訊息驗證(`gitmoji check`)功能。其主要優勢在於強制程式碼審查的邏輯單元性、自動化表情符號轉換(透過 Git 鉤子),以及透過簽名行(包含模型、工具鏈和子代理資訊)記錄提交的 AI 參與歷程。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/D1no/gitmoji/tree/HEAD/skills/gitmoji

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Triangle 提交

提交主題格式如下:

<區域><行為或意圖>[修飾詞] <票號> (<範圍>): <摘要>
🧩👔 #412 (server): allow an appeal within 30 days of refusal
🎨💄 — (tokens): take the new hues from Figma

表情符號是行首的第一個字元,前後無空格。最後一個範例是由自動化作業建立的提交:它沒有票號,因此使用長破折號代替。

詞彙庫刻意設計得很大,您無需全部記住。gitmoji 指令會分段提供。只需閱讀您需要的部分即可。

指令

使用 gitmoji 指令。如果該指令不在 PATH 中,請閱讀此技能資料夾中的 references/vocabulary.txt 以取得完整詞彙表,並告知使用者指令缺失。

時機執行
您需要區域列表gitmoji guide areas
您知道區域gitmoji guide 🧩 (任何區域表情符號或名稱)
區域指南中無符合項目gitmoji guide groups,然後指定一個群組:gitmoji guide "repair"
兩個條目似乎都符合gitmoji guide 🛡️,或群組:gitmoji guide "protection"
工作是試驗、暫行方案或破壞性變更gitmoji guide modifiers
您需要範圍名稱gitmoji guide scopes
您即將撰寫摘要或內文gitmoji guide message
執行 git commit 之前gitmoji staged,然後對第一行執行 gitmoji check -m '<subject>',或對整個訊息執行 gitmoji check <file>
您輸入了短代碼例如 :jigsaw::necktie:無需操作:鉤子會為您寫入表情符號
您正在復原一個提交git revert <commit>;Git 自己的第一行保持不變
鉤子拒絕了一個主題閱讀其訊息;它會指出需要修正的地方
您想在分支合併前審視其提交gitmoji history trunk..HEAD (目標分支,然後是您的分支)
鉤子表示倉庫採用了另一個版本閱讀它提供的地址中變更了什麼,並在更改設定前通知使用者

在撰寫程式碼之前:規劃提交

閱讀票號,並將您預計要撰寫的主題列成清單。每一項都是一個審查者可以獨立接受的決策,並且每一項都是票號要求的事情。每個項目的範圍是擁有該決策的套件 (gitmoji guide scopes)。

這些是提示,不是一個需要填滿的堆疊。僅在票號為問題提供了答案時規劃提交:

  • 業務決定了什麼 (👔),以及隨著時間推移會發生什麼 (⛓️)?
  • 在嘗試某個步驟之前,什麼會被拒絕 (🛡️)? 當一個步驟失敗時,它如何恢復,它報告什麼錯誤碼,以及人們被告知什麼 (🥅)?
  • 各部分之間協定了什麼形狀 (🏷️),以及儲存了什麼 (💾)?
  • 使用者看到並做了什麼,他們在哪個提交上首次獲得它 (✨)?
  • 我們如何知道使用者在實際產品上能順利通過 (✅,獨立提交,在產品可以那樣執行時才加入)?

當流程還無法執行時,先交付功能,並在票號上說明其 ✅ 尚未完成。不要為了填補空缺而將 ✅ 放在較小的檢查上;那是 ☑️ 的用途。

在規劃新的端點、儲存空間或政策之前,先檢查是否有現有的擁有者。如果缺少某個產品決策且會影響交付內容,請記下問題並詢問。不要在提交內部解決它。

一個功能如果只是一個決策,且只有其呼叫者和所需的檢查,那就是一個提交。只有在票號包含多個審查者可以單獨接受的決策時,才規劃更多行。票號從未要求的行就是過度細分。

每次提交前:四個問題

  1. 這個變更是哪個區域的一部分或關於哪個區域? 測試、文件和遊樂場採用它們所屬事物的區域。
  2. 現在有什麼不同,或者您做了什麼? 如果提交變更了承諾的內容,請命名行為(名詞)。否則,命名意圖(動詞)。
  3. 這項工作尚未確定嗎? 只有在這種情況下才加入第三個表情符號:🧪 試驗、🚧 暫行方案、💥 消費者必須適應。試驗在 🏁(保留)或 ⚰️(放棄)之前,每次提交都保留 🧪,在此之前沒有任何已確定的內容可以依賴它。按照票號選擇的方向進行建置不是試驗。
  4. 哪個票號? 使用倉庫的票號格式。只有自動化作業才使用 —。

然後執行 gitmoji check -m '<subject>'。

在暫存之前,以一個不在場的人的角度閱讀變更。如果無法從程式碼中看出原因,請在程式碼旁編寫註解:為什麼它會是這樣,什麼不能更改,某個值從哪裡來。說明「原因」,而不是該行做了什麼。一條註解幾乎不花費您任何成本,卻能為下一個閱讀者——一個人、一位初學者或一個沒有您當時情境的代理——省去猜測的時間。

當一個配對不適用時

這代表需要重新審視的信號,而不是選擇最接近的標籤。

  • 當兩個標籤都適用時,說明審查者現在可以接受什麼以及他們可以推遲什麼。當這兩個決策可以不同,並且保留的部分仍能獨立運作時,進行拆分。按路徑或區塊暫存 (git add -p)。
  • 當唯一的呼叫者、其連線以及所需的拒絕檢查都沒有自己的承諾時,將它們保持在一起。根據其重點標記提交;其餘的隨之附帶。
  • gitmoji staged 報告兩個範圍:提出同樣的問題。如果變更只有整體才有意義(例如一種形狀在兩種語言中鏡像),則保持在一起,並命名擁有該決策的套件。
  • 由主要變更強制帶入的部分隨之附帶:其型別、其測試、一個故事、一個鎖定檔。

每個提交仍然必須能夠獨立建置並通過測試。如果拆分會破壞這一點,請將強制帶入的部分保留在一起,並在內文中說明。

撰寫

  • 摘要: 系統現在做什麼,使用領域詞彙,以小寫動詞開頭。整行第一行(包括表情符號、票號和範圍)應在 140 個字元以內,越短越好;gitmoji check -m '<subject>' 會在您提交前為您計數。不要包含檔案名稱、票號或「如何」之類的內容。
  • 描述: 您撰寫的每個提交都必須有描述,鉤子會拒絕沒有描述的提交。只有標記(🔖、🔺)、自動化作業建立的提交以及 Git 自行撰寫的訊息不需要描述。在第一行下方,一個空行,然後說明變更的原因:理由、為什麼這樣做而不是顯而易見的另一種方式,或者您選擇的價值。一兩行通常就夠了;最多六行。將票號引用放在句子內部(例如「See #42 for the decision」)。當某人編輯提交時,Git 可以刪除以 #42 開頭的行。不要重複 diff、列出檔案或描述您的流程。
  • 表情符號,而不是短代碼。 只有字元本身被提交。

誰撰寫的

絕不要將自己新增為作者或共同作者。 不要使用 Co-Authored-By: 行,不要在 git config user.* 或 --author 中設定代理身份。作者是負責的人,鉤子會拒絕代理身份出現在那裡。有些工具會未經要求就為自己新增共同作者行;當鉤子因此拒絕提交時,請移除該行並重新提交。

相反,在內文結尾用一個空行和一個說明提交內容的簽名行結束:

_
example-model (high), editor
Claude Code (example-session)
Sub-agents: 2 × example-helper (medium)
Team: reviewer, tester
Research: 3 searches, 12 pages

前三行始終存在。後三行僅在適用時出現。提交時,鉤子會將底線替換為 △ 以及(在反引號內)訊息所依據的詞彙版本,因此儲存的簽名看起來像這樣:

△ `1.2.3`
example-model (high), editor
Claude Code (example-session)

撰寫底線;絕不要自己撰寫 △ 行。鉤子會用它來關閉每條訊息,包括人的訊息,人的訊息則只會有那一行而沒有簽名。gitmoji history 讀取它來判斷哪些提交屬於哪個版本。

專案可以在 [rules] 下設定 signature = "agents",以便在支援的代理工作階段執行提交鉤子時要求提供模型和工具鏈行。人類可以使用一般的描述進行提交。發佈標記和 Git 生成的訊息保留其現有豁免。

行說明
_簽名從此處開始。鉤子會將其轉換為 △ `<version>` 。
模型行模型及其投入程度。如果有人給了您一個名字,則在逗號後加上您的名字。
工具鏈行工具鏈以及(如果有的話)在括號中的工作階段 ID。
Sub-agents:有多少個子代理根據模型和投入程度參與了此提交的部分工作。
Team:您為此提交交換過訊息的其他代理。
Research:為此提交進行的網路搜尋、閱讀的頁面和文件查詢。

不要憑記憶撰寫上述任何內容。 執行此技能資料夾中 scripts/ 路徑下為您的工具鏈提供的腳本,並貼上其輸出結果。路徑相對於此檔案所在的資料夾,無論技能安裝在何處:

python3 scripts/claude-code.py

在 Claude Code 中,該資料夾是 ${CLAUDE_SKILL_DIR}。腳本會讀取工具鏈自身的工作階段記錄。如果您的工具鏈在該位置沒有腳本,scripts/README.md 會說明如何一次性建立一個並將其加入。如果找不到記錄,腳本會輸出 unknown。倉庫可能會要求您省略某一行,例如工作階段 ID;其自身的說明會提到這一點。

如果工作階段跨越數個任務或倉庫,請將可選的活動行與此提交進行核對。僅保留您可以歸因於此提交的貢獻。

內文可能包含的行

  • 🩹 需要 Limitation: <what the dependency cannot do>。
  • 📥 需要 Source: <the run, tool or system it came from>。
  • 🏁 和 ⚰️ 說明決定了什麼。
  • 🐛 可以命名原因:Broken-by: <sha>。

升級 Gitmoji 時

CLI、技能和詞彙庫共享一個版本號。當倉庫的設定指定了一個與指令本身不同的版本時,鉤子會發出警告。通知使用者,並閱讀警告提供的地址中變更了什麼。當使用者想要新版本時,在設定檔的 [vocabulary] 下設定它,然後單獨提交該設定變更,並在版本號前後加上反引號:

🔺 gitmoji `<version>`: <what changes for this repository>

除非使用者要求,否則不要改寫已共享的歷史:在較早規則下建立的提交可以保持不變。gitmoji history --unmigrated 會顯示哪些提交在現行規則下無法通過。在變更鎖定版本後執行 gitmoji init 以重新整理已安裝的技能和受管理工作流程。

合併 Pull Request 與升級歷史

啟用 PR 標題工作流程,並選取 Pull request title and description 作為預設合併訊息。撰寫人類可讀的標題。Gitmoji 會在提交變更時維護其表情符號前綴。使用 Create a merge commit 並採用建議的訊息。GitHub 會保留原作者的提交,並附加整合的 PR 編號。

對於現有歷史,請使用升級指南和已安裝的 scripts/gitmoji-upgrade-history.py。在建立本地候選版本之前檢查乾執行結果。連結需要證據證明是哪個 PR 合併的。共用分支的替換是倉庫擁有者的單獨決策。

Git 撰寫的訊息

合併可以有任意標題。在待處理的合併期間,鉤子會保留 Git 的訊息檔案,而 gitmoji history 會透過其多個父提交來識別儲存的合併。純文字的 check -m 只能處理主題。它能識別常見的 Git 分支、標籤和提交合併標題、GitHub Pull Request 合併標題、編號的 Merge #N 標題、引用的 Git 還原和重新套用主題、編號的 Revert #N 和 Reapply #N 標題(附帶一個標題)、Git 的預設壓縮 (squash) 日誌標題,以及自動壓縮 (autosquash) 前綴 fixup! 、squash! 和 amend! 。

使用自訂 PR 標題的壓縮合併會產生一個普通的單一父提交。Cherry-pick 和 rebase 也可能攜帶普通主題。像其他作者提交一樣檢查這些主題。單獨的 PR 編號不能識別合併。

在導入期間,專案可以在 gitmoji.toml 的 [rules] 中設定 untagged = "warn",以接受純文字主題並標記它們以供審查。預設值為 "error"。設定為 "off" 時,缺少標籤會被靜默接受。其他檢查仍然適用。在您的分支上使用 gitmoji history trunk..HEAD 來找出需要在共用之前重新措辭的主題。歷史記錄始終嚴格檢查未標記的主題。

當無任何內容適用時

不要扭曲條目。使用最接近的誠實條目,在內文中加入一行 Miss: <what you wanted to say>,並告知使用者。Miss 正是詞彙庫得以修正的方式。

相關技能