AI工作流專案規格計劃書模板

2026-06-01 4 次瀏覽

AI 專案規格計劃書模板

用途：供 AI 閱讀、理解、並據此撰寫程式碼的標準化規格文件
版本：v1.0
建立日期：YYYY-MM-DD
最後更新：YYYY-MM-DD

1. 專案概覽

1.1 專案名稱

專案名稱：[PROJECT_NAME]
專案代號：[PROJECT_CODE]

1.2 一句話描述（供 AI 快速理解）

[用一句話描述這個專案的核心目的，例如：「一個讓使用者上傳 PDF 並用自然語言查詢內容的 Web 應用程式」]

1.3 背景與目標

問題陳述：[描述要解決的問題]
目標用戶：[描述主要使用者族群]
核心價值：[這個產品帶來的主要價值]
成功指標：[如何衡量成功，例如：回應時間 < 200ms、錯誤率 < 0.1%]

1.4 範疇邊界

項目包含 ✅ 不包含 ❌ 功能 A ✅ 功能 B ❌ 功能 C ✅

2. 技術堆疊

2.1 前端

框架: [例：React 18 / Vue 3 / Next.js 14]
語言: [例：TypeScript 5.x]
樣式: [例：Tailwind CSS 3.x / CSS Modules]
狀態管理: [例：Zustand / Redux Toolkit]
HTTP 客戶端: [例：Axios / fetch]

2.2 後端

框架: [例：FastAPI / Express / NestJS]
語言: [例：Python 3.11 / Node.js 20]
ORM: [例：Prisma / SQLAlchemy]
驗證: [例：JWT / OAuth2]

2.3 資料庫

主資料庫: [例：PostgreSQL 15]
快取: [例：Redis 7]
搜尋引擎: [例：Elasticsearch（選填）]

2.4 基礎設施

雲端平台: [例：AWS / GCP / Vercel]
容器化: [例：Docker + Docker Compose]
CI/CD: [例：GitHub Actions]
監控: [例：Sentry / Datadog]

3. 架構設計

3.1 系統架構圖（文字描述）

[Client Browser]
      │
      ▼
[CDN / Load Balancer]
      │
      ▼
[Frontend App] ──── REST/GraphQL ────► [Backend API Server]
                                               │
                                    ┌──────────┼──────────┐
                                    ▼          ▼          ▼
                               [Database]  [Cache]  [File Storage]

3.2 目錄結構

project-root/
├── frontend/
│   ├── src/
│   │   ├── components/     # 可複用 UI 元件
│   │   ├── pages/          # 頁面元件
│   │   ├── hooks/          # 自定義 Hooks
│   │   ├── store/          # 狀態管理
│   │   ├── services/       # API 呼叫層
│   │   ├── types/          # TypeScript 型別定義
│   │   └── utils/          # 工具函式
│   └── public/
├── backend/
│   ├── src/
│   │   ├── routes/         # 路由定義
│   │   ├── controllers/    # 請求處理
│   │   ├── services/       # 業務邏輯
│   │   ├── models/         # 資料模型
│   │   ├── middleware/     # 中介軟體
│   │   └── utils/          # 工具函式
│   └── tests/
├── docker-compose.yml
└── README.md

3.3 模組依賴規則

⚠️ AI 請遵守以下依賴方向，禁止反向依賴

pages → components → hooks → services → types
controllers → services → models → database

4. 功能需求

格式說明：每個功能用以下格式描述，讓 AI 能直接轉換為程式碼

4.1 功能清單

ID 功能名稱優先級狀態 F-001 使用者註冊與登入 P0（必要）待開發 F-002 [功能名稱] P1（重要）待開發 F-003 [功能名稱] P2（次要）待開發

功能規格卡片（每個功能一張）

`F-001` 使用者註冊與登入

功能描述
使用者可以用 Email + 密碼註冊帳號，並登入系統取得 JWT Token。

輸入

