AI驅動的軟件工程（中）：文檔驅動的編碼與執行

📚 系列文章導航
AI驅動的軟件工程（上）：人機協同的設計與建模
AI驅動的軟件工程（中）：文檔驅動的編碼與執行
AI驅動的軟件工程（下）：AI輔助的質檢與交付

大家好，我是阿威。

在上一篇文章 《人機協同的設計與建模》 中，我們探討了如何與AI協作，將一個模糊的想法，通過一個結構化的三階段流程，打磨成一套完整、嚴謹的設計藍圖。我們得到了《需求規格說明書》、《系統設計說明書》以及每個模塊的《詳細設計說明書》。

這套設計文檔，是我們項目的堅實地基。但一個更嚴峻、也更令人興奮的挑戰隨之而來：我們能把這套藍圖直接交給AI，讓它自己來完成所有的編碼實現嗎？

如果你的經驗和我最初一樣，那么答案可能是否定的。直接把設計文檔丟給一個通用的AI助手，然后說“照著這個去寫代碼”，結果往往是一場災難。AI會很快忘記文檔的細節，它會用自己“喜歡”的方式組織代碼，它會在不同模塊間創造出不一致的接口。最終，你得到的會是一個難以維護的、拼接起來的“代碼怪獸”。

問題出在哪里？問題在于，我們只給了AI一張“地圖”（設計文檔），卻沒有給它一套“導航系統和駕駛手冊”（開發流程與規范）。一個人類開發者拿到設計文檔后，會運用自己腦中的整個軟件工程知識體系——版本控制、代碼規范、測試、日志記錄——來進行工作。而AI的腦中，沒有這些隱性的紀律。

要讓AI成為真正的核心開發者，我們就必須為它顯式地構建這一整套工程紀律。

這就是我在這篇文章中要分享的核心方法論：AIDC（AI-Driven Development and Collaboration）。它的精髓在于，我們不依賴AI那短暫、不可靠的內置記憶，而是通過一系列外部化的文檔，為它打造一個持久的“外部大腦”和一套強制執行的“行為準則”。我們不再請求它“寫代碼”，而是指令它“遵循流程”。

歡迎來到整個體系的“發動機艙”。在這里，我們將見證，設計藍圖是如何被一個遵循嚴格紀律的AI，一行行地轉化為真實可用的代碼。

AIDC方法論：為AI打造開發“熔爐”

AIDC的核心，是承認并正視AI的固有局限性，然后用工程化的手段去系統性地解決它們。這個方法論建立在四大原則之上，它們共同構成了一個足以熔煉出高質量代碼的“開發熔爐”。

1. 外部化記憶 (Externalized Memory)
AI的記憶是昂貴且善變的。因此，我們將所有關鍵信息——需求、設計、計劃、規范、甚至開發過程中的每一次提交記錄——全部持久化為項目內的Markdown文檔。這些文檔共同構成了AI的“外部長期記憶”。在每一次執行任務前，AI的第一個動作，必須是“閱讀”這些記憶。

2. 指令驅動執行 (Instruction-Driven Execution)
我們與AI的交互，不再是開放式的“對話”，而是明確的“指令下達”。通過一份我稱之為“標準作業程序（SOP）”的文檔，我們將AI的每一步操作都固化為可預測、可重復的指令。這從根本上杜絕了AI在執行任務時的隨機性和行為偏差。

3. 自動化守衛 (Automated Guardians)
我絕不會浪費時間去檢查AI寫的代碼有沒有遵循PEP8，或者括號是不是對齊了。這些低級但重要的工作，必須交由自動化工具來強制執行。通過在流程中嵌入Linter、格式化器、類型檢查器等工具，我們為項目建立了一道“自動化防線”，AI必須自己確保它的產出能通過這道防線。

4. 人機角色明確 (Defined Human-AI Roles)
在編碼階段，我們的角色再次轉換。我不再是“架構師”，而是**“項目經理”和“代碼審查者”。我負責下達高級別的開發任務（比如“去實現這個模塊”），并在關鍵節點審查代碼的業務邏輯。而AI的角色，則是“軟件開發者”和“DevOps助理”**，它負責執行SOP中定義的所有具體、繁瑣的戰術操作。

基于這四大原則，AIDC的開發生命周期被劃分為四個清晰的階段。

