EvolveHQ/docflow

引導

你正在當前儲存庫中安裝（或改造）一套文件驅動的慣例集。最終狀態是一個可以透過一組小型規範檔案，同時由人類和編碼代理驅動的儲存庫。請沿用此處描述的機制 — 與任何其他專案無關。

步驟 1 — 偵測情況

在詢問任何問題之前，先檢查儲存庫。重複使用本次會話中已提供的明確答案和批准；切勿用設定檔預設值取代它們或再次詢問。在撰寫之前，根據這些答案總結已確定的製品根目錄、深度、佇列、閘門和協調/整合模式。如果主機將選定的資料夾鏡像到沙盒中，請識別實際的目標路徑以及已驗證的輸出如何到達選定的資料夾；切勿僅僅因為鏡像通過測試就將未觸及的目標標記為完成。

• 全新儲存庫（無原始碼、無文件）：你正在從零開始建立。

• 現有儲存庫：你正在改造。

  • 在提出變更之前，先閱讀任何現有的 README.md、CONTRIBUTING.md、AGENTS.md、CLAUDE.md、docs/、adr/、.github/。
  • 保留現有內容。合併，不要覆蓋。如果現有慣例與下列慣例衝突，請在評估摘要中提出衝突。
  • 如果 ADR 已以其他格式存在，請提出遷移計畫（重新編號、保留、翻譯），而不是建立一個平行目錄樹。

• 已經是 docflow 儲存庫（包含 AGENTS.md + CONVENTIONS.md + ADR 目錄）：你是在擴展現有設定，而不是在建立新結構。不要重新建立核心結構或重新詢問已解決的問題 — 從 CONVENTIONS.md/AGENTS.md 讀取已記錄的選擇（ADR 形狀、狀態生命週期、製品根目錄、多代理模式以及哪些可選層已存在）。然後，提供啟用任何仍然缺少且先前選擇略過的可選層 — plan/、_agent/、GLOSSARY.md、domains/ 或第二個 ADR 形狀（技術範本） — 並僅撰寫所選擇的項目，以合併方式，置於已記錄的製品根目錄下，保持其他所有內容不變。僅詢問新層所需的問題（例如，啟用 _agent/ 時的協調問題 — 在沒有同時記錄驗證閘門和計畫佇列的情況下，單一撰寫者最終不會有 _agent/ 目錄，因為該層根本就不需要）。這是加入你在首次引導時推遲的層的入口點。仍保留早期引導所寫協調檔案的儲存庫，請保留它們：在此保持原地不動，讓審計技能報告佈局。

  啟用 GLOSSARY.md 會寫入規範殼層，絕不重寫。 當選擇此層且檔案不存在時，從 templates/GLOSSARY.md 撰寫 — 可選標題和散文，然後是在產生的 CONVENTIONS.md 的 §詞彙表中所記錄的單一 術語 | 定義 表格。如果檔案已存在，則保持不變：啟用此層不會新增任何內容，而 add-convention 會以規範形狀擴展現有檔案，或者 audit 提供已同意的遷移。

  啟用第二個 ADR 形狀是方案切換，而非檔案複製。 這是唯一會改變已記錄選擇的推遲層，因此請一次性全部撰寫或完全不撰寫：用雙形狀文字替換 CONVENTIONS.md 中的 §ADR 形狀，將技術章節順序和形狀要點加入 AGENTS.md，撰寫 adr/0000-template-technology.md，並使用 Shape 欄重新產生 INDEX.md。現有 ADR 保持其編號並保留為能力 — 缺失的 shape: 欄位已意味著能力，因此不會重寫任何 ADR，也不會重新編號。部分切換會使儲存庫處於步驟 4.5 交叉檢查稱為矛盾的狀態：存在一個技術範本，但單一形狀方案永遠不會選用它。

  已經使用舊版範圍編碼的儲存庫會收到遷移提議。 一些雙形狀儲存庫是在形狀成為宣告欄位之前建立的，並將其編碼在編號中：§ADR 形狀記錄了一個截止點（低於該點為能力，等於或高於該點為技術），並且 adr/ 包含一個非 0000 編號的範本（例如 adr/0100-template.md）。任一個訊號單獨都能識別它。這樣的儲存庫並不是缺少一個層 — 它已經擁有兩種形狀 — 因此不要提供上述的方案切換，這會使其陷入兩個競爭編碼的困境。提供遷移到已宣告欄位的方案，條件與審計技能使用的相同：

  • 首先顯示舊到新的編號對應圖，作為試運行：能力 ADR 保留其編號；技術 ADR 在最高能力 ADR 編號之後依序取得新編號。同時，列出會受影響的參考（depends-on、supersedes / superseded-by、相對 adr/NNNN-*.md 連結、INDEX.md、域 README.md 列表、plan/todo/ 的擁有 ADR 行）以及保留為歷史記錄的內容（plan/done/ 頁尾、提交訊息、標籤）。
  • 未經明確確認該對應圖，不得撰寫任何內容。 拒絕是有效的結果：儲存庫保留範圍編碼並繼續通過其自身的規則。
  • 確認後，完全依照審計技能的遷移步驟規定應用遷移 — 重新編號、在每個 ADR 上蓋上 shape:、重寫目錄內的所有參考、用 adr/0000-template-technology.md 取代邊界範本、將 §ADR 形狀重寫為已宣告欄位並刪除任何種子 ADR 例外條款、使用 Shape 欄重新產生 INDEX.md — 並將其作為一個提交，其訊息列出每一對舊到新的編號。該程序是唯一的真相來源；請勿在此處改寫另一種變體。
  • 然後正常繼續處理真正缺少的層（plan/、_agent/、GLOSSARY.md、domains/）。