interface RegisterInput {
  email: string;       // 格式：有效 email，唯一值
  password: string;    // 最少 8 字元，需含大小寫與數字
  name: string;        // 最少 2 字元，最多 50 字元
}

輸出

interface AuthResponse {
  token: string;       // JWT，有效期 7 天
  user: {
    id: string;
    email: string;
    name: string;
    createdAt: string; // ISO 8601 格式
  };
}

業務邏輯（步驟）

驗證 Email 格式與唯一性
密碼用 bcrypt（cost factor 12）加密
寫入資料庫
產生 JWT 並回傳

邊界條件

Email 已存在 → 回傳 409 Conflict
密碼格式不符 → 回傳 422 Unprocessable Entity
資料庫錯誤 → 回傳 500 Internal Server Error，記錄 log

相關檔案

路由：backend/src/routes/auth.ts
服務：backend/src/services/authService.ts
測試：backend/tests/auth.test.ts

`F-002` [功能名稱]

功能描述
[描述]

輸入

interface [InputName] {
  // 欄位定義
}

輸出

interface [OutputName] {
  // 欄位定義
}

業務邏輯（步驟）

[步驟一]
[步驟二]

邊界條件

[條件] → [預期行為]

5. 非功能需求

5.1 效能需求

指標目標值測量方式 API 回應時間（P95） < 200ms APM 監控首頁載入時間（LCP） < 2.5s Lighthouse 並發用戶數 1,000 壓力測試資料庫查詢時間 < 50ms Query log

5.2 安全性需求

[ ] 所有 API 需驗證 JWT Token（除公開路由外）
[ ] 密碼禁止明文儲存，使用 bcrypt 加密
[ ] 所有輸入需進行 sanitization，防止 XSS / SQL Injection
[ ] HTTPS only，禁止 HTTP
[ ] 敏感資料（API Key 等）只能存在環境變數，禁止 hardcode

5.3 可用性需求

服務可用率：99.9%（允許每月約 44 分鐘停機）
資料備份頻率：每日一次

6. 資料模型

6.1 實體關係（ER 描述）

User ──── 1:N ──── Post
User ──── 1:N ──── Comment
Post ──── 1:N ──── Comment

6.2 資料表定義

`users` 表

CREATE TABLE users (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email       VARCHAR(255) NOT NULL UNIQUE,
  password    VARCHAR(255) NOT NULL,           -- bcrypt hash
  name        VARCHAR(50)  NOT NULL,
  role        ENUM('user', 'admin') DEFAULT 'user',
  is_active   BOOLEAN DEFAULT true,
  created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- 索引
CREATE INDEX idx_users_email ON users(email);

`[table_name]` 表

CREATE TABLE [table_name] (
  id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  -- 欄位定義
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

6.3 TypeScript 型別對應

// 對應 users 表
interface User {
  id: string;
  email: string;
  name: string;
  role: 'user' | 'admin';
  isActive: boolean;
  createdAt: Date;
  updatedAt: Date;
}

// DTO（不含密碼等敏感欄位）
type UserDTO = Omit<User, 'password'>;

7. API 規格

7.1 基礎設定

Base URL: https://api.example.com/v1
Content-Type: application/json
Authorization: Bearer {JWT_TOKEN}

7.2 統一回應格式

成功回應

{
  "success": true,
  "data": { },
  "meta": {
    "page": 1,
    "total": 100
  }
}

錯誤回應

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email 格式不正確",
    "details": [ ]
  }
}

7.3 端點定義

`POST /auth/register` — 使用者註冊

項目內容方法 POST 路徑 /auth/register 驗證不需要限流 10 次/分鐘（per IP）

Request Body

{
  "email": "[email protected]",
  "password": "Passw0rd!",
  "name": "王小明"
}

Response 201 Created

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "uuid-here",
      "email": "[email protected]",
      "name": "王小明"
    }
  }
}

錯誤碼

