0x0w1/jig

README

使用此技能來根據倉庫的實際狀態建立或更新其 README.md。

程序

1. 掃描倉庫：
   • 清單和建置檔案：pyproject.toml、package.json、Cargo.toml、go.mod、Makefile、鎖定檔案。
   • 進入點、CLI 參數定義、腳本和服務配置（Dockerfile、docker-compose*.yml）。
   • docs/ 下的現有文件和程式碼中的使用範例。
2. 分類專案類型：CLI 工具、函式庫、服務/應用程式 或 其他。當未設定設定檔時，類型會選擇以下章節佈局。
3. 根據下面的設定檔合約來確定 README 設定檔。解析成功的設定檔會取代此倉庫的通用預設值；當沒有設定檔可解析時，請提出一個，並無論如何都繼續進行。
4. 根據當前狀態進行分支處理：
   • 沒有 README.md → 建立路徑：使用下面的章節佈局起草 README。
   • README.md 存在 → 更新路徑：根據倉庫檢查 README 中每個可驗證的陳述——命令、選項、檔案路徑、連結、功能陳述。將不符之處收集到一份差異清單中，回報該清單，然後套用修正。保留仍然準確的章節不變。
5. 對寫入的每一行套用準確性規則。
6. 套用來自下面壓縮規則的壓縮遍歷：
   • 建立路徑：在起草時套用。由於尚未發佈任何內容，因此沒有需要提議的內容。
   • 更新路徑：將重複和誇大其詞的內容收集到一個提案中——命名每個事實、其重複出現的位置、以及會存放它的詳細文件——然後在移動任何內容之前詢問。即使使用者拒絕該提案，也要回報它。
7. 合併變更：
   • 當倉庫具有 develop-task-flow 技能（或已安裝的 jig-develop-task-flow）時，請遵循它：建立一個 chore/<slug> 分支，進行帶有 docs: 提交訊息的壓縮合併，然後推送到 develop。
   • 否則，建議在當前分支上進行一次普通的提交。

設定檔合約

即使是相同專案類型的兩個倉庫，它們的 README 寫法也可能不同：一個保留翻譯鏡像，另一個將安裝步驟移到指南中，第三個則有其貢獻者已經遵循的表格慣例。這些是決定，而非可以透過掃描倉庫獲得的事實，因此它們會被記錄一次，並在每次後續執行時讀取。

按以下順序解析設定檔：

1. JIG_README_PROFILE 環境變數。
2. git config --local --get jig.readmeProfile。
3. .jig/readme.md。

當設定檔解析成功時，它會覆蓋下面針對該倉庫的章節佈局和語言規則；它未提及的任何內容都將回退使用它們。讀取它，遵循它，並在報告中命名它。

當沒有設定檔可解析時，請根據掃描結果起草一個並提出建議：分類後的類型、倉庫已使用的書寫語言、是否存在鏡像、當前 README 隱含的章節順序，以及哪些詳細文件已經容納了超出的內容。僅在使用者接受後才寫入 .jig/readme.md。如果使用者拒絕或沒有回應，則繼續使用通用預設值並說明情況——缺少設定檔是正常狀態，而非阻礙。

該檔案僅記錄決定。它不包含門檻值或檢查清單；README 的品質仍然由此技能在面對倉庫時做出判斷。

# README 設定檔

> 基礎：<此決定方式>，<YYYY-MM-DD>

## 語言

規範：`README.md`（英文）。鏡像：`README.ko.md`（韓文），在同一任務中更新。

## 章節

標題和連結列、這是什麼、快速開始、技能、文件、授權。

## 詳細文件

安裝選項 → `docs/installation.md`。路線圖和設計記錄 → `docs/roadmap.md`，僅從文件首頁連結。

## 慣例

識別碼表格保持描述儲存格僅限一個子句。貢獻者命令保持在 `<details>` 區塊內。

章節標題是合約內容；其下的文字屬於倉庫本身。如果設定檔是在這些標題存在之前寫的，但只要它使用這些標題，仍然可以正確讀取。

章節佈局

必需的章節，按順序：

1. 標題加上一行描述。
2. 簡介：專案的用途及其存在的原因。
3. 安裝。
4. 用法。

按專案類型的補充：

