將設計規格從Excel轉移到Markdown，利用AI生成Java代碼，從而防止設計與代碼脱節，並將開發時間縮短55%。
在企業級Java開發中，設計文檔通常被困在諸如Excel或Word之類的二進制孤島中，導致它們與實際代碼漸行漸遠。本文展示了一種模式，即通過使用結構化的Markdown和生成式AI，將設計文檔視為源代碼。
我們都經歷過這種情況：架構團隊向開發團隊交付一份詳細設計文檔（[Detailed Design Document]DDD）。它是一個50頁的Word文件，或者更糟，是一個包含多個標籤頁、用於定義Java類、字段和驗證規則的大型Excel電子表格。
當你寫下第一行代碼時，這份文檔就已經過時了。
二進制文件幾乎無法進行版本控制，差異對比不切實際，並且將定義複製粘貼到Javadoc中非常繁瑣。在企業級規模下，這種"代碼漂移"（即實現與設計脱節）成為了技術債務的主要來源。
通過將設計文檔轉移到結構化的Markdown並利用生成式AI，我們可以將文檔完全視為源代碼。這在架構師的意圖和開發人員的集成開發環境（IDE）之間架起了一座橋樑。
問題：二進制壁壘
在傳統的瀑布模型或混合開發環境中，設計存在於Office文檔（Word/Excel）中，而代碼則以文本格式（Java/YAML）存在。由於格式不兼容，自動化流程中斷。你無法輕易地將Excel表格"編譯"成Java POJO，當然也無法對Word文檔進行單元測試。
為了彌合這一差距，設計信息需要具備以下特點：
- 基於文本（以便於Git版本控制）。
- 結構化（以便於機器解析）。
- 人類可讀（以便於審查和協作）。
解決方案就是使用結構化Markdown。
解決方案：將Markdown作為數據源
我們不應僅將Markdown視為編寫README文件的方式，而應將其作為一種結構化的規格説明格式。通過標準化標題和佈局，Markdown文件就成為一種一致且對機器友好的數據源，生成式AI工具（GitHub Copilot、ChatGPT等）可以解析它來生成樣板代碼、圖表，甚至為利益相關者生成遺留的Excel報告。
1. 目錄結構
為使此方法有效，設計文檔必須與代碼存放在一起，並鏡像包結構，以便它們同步演進。
模式示例：
/project-root
/src
/main/java/com/app/backend/RegisteredUser.java
/design-docs
/backend
RegisteredUser.md
OrderService.md
/diagrams
architecture.mermaid通過將.md文件與.java文件保存在相同的倉庫結構中，我們在規格説明和實現之間建立了直接、可追溯的聯繫。
2. 結構化規格説明
關鍵在於將Markdown寫成實際的規格説明，而不是博客文章。我們使用特定的標題（例如## Class Summary, ## Members）作為自動化工具的掛鈎點。
示例：RegisteredUser.md
# RegisteredUser
## Class Summary
Represents a user who has completed the registration process.
Manages user credentials and validation status.
## Members
| Name | Type | Description |
| :--- | :--- | :--- |
| userId | String | Unique identifier for the user. |
| userPassword | String | Encrypted password string. |
## Methods
+ fn isValidUserId(): bool
- Logic: Returns true if userId length >= 3.
+ fn isValidUserPassword(): bool
- Logic: Returns true if password length >= 8.這種格式對產品負責人是可讀的，同時對大語言模型（LLM）來説也足夠結構化，足以解釋類型定義和邏輯約束。
實施：從文本到Java
一旦我們用結構化的Markdown表達了設計，生成式AI就可以彌合與Java代碼之間的鴻溝。在富士通的案例研究中，他們利用一個VS Code擴展和OpenAI API來讀取這些Markdown規格説明，並生成初始的類框架。
你可以使用任何生成式AI編碼助手來複制這個工作流。由於提示上下文包含一個嚴格、可預測的結構，幻覺率會顯著下降。
提示上下文示例：
"請閲讀以下Markdown設計文檔。根據'Methods'部分中的描述，生成一個包含Javadoc、字段和驗證邏輯的Java類。"
生成輸出示例：
package com.app.backend;
/**
* Represents a user who has completed the registration process.
* Manages user credentials and validation status.
*/
public class RegisteredUser {
private String userId;
private String userPassword;
public RegisteredUser(String userId, String userPassword) {
this.userId = userId;
this.userPassword = userPassword;
}
/**
* Logic: Returns true if userId length >= 3.
*/
public boolean isValidUserId() {
return this.userId != null && this.userId.length() >= 3;
}
/**
* Logic: Returns true if password length >= 8.
*/
public boolean isValidUserPassword() {
return this.userPassword != null && this.userPassword.length() >= 8;
}
}AI不會猜測；它會嚴格按照書面描述實現指定的業務規則（>=3, >=8）。如果設計發生變更，你只需更新Markdown，然後重新生成代碼。
可視化架構
當不再使用Excel、Visio或其他圖表工具時，一個常見的擔憂是失去了"繪製"系統的能力。但既然我們的設計現在存在於結構化的文本中，我們就可以將其編譯成圖表。
利用標準化的Markdown標題，我們可以通過簡單地掃描目錄來自動生成Mermaid.js類圖。
輸入（Markdown標題）：
Class: RegisteredUser depends on Class: UserProfile
#Mermaid Diagram
classDiagram
class RegisteredUser {
+String userId
+String userPassword
+isValidUserId()
}
class UserProfile {
+String email
}
RegisteredUser --> UserProfile這確保了你的架構圖始終反映設計文檔的當前狀態，而不是架構師三個月前繪製的內容。
"Excel"需求
許多企業仍然需要Excel文件用於正式籤核或非技術利益相關者。
但現在，既然真實來源是結構化的文本（Markdown），生成Excel就變得微不足道。一個簡單的腳本（甚至一個AI提示）就可以解析標題並自動填充CSV或XLSX模板。
- 舊方式：主文件是Excel -> 開發人員手動編寫Java。
- 新方式：主文件是Markdown -> 自動生成Java併為管理層自動生成Excel。
結果與投資回報率
轉向Markdown先行方法不僅僅是整理你的倉庫。在分析的案例研究中，團隊看到了明確的生產力提升：
- 開發速度加快55%：樣板代碼（類、測試）直接從Markdown規格説明生成。
- 減少溝通開銷：AI輔助的Markdown轉換比處理Excel單元格更快、更準確。
- 真正的差異對比能力：Git現在能準確顯示誰在何時更改了業務規則（通過Git提交歷史）。
結論
文檔常常淪為事後的補救措施，因為我們用於設計的工具（Office套件）與我們用於開發的工具（IDE）格格不入。通過採用Markdown作為一種正式的規範語言，我們將設計工作直接拉入了DevOps流程。
所以，下次當你被要求編寫詳細設計時，請跳過電子表格。打開一個.md文件，定義一個清晰的結構，然後讓代碼從中流淌而出。
【注】本文譯自：Markdown-First Approach to Enterprise Java
