經過前27天的探索和實踐，我們建立了完整的System Prompt體系。但在實際使用過程中，團隊仍然會踩到各種坑。今天我們來總結System Prompt設計層面的常見錯誤，幫助其他團隊避免重蹈覆轍。

一、規範撰寫的常見錯誤

1.1 語意模糊：用感性詞彙描述技術標準

** 錯誤範例：**

請寫出乾淨、優雅、漂亮的程式碼

問題分析：

• "乾淨"、"優雅"、"漂亮"是主觀感受，AI無法量化
• 不同開發者對這些詞彙的理解差異很大
• 導致AI產出不一致的結果

** 改善做法：**

程式碼品質標準：
- 函數長度不超過50行
- 變數命名使用描述性英文單字
- 每個函數只負責一個功能（單一職責原則）
- 必須包含錯誤處理機制

1.2 規則衝突：同時要求互相矛盾的標準

** 錯誤範例：**

開發原則：
- 程式碼要簡潔明瞭
- 功能要完整詳細
- 效能要最佳化
- 安全性要嚴格把關
- 所有功能都要有完整測試

問題分析：

• 多個要求之間可能產生衝突
• AI遇到衝突時會隨機選擇，導致不一致
• 缺乏優先順序指導

** 改善做法：**

開發原則（按優先順序）：
P1_SECURITY: 安全性檢查與輸入驗證（不可妥協）
P2_FUNCTIONALITY: 功能正確性與錯誤處理
P3_CONSISTENCY: 命名規範與程式風格
P4_OPTIMIZATION: 效能優化與程式碼簡潔

當原則衝突時，遵循優先順序決策。

1.3 約束條件設定過於籠統

** 錯誤範例：**

安全考量：
- 要注意安全性問題
- 避免常見的安全漏洞
- 保護用戶資料

問題分析：

• 沒有具體的檢查項目
• AI無法知道要實施哪些具體措施
• 容易遺漏重要的安全檢查

** 改善做法：**

安全檢查清單：
INPUT_VALIDATION:
- 所有用戶輸入必須驗證資料型別
- 使用白名單驗證而非黑名單
- 實施長度限制和格式檢查

SQL_SECURITY:
- 必須使用準備語句防止SQL注入
- 範例：$stmt = $pdo->prepare("SELECT * FROM users WHERE id = ?");
- 禁止字串拼接組合SQL查詢

DATA_PROTECTION:
- 敏感資料加密儲存
- 日誌中不可記錄密碼或金鑰
- API回應不可洩露內部錯誤詳情

二、模組化架構的設計陷阱

2.1 過度細分導致管理複雜

** 錯誤做法：**

.prompts/
├── base/naming/functions.md
├── base/naming/variables.md  
├── base/naming/classes.md
├── base/style/indentation.md
├── base/style/spacing.md
├── base/style/brackets.md
├── base/comments/inline.md
├── base/comments/function.md
└── base/comments/class.md

問題分析：

• 模組過多增加維護負擔
• 模組間的依賴關係變得複雜
• 新人學習成本過高

** 改善做法：**

.prompts/
├── base/
│   ├── naming-style.md      # 統整命名與格式
│   ├── security-rules.md    # 安全相關規範
│   └── testing-standards.md # 測試相關規範
├── lang/
│   ├── javascript.md
│   └── php.md
└── project/
    └── api-specific.md

2.2 模組循環依賴問題

** 錯誤範例：**

<!-- base/naming.md -->
@import project/api-conventions.md

<!-- project/api-conventions.md -->  
@import base/naming.md
@import base/security.md

<!-- base/security.md -->
@import project/api-conventions.md

問題分析：

• 模組間形成循環引用
• AI載入順序混亂
• 難以追蹤規則來源

** 改善做法：**

