← 返回觀點
/智慧方案FDE團隊

AI 寫的程式變更說明,先放人挑過的重點再展開細節

問題、解法與驗證全擠在一起,讀者得往下翻才知道修改用途。由交付者挑選開頭,後面保留完整內容,再把呈現規則整理成技能。

AIEgentWrX人機協作
AI 寫的程式變更說明,先放人挑過的重點再展開細節

同事寄來一份 AI Agent 整理的程式變更說明,問題背景、修改方式與驗證步驟都寫得很完整,你卻得一路往下找,才知道有哪些事需要自己確認。如果團隊也覺得這類文件讀起來很吃力,先別急著要求 AI 把整份文件刪短。需要查核的人還是得看細節,但只想知道自己的工作會受到什麼影響的人,需要在開頭就看到與自己有關的內容。

智慧方案的建議是:負責交付文件的人先挑出讀者最需要知道的重點,放在開頭,讓同事知道為什麼要讀、讀完要做什麼,後面再保留完整說明。等團隊確認這樣寫確實適用,再訂成固定的文件撰寫規則,就不必每次都等長文產出後才重新刪改。

說明寫得完整,為什麼還是讓人不想讀?

Simon Willison 在近期文章裡談到類似的困擾。他用合併請求(pull request,PR)整理程式變更、記錄決策,再合併完成的成果;不過,即使 AI Agent 把問題、解法與驗證寫得準確又完整,他仍然不想讀完。因此,他會親自挑選重點放在開頭,再把完整說明放進可以點開閱讀的區塊。開頭可以直接採用 AI 寫好的文字,但要先由他判斷,哪些內容值得讀者花時間看。

這是他個人的編輯經驗,原文沒有提供閱讀時間或團隊成效的比較數據。我們建議企業參考他安排內容先後順序的做法:送出文件之前,先想清楚收件人會拿這份文件做什麼,再決定哪些資訊要放在前面,不必一開頭就交代所有工作經過。

以採購比價說明為例,如果這份文件是要請主管決定是否採用某家供應商,開頭就應寫清楚建議採用哪一家、還有哪些條件需要確認,報價明細、比較方式與往來紀錄則留在後面。不過,如果交期還沒確認,而且會影響主管的決定,就不能為了讓摘要短一點,把這件事放到最後。這只是說明文件可以怎麼安排,並非實際發生的客戶案例;你可以先拿團隊現有的文件試著調整,看看讀者是否仍得翻到後面,才知道自己要決定什麼。

開頭先說清楚文件用途、工作影響,以及讀者要做什麼

建議先從團隊經常交付的文件中選一種,例如程式變更說明,訂出大家共用的格式。與其只要求 AI「寫精簡一點」,不如明確列出開頭必須回答哪些問題,負責交付的人也能據此檢查內容。

  • 解決什麼問題:寫清楚使用者原本遇到什麼困難、這次修改後能做什麼,不要只列出改了哪些程式。
  • 影響哪些使用者:說明哪些人的操作方式會改變;如果還有某些情況沒處理,也要一併交代,避免讀者以為所有問題都已解決。
  • 讀者接下來要做什麼:明確列出需要確認、測試或核准的事項;如果只需要讓對方知道,也請直接說明,不要讓同事自己猜。

詳細解法、驗證步驟與限制可以保留在後面,讓需要查核的人繼續閱讀。至於哪些內容要放在開頭,得看會不會影響讀者的決定:限制的詳細原因可以留到後面說明,但如果這項限制會影響是否同意執行,就應先在開頭提醒。同樣地,文件若需要主管核准,摘要就要寫清楚還在等待核准,不能把 AI Agent 的建議寫成已經決定要執行的事項。

呈現方式可以配合團隊現有的工具。原文提到,GitHub 的議題留言與 PR 說明可以使用 <details><summary> 標籤,讓讀者自行展開完整內容;如果使用其他協作系統,則要先確認是否支援,不支援的話,分成摘要與詳細說明即可。送出文件前,請先只讀開頭,確認收件人能不能看懂這份文件跟自己有什麼關係,以及接下來需要做什麼。

把試過好用的寫法做成技能,開頭重點仍由人決定

請同事試讀、確認格式好用之後,就可以把適用的文件類型、摘要要回答的問題,以及詳細內容的安排方式寫成技能(AI Skill),讓 AI Agent 之後依照同一套做法與規則撰寫。除了格式,也要附上合適的範例,說明哪些內容必須留在開頭、為什麼不能省略,避免只給 AI 空白欄位,卻讓它自己猜要填什麼。

EgentWrX 讓使用者可以自行建立技能,也可以請 AI 生成草稿;AI Agent 可在適合的情境使用這些技能,使用者也能在對話中主動指定。若要讓全公司使用同事自建的技能,則須經過後台審查核准。這裡要建立的是文件撰寫規則,至於每次交付有哪些重點,仍應由熟悉這項工作、負責交付的人判斷。

建議在文件送出前,由負責交付的人先核對摘要與後面的詳細說明是否一致,再檢查有沒有漏掉重要影響、尚待確認的條件,或需要取得的核准。摘要不必逐字重寫,AI 草稿裡合適的內容可以直接挑出來使用;不過,挑選的人要能說明,為什麼收件人需要先看到這些內容。

下一份文件就可以拿來試行:請實際收件人只讀開頭,再用自己的話說說這份文件是做什麼用的,以及接下來要做什麼。如果對方沒注意到重要限制,就先檢查摘要有沒有寫清楚,再調整技能裡的規則與範例;不要只是把字數上限調低,卻讓同事讀完後還是不知道該做什麼。

常見問題

AI 寫的工作說明太長,要把詳細內容全部刪掉嗎?
不必,建議先把開頭的重點與詳細說明分開,再刪掉真正重複的內容。解法、驗證步驟或限制如果仍是同事查核時需要的資料,就應保留;不過,會影響是否核准的條件要先寫在摘要,不能為了縮短篇幅而放到後面。
開頭摘要可以直接使用 AI 寫好的文字嗎?
可以,但負責交付的人要先確認內容正確,也符合收件人的需要。人工挑選不代表每個字都要重寫,檢查時應核對摘要與詳細說明是否一致,避免把還沒確認的事項寫成已經定案,也別漏掉需要取得哪些核准。
公司的協作系統不能收合內容,還能採用這種寫法嗎?
可以,把摘要與詳細說明清楚分段就好,不必為了收合內容而更換系統。先讓收件人看懂文件用途、對工作的影響,以及接下來要做什麼,再提供查核所需的細節;若想使用可展開區塊,請先確認交付文件時使用的工具是否支援,並預覽收件人會看到的畫面。
30 分鐘,一起盤點哪些工作適合先交給 AI

想讓每位同仁都有自己的 AI 分身?

顧問會盡快與您聯繫。

ISO/IEC 27001:2022 資訊安全管理驗證