在詢問評估問題之前，用一行說明適用哪種情況。

步驟 2 — 目標佈局

<repo>/
  AGENTS.md              # 編碼代理的硬性規則 — 進入點
  CLAUDE.md              # 單行：@AGENTS.md
  README.md              # 面向人類的專案摘要（如果存在則保留）
  CONVENTIONS.md         # 撰寫規則：ADR、命名、狀態、審計、git
  INDEX.md               # 所有 ADR 的產生表格
  GLOSSARY.md            # 共享術語（可選 — 見 Q7）
  adr/
    0000-template.md     # 能力 ADR 範本（始終存在）
    0000-template-technology.md  # 技術 ADR 範本（僅在雙形狀時存在 — 見 Q2）
    NNNN-<kebab-slug>.md # 每個決策一個 ADR，連續編號
  domains/<slug>/README.md   # 可選（見 Q7）
  plan/
    README.md
    todo/NNNN-<slug>.md
    done/<YYYY-MM-DD>-<slug>.md
  _agent/                # 代理操作合約（見 Q5）— 可選
    ROLES.md             # 誰撰寫什麼（僅多位撰寫者）
    LOCKS.md             # 檔案聲明互斥鎖（僅共享檢出）
    prompts/autonomous.md  # 無人值守運作的行為（僅在有
                         #   驗證閘門 — Q8 — 和計畫佇列 — Q4a 時）
  federation.md          # 僅多儲存庫（Q11）：此儲存庫的回指指標
  federation-index.md    # 僅多儲存庫（Q11）：成員索引 — 僅主儲存庫

放置位置。 上方的樹狀結構顯示的是根目錄選項。AGENTS.md 和 CLAUDE.md 始終位於儲存庫根目錄；adr/、plan/、_agent/、INDEX.md 和 CONVENTIONS.md 則放在 Q12 中所選擇的製品根目錄下（預設為 .docflow/，例如 .docflow/adr/、.docflow/plan/）。

發現機制。 工具無需先讀取 CONVENTIONS.md 即可定位製品根目錄：儲存庫根目錄下的 .docflow/ 目錄即為根目錄；對於任何其他根目錄，引導會在儲存庫根目錄下撰寫一個 .docflow 檔案 — 一個單行指標，root: <路徑>（例如 root: docs/、root: .）。兩者都不存在表示一個合約前的儲存庫（工具會探測 docs/，然後是儲存庫根目錄，尋找命名了製品根目錄的 CONVENTIONS.md）或不是一個 docflow 儲存庫。

_agent/ 是代理操作合約 — 誰撰寫什麼、唯一的真正互斥鎖、以及無人值守運作的行為。它不包含 git 已記錄的任何內容：沒有重複的出貨記錄、沒有進行中工作的儀表板、沒有當前狀態的快照、沒有交接。上述三個檔案中的哪些存在完全取決於 Q5、Q8 和 Q4a，而一個完全沒有 _agent/ 目錄的儲存庫是有效的結果。

核心 vs 可選層。 只有核心是始終會撰寫的：AGENTS.md、CLAUDE.md、CONVENTIONS.md、adr/0000-template.md 和 INDEX.md。僅包含這些內容的儲存庫是一個有效且輕量級的 docflow 儲存庫 — 一個帶有慣例的經典 ADR 目錄。其他一切都是選擇加入的層：plan/ 佇列（Q4a）、_agent/ 合約（Q5 + Q8 + Q4a — 一個沒有同時具備驗證閘門和計畫佇列的單一撰寫者將不會獲得任何這些內容）、GLOSSARY.md 和 domains/（Q7）。省略任何可選層都是有效狀態，而非錯誤；需要缺少層的生命週期技能會乾淨地拒絕並指出缺少的內容。

