Ryan He你們怎麼記錄工程決策背後的「為什麼」，而不只是記錄「做了什麼」？ https://news.ycombinator.com/item?id=47368874
這篇 Hacker News 上的 Ask HN 討論由使用者 zain__t 發起，描述了一個工程團隊常見的痛點：團隊最近招聘了一位八年經驗的資深工程師，結果這位新人花了整整三週時間扮演「程式碼考古學家」，只為了理解程式碼背後的決策邏輯，例如為何選用 Redis 而非記憶體快取、為何某個服務使用 GraphQL 而其他地方都用 REST、為何企業用戶的驗證流程有個奇怪的例外處理。這些答案散落在沒有描述的已關閉 PR、十八個月前的 Slack 對話串，以及兩位已離職工程師的腦袋裡。團隊曾嘗試過 ADR（Architecture Decision Records，架構決策紀錄）只撐了六週就沒人維護，PR 描述範本一個月內就被忽略，Notion 架構文件則已經十四個月沒更新。發文者因此向社群提問：是否有長期有效的系統、能否自動化這個流程、還是每次新人到職大家都默默承受這樣的痛苦。
社群回應中，最受認同的觀點之一來自一位使用者 Gggg1234，他精準指出問題核心：「為什麼」本身是一個活的產物，它從對話、工單評論、Slack 討論串、PR 審查和口頭討論中浮現，散佈在十幾種工具裡。要求工程師手動把這些整合成一份文件，等於要他們一邊交付功能一邊做即時考古。他建議建立一套系統，被動地擷取 PR、commit 訊息、關聯工單、審查評論甚至 Slack 對話串等訊號，再從周圍的討論與程式碼差異中推論出決策理由，最終以結構化、可查詢的知識形式儲存，讓新工程師能直接提問並獲得從原始來源綜合而成的答案。ADR 之所以失敗，正是因為它要求額外心力；一個被動理解變更脈絡的系統則完全不需要工程師改變行為。
另一派觀點則強調文件必須緊鄰程式碼才能存活。使用者 lowenbjer 分享了在多家公司帶領工程團隊的經驗，主張以檔案層級的標頭註解說明每個元件的用途與架構角色，搭配完善的 README 串聯全貌，並可設定以 LLM 為判斷者的 git hook，在每次 PR 時檢查程式碼變更是否與現有文件一致，不一致就擋下合併。使用者 al_borland 也分享了在程式碼中留下結構化註解的做法，例如標註「此處原本使用某方案，因某原因改為新方案」或「這段看起來不合理，但正常寫法因某原因行不通」。使用者 hammadfauz 則提出一套完整的工作流程：在專案追蹤器中建立工單、每個 commit 訊息開頭帶上工單編號、一個分支對應一個工單、一個 PR 合併並關閉一個工單、不使用 squash merge，這樣透過
也有人從更根本的層面提出見解。使用者 hermitcrab 分享了二十五年前研究「設計理由」（design rationale）記錄的經驗，指出這在核反應爐等長壽命產物上尤其關鍵，而最大的障礙在於做決策的人缺乏記錄理由的動機——他們可能認為這會降低自身的職涯安全感、可能擔心文字紀錄成為日後被追究的證據、而且確實很耗時。使用者 lwhsiao 則提出犀利的反論：應該招聘重視書寫的人，並建立以書寫為核心的文化，以 Oxide 公司嚴謹且大量的 RFD（Requests for Discussion）為範例。使用者 rich_sasha 則務實地指出，很多技術決策其實根本沒有好理由——可能只是某人喜歡那個技術然後離職了、可能當初跑分看起來較好但需求早已漂移、可能是權宜之計卻再也沒人有時間替換。因此他建議記錄高層級原則並堅持執行、留住資深人員並耐心傳承、以及撰寫不求完美同步但能提供線索的 wiki 頁面。
整體而言，這場討論反映出工程團隊對決策脈絡流失的普遍焦慮，而社群共識大致分為三個方向：其一是讓文件盡可能靠近程式碼以降低維護摩擦；其二是透過嚴格的工具鏈整合與流程紀律確保可追溯性；其三則是發文者本人積極倡導的方向——利用 LLM 從既有的 PR、Slack 對話串與工單中被動擷取並結構化決策理由，將「撰寫文件」這個步驟徹底消除，只需工程師一鍵確認即可。多數人認同核心難題不在於工具，而在於人的動機與組織文化，而 AI 能否真正跨越這道鴻溝，仍是一個值得持續觀察的命題。
👥 50 則討論、評論 💬
https://news.ycombinator.com/item?id=47368874
這篇 Hacker News 上的 Ask HN 討論由使用者 zain__t 發起，描述了一個工程團隊常見的痛點：團隊最近招聘了一位八年經驗的資深工程師，結果這位新人花了整整三週時間扮演「程式碼考古學家」，只為了理解程式碼背後的決策邏輯，例如為何選用 Redis 而非記憶體快取、為何某個服務使用 GraphQL 而其他地方都用 REST、為何企業用戶的驗證流程有個奇怪的例外處理。這些答案散落在沒有描述的已關閉 PR、十八個月前的 Slack 對話串，以及兩位已離職工程師的腦袋裡。團隊曾嘗試過 ADR（Architecture Decision Records，架構決策紀錄）只撐了六週就沒人維護，PR 描述範本一個月內就被忽略，Notion 架構文件則已經十四個月沒更新。發文者因此向社群提問：是否有長期有效的系統、能否自動化這個流程、還是每次新人到職大家都默默承受這樣的痛苦。
社群回應中，最受認同的觀點之一來自一位使用者 Gggg1234，他精準指出問題核心：「為什麼」本身是一個活的產物，它從對話、工單評論、Slack 討論串、PR 審查和口頭討論中浮現，散佈在十幾種工具裡。要求工程師手動把這些整合成一份文件，等於要他們一邊交付功能一邊做即時考古。他建議建立一套系統，被動地擷取 PR、commit 訊息、關聯工單、審查評論甚至 Slack 對話串等訊號，再從周圍的討論與程式碼差異中推論出決策理由，最終以結構化、可查詢的知識形式儲存，讓新工程師能直接提問並獲得從原始來源綜合而成的答案。ADR 之所以失敗，正是因為它要求額外心力；一個被動理解變更脈絡的系統則完全不需要工程師改變行為。
另一派觀點則強調文件必須緊鄰程式碼才能存活。使用者 lowenbjer 分享了在多家公司帶領工程團隊的經驗，主張以檔案層級的標頭註解說明每個元件的用途與架構角色，搭配完善的 README 串聯全貌，並可設定以 LLM 為判斷者的 git hook，在每次 PR 時檢查程式碼變更是否與現有文件一致，不一致就擋下合併。使用者 al_borland 也分享了在程式碼中留下結構化註解的做法，例如標註「此處原本使用某方案，因某原因改為新方案」或「這段看起來不合理，但正常寫法因某原因行不通」。使用者 hammadfauz 則提出一套完整的工作流程：在專案追蹤器中建立工單、每個 commit 訊息開頭帶上工單編號、一個分支對應一個工單、一個 PR 合併並關閉一個工單、不使用 squash merge，這樣透過
git blame 就能追溯到工單描述與 PR 討論中的完整脈絡。使用者 nonameiguess 則以大型長期專案的經驗力挺 ADR，並分享了一個橫跨多家公司與政府機構、為期數十年的專案，靠著嚴格使用整套 Atlassian 工具鏈——Bitbucket、Jira、Confluence、Fish Eye、Crucible——完整串聯 commit、PR、工單與 ADR，幾乎不需要口頭提問，只要沿著連結追蹤就能找到完整的決策歷史。也有人從更根本的層面提出見解。使用者 hermitcrab 分享了二十五年前研究「設計理由」（design rationale）記錄的經驗，指出這在核反應爐等長壽命產物上尤其關鍵，而最大的障礙在於做決策的人缺乏記錄理由的動機——他們可能認為這會降低自身的職涯安全感、可能擔心文字紀錄成為日後被追究的證據、而且確實很耗時。使用者 lwhsiao 則提出犀利的反論：應該招聘重視書寫的人，並建立以書寫為核心的文化，以 Oxide 公司嚴謹且大量的 RFD（Requests for Discussion）為範例。使用者 rich_sasha 則務實地指出，很多技術決策其實根本沒有好理由——可能只是某人喜歡那個技術然後離職了、可能當初跑分看起來較好但需求早已漂移、可能是權宜之計卻再也沒人有時間替換。因此他建議記錄高層級原則並堅持執行、留住資深人員並耐心傳承、以及撰寫不求完美同步但能提供線索的 wiki 頁面。
整體而言，這場討論反映出工程團隊對決策脈絡流失的普遍焦慮，而社群共識大致分為三個方向：其一是讓文件盡可能靠近程式碼以降低維護摩擦；其二是透過嚴格的工具鏈整合與流程紀律確保可追溯性；其三則是發文者本人積極倡導的方向——利用 LLM 從既有的 PR、Slack 對話串與工單中被動擷取並結構化決策理由，將「撰寫文件」這個步驟徹底消除，只需工程師一鍵確認即可。多數人認同核心難題不在於工具，而在於人的動機與組織文化，而 AI 能否真正跨越這道鴻溝，仍是一個值得持續觀察的命題。
👥 50 則討論、評論 💬
https://news.ycombinator.com/item?id=47368874
Leon