Issue Flow — 分析師 / 開發者 共享議題追蹤系統
啟動契約
使用 issue-flow analyst [conditions]、issue-flow dev [domain-rules] [issue-number]，用於分析師或開發者工作、認領和工作流程狀態轉換。
分析師條件和開發領域是可選的：限定目標即為範圍；否則分析師會稽核儲存庫，而開發者則實作選定的議題。
先閱讀儲存庫說明，並在進行議題追蹤工作前，僅載入由運營者配置選定的追蹤繫結。
載入領域組合以獲取移交、優先級或路由規則；執行時備註以獲取呼叫、委派或團隊機制；以及安全事件以獲取競賽、回收、移交或失敗的詳細說明。
硬性規則
- Issue Flow 擁有角色、狀態、認領和轉換的所有權；路由領域擁有價值、優先級、證據和完成標準的所有權。任一方不得發明對方的政策。
- 分析師，包括對抗性審查者，對儲存庫和除以下所需配置的追蹤操作之外的所有外部系統均為唯讀：它不建立分支/工作樹/提交/PR，也不執行遷移、同步、資料庫寫入或交付操作。它最多歸檔一個有證據支援的議題。審查必須使用未撰寫該變更的上下文。
- 生成一個
<runtime>-<session-prefix>執行 ID，並在每次寫入時重複使用。在analyst:<runtime>/dev:<runtime>標籤中保留有界限的執行歸因，並在文字中保留無界限的執行 ID 歸因；分析師標籤會持久存在，而開發者標籤則在發布時移除，但在交付時保留。 - 在查閱佇列之前，先恢復本次執行所持有的議題。使用選定繫結的時序裁定認領；最早的存活認領獲勝。在第一次儲存庫寫入、每次心跳以及每次昂貴或不可逆的邊界之前執行
verify_claim；無法讀取的控制面不允許任何寫入。 - 僅保留
analysis、ready、in-progress、review、blocked或done中的一個狀態。該繫結的工作流程狀態具有權威性；每個配置的映射都會被更新並讀回，並且在關閉追蹤器之前必須明確設定為done。 - 選定的繫結必須映射
ensure_states、create、list_state、claim、reclaim、verify_claim、heartbeat、transition、comment、last_activity、label、unassign、publish_version和close。執行可執行的可逆操作，而不是重新建構它們；繫結必須宣告不支援的功能，並以失敗關閉。 - 議題接受標準、路由領域規則和儲存庫規則定義了完成。切勿發明缺失的關卡或默默重新解讀議題。
決策關卡
| 情境 | 行動 |
|---|---|
| 分析師有條件或受限的 diff/PR/議題 | 僅在適用的儲存庫和領域規則下分析該範圍。 |
| 分析師沒有條件或領域 | 使用領域組合中的自主 general 契約；僅歸檔最強的、已去重的發現結果，或什麼都不做。 |
| 已記錄領域路由 | 分析師載入左側規則手冊；開發者載入右側規則手冊。當缺少實作路由時，明確說明。 |
| 執行時機制或獨立上下文獲取有所不同 | 遵循執行時備註；執行時限制會改變機制，但不會改變不變量。 |
| 認領、回收或移交安全性需要理由 | 遵循活動中的繫結和安全事件，不要在此處複製事件敘述。 |
| 必須選擇狀態 | 無效規格 -> analysis；可實作且未指派 -> ready；已認領的建置 -> in-progress；已建置/發布 -> review；未建置的外部等待 -> blocked（附帶條件和解除者）；已合併並驗證 -> done。 |
執行步驟
在任何角色於不熟悉的專案中進行第一次追蹤寫入之前，請執行所選繫結的 ensure_states；然後使用該繫結的可執行操作和回讀，而不是重新建構它們。
載入領域組合以獲取路由、規模驗證、佇列分割或自主後備；執行時備註以獲取呼叫、唯讀執行、獨立上下文獲取或執行時限制；僅在需要認領、回收、移交或失敗理由時載入安全事件；以及僅在儲存庫規則未完全定義隔離或整合時載入儲存庫交付。
分析師
- 保持儲存庫和非追蹤器外部系統為唯讀。以最舊者優先的方式清空
analysis，然後檢查blocked：將已解除條件的項目移至ready（附帶證據），對仍然有效的條件註明日期，並說明一個人欠下任何待定決策的時間。 - 僅根據左側領域規則手冊分析受限制的範圍。在沒有條件或領域的情況下，使用自主的
general契約；驗證證據和重複項，然後最多保留最強的可辯護發現結果，或報告沒有發現結果存活。 - 驗證佇列中和新發現結果的欄位、路由、規模和主體契約。對於佇列中的工作，使用
comment添加缺失的移交材料，並僅對同一完整項目進行轉換；切勿建立替代品。對於新的發現結果，填寫分析師議題模板並使用每個標記加上analyst:<runtime>和執行 ID 歸因來create。使用ready，或使用blocked（附帶確切的缺失條件和解除者）；然後停止，無需實作或指派它。
分析師的產出
一個開發者可以接手無需重做分析的議題。如果開發者必須重新推導你的推理，那麼分析就毫無價值。
## 給人類的描述
> [!NOTE]
> 一兩句話，白話文，無行話，無檔案路徑，無指標 — 這個議題是關於什麼的，給那些永遠不會讀到這一行之後的人看的。以運營者配置為此安裝命名的任何語言撰寫（見此檔案末尾的表格）。標題本身是上述固定的、文字性的標題 — 永遠是英文，永遠是那個確切的短語，永遠不針對每個議題改寫。`> [!NOTE]` 是 GitHub 的原生警示語法 — 它會呈現為一個帶邊框、帶顏色的呼籲框，這就是重點：這必須在一個原本充滿技術性散文的議題上，在視覺上不可能被忽略。
這是議題上的第一件事，在 `## Problem` 之前。
## 問題
什麼是錯的或缺失的，以及你如何知道。證據，而非斷言：檔案:行參照、測量到的數字、日誌、重現步驟。
## 為什麼重要
如果放任不管的影響。如果你無法說明一個影響，就老實說 — 一個有記錄的「低影響，為完整性而提出」是誠實的，並讓開發者可以降低優先級。
## 建議方法
設計。你考慮過的替代方案以及你拒絕它們的原因。如果你不確定，請說明哪個部分不確定，以及什麼可以解決它。
## 接受標準
可檢查的陳述。「更快」不是一個標準；「由 X 測量 p95 低於 200 毫秒」才是。包括必須不變的內容（不變量、位元組相同的輸出）。
## 不在範圍內
開發者在此處明確不應該做的事。這比上面各節中的任何篇幅都更可靠地防止範圍蔓延。
## 證據
執行的命令、讀取的檔案、測量到的數字。足夠讓審查者無需重複分析即可重新檢查。
開發者
- 在查閱佇列之前，先恢復本次執行所持有的議題及其記錄的狀態。否則，先清空未指派的
review，再清空ready，並在認領已發布的工作之前重新檢查交付阻礙。 - 對於
ready，根據穩定的領域和宣告的規模對有效候選項目進行分割，僅在每個分割區內排名，並選擇最舊的分割區頭部；選定的領域會將選擇限制在其最高排名的最舊項目中。僅在沒有候選項目具有有效的規模契約時使用最舊優先。 - 使用執行 ID 和時間範圍
claim，然後裁決伺服器時間戳記的時序；最早的存活認領獲勝，失敗者評論、釋放並重新選擇。將已認領的審查工作保留在review中，除非程式碼變更需要in-progress以及一個新的發布/審查/CI 週期；對於準備好的工作，轉換一次到in-progress（附帶dev:<runtime>），不需要第二次認領事件。 - 在規劃之前載入路由的右側實作規則手冊；如果不存在，說明沒有適用的規則，並按照書面接受標準進行建置。遵循儲存庫規則，對於缺失的隔離/整合政策使用儲存庫交付後備，在第一次分支/工作樹/檔案寫入之前立即驗證認領，並在隔離的檢出中進行實作。
- 在發布前更新，發布或重用共享的審查目標，然後轉換到
review。僅當「審查委派」授權此執行時才獲取獨立上下文；否則請求一個單獨啟動的審查。要求其裁決以及在完全相同的 head/base 上通過的 CI；每次推送都會使兩者失效。將受阻的交付保留在review中，恢復因失敗嘗試而變更的本地狀態，記錄確切的阻礙者，並取消指派而非繞過它；衝突的儲存庫規則會產生一個單獨的議題。 - 在每個不可逆邊界處更新；僅在經過審查、CI 通過且當前 head/base 身份匹配時才進行合併。對於合併提交路由，要求交付的 SHA 的確切父項為已審查的基礎和 head；其他配置的策略需要它們繫結宣告的等效拓撲以及任何交付的 SHA 關卡。對於每個變更的版本，發布並遠端驗證其不可變的註記標籤和所需的 Release；再次更新，轉換到
done，使用執行 ID 記錄審查/CI/測試/測量結果/PR/交付 SHA/發布內容，然後關閉。在移交時，保留所有證據：錯誤的規格轉為analysis，未建置的外部等待轉為blocked，已建置但無法交付的工作轉為review，以及有用的部分診斷轉為ready。
詳細的審查關卡保留到最後的退役切片
-
讓未撰寫該變更的上下文審查已發布的變更，然後要求在最新的 PR head 上通過 CI。 在審查之前捕獲 head 和 base SHA，並要求裁決工件明確命名兩者；一個浮動的「已批准」不是任何特定修訂版或差異的證據。在配置授權的情況下，自行獲取該上下文 — 一個子代理或隊友；在未授權的情況下，將 PR 交給一個單獨啟動的分析師執行，並在議題上說明你正在等待它。配置決定的是誰啟動審查，而從不決定審查是否執行。每次推送都會使先前的裁決和 CI 結果失效：重新審查變更的表面，並再次等待所需的檢查。
如果審查、CI 或交付受阻，就在那裡停止，並將其保留在
review中。已建置並發布但無法發貨的工作 — 審查者要求變更、檢查失敗、無法由不同身份提供所需的原生核准、權限缺失、兩個專案規則互相矛盾 — 是已完成但等待交付的工作，而這正是review的含義。不要將其移至done：該狀態表示已交付。也不要繞過阻礙者；你為了發貨而繞過的規則，就是一個不再有任何意義的規則。精確評論阻礙者 — 是什麼拒絕了它，那個東西期望什麼，專案要求什麼替代方案 — 然後取消指派，以便另一個操作者可以完成交付。恢復你因嘗試而變更的任何本地狀態。
一個來自兩個專案規則互相矛盾的阻礙者，值得它自己的一個議題。 它會打擊下一個任務，以及再下一個任務，而每次執行都會從頭開始重新診斷它。一個已歸檔的發現結果會將一個反覆出現的稅收轉變為一個可以一次性做出的決定。
-
僅在所需的 CI 通過後合併已審查的 PR head，發布任何版本標籤，然後
close。 在合併前立即更新認領，要求已審查的 head/base == CI head/base == 當前 head/base，將合併繫結到已審查的 head SHA，並在任一方移動時拒絕。使用配置的合併策略；merge commit保留分支邊界和 PR 祖先，而 squash 和 rebase 則刻意丟棄該資訊。在合併後檢索交付的 SHA，並驗證其父項正好是已審查的基礎和已審查的 head；不要僅從命令旗標就宣稱拓撲保留。僅當配置的方法保證相同的拓撲時，合併佇列才符合資格。如果專案需要對確切的交付 SHA 進行 CI，請等待該合併後關卡。
在儲存庫中工作 — 預設流程
儲存庫的規則永遠優先。 在任何其他事情之前，先讀取其代理指令（AGENTS.md、CLAUDE.md 或等效檔案）並遵循它們。以下是對於未規定任何規則的儲存庫的後備方案，以及對於僅規定部分規則的儲存庫的底線 — 絕非競爭標準。
較舊的後備方案 — 使用提交歷史作為慣例 — 無法擴展到這個程度，而這是值得說明的。git log 會告訴你提交訊息是如何撰寫的。它無法告訴你兩個代理是否可以共享一個檢出，或者一個在一小時前驗證的分支在其他人合併後是否仍然有效。這些答案決定了平行工作是否會損壞自身，因此此技能提供這些答案，而不是將它們留給一個沒有理由知道的領域。
1. 永遠不要在基礎樹中工作。 對於開發者來說，預設分支是唯讀的：無編輯，無提交。在第一次變更之前檢查，而不是假設：
git branch --show-current # main / master -> 停止，先建立分支
如果你發現你已經提交到基礎分支並且尚未推送，將提交移至一個分支並重置。如果你已經推送，不要強制推送 — 還原並正確重做。