HTTP 狀態碼 error.code 說明 409 EMAIL_ALREADY_EXISTS Email 已被使用 422 VALIDATION_ERROR 欄位格式錯誤 500 INTERNAL_ERROR 伺服器錯誤

`GET /[resource]` — [端點說明]

項目內容方法 GET 路徑 /[resource] 驗證需要 JWT

Query Parameters

page    int     頁碼，預設 1
limit   int     每頁筆數，預設 20，最大 100
sort    string  排序欄位，預設 created_at
order   string  asc / desc，預設 desc

8. UI／UX 規格

8.1 設計系統

色彩

:root {
  --color-primary:    #[hex];    /* 主色 */
  --color-secondary:  #[hex];    /* 輔色 */
  --color-success:    #22C55E;
  --color-warning:    #F59E0B;
  --color-error:      #EF4444;
  --color-bg:         #[hex];    /* 背景 */
  --color-text:       #[hex];    /* 主文字 */
  --color-text-muted: #[hex];    /* 次要文字 */
}

間距系統（8px base）

xs: 4px  |  sm: 8px  |  md: 16px  |  lg: 24px  |  xl: 32px  |  2xl: 48px

字體

font-family-display: '[顯示字體]', sans-serif;  /* 標題 */
font-family-body:    '[內文字體]', sans-serif;  /* 內文 */
font-family-mono:    '[等寬字體]', monospace;   /* 程式碼 */

8.2 頁面清單

頁面 ID 路由元件檔案說明 P-001 / HomePage.tsx 首頁 P-002 /login LoginPage.tsx 登入頁 P-003 /dashboard DashboardPage.tsx 儀表板（需登入） P-004 /[route] [Component].tsx [說明]

8.3 頁面規格卡片

`P-002` 登入頁

版面結構

┌────────────────────────┐
│        Logo            │
│                        │
│   ┌────────────────┐   │
│   │  Email Input   │   │
│   │  Password      │   │
│   │  [登入按鈕]    │   │
│   │  忘記密碼連結  │   │
│   └────────────────┘   │
│                        │
│   還沒有帳號？註冊     │
└────────────────────────┘

互動行為

表單送出前進行前端驗證
登入中顯示 loading spinner
成功後跳轉至 /dashboard
失敗顯示 inline 錯誤訊息

狀態管理

interface LoginPageState {
  email: string;
  password: string;
  isLoading: boolean;
  error: string | null;
}

9. 錯誤處理規範

9.1 錯誤碼定義

錯誤碼 HTTP 狀態碼說明前端處理方式 UNAUTHORIZED 401 未登入或 Token 過期跳轉登入頁 FORBIDDEN 403 無此操作權限顯示提示訊息 NOT_FOUND 404 資源不存在顯示 404 頁面 VALIDATION_ERROR 422 輸入格式錯誤顯示欄位錯誤 RATE_LIMITED 429 請求過於頻繁顯示倒數計時 INTERNAL_ERROR 500 伺服器錯誤顯示通用錯誤訊息

9.2 後端 Log 規範

// 每個 Error log 必須包含以下欄位
interface ErrorLog {
  level: 'error' | 'warn' | 'info';
  message: string;
  code: string;
  requestId: string;    // 追蹤用
  userId?: string;      // 若已驗證
  stack?: string;       // 僅限 error level
  timestamp: string;    // ISO 8601
}

10. 測試規格

10.1 測試類型與覆蓋率目標

測試類型工具覆蓋率目標單元測試 Jest / Vitest ≥ 80% 整合測試 Supertest 核心 API 100% E2E 測試 Playwright 主要流程 100%

10.2 測試案例格式

// 格式：describe → it → AAA（Arrange, Act, Assert）

