convention.sh

convention.sh 是什麼？

convention.sh 是一個託管工具包，用於教導程式代理產生更一致、可上線的 TypeScript。它提供一個手工調整的 TypeScript 慣例庫，讓代理按需擷取，而非依賴靜態、提示大小的規則集。

核心目的是透過提供具體慣例——如更嚴格的類型模式與執行時驗證方法——來減少粗糙的 TypeScript 輸出，並透過標準介面傳遞。

主要功能

• 託管 MCP 慣例伺服器：convention.sh 以託管 Model Context Protocol (MCP) 伺服器運行，代理可查詢所需慣例片段。
• 按需片段擷取（27 種慣例）：代理無需在每個提示中嵌入規則牆，而是僅在需要時從 27 種慣例庫拉取相關片段。
• 針對 TypeScript 正確性的慣例：列出的慣例強調嚴格類型（避免 any）、使用 Zod 驗證不受信任輸入，並偏好區別聯合而非可選欄位。
• 透過 MCP 的模型上下文整合：透過在代理設定中加入 MCP 端點，即可與任何支援 Standard Model Context Protocol 的代理配合。
• 無需重新部署即保持最新：慣例從託管 MCP 端點提供，後續請求即自動擷取變更，無需重寫提示或應用程式重新部署。

如何使用 convention.sh

1. 在代理中加入 MCP 端點，使用提供的終端指令註冊託管端點：claude mcp add conventiondotsh --transport http https://mcp.convention.sh。
2. 開始在程式代理中執行常規 TypeScript 任務。
3. 讓代理按需請求慣例：任務中，代理會向 convention.sh 伺服器索取所需特定慣例片段。

若使用與範例不同的 MCP 相容代理，請設定其呼叫 convention.sh 描述的相同託管 MCP 端點。

使用情境

• 以一致風格重構 TypeScript 模組：生成或更新 TypeScript 程式碼時，請求慣例，讓代理套用相同的類型與輸入驗證模式。
• 在 API 處理器中驗證不受信任輸入：使用建議 Zod 驗證的慣例，保持輸入檢查明確且一致。
• 避免可選欄位歧義：設計資料結構時，偏好區別聯合而非可選欄位，讓生成程式碼中的變體處理更清晰。
• 減少長時間編碼工作階段的提示膨脹：讓代理僅在需要時拉取特定慣例片段，保持提示聚焦。
• 團隊標準化代理輸出：從共享託管端點提供相同慣例片段，讓套用 MCP 整合的代理跨機器保持一致（更新於下次請求自動擷取）。

常見問題

• 這裡的「按需」是什麼意思？ 慣例透過託管 MCP 伺服器傳遞，代理在任務中僅從 27 種慣例庫請求所需片段，而非每次接收完整規則集。

• 我需要自行建置或託管嗎？ 網站描述 convention.sh 為託管 MCP 伺服器，因此您只需將端點加入代理，而非自行託管慣例庫。

• 如何與我的程式代理整合？ 使用 MCP 整合流程：設定 MCP 相容代理使用託管端點 https://mcp.convention.sh。頁面包含新增 MCP 伺服器的範例指令。

• 包含哪些 TypeScript 規則？ 頁面列出範例慣例，聚焦嚴格類型（無 any）、使用 Zod 驗證不受信任輸入，以及偏好區別聯合而非可選欄位。

• 慣例變更時需要更新提示嗎？ 不需要——慣例從託管 MCP 端點提供，代理於下次請求即擷取新規則，無需重新部署或跨機器過時副本。

替代方案

• 靜態提示規則清單或維基：您可以直接在每個提示中加入 TypeScript 指南，但這容易增加提示體積，且仍可能導致應用不一致。
• 本機 linting/格式化工具鏈（例如 TypeScript ESLint）：這些工具有助於強制風格並事後捕捉問題，而 convention.sh 則透過 MCP 在程式碼生成時提供慣例。
• 其他基於檢索的代理上下文工具：若您已使用 RAG 或基於工具的上下文擷取來進行程式碼工作，可自行建置類似的「按需擷取慣例」工作流程，不過這需要您自行維護慣例庫與檢索邏輯。