階段一我們已經完成。現在，我們從階段二開始，看看如何一步步為AI鋪設好軌道。

奠基與初始化：AI的第一次DevOps任務

在正式編碼前，我需要AI為我創建一個專業、規范的開發環境。這本身就是對AIDC方法論的一次小型演練。

我會給AI下達第一個指令：

“根據我們已經完成的設計，請初始化AgentWeaver項目。你需要：

創建標準的項目目錄結構（例如 agentweaver/, docs/, tests/）。
將我們之前生成的所有設計文檔，歸檔到 docs/ 目錄下。
初始化Git倉庫。
創建一份專業的 .gitignore 文件、一份包含基礎依賴的 requirements.txt 和一份包含項目簡介的 README.md。”

AI會像一個DevOps助理一樣，使用它的文件操作和終端工具，精確地完成這些任務。這個過程的產出，是一個結構清晰、已納入版本控制的項目倉庫骨架。更重要的是，它讓AI從一開始就進入了“被指令、被管理”的工作模式。

規范與流程定義：鍛造AI的“SOP”

這是整個方法論最核心、最關鍵的一步。我們要在這里，和AI一起，創造出未來將要嚴格“統治”AI自身行為的一系列“法律文件”。這些文件將構成它的“外部大腦”，是后續所有開發活動的基石。

我會指示AI創建以下幾份核心治理文檔：

《AI開發者標準工作流程(SOP).md》：這是給AI自己看的“用戶手冊”，是“指令驅動執行”原則的最終體現。它用最明確的指令語言，規定了AI從接收任務到完成提交的每一個步驟。后文我們會詳細拆解這份SOP的內容。

# AI 開發者標準工作流程 (SOP)**版本: 1.0**## 1. 核心指令本文檔是指導你在 AgentWeaver 項目中執行開發任務的標準操作流程（SOP）。**你必須嚴格、完整地遵循以下所有步驟**。在每個新會話開始時，用戶會將此文檔作為核心指令提供給你。---## 2. 階段一：上下文同步與理解 (強制執行)在開始任何編碼之前，你必須首先完成對項目狀態的全面同步。這是強制性步驟，不可跳過或部分執行。-   **指令 1.1：理解高層設計**-   [ ] 讀取并完全理解 `docs/需求規格說明書.md`。-   [ ] 讀取并完全理解 `docs/概要設計說明書.md`。-   **指令 1.2：理解模塊詳細設計**-   [ ] 讀取并完全理解當前任務分配的模塊詳細設計文檔，例如 `docs/詳細設計-X-模塊名.md`。-   **指令 1.3：遵循開發規范**-   [ ] 讀取并完全理解 `docs/開發編碼規范.md` 。你后續的所有代碼輸出都**必須**嚴格遵守此規范。-   **指令 1.4：回顧開發歷史**-   [ ] 讀取并完全理解 `docs/開發日志.md` ，了解項目此前的關鍵決策和問題。-   **指令 1.5：明確當前進度**-   [ ] 讀取并完全理解 `docs/項目開發計劃.md` ，找到你將要開發的任務條目，明確其當前狀態和依賴關系。---## 3. 階段二：計劃制定與任務執行在完全理解上下文后，開始進行計劃和編碼。-   **指令 2.1：制定開發計劃**-   [ ] 基于以上所有文檔，為你當前要開發的模塊制定一個詳細的、分步驟的執行計劃。-   [ ] **必須**使用你的 `todo_write` 工具，將此計劃轉化為一個代辦事項清單。清單的粒度應足夠細，例如到**函數級別**或**接口級別**。-   **指令 2.2：執行開發任務**-   [ ] 嚴格按照你創建的代辦事項清單，逐項完成開發。-   [ ] 使用 `edit_file` 工具進行編碼。-   [ ] 每完成一個清單項，立即使用 `todo_write` 工具更新其狀態為 `completed`。---## 4. 階段三：代碼驗證與版本提交在模塊核心功能開發完成后，或在每個有意義的節點，執行以下驗證和提交流程。-   **指令 3.1：代碼質量檢查**-   [ ] **必須**使用 `run_terminal_cmd` 工具執行以下命令：1.  格式化代碼: `black .`2.  靜態檢查與修復: `ruff check . --fix`-   [ ] 如果命令執行后報告任何錯誤，你**必須**修復它們，并重新運行檢查，直到所有檢查都通過。-   **指令 3.2：提交到版本控制**-   [ ] 使用 `run_terminal_cmd` 工具執行 `git add .`。-   [ ] 執行 `git commit`。**提交信息（commit message）必須嚴格遵循以下格式**：-   **格式**: `<類型>(<范圍>): <主題>`-   **示例**: `feat(api): 實現創建任務的POST端點`-   **類型**: `feat` (新功能), `fix` (bug修復), `docs` (文檔), `style` (格式), `refactor` (重構), `test` (測試), `chore` (構建或工具)。-   **主題**: **必須使用中文書寫**，簡明扼要地描述本次提交的內容。---## 5. 階段四：項目狀態歸檔與更新每次成功提交后，你**必須**立即更新項目的狀態記錄，以確保信息的實時同步。-   **指令 4.1：更新開發日志**-   [ ] 使用 `edit_file` 工具打開 `docs/開發日志.md`。-   [ ] **必須**在文件**末尾追加一行**，記錄本次開發。**嚴禁修改歷史日志**。格式如下：-   `YYYY-MM-DD HH:MM - <模塊名>: <本次開發的簡要總結，包括遇到的關鍵問題和解決方案>`-   **指令 4.2：更新項目開發計劃**-   [ ] 使用 `edit_file` 工具打開 `docs/項目開發計劃.md`。-   [ ] 找到與本次開發相關的任務條目（可以是模塊、功能或接口）。-   [ ] 將其狀態從“待開發”更新為“**完成**”。-   [ ] 如果開發中遇到問題導致阻塞，則更新為“**擱置**”或“**錯誤**”，并**必須**在同一行附上簡要原因。---
**流程結束。此工作流是確保你高效、可靠地參與本項目的核心。請在每次會話中嚴格遵循。**