• CLI 工具：命令和選項表格。
• 函式庫：帶有範例程式的 API 摘要。
• 服務/應用程式：如何執行（開發和生產）以及所需的環境變數。

可選：文件連結、授權。

佈局規則

• 對於人們會複製的識別碼（技能名稱、命令、選項、路徑），表格是合適的。破壞此類名稱的是欄之間的寬度比例：GitHub 根據內容調整欄位大小，因此如果描述欄比識別碼欄長好幾倍，就會壓縮識別碼，直到它在名稱中間換行，讀者就會看到一個不存在的名稱。
• 保持描述儲存格大致與識別碼一樣短，大約一個子句。當描述過長時，請縮短它們或將整個內容移至列表中：- **name** — 描述。
• 描述內部的換行是預期的，無需處理。

壓縮規則

讀者在決定使用專案之前會先閱讀 README。其中的所有內容都在爭奪這份注意力，因此長度是一個徵兆：冗長的 README 幾乎總是一個事實被寫在多個地方，而不是一個有很多話要說的專案。

**移動，不要刪除。**當同一個事實出現在多個地方時，將其保留在讀者最先到達的地方，並將剩餘的內容移動到已涵蓋該事實的詳細文件中，僅在沒有此類文件時才建立它。什麼都不會丟失；README 不再重複自己。沒有要達到的行數目標——一個包含真正需要的 API 範例的函式庫 README 並不算太長，而一個說了同一件事兩次的簡短 README 仍然是錯的。

**以讀者獲得的好處開頭。**簡介應該說明什麼變得更容易，而不是存在哪些功能。記錄合併時的分級版本說明 是一個功能；你不再需要推測某個版本為何是次要版本 才是讀者獲得的好處。根據證據的強弱對陳述進行排序，最有力的優先，並讓周圍的文字以相同的順序列出它們——一個段落及其要點不得暗示不同的優先順序。

**僅陳述倉庫能夠支持的內容，並說明何時適用。**倉庫無法證實的陳述應被省略，而非軟化。說明價值出現的條件，以便不符合該條件的讀者可以快速排除該專案，而不是後來才發現。

**刪除安裝前不會被閱讀的內容。**路線圖、設計記錄和方向說明是專案為自己保留的內容。從文件首頁連結它們，而不是從 README。

**折疊貢獻者材料。**建置、重新產生和驗證命令是為已經複製倉庫的人服務的。將它們放在 <details> 區塊或貢獻指南文件中。

**合併僅因一個值而異的區塊。**針對不同平台或目標、僅參數不同的獨立命令區塊，應合併為一個區塊並命名該參數。

**給讀者一個越過頂部的方法。**當 README 有超過大約四個章節時，在標題下方放置一行連結列，以便再次訪問的讀者可以直接跳轉到他們要找的章節。

準確性規則

• 僅撰寫已根據倉庫驗證過的安裝和執行命令：腳本、清單或鎖定檔案必須顯示它們。
• 驗證每個連結的檔案路徑是否存在。
• 不要描述倉庫中不存在的功能、徽章或整合。
• 當無法驗證某項陳述時，請省略它並回報。

安全規則

• .jig/readme.md 僅在使用者接受提案後才寫入，絕不作為一般 README 更新的副作用。
• 未經明確確認，絕不覆蓋現有的 .jig/readme.md。提出變更並說明它將取代什麼。
• 不觸碰 .jig/ 下的任何其他內容。version-rubric 擁有 .jig/versioning.md。
• 已發佈的 README 永遠不會在未通知的情況下被重新組織；壓縮遍歷會提出並等待。
• 保留使用者做出的、不相關的變更。

語言規則

• 現有的 README 保留其語言。
• 新的 README 使用倉庫文件已有的語言撰寫，預設為英文，技術術語放在反引號中。
• 使用者的明確語言要求會覆蓋以上規則。

報告

• 專案類型和所採取的路徑（建立或更新）。
• README 設定檔：路徑和來源，或已提議但被拒絕，或沒有設定檔並使用通用預設值執行。
• 在更新路徑上：差異清單以及已修正的內容。
• 壓縮提案：每個在多個地方重複的事實、它將被移動到哪裡，以及使用者是否接受。
• 無法驗證並被省略的陳述。