對於多儲存庫產品（一個產品分散在多個儲存庫中 — 見 Q11），會出現兩個額外的檔案：federation.md，每個成員儲存庫攜帶的小型回指指標；以及 federation-index.md，僅存在於主/建立儲存庫的權威成員列表。所有聯合製品 — federation.md、federation-index.md 和衍生的彙總 ROLLUP.md — 都放在已配置的製品根目錄下。獨立的儲存庫沒有這些檔案。

步驟 3 — 要安裝的慣例

1. ADR 是唯一真相來源。 每個 ADR 一個決策。拆分變成新的 ADR 並取代舊的；切勿在現有 ADR 內部擴展範圍。
2. 最多兩個 ADR 形狀，由欄位宣告。 區分兩者的儲存庫將區別記錄在每個 ADR 的 shape: 元資料欄位中（capability 或 technology；缺失的欄位意味著能力）— 絕不在編號範圍中。每個 ADR，無論其形狀為何，都取用下一個連續編號，並且每個形狀都有自己的範本，兩者都編號為 0000。
   • 能力 ADR（系統必須做什麼）。章節順序：元資料 → 背景 → 能力聲明 → 使用者故事/場景 → 驗收標準 → 非範圍 → 開放問題 → 參考資料 → 修訂歷史 → 批准。
   • 技術 ADR（如何建構）。章節順序：元資料 → 背景 → 決策 → 理由 → 後果 → 驗收標準 → 非範圍 → 開放問題 → 參考資料 → 修訂歷史 → 批准。理由必須列出考慮過的替代方案，並給出具體的拒絕原因（而不是「更簡單」/「更習慣用法」）。
3. 狀態生命週期： 提議中 → 已接受 → 已實作 → (已取代 | 已棄用)。終端狀態可從任何先前狀態達到。狀態驅動計畫資料夾的放置：已接受 → plan/todo/，已實作 → plan/done/。
4. 檔案名稱： adr/NNNN-kebab-slug.md，零填充 4 位數，連續，無保留間隙。交叉引用使用相對路徑。
5. 驗收標準是可測試的且已編號。 測試在實際可行的情況下映射回它們。
6. 審計紀律。 實質性的 ADR 變更會附加一個修訂歷史行。編輯性變更（錯字、格式、連結修正）被排除，但在提交訊息中標記為 editorial。批准表在 ADR 被接受時填入，並在每次後續實質性修訂時更新。
7. INDEX.md 會重新產生 在任何 ADR 變更後從 ADR 元資料產生。視為衍生產品，非手動編輯。
8. plan/ 是工作佇列。 當工作上線時，git mv plan/todo/X plan/done/<date>-X，任何計畫項目的狀態移除、擁有 ADR 狀態前進以及 INDEX.md 重新產生都分組在完成提交中。在直接合併到主線整合下，該提交被推送到整合分支，並且移動檔案的頁尾會命名 HEAD SHA（以及適用的部署工件 ID）。在拉取請求整合下，這些變更是拉取請求分支在被標記為準備好之前的最後一個提交，頁尾命名拉取請求，而合併是完成事件。
9. 協調是合約，不是日誌。 _agent/ 僅包含 git 無法告訴你的內容，並且每種模式（Q5）精確地規定其自己的檔案 — 不會在那裡撰寫其他任何內容。在共享檢出中，代理在編輯前會將一行附加到 _agent/LOCKS.md（<代理ID> | <路徑> | <ISO-8601 時間戳記>），並在提交時將其移除；該分類帳是唯一的真正互斥鎖，而佇列項目則在項目本身上被聲明。在單獨工作目錄樹中，佇列項目通過推送 claim/<item-key>（佇列檔案名稱不含副檔名）以及從其拉出的一個草稿拉取請求（如果整合是基於拉取請求的）來聲明；推送就是排除第二位撰寫者的方式，且不保留分類帳。在單一撰寫者下，沒有需要序列化的內容，也沒有需要聲明的內容。沒有任何模式保留重複的出貨狀態、進行中工作的儀表板或當前狀態的快照：git 歷史和 plan/done/ 是記錄，而活動中的分支和拉取請求是進行中的內容。
10. Git 合約。 Conventional Commits。在觸及 ADR 的提交上強制加上 Rationale: 頁尾。除非使用者選擇退出，否則需要簽署提交。除非使用者要求，否則代理工作不使用 Co-Authored-By 追蹤。
11. AGENTS.md 是硬性規則的進入點； CLAUDE.md 是針對讀取它的相容代理的單行 @AGENTS.md。
12. ADR 是內部製品 — 絕不讓使用者看到。 ADR 編號、ADR 標題以及 ADR 目錄的存在絕對不能出現在觸及使用者的產品程式碼路徑中：UI 字串、API 回應主體、錯誤訊息、發送給客戶的日誌行、公開文件、發行說明、行銷文案或支援通訊。ADR 是為建構者設計的，而非使用者。允許在以下位置引用：程式碼註解（`// 參閱 a……

……（原文因長度截斷）`）