《項目開發計劃.md》：這是一個高階的路線圖。我會讓AI基于《系統設計說明書》中的模塊列表，生成這份計劃。它通常是一個Markdown表格，包含模塊名、負責人（默認是AI）、狀態（如：待開發、進行中、完成）、依賴關系和預計完成日期。這份文檔是“外部化記憶”的一部分，用于宏觀地追蹤項目進度。

該項目計劃文檔完全由AI自主生成并在開發完成某個模塊時遵循《AI開發者標準工作流程(SOP).md》規則自主更新，無需人類干預

《開發日志.md》：這是一份嚴格按時間順序、只增不改的日志文件。我要求AI在每一次代碼提交后，都必須在這里追加一行記錄，注明時間、開發的模塊，以及對本次工作的簡要總結。這份日志提供了寶貴的、可追溯的開發歷史。

開發日志文檔也完全由AI遵循《AI開發者標準工作流程(SOP).md》自主生成、更新

《開發編碼規范.md》：這份文檔定義了代碼風格、命名約定、注釋標準等。我會提供一些初步的規則，然后讓AI將其擴充和完善，并保存成正式文檔。在后續的開發中，AI必須嚴格遵守這份它自己參與制定的規范。

該規范文檔由人類指導AI完成，在AI進行編碼時會依據《AI開發者標準工作流程(SOP).md》定義的流程規則完全遵守該開發編碼規范

當這四份文檔創建完成后，我們就擁有了一套完整的項目治理體系。AI不再是一個自由的“藝術家”，而是一個有法可依、有章可循的“工程師”。

迭代開發循環：SOP驅動下的AI一日

現在，萬事俱備。我們終于可以進入激動人心的編碼階段了。讓我們以開發“AIFactory”模塊為例，完整地走一遍AI在SOP驅動下的標準工作流程。

我的任務下達過程非常簡單，我只需要對AI說：

“任務：實現‘AIFactory’模塊。請嚴格遵循《AI開發者標準工作流程(SOP)》進行操作。”

接下來，所有事情都將由AI根據SOP自動完成。

步驟一：上下文同步（強制）

這是SOP中的第一條，也是最重要的一條指令。AI必須首先閱讀所有相關的“記憶”文檔，以構建完整的上下文。它會依次執行：

讀取 docs/需求規格說明書.md
讀取 docs/系統設計說明書.md
讀取 docs/詳細設計-AIFactory模塊.md （本次任務的核心依據）
讀取 docs/開發編碼規范.md
讀取 docs/開發日志.md （了解歷史）
讀取 docs/項目開發計劃.md （明確當前任務的位置）

