開發日誌 #1：需求分析模組開發
專案背景
軟體開發的第一步永遠是「理解需求」。但實際工作中，客戶提供的需求往往是：
「我想做一個網站，有會員系統、購物車、還有後台管理。」
這樣的需求描述：
- ❌ 缺少細節
- ❌ 沒有優先級
- ❌ 技術約束不明確
- ❌ 驗收標準模糊
因此，我決定開發一個 需求分析模組，讓 AI 自動將這些非結構化的需求轉換為標準化、完整的需求文件。
設計目標
核心需求
- 輸入靈活：接受任何形式的需求描述
- 輸出標準化：生成固定格式的需求文件
- 完整性：AI 要能補充客戶沒提到的部分
- 可追溯：記錄 Token 使用、時間戳等元數據
- 多用戶支援：不同客戶/專案的需求獨立管理
輸出文件結構設計
經過思考，我定義了 9 個標準章節：
1. 專案概述 - 專案名稱、目標、目標用戶
2. 功能需求 - 核心功能 + 次要功能
3. 非功能需求 - 性能、安全、可用性
4. 技術約束 - 語言、框架、部署環境
5. 數據模型（初步）- 主要實體和欄位
6. API 端點設計 - RESTful API 列表
7. 用戶故事 - As a... I want... So that...
8. 約束與假設 - 限制條件和假設
9. 成功指標 - KPI 和衡量標準這個結構參考了業界最佳實踐（IEEE 830、敏捷用戶故事等），確保需求文件的完整性和可執行性。
技術架構
核心類別設計
class RequirementAnalyzer:
"""需求分析器"""
def __init__(
self,
api_key: str,
model: str = "claude-sonnet-4-20250514",
max_tokens: int = 4096
):
"""
初始化分析器
Args:
api_key: Anthropic API Key
model: Claude 模型
max_tokens: 最大輸出 token 數
"""
self.client = Anthropic(api_key=api_key)
self.model = model
self.max_tokens = max_tokens
self.logger = logger主要方法
analyze() - 核心分析方法：
async def analyze(
self,
user_requirement: str,
output_dir: str,
user_id: Optional[str] = None,
project_name: Optional[str] = None
) -> Dict[str, Any]:
"""
分析用戶需求並生成需求文件
流程：
1. 調用 Claude API 分析需求
2. 生成標準化的 9 章節需求文件
3. 儲存文件和元數據
4. 返回結果
"""System Prompt 工程
這個模組最關鍵的部分是 System Prompt 的設計。我需要讓 Claude 理解我想要的輸出格式和品質標準。
Prompt 設計思路
1. 明確角色定位
system_prompt = """你是一個資深的軟體需求分析師。你的任務是：
1. 理解用戶提供的需求描述
2. 分析需求的完整性
3. 生成結構化、專業的需求文件
"""2. 定義輸出格式
## 輸出格式
請生成一份完整的需求文件，使用 Markdown 格式，包含以下 9 個標準章節：
1. **專案概述**
- 專案名稱
- 專案目標（1-2 段描述）
- 目標用戶
2. **功能需求**
### 2.1 核心功能
每個功能包含：
- 功能名稱
- 詳細描述（3-5 句話）
- 優先級（高/中/低）
- 驗收標準（至少 3 條）
### 2.2 次要功能
- 列出次要或未來可能添加的功能
... (其他章節)3. 設定品質標準
## 重要原則
- 使用繁體中文
- 描述要具體且可執行
- 對於用戶沒有提及的部分，根據常識和最佳實踐進行合理推斷，並標註 "(推斷)"
- 保持清晰的層級結構
- 使用表格呈現結構化數據
- 驗收標準要可測試
- API 設計要遵循 RESTful 原則4. 提供範例
為了讓 Claude 更好地理解期望的輸出，我在 Prompt 中加入了簡短的範例：
## 範例輸出
### 2.1 核心功能
#### 功能 1: 用戶註冊
- **描述**: 允許新用戶創建帳號。用戶需提供 email、密碼和暱稱。系統會驗證 email 格式並檢查是否重複。註冊成功後發送驗證郵件。
- **優先級**: 高
- **驗收標準**:
1. Email 格式驗證正確
2. 密碼強度檢查（至少 8 位，包含數字和字母）
3. 重複 email 會提示錯誤
4. 註冊成功後發送驗證郵件完整 System Prompt
最終的 System Prompt 長度約 1500 tokens，涵蓋了：
- 角色定義
- 任務說明
- 9 個章節的詳細格式要求
- 品質標準
- 輸出範例
多用戶隔離設計
為了支援多客戶/專案，我設計了資料夾隔離機制：
檔案結構
output/
├── user_a/
│ ├── req_project_1_20251011_143052.md
│ ├── req_project_1_20251011_143052.md.metadata.json
│ └── req_project_2_20251011_150000.md
├── user_b/
│ └── req_project_3_20251011_160000.md
└── user_c/
└── req_project_4_20251011_170000.md
實作邏輯
def _get_user_output_dir(self, base_dir: str, user_id: Optional[str]) -> str:
"""獲取用戶的輸出目錄"""
if user_id:
user_dir = Path(base_dir) / user_id
else:
user_dir = Path(base_dir)
user_dir.mkdir(parents=True, exist_ok=True)
return str(user_dir)檔案命名規則
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
filename = f"req_{project_name}_{timestamp}.md"這樣的設計確保：
- ✅ 不同用戶的需求完全隔離
- ✅ 檔名包含專案名稱和時間戳，易於識別
- ✅ 支援同一專案的多個版本（不同時間戳）
元數據追蹤
每個需求文件都會生成對應的元數據文件（.metadata.json），記錄詳細資訊：
元數據結構
{
"timestamp": "20251011_143052",
"user_id": "client_a",
"project_name": "online_bookstore",
"file_path": "./output/client_a/req_online_bookstore_20251011_143052.md",
"input_length": 256,
"output_length": 4587,
"model": "claude-sonnet-4-20250514",
"tokens_used": {
"input": 1256,
"output": 3842
}
}用途
元數據提供了：
- 成本追蹤：記錄 Token 使用量，計算 API 成本
- 版本管理：時間戳可以追蹤需求的演變
- 品質分析：輸出長度可以評估需求文件的完整性
- 審計追蹤：完整記錄誰、何時、生成了什麼
實測效果
測試案例：線上書店
輸入需求：
開發一個線上書店系統
核心功能：
1. 書籍管理：CRUD 操作
2. 購物車：添加、修改、刪除商品
3. 訂單系統：下單、支付、追蹤
4. 用戶系統：註冊、登入、個人資料
技術要求：
- 後端：Python Django
- 前端：React + TypeScript
- 資料庫：PostgreSQL
非功能需求：
- 支援 1000+ 併發用戶
- 響應時間 < 2 秒
生成結果：
# 需求文件：線上書店系統
## 1. 專案概述
**專案名稱**: 線上書店系統
**專案目標**:
建立一個功能完整的線上書店平台，提供書籍瀏覽、購買、訂單管理等服務。
系統旨在為用戶提供流暢的購書體驗，同時為管理員提供高效的書籍和訂單管理工具。
**目標用戶**:
- 一般消費者：瀏覽和購買書籍
- 管理員：管理書籍庫存、處理訂單
## 2. 功能需求
### 2.1 核心功能
#### 功能 1: 書籍管理
- **描述**: 管理員可以新增、編輯、刪除和查詢書籍資訊。每本書包含標題、作者、ISBN、價格、庫存、分類、封面圖片和描述。系統支援批次匯入和匯出書籍資料。
- **優先級**: 高
- **驗收標準**:
1. 可以成功新增包含所有必要欄位的書籍
2. 編輯功能正確更新書籍資訊
3. 刪除功能包含二次確認
4. 支援關鍵字搜尋書籍（標題、作者、ISBN）
5. 批次匯入支援 CSV 格式，錯誤時提供明確訊息
... (更多功能)
## 3. 非功能需求
- **性能要求**:
- 支援至少 1000 個併發用戶
- 頁面響應時間 < 2 秒
- 資料庫查詢優化（使用索引）
- **安全性要求**:
- 密碼使用 bcrypt 加密存儲
- API 使用 JWT token 認證
- 支付資訊使用 HTTPS 加密傳輸 (推斷)
- 防止 SQL Injection 和 XSS 攻擊 (推斷)
... (完整的 9 個章節)觀察重點
✅ 完整性：
- AI 自動補充了沒提到的細節（如防止 SQL Injection）
- 標註 “(推斷)” 讓開發者知道哪些是 AI 推測的
✅ 結構化：
- 清晰的層級結構
- 表格化的 API 端點列表
- 格式統一的驗收標準
✅ 可執行性：
- 具體的驗收標準（可測試）
- 詳細的 API 設計（URL、Method、參數）
- 明確的數據模型（欄位、類型、關聯）
輔助功能實作
1. 列出需求文件
def list_requirements(
self,
output_dir: str,
user_id: Optional[str] = None
) -> list:
"""列出所有需求文件"""
user_dir = self._get_user_output_dir(output_dir, user_id)
req_files = list(Path(user_dir).glob("req_*.md"))
# 按時間倒序排列
return sorted(
[str(f) for f in req_files],
reverse=True
)2. 獲取最新需求
def get_latest_requirement(
self,
output_dir: str,
user_id: Optional[str] = None
) -> Optional[str]:
"""獲取最新的需求文件"""
files = self.list_requirements(output_dir, user_id)
return files[0] if files else None互動式測試工具
為了方便測試，我開發了互動式腳本 interactive_test.py：
async def main():
print("=" * 60)
print(" 需求分析互動式測試工具")
print("=" * 60)
# 選擇輸入方式
print("\n請選擇需求輸入方式:")
print("1. 從 console 輸入")
print("2. 從文件讀取")
choice = input("\n請輸入選項 (1/2): ").strip()
if choice == "1":
print("\n請輸入需求描述 (輸入完成後按 Ctrl+D 或 Ctrl+Z):")
requirement = sys.stdin.read()
else:
file_path = input("\n請輸入需求文件路徑: ").strip()
with open(file_path, 'r', encoding='utf-8') as f:
requirement = f.read()
# 執行分析
result = await analyzer.analyze(
user_requirement=requirement,
output_dir="./output",
user_id=user_id,
project_name=project_name
)
# 顯示結果
if result["success"]:
print(f"\n✅ 需求分析完成！")
print(f"📄 文件路徑: {result['file_path']}")
print(f"📊 Token 使用: {result['metadata']['tokens_used']}")使用體驗：
$ python interactive_test.py
============================================================
需求分析互動式測試工具
============================================================
請選擇需求輸入方式:
1. 從 console 輸入
2. 從文件讀取
請輸入選項 (1/2): 2
請輸入需求文件路徑: sample_requirement.txt
📝 需求內容預覽:
開發一個線上學習平台...
專案名稱 (預設: project): online_learning
用戶 ID (預設: user): client_edu
確認開始分析? (y/n): y
🔄 正在分析需求...
✅ 需求分析完成！
📄 文件路徑: ./output/client_edu/req_online_learning_20251011_143052.md
📊 Token 使用: {'input': 1256, 'output': 3842}技術總結
成功經驗
1. Prompt 工程是關鍵
精心設計的 System Prompt 直接決定輸出品質：
- 明確的角色定位
- 詳細的格式要求
- 具體的範例
- 清晰的品質標準
2. 標註推斷內容很重要
讓 AI 標註哪些是推斷的，避免：
- 客戶誤以為所有內容都是他們提供的
- 開發者不確定哪些需要再確認
3. 元數據追蹤提升可維護性
記錄詳細的元數據（Token 使用、時間戳等）對於：
- 成本控制
- 版本追蹤
- 品質分析
都非常有幫助。
改進空間
1. Token 使用優化
目前每次分析都要消耗 1000-3000 tokens。可以考慮：
- 快取 System Prompt
- 使用更精簡的 Prompt
- 根據需求複雜度動態調整 max_tokens
2. 增量更新功能
目前每次都生成全新的需求文件。未來可以支援：
- 讀取舊版需求文件
- 只更新變更的部分
- 生成變更摘要
3. 需求驗證
可以加入需求完整性檢查：
- 必要章節是否都有內容
- 驗收標準是否可測試
- API 設計是否遵循 RESTful 原則
階段總結
第一階段完成了需求分析模組的核心功能：
✅ 完成項目：
- Claude API 整合
- System Prompt 工程
- 標準化 9 章節輸出
- 多用戶隔離設計
- 元數據追蹤機制
- 互動式測試工具
✅ 技術突破：
- Prompt 設計能力
- 異步 API 調用
- 檔案結構管理
- 錯誤處理機制
📊 實測數據：
- 處理時間：5-10 秒
- Token 使用：1000-3000
- 輸出品質：完整且結構化
🎯 下一步： 基於這些需求文件，開發系統設計模組，讓 AI 能夠探索現有專案並生成詳細的實作設計。