Johan409IA/skills

Project Docs

協助建立並維持軟體專案的完整文件集，遵循固定的結構，以及 AGENTS.md 與 MEMORY.md 之間的固定關係。每當使用者需要從無到有產生文件、在變更後重新整理文件，或保持跨檔案的一致性時，請使用此技能。

目標結構

此技能管理的每個專案應朝向以下佈局收斂：

mi-proyecto/
├── README.md          # 這是什麼、如何啟動
├── AGENTS.md           # 給代理人的規則與指示
├── MEMORY.md            # 現行決策與已捨棄的內容
├── CHANGELOG.md          # 各版本之間的變更
├── DESIGN.md             # 視覺設計系統（僅在有 UI 時）
└── docs/
    ├── architecture.md
    ├── plans/            # 代理人的計畫，一個檔案一個計畫
    └── (OpenAPI + Scalar 從 API 在 /docs 提供服務)

如果專案已有其中部分檔案，請先閱讀它們並在原地更新，而非盲目覆寫。如果缺少某個檔案，請依照下方對應的範本建立。

工作流程

1. 調查現有內容。 列出專案根目錄及 docs/ 以查看已有哪些檔案。完整閱讀任何現有的 AGENTS.md/MEMORY.md/CHANGELOG.md/README.md/docs/architecture.md —— 這些檔案依設計都很簡短。
2. 確認範圍。 如果使用者指名某個檔案（例如「更新 CHANGELOG」），就專注於該處，但仍需檢查該變更是否應擴散到 MEMORY.md 或 AGENTS.md（請參閱下方的傳播規則）。如果使用者說的是籠統的內容，例如「記錄我的專案」或「更新文件」，則逐一檢查上方結構中的每個檔案。
3. 從程式碼庫本身（套件清單、進入點、腳本、路由、最近的提交）蒐集所需的事實，而不是憑空猜測。不要發明指令、堆疊細節或端點 —— 透過閱讀程式碼或設定檔來驗證它們。
4. 使用對應的參考範本寫入或更新每個檔案。 嚴格遵守 AGENTS.md（約 30-40 行）和 MEMORY.md（約 50 行）的長度限制 —— 這些是承載約束條件，而非建議，因為代理人每個工作階段都會重新閱讀這些檔案，過於臃腫的版本會失去效用。
5. 回報哪些檔案是新建的、哪些是更新的，並標註任何你無法驗證的內容（例如「未找到測試指令，請確認」）。

文件

README.md

為人類回答「這是什麼以及如何執行」。請參閱 references/readme-template.md。直接從專案實際的腳本（package.json、Makefile、pyproject.toml 等）中提取執行/安裝/測試指令 —— 絕不猜測指令名稱。

AGENTS.md

為在此儲存庫中工作的編碼代理人提供的指示。請參閱 references/agents-template.md 以了解確切的章節與順序。硬性限制：總共約 30-40 行。如果已經更長，你在更新時的工作不僅是 新增，更是 刪減 —— 將任何讀起來像是暫時性決定或進行中註記的內容移至 MEMORY.md，並僅在此處保留持久的規則。

MEMORY.md

工作階段間記憶：目前什麼為真、關鍵決策的原因、嘗試過但被拒絕的內容、下一步要做什麼。請參閱 references/memory-template.md。硬性限制：約 50 行。更新時，要主動刪減 —— 刪除或壓縮不再重要的條目，而不是讓檔案無限增長。

AGENTS.md 和 MEMORY.md 的關係（這是核心慣例 —— 務必正確處理）：

• AGENTS.md 必須包含一個簡短的「記憶 (Memoria)」章節，告訴代理人在開始任務時閱讀 MEMORY.md，並在任務結束時更新它。以此確切措辭為基礎，僅在專案已有不同表述時才進行調整：

  ## Memoria
  - Al empezar, lee `MEMORY.md` para conocer el estado del proyecto y las decisiones tomadas.
  - Al terminar una tarea, actualízalo: estado actual, decisiones importantes (con su porqué) y errores a evitar.
  - Mantenlo breve (máximo ~50 líneas): resume o elimina lo que ya no aporte.
  - Si algo se convierte en una regla permanente, propón moverlo a `AGENTS.md` en lugar de dejarlo en la memoria.
  - No guardes nunca datos sensibles (claves, tokens, datos personales).
  

• AGENTS.md 的「限制 (Límites)」章節必須包含 ✅ Siempre: actualizar MEMORY.md al terminar cada tarea.
• 傳播規則：MEMORY.md 存放目前為真的內容 —— 當前狀態、附有理由的決策、學到的教訓、下一步。AGENTS.md 存放永遠為真的內容 —— 永久規則、慣例、技術堆疊、限制。當 MEMORY.md 中的某個項目不再是一次性決策而成為常設規則時（例如「我們決定永遠不使用 X」變成「永遠不使用 X，就是這樣」），將其向上移至 AGENTS.md 並從 MEMORY.md 中移除。更新任一檔案時，務必檢查是否應進行此升級。
• 切勿將機密、令牌或個人資料寫入任一檔案。

CHANGELOG.md

回答「各版本之間變更了什麼」。遵循 Keep a Changelog 慣例（每個版本下包含 Added/Changed/Fixed/Removed，最新的在上方，頂部有一個 Unreleased 章節用於進行中的工作）。請參閱 references/changelog-template.md。更新時，隨著工作進行將條目新增在 Unreleased 下方，僅在使用者指示發行時才建立新的帶日期版本章節。

DESIGN.md