這個看似冗余的步驟，恰恰是解決AI“失憶癥”的唯一有效方法。它確保了AI在開始工作時，腦子里裝的是項目的全局視圖，而不僅僅是我剛剛下達的一句簡單指令。

步驟二：制定計劃（TODO List）

在完全理解了上下文之后，SOP指令AI進行任務分解。
AI會基于詳細設計-AIFactory模塊.md中的內容，使用它的todo_write工具，為自己生成一份細粒度的、精確到函數級別的執行計劃。

這份TODO清單可能會是這樣：

[ ] 在 agentweaver/core/ 目錄下創建 ai_factory.py 文件。
[ ] 在 ai_factory.py 中定義抽象基類 BaseLLM。
[ ] 實現 OpenAIModel 類，繼承自 BaseLLM。
[ ] 實現 LocalHFModel 類，繼承自 BaseLLM。
[ ] 實現核心類 AIFactory。
[ ] 在 AIFactory 中實現 register_model 方法。
[ ] 在 AIFactory 中實現核心方法 get_model，包含緩存邏輯。
[ ] 為模塊添加必要的異常類，如 ModelNotFoundError。

這份清單不僅讓任務的執行過程變得透明、可控，也再次強化了AI的短期記憶，讓它對即將開始的工作有了清晰的步驟規劃。

步驟三：執行編碼

AI會嚴格按照它自己創建的清單，逐項進行編碼。它會使用edit_file工具，一次只專注于一個最小化的任務，比如創建文件、實現一個類或一個方法。

每當它完成一項，比如實現了BaseLLM類，它就會再次調用todo_write工具，將對應項的狀態更新為completed。

[x] 在 agentweaver/core/ 目錄下創建 ai_factory.py 文件。
[x] 在 ai_factory.py 中定義抽象基類 BaseLLM。
[ ] 實現 OpenAIModel 類，繼承自 BaseLLM。
…

這個過程會一直持續，直到清單上的所有任務都被勾選完成。

步驟四：自我檢查（自動化守衛）

在模塊的核心功能編碼完成后，SOP中一個強制性的驗證流程被觸發。
AI必須使用run_terminal_cmd工具，在項目根目錄下執行以下命令：

black . (代碼格式化)
ruff check . --fix (靜態檢查與自動修復)

如果這些命令返回任何錯誤或警告，SOP要求AI必須自行修復這些問題，然后重新運行檢查，直到所有檢查都干凈通過。我，作為人類，完全不需要介入這個過程。自動化工具成為了保證代碼基礎質量的第一道，也是最有效的一道防線。

步驟五：版本提交

通過所有自動化檢查后，代碼進入了提交階段。
SOP要求AI使用run_terminal_cmd工具執行git add .和git commit。

其中，commit message必須嚴格遵循我在《開發編碼規范.md》中定義的格式。
例如：feat(core): 實現AI工廠模塊的核心功能

類型(type): feat (新功能), fix (bug修復), docs (文檔) 等。
范圍(scope): 影響的模塊，如core, api。
主題(subject): 用中文簡明扼要地描述本次提交。

這種規范化的提交信息，使得我們的Git歷史清晰、可讀，為未來的代碼考古和自動化工具集成打下了良好基礎。

步驟六：狀態歸檔

一次成功的提交，并不意味著一個開發循環的結束。SOP的最后一步，也是“外部化記憶”原則的最后一道保障，是讓AI立即更新項目的狀態記錄。

AI會使用edit_file工具，執行兩個操作：

更新開發日志: 在docs/開發日志.md文件的末尾追加一行新記錄，嚴禁修改歷史。

2023-10-27 15:30 - AIFactory模塊: 完成了核心功能的開發，包括模型注冊和基于配置的動態加載。關鍵是實現了緩存機制以提高性能。
更新項目開發計劃: 在docs/項目開發計劃.md中，找到“AIFactory模塊”這一行，將其狀態從“進行中”更新為“完成”。

至此，一個完整的、閉環的、可追溯的開發循環才算真正結束。從上下文同步到狀態歸檔，每一步都在SOP的嚴格規定下進行，AI的行為是可預測的，其產出是高質量且符合規范的。