documentation-and-adrs

documentation-and-adrs 技能概覽

documentation-and-adrs 技能能做什麼

documentation-and-adrs 技能能幫助 agent 撰寫以決策為核心的技術文件，特別是 Architecture Decision Records（ADR）。它真正的用途不是「多寫一點文件」，而是「記錄團隊為什麼選這個方案、哪些限制很重要，以及哪些替代方案被否決」。當程式碼本身無法說明未來的維護決策時，這個技能就很有價值。

最適合的使用者與工作目標

這個技能最適合工程師、技術主管、架構師，以及正在撰寫架構、API、基礎設施、認證、資料模型或使用者可見功能變更相關 Technical Writing 的團隊。當你需要能留給未來工程師或 agent 的長效脈絡，而不只是把今天的工作說得好看，請使用 documentation-and-adrs。

它和一般 prompt 的差異

一般 prompt 可能會產出一份清楚的摘要，但 documentation-and-adrs skill 的重點是決策紀錄：背景、限制、選項、取捨與後果。這個框架很重要，因為多數品質不佳的文件問題不在於描述不夠，而在於只講了實作，卻漏掉未來維護者真正需要的思考脈絡。

什麼情況下不該安裝

如果你只想要行內註解、簡單的 README 整理，或是一次性原型的文件，就先不要用這個技能。對於意圖已經很明顯、而且沒有值得保留的決策歷史的簡單程式路徑，它也不是理想選擇。

如何使用 documentation-and-adrs 技能

安裝時的脈絡與從哪裡開始讀

執行 documentation-and-adrs install 時，先從 addyosmani/agent-skills repository 安裝這個技能，然後先讀 skills/documentation-and-adrs/SKILL.md。這個技能只提供單一的引導檔，沒有輔助腳本或參考檔可依賴，因此輸入品質比工具型技能更重要。

如果你的環境支援 skill 安裝，可以使用：
npx skills add addyosmani/agent-skills --skill documentation-and-adrs

接著檢視：

• skills/documentation-and-adrs/SKILL.md

documentation-and-adrs 技能需要什麼輸入

這個技能最適合你提供的是「決策面」，而不只是想要的輸出格式。強而有力的輸入通常包含：

• 正在提議的變更
• 受影響的系統或 API
• 例如效能、合規、成本、期限或相容性等限制
• 已評估過的替代方案
• 預期後果與風險
• 目標受眾與輸出位置，例如 docs/adr/ 或 docs/architecture/

弱的輸入： 「幫我寫一份把系統搬到 GraphQL 的 ADR。」

較強的輸入：

• 現況：REST API 在多個 mobile clients 上有版本管理痛點
• 需要決策：是否在新的產品面採用 GraphQL
• 限制：既有 REST endpoints 需保留 12 個月、平台團隊人力精簡、需要欄位層級的 client 彈性
• 替代方案：改善 REST 規範、tRPC、GraphQL gateway
• 決策擁有者：platform lead
• 輸出：包含 status、context、decision、consequences 與 rejected alternatives 的 ADR

如何下 prompt 才能更好地運用 documentation-and-adrs

好的 documentation-and-adrs usage prompt，應該同時要求結構與推理品質。可參考這個穩定的模式：

1. 先說明決策或文件類型。
2. 提供專案背景與限制。
3. 列出評估過的選項。
4. 要求 agent 點出取捨、假設與後續行動。
5. 指定目標格式。

範例 prompt：
“Use the documentation-and-adrs skill to draft an ADR for choosing an authentication strategy for our B2B SaaS. Compare hosted auth, self-managed OAuth, and passkeys-first. Include context, constraints, decision drivers, rejected options, consequences, migration notes, and open questions. Audience is future backend and security engineers.”

給實際團隊的建議工作流程

對於實務上的 documentation-and-adrs guide 工作流程，建議依照這個順序：

1. 從 issues、PR、architecture notes 與 team chat 蒐集事實。
2. 先請 agent 萃取決策驅動因素，再開始起草。
3. 初稿完成後，檢查是否漏掉替代方案或未明說的限制。
4. 把輸出整理成 repository 文件或 ADR，並固定命名與存放位置。
5. 等決策在 production 驗證後，再更新紀錄。

這個技能在搭配具體原始材料時，特別適合 Technical Writing。若你要它去推測任何地方都沒提供的商業或架構理由，它的效果就會明顯變弱。

documentation-and-adrs 技能 FAQ

documentation-and-adrs 適合 Technical Writing 新手嗎？

可以，但前提是新手已經拿得到決策背後的事實。這個技能能替 ADR 與決策文件提供很好的結構，但不能取代技術判斷。新手通常在提供會議紀錄、issue 連結，或粗略的優缺點清單時，效果會比直接要求它憑空生一份文件更好。

它和單純要求「寫文件」有什麼不同？

一般的文件 prompt 通常是以可讀性為優先。documentation-and-adrs 則是以決策的可維護性為優先：為什麼選這條路、當時有哪些限制、以及未來讀者在變更前應該知道什麼。這種差異在架構、公開 API 和基礎設施選擇上最重要。

這個技能的邊界是什麼？

這個技能不是整個 repo 的文件系統、style linter，也不是會自動化產生文件的 generator。它提供的是流程與結構上的指引，不是由工具強制執行的腳本或 template。如果你需要自動同步文件、標準強制或發佈流程，還是得搭配其他工具。

什麼時候不該使用 documentation-and-adrs skill？

不要拿它來處理瑣碎的實作細節、顯而易見的 refactor、重複的程式碼註解，或沒有長期價值的猜測型原型。如果團隊還沒有做出真正的決策，可以用這個技能比較選項，但不要在決策尚未完成前，就假裝已經有最終 ADR。

如何改進 documentation-and-adrs 技能

提供可以用來做決策的輸入，而不是只有摘要型輸入

要最快改善 documentation-and-adrs skill 的輸出，關鍵是提供能支撐決策的證據。請包含被否決的選項、限制，以及預期後果。少了這些，輸出雖然會很順，但也會很空泛。若可以，提供 design docs、PR 說明、RFC 或 incident review 的片段。

留意常見失敗模式

最常見的問題有：

• 重複實作細節，卻沒有記錄決策理由
• 只列出替代方案，卻不說明它們為什麼沒被選上
• 漏掉風險、遷移成本或營運後果
• 只寫給今天的 reviewer，看不見未來維護者的需求

如果你看到這些情況，請要求重寫，重點放在「decision drivers、rejected alternatives、downstream consequences」。

初稿完成後，先從結構修正，而不是整份重寫

第一版之後，與其整份推翻，不如請 agent 針對薄弱段落加強。好的追問包括：

• “Make the tradeoffs more explicit.”
• “Add assumptions and what would change this decision.”
• “Separate immediate consequences from long-term maintenance impact.”
• “Rewrite for future engineers unfamiliar with this subsystem.”

讓技能配合你的 repo 慣例

要讓 documentation-and-adrs for Technical Writing 更有用，請直接告訴 agent 你的檔名規則、ADR 格式與文件位置。例如，說明你是用像 docs/adrs/0007-auth-strategy.md 這類有序 ADR，還是把主題式文件放在 docs/architecture/ 底下。你的 prompt 越貼近 repository 的文件慣例，產出後需要的整理就越少。