describe('AuthService', () => {
  describe('register()', () => {
    it('應使用 bcrypt 加密密碼後儲存', async () => {
      // Arrange
      const input = { email: '[email protected]', password: 'Test1234!' };

      // Act
      const result = await authService.register(input);

      // Assert
      expect(result.user.email).toBe(input.email);
      expect(result.token).toBeDefined();
    });

    it('若 Email 已存在應拋出 EmailAlreadyExistsError', async () => {
      // Arrange — 預先建立相同 email 的用戶
      // Act & Assert
      await expect(authService.register(duplicateInput))
        .rejects.toThrow(EmailAlreadyExistsError);
    });
  });
});

10.3 必要測試案例清單

功能測試案例類型登入正確帳密登入成功整合登入錯誤密碼回傳 401 整合登入不存在的 Email 回傳 401 整合 [功能] [案例] [類型]

11. 部署與環境

11.1 環境變數

# ===== 應用程式 =====
NODE_ENV=production          # development / staging / production
PORT=3000
APP_URL=https://example.com

# ===== 資料庫 =====
DATABASE_URL=postgresql://user:pass@host:5432/dbname
REDIS_URL=redis://host:6379

# ===== 驗證 =====
JWT_SECRET=[至少 32 字元的隨機字串]
JWT_EXPIRES_IN=7d

# ===== 第三方服務 =====
# SMTP_HOST=
# SMTP_PORT=
# [其他服務的 API Key]

11.2 環境對應表

設定 Development Staging Production Log Level debug info warn 資料庫本地 Docker 測試 DB 正式 DB Email Mailtrap Mailtrap SendGrid

11.3 Docker 設定摘要

# docker-compose.yml 必要服務
services:
  app:      # 主應用程式
  db:       # PostgreSQL
  cache:    # Redis
  # [其他服務]

12. AI 指令集

這個區塊專門給 AI（如 Claude）閱讀，說明如何根據本文件生成程式碼

12.1 編碼規範

- 語言：TypeScript（strict mode 開啟）
- 縮排：2 spaces
- 引號：單引號（'）
- 分號：不使用
- 命名：
    - 變數／函式：camelCase
    - 類別／介面：PascalCase
    - 常數：UPPER_SNAKE_CASE
    - 資料庫欄位：snake_case
- 匯入順序：node 內建 → 第三方套件 → 本地模組

12.2 禁止事項（AI 不得這樣寫）

❌ 禁止 hardcode 任何 secret 或 API Key
❌ 禁止使用 any 型別（TypeScript）
❌ 禁止省略錯誤處理
❌ 禁止直接在 controller 寫業務邏輯（應放在 service）
❌ 禁止在前端儲存 JWT 於 localStorage（使用 httpOnly cookie）
❌ 禁止產生不在規格內的 API 端點

12.3 生成程式碼的優先順序

1. 先寫型別定義（interfaces / types）
2. 再寫資料存取層（model / repository）
3. 再寫業務邏輯（service）
4. 再寫路由與控制器（route / controller）
5. 最後寫測試（tests）

12.4 當需求不明確時

若規格書中有以下情況，AI 應停下並詢問：
- 型別定義有歧義
- 業務邏輯步驟有缺漏
- 邊界條件未覆蓋到某種情況
- 需要選擇技術方案但規格未指定

請勿自行假設並繼續，而是列出問題請人確認。

12.5 每次生成後的 Checklist

生成程式碼後，AI 請自我確認：
□ 是否符合目錄結構規範？
□ 是否有完整的型別定義？
□ 是否有錯誤處理？
□ 是否符合命名規範？
□ 是否有對應的測試案例（若為功能程式碼）？
□ 是否有任何 TODO 或 FIXME 需要告知使用者？

附錄

A. 術語表

術語定義 JWT JSON Web Token，用於 API 驗證的加密 token DTO Data Transfer Object，資料傳輸物件 P0/P1/P2 優先級：P0 必要、P1 重要、P2 次要 [術語] [定義]

B. 版本記錄

版本日期變更說明作者 v1.0 YYYY-MM-DD 初始版本 [姓名]

C. 相關文件連結

設計稿：[Figma 連結]
API 測試集：[Postman / Insomnia 連結]
專案看板：[Notion / Linear 連結]