建立清晰的依賴層次：
Level 1: base/* (基礎規範，不依賴其他模組)
Level 2: lang/* (語言特定，依賴base)
Level 3: project/* (專案特定，依賴base和lang)

依賴規則：高層級可以引用低層級，反之則不行。

2.3 模組內容重疊造成衝突

** 錯誤範例：**

<!-- base/naming.md -->
變數命名使用camelCase

<!-- lang/php.md -->
PHP變數命名使用snake_case

<!-- project/legacy.md -->
為了兼容性，使用PascalCase命名

問題分析：

• 同一項目有多個不同的規定
• AI不知道該遵循哪個規範
• 產出結果不穩定

** 改善做法：**

建立清晰的覆蓋機制：
<!-- base/naming.md -->
預設命名規範：camelCase

<!-- lang/php.md -->  
PHP覆蓋規範：
- 變數和函數：snake_case（覆蓋預設規範）
- 類別：PascalCase（沿用預設規範）

覆蓋說明：專案特定 > 語言特定 > 基礎規範

三、Context 管理的典型問題

3.1 規範內容過長導致截斷

** 常見問題：**

• System Prompt總長度過長
• 重複的冗長描述
• 大量範例程式碼嵌入規範中

後果：

• 重要規範被截斷遺失
• AI只能參考部分內容
• 產出品質不穩定

** 解決策略：**

內容精簡原則：
1. 用關鍵字取代長句描述
2. 範例程式碼另外提供，不嵌入規範  
3. 使用縮寫建立團隊共同語言

錯誤：「請確保在所有的資料庫查詢操作中都要使用準備語句來防止SQL注入攻擊」
正確：「SQL查詢：必須使用準備語句（防SQL注入）」

3.2 規範載入順序錯亂

** 錯誤範例：**

# 載入順序不當
@prompts/emergency/quick-fix.md
@prompts/base/naming.md
@prompts/lang/javascript.md
@prompts/base/security.md

問題分析：

• 緊急修復規範被基礎規範覆蓋
• AI優先參考後載入的內容
• 規範效果不符預期

** 改善做法：**

規範載入順序原則：
1. 基礎規範先載入（建立foundation）
2. 語言特定規範（技術細節）
3. 專案特定規範（業務邏輯）
4. 情境特定規範（最高優先級）

範例：
@prompts/base/naming.md
@prompts/lang/javascript.md  
@prompts/project/api-rules.md
@prompts/emergency/quick-fix.md  # 最後載入，最高優先級

四、工具整合的常見錯誤

4.1 忽略不同AI工具的特性差異

** 錯誤假設：**

• 認為所有AI工具理解規範的方式相同
• 直接複製貼上相同的規範給不同工具
• 忽略工具特定的語法需求

實際問題：

• Claude偏好詳細說明，Cursor偏好精簡指令
• 規範在不同工具下產生不同效果
• 團隊成員使用結果不一致

** 改善做法：**

# .cursorrules (精簡版)
ROLE: Senior Developer
TECH: JavaScript ES6+
RULES: camelCase, async/await, JSDoc
SECURITY: Input validation, SQL prepared statements

# CLAUDE.md (詳細版)  
# JavaScript 開發規範

## 角色設定
你是一位資深JavaScript開發者，專精於現代ES6+語法。

## 技術規範
- 命名：使用camelCase命名變數和函數
- 異步處理：優先使用async/await而非Promise.then()
- 文檔：為複雜函數提供JSDoc註解

## 安全要求
- 所有用戶輸入必須驗證
- 資料庫查詢使用準備語句

4.2 版本管理策略錯誤

** 常見錯誤：**

• 不同專案使用不同版本的規範
• 規範更新後沒有通知團隊同步
• 缺乏規範版本的回滾機制

** 改善做法：**

建立規範版本管理制度：
1. 規範文件添加版本號和更新日期
2. 重大更新透過PR流程審查
3. 建立向後相容性檢查
4. 提供版本遷移指南

範例：
<!-- version: 2.1.0 | updated: 2024-09-27 | author: team -->
# JavaScript 開發規範 v2.1.0

## 版本更新說明
- v2.1.0: 新增async/await優先規則
- v2.0.0: 重構模組化架構
- v1.x: 舊版規範（已棄用）

五、效果驗證的典型盲點

5.1 只關注輸出格式，忽略邏輯正確性

** 簡單的驗證方式：**

• 只檢查程式碼是否符合命名規範
• 只驗證格式是否一致
• 忽略業務邏輯的正確性

問題後果：

• 程式碼看起來很統一，但功能有缺陷
• 安全檢查流於形式
• 測試覆蓋不足

** 詳細的驗證方式：**

多層次驗證機制：
1. 格式檢查：Linter自動檢查命名和格式
2. 功能驗證：單元測試檢查業務邏輯
3. 安全審查：專門工具檢查安全漏洞
4. 整合測試：確保系統整體運作正常

驗證清單：
- [ ] 命名符合團隊規範
- [ ] 錯誤處理機制完整  
- [ ] 安全檢查已實施
- [ ] 測試覆蓋率達標
- [ ] 業務邏輯正確

結語

System Prompt的設計是一個持續迭代的過程，避免這些常見陷阱能讓我們少走彎路：

核心避坑原則：

1. 具體化勝過抽象化 - 用量化標準取代感性描述
2. 優先順序勝過完美覆蓋 - 建立清晰的規則優先級
3. 簡潔勝過複雜 - 避免過度細分和循環依賴
4. 驗證勝過假設 - 多層次檢查確保規範有效執行

完美的規範不存在，但持續改進的規範能帶來巨大價值。