回答「它長什麼樣子以及 UI 應如何建構」—— 視覺設計系統，由產生 UI 的代理人閱讀。它位於專案根目錄（而非 docs/ 內），與 AGENTS.md 相鄰。它遵循開放的 Google Stitch DESIGN.md 格式（規範：github.com/google-labs-code/design.md，目前為 alpha）。請參閱 references/design-template.md 以了解範本及各區塊的說明。

• 僅適用於有用戶介面的專案（網頁、行動、桌面）。如果專案是純 API/CLI/函式庫且無 UI，請勿建立此檔案，並在報告中說明原因。
• 兩層結構：具有機器可讀標記（colors、typography、rounded、spacing、components）的 YAML 前端資料 —— 這些是規範性數值 —— 加上解釋原因的 Markdown 主體。標記說明什麼；散文說明何時與為何，並按名稱引用標記，而非重複十六進位色碼。
• 章節順序固定：Overview → Colors → Typography → Layout → Elevation & Depth → Shapes → Components → Do's and Don'ts。保持這些標題使用英文，與原文完全相同（工具會按名稱比對它們；別名 Brand & Style、Layout & Spacing 和 Elevation 也可接受），並使用專案的語言撰寫散文。章節可以省略但不能重新排序，重複的標題是錯誤。允許額外的章節（例如 Iconography & Imagery、Motion、Accessibility）—— 務必將它們放在 Do's and Don'ts 之後。
• 從程式碼中獲取數值，絕不發明：Tailwind 設定、CSS 變數（:root、globals.css）、UI 函式庫主題檔案、載入的字型、Figma/DTCG 標記匯出。如果專案有 UI 但尚未定義視覺識別，請提議數值並在報告中標註為「提議，請確認」。
• 如果 DESIGN.md 已存在，請閱讀並在原地更新 —— 絕不無聲覆寫。當顏色、字型或間距變更時，保持標記與程式碼同步。
• 無嚴格行數限制（它像 docs/architecture.md 一樣是參考文件），但保持每個章節精簡：3-6 個要點或一個簡短段落。
• 驗證：如果 Node 可用，執行 npx @google/design.md lint DESIGN.md 並修正錯誤（broken-ref）和合理的警告（missing-primary、contrast-ratio、section-order）；否則告知使用者該指令。
• 如果 AGENTS.md 存在但未提及 DESIGN.md，建議使用者（不要自行套用）新增一行指標，以便 UI 代理人在產生 UI 前先閱讀它 —— 請注意 AGENTS.md 約 30-40 行的限制。

docs/architecture.md

回答「這是如何建構的」—— 元件、資料流、關鍵設計決策及其原因、顯著限制。請參閱 references/architecture-template.md。這是唯一一個可以比其他檔案更長的文件，因為它是參考文件，不是每個工作階段都會重新閱讀 —— 但還是傾向使用圖表和簡短章節而非長篇散文。在說明主要元件/資料流視圖時，若適用請使用 mermaid 圖表。

docs/plans/

當代理人為非平凡任務（多步驟實作計畫、遷移計畫、重構計畫）產生計畫時，將其儲存在此處作為獨立檔案，而不是僅留在對話中。如果目錄不存在則建立它。檔案命名為 YYYY-MM-DD-short-slug.md（例如 2026-10-03-add-payment-webhook.md），以便按時間排序。每個計畫檔案應自成一體：目標、方法、步驟、未解決問題。不要刪除舊計畫 —— 它們是歷史記錄；如果專案想要一個「已完成」標記，請在檔案頂部新增一行狀態註記，而非移除它。

API 文件 —— OpenAPI + Scalar

這些不是靜態 Markdown 檔案 —— 它們是從 API 即時提供的，通常透過 Scalar 的 API 參考渲染器在 /docs 或 /reference 路由提供，讀取 OpenAPI 規範。當被要求設定或更新 API 文件時：

1. 檢查專案是否已產生 OpenAPI 規範（框架裝飾器/註解、openapi.yaml/openapi.json 檔案，或已在相依性中的規範產生函式庫）。
2. 如果規範已存在但尚未透過 Scalar 提供服務，則為專案的框架接上 Scalar 中介軟體/處理器（Scalar 有針對大多數常見後端框架的官方整合 —— 請檢查當前的套件名稱/API，而非假設，因為這個生態系統發展迅速）並將其掛載在 /docs 處。
3. 如果尚無規範，則從現有路由/處理器產生一個（大多數框架都有能從路由定義/類型推導 OpenAPI 的函式庫 —— 優先選擇此方式而非手寫 YAML），然後再接上 Scalar。
4. 絕不手動維護一個龐大的靜態 OpenAPI YAML —— 如果框架能從程式碼推導，這會立即不同步。偏好程式碼優先的產生方式。
5. 設定完成後，在 README.md 中註明 /docs URL，以便人類知道在哪裡找到它。

完成前的檢查清單

• AGENTS.md 不超過約 40 行，並包含指向 MEMORY.md 的「記憶」章節
• MEMORY.md 不超過約 50 行，且沒有屬於 AGENTS.md 的永久性內容遺留在那裡
• README.md 指令已根據實際專案設定驗證，而非假設
• CHANGELOG.md 遵循 Keep a Changelog 格式，並包含 Unreleased 章節
• DESIGN.md（僅在專案有 UI 時）位於專案根目錄，其標記與實際程式碼相符，章節遵循規範順序，且 npx @google/design.md lint DESIGN.md 無錯誤
• docs/architecture.md 反映當前結構，而非過時內容
• 新的代理人計畫已儲存在 docs/plans/ 下，並使用帶日期的檔案名稱
• 任何文件中均未寫入敏感內容（金鑰、令牌、個人資料）