前言

無論是需求、規範還是用户故事，用於指導代碼實現的任何信息，都必須具備一些關鍵特質（如敏捷方法中的 INVEST 原則）。隨着人工智能逐漸參與代碼生成，需求不僅要滿足人類開發者的理解，還需要更加明確、結構化，以便 AI 能正確、可靠地生成符合項目約束的代碼。因此，編寫需求時標準更高，既要清晰給人看，更要讓 AI 能"看懂"並正確實現。

本文是系列文章的第一部分，重點討論確保需求本身的質量——需求是否被正確記錄、是否正確、是否完整。這是所有後續工作的基礎。

文檔化

軟件需求必須被記錄下來，而不能僅僅存在於我們的腦海中。只要易於維護，文檔可以儘可能輕量級。畢竟，文檔的目的是成為一個單一的事實來源。

當我們説需求必須"文檔化"以便人類開發人員使用時，我們的意思是它們需要被記錄在某個可訪問的地方（維基、需求文檔、用户故事等）。如果它們只存在於某個人的腦海中，或者分散在聊天消息中，它們可能就不會非常有效。這有助於確保一致性，提供一個參考點，並有助於新員工入職。儘管輕量級文檔通常是首選（例如用户故事），但通常有一個隱含的理解，即人類可以通過對話、經驗和共享上下文來填補空白。

但對於 AI 來説，情況就完全不同了。 對於人工智能代碼生成，"文檔化"特質承擔了更具挑戰性的角色：

1. 文檔是主要輸入

人工智能代碼助手不會參加計劃會議。它們可能無法實時提出澄清問題（儘管一些工具允許交互式細化）。目前，它們缺乏人類開發人員多年的情境經驗。書面需求文檔可能是人工智能為特定任務接收到的最直接且通常是唯一的指令集。其質量可以直接決定生成代碼的質量。這就像你給 AI 一張地圖，如果地圖畫錯了，AI 就會走錯路。

2. 需要機器可解釋性

儘管我們可以很好地理解自然語言，即使存在一些歧義，但人工智能模型在清晰、結構化且無歧義的輸入下表現最佳。這意味着文檔的格式和精確性可能是一個遊戲規則改變者。模糊的語言可能導致人工智能做出不可預測或錯誤的假設。就像你跟人説話，對方可能能理解你的意思，但跟 AI 説話，必須説得清清楚楚，不能有歧義。

3. 結構化格式有助於一致性

我們可以使用 Gherkin 進行行為驅動開發（BDD），特定的提示模板，甚至是像 JSON/YAML 這樣的結構化數據格式來處理類似配置的需求。使用預定義的結構或模板來記錄需求是非常有用的。這樣，必要的細節（如錯誤處理、邊緣情況和非功能性需求）可以被一致地考慮並提供給人工智能。這可以導致更可預測和可靠的代碼生成。就像填表格，格式統一了，AI 就能更好地理解。

4. 單一事實來源至關重要

因為文檔是提供給人工智能的規範，確保它是權威的、最新的版本至關重要。在重新生成之前，必須在文檔中反映任何更改。如果文檔版本不一致，AI 可能會用舊版本生成代碼，那就麻煩了。

正確性

我們必須正確理解系統需要什麼以及不需要什麼。這聽起來可能很簡單，但有多少次我們實現了錯誤的需求？在這裏，輸入錯誤，輸出錯誤（GIGO） 規則適用。就像做菜一樣，如果食材不對，再好的廚師也做不出好菜。

對於人工智能代碼生成，正確性的重要性可以通過以下方面來評估：

1. 人工智能按字面執行

人工智能代碼生成器是將指令（需求）翻譯成代碼的強大工具。然而，它們通常缺乏對領域的深入理解。目前，它們缺乏質疑指令本身是否合乎邏輯或是否符合更廣泛的業務目標的"常識"。如果你給人工智能一個表述明確但功能錯誤的需求，人工智能可能會生成完美實現該錯誤功能的代碼。這就像你讓 AI 去"買蘋果"，如果需求寫的是"買紅色的蘋果"，AI 就會去買紅蘋果，即使你實際想要的是 iPhone。

2. 減少隱式糾正的機會

我們可能會閲讀一個需求，並根據我們的經驗或對項目背景的理解，發現邏輯錯誤或與已知業務規則相矛盾的地方。我們可能會説："你確定這是對的嗎？通常在這種情況下我們做 X。"這為早期發現錯誤需求提供了一個寶貴的反饋循環。人工智能不太可能提供這種主動的、情境感知的合理性檢查。它通常假設接收到的需求是意圖中的事實。AI 不會質疑你，它只會照做，所以需求必須是對的。

3. 驗證是關鍵

確保正確性的責任主要落在需求定義和驗證過程上，在人工智能參與之前。定義和審查需求的人必須嚴格確認他們要求的是真正需要的東西。在把需求交給 AI 之前，一定要仔細檢查，因為 AI 不會幫你發現需求錯誤。

完整性

這關乎沒有缺失的屬性或功能。儘管不完整的需求是一個問題，但我們可以推斷缺失的細節，提出澄清問題，或者依賴隱含的知識。然而，對於人類來説，這並不總是如此！即使經過數小時的會議和討論，需求也可能仍然不完整。

在人工智能生成代碼的情況下，我看到人工智能助手朝兩個方向發展。有些情況下，人工智能助手生成了明確陳述的內容。由此產生的差距導致功能不完整或人工智能做出了可能錯誤的假設。也有一些情況下，人工智能助手發現了缺失的屬性並提出了建議。但你不能指望 AI 總是能發現缺失的部分，所以最好一開始就把需求寫完整。

在任何情況下，為了完整性，我認為我們仍然值得儘可能明確。需求不僅必須詳細説明"快樂路徑"（正常流程），還必須包括：

• • 邊緣情況：明確列出已知的邊緣情況。比如用户輸入為空、數據超出範圍、網絡超時等。
• • 錯誤處理：指定如何處理錯誤（例如，特定的異常、返回代碼、日誌消息）。不要只説"處理錯誤"，要説清楚怎麼處理。
• • 非功能性需求（NFRs）：性能目標、安全約束（輸入驗證、輸出編碼、認證/授權點）、可擴展性考慮以及數據處理/隱私規則必須明確説明。這些往往容易被忽略，但對 AI 來説很重要。
• • 假設：明確列出所做的任何假設。比如假設用户已經登錄、假設數據格式正確等。

總結

在人工智能時代，需求的基礎質量變得更加重要。文檔化、正確性、完整性是確保需求本身"合格"的三個關鍵特質：

• • 文檔化確保需求被正確記錄，成為 AI 可以理解和使用的輸入
• • 正確性確保需求本身是對的，避免"垃圾進，垃圾出"
• • 完整性確保需求沒有遺漏，包含所有必要的細節

只有需求本身的質量得到保證，我們才能進入下一步：確保需求能被正確理解。在下一篇文章中，我們將討論無歧義性和一致性，這是確保需求表達清晰、易於理解的關鍵特質。