code-documentation

此技能為軟體專案中的技術文件管理提供了強大的框架。專為開發人員、技術寫作人員和 AI 代理設計，確保專案文件保持一致、可讀且即時。透過遵守結構化模板，使用者可以減少入職期間的認知負載並提高程式碼庫的可維護性。該工具執行「將文件保留在程式碼附近」的原則，促進更好的開發者體驗與更可靠的知識共享。

• 標準化 README 模板，包含快速入門、安裝、使用方式、配置表與貢獻指南。

• 支援 JSDoc/TSDoc 註釋，從原始碼生成清晰的 API 參考文件。

• 支援 OpenAPI 與 Swagger 規範，用於記錄 RESTful 端點與請求/回應模式。

• 架構決策記錄 (ADR) 模板，用於追蹤技術決策、背景、原理與影響。

• 行內註解準則，用於區分解釋「為什麼」（業務邏輯、權宜之計）與「是什麼」（顯而易見的程式碼區塊）。

• 元件級文件標準，用於管理模組、資料流與外部依賴關係。

• 將此技能整合至 CI/CD 管道或開發工作流中，以強制執行微服務或程式庫間的一致性。

• 優先編寫範例而非詳盡的解釋，以保持文件的實用性。

• 採用漸進式揭露：為新手提供簡潔的 README 快速入門，並連結至更深度的 API 參考以滿足資深使用者需求。

• 務必將技術文件與實作碼保存在同一個儲存庫中，以確保更新與功能變更同步。

• 避免冗餘註解；專注於捕捉設計意圖、HACK、TODO 以及從函數簽名中無法直接看出的複雜業務規則。

• 利用基於 Markdown 的 ADR 來維護專案演進的歷史記錄，這對於長期架構穩定性至關重要。