軟體工程

AI 導向的現代軟體開發方法論 — 從 Prompt 到部署的完整流程

課程概述

本課程介紹 AI 導向的現代軟體開發方法論，重點在於如何與 AI 協作、建立完善的測試體系、設計清晰的 API、以及運用 Git 和 CI/CD 管線。課程內容對應 The Modern Software 線上教材，以及本倉庫的 code/軟體工程/ 範例和 wiki/軟體工程/ 知識庫。

三大支柱

AI 協作 — Prompt、Context、Harness、Skill 四大工程
測試先行 — 測試金字塔、pytest、Playwright、test.sh
API 驅動 — CLI → REST → React 的前後端分離

開發紀律

Git 工作流 — 分支策略、Pull Request、Code Review
CI/CD — 自動化建構、測試、部署
KISS 原則 — Keep It Simple, Stupid

開發 Pipeline

現代軟體開發從意圖到部署的完整流程：

Prompt
描述意圖

→

Context
提供背景

→

Harness
設計約束

→

Code Gen
AI 生成

→

Test
自動驗證

→

Deploy
持續交付

範例專案：Todo 應用（多種實作）

同一份 Todo 應用以 Python (FastAPI)、Rust (Axum + SQLite)、Rust (sled + Redis + Nginx) 分別實作，展示語言與架構選擇對效能與開發體驗的影響。詳見 Rust 軟體工程、Rust 測試。

總覽文件 (todo/README.md)

Python 版

todo-py/

CLI: todo add/list/done/delete — cli.py
API: FastAPI + SQLite — api.py
Frontend: React + Vite — frontend/
測試: test_cli.py + test_api.py (13 tests)
AI: AGENTS.md

Rust + SQLite

todo-rust/

CLI: todo add/list/done/delete — cli.rs (clap)
API: Axum + rusqlite — api.rs
資料庫: rusqlite + WAL — database.rs
測試: cli_test.rs (6 tests) — Rust 測試說明
對比: BENCHMARKS.md

Rust + sled + Redis

todo-rust-fast/

儲存: sled (lock-free, mmap) — db.rs
快取: Redis (選用, 10s TTL) — cache.rs
壓縮: brotli + gzip (tower-http)
反向代理: nginx/todo.conf
對比: BENCHMARKS.md

金流整合範例

展示三種金流閘道的整合方式：Stripe（國際）、綠界 ECPay（台灣）、以及自建金流系統 Pay4。

payment/README.md

Stripe 閘道

stripe_gateway.py

Pay: PaymentIntent create + confirm
Webhook: 驗證簽章 + 事件分派
Refund: 全額 / 部分退款
測試: mock stripe SDK (6 tests)

綠界 ECPay

ecpay_gateway.py

CheckMacValue: SHA256 簽章產生 + 驗證
Callback: ReturnURL 同步 + PaymentInfoURL 非同步
查詢退款: query_trade / refund
測試: 簽章比對 + callback 場景 (8 tests)

Pay4 自建金流

pay4_gateway.py

整合: 將 payment/ 統一介面接到 pay4/
CLI: --provider pay4 三閘道統一操作
跨行程: 自動初始化 + 重複使用商家
測試: 真實 pay4 訂單流 (6 tests)

Pay4 自建金流引擎

一套從頭實作的金流系統，不依賴任何第三方金流 SDK。涵蓋商家管理、訂單收款、雙式記帳帳本、清算撥款、Webhook 通知。

pay4/README.md · 規劃書

六大核心模組

▶

# merchant.py — 商家註冊、API Key 產生
# engine.py   — 付款狀態機 pending→paid→refunding→refunded
# ledger.py   — 雙式記帳，借貸平衡
# settlement.py — 批次清算撥款（彙總→手續費→撥款）
# webhook.py  — 事件佇列 + HMAC-SHA256 + 3 次重試
# cli.py      — pay4.cli init / merchant / order / settle / ledger
# api.py      — FastAPI REST API (API Key 驗證)

雙式記帳範例

▶

# 訂單 $1000, 手續費 3%
# Step 1: 付款
#   merchant:A:receivable → merchant:A:balance    +$970
#   merchant:A:balance    → pay4:revenue          +$30
# Step 2: 清算撥款
#   merchant:A:balance    → pay4:bank             +$970

語言與工具對效能的影響

同一份 Todo 應用分別用 Python (FastAPI) 和 Rust (Axum + SQLite / sled + Redis) 實作，展示語言與架構選擇對執行效能和開發體驗的差異。

核心指標對比

▶

#                   Python        Rust+SQLite   Rust+sled+Redis+Nginx
# 啟動時間         ~500ms         ~8ms          ~10ms
# 記憶體 (idle)    ~80MB          ~5MB          ~12MB
# 吞吐量           ~12k req/s     ~128k req/s   ~450k req/s
# 延遲 p99         ~15ms          ~1.2ms        ~0.2ms
# 開發速度         Python 快     Rust 慢 (編譯)  Rust 慢 (編譯)
# 型別安全         執行期檢查     編譯期保證      編譯期保證

為什麼 Rust 更快

▶

# 1. 啟動時間：Python 載入直譯器 + 模組 vs Rust 直接執行
# 2. 記憶體：Python 物件 (int=28B) vs Rust 值 (i64=8B, 無 GC)
# 3. 吞吐量：FastAPI 單執行緒 vs Axum 多執行緒 async + sled mmap
#    Redis 快取 read-heavy ~1.7x, Nginx proxy + keepalive ~1.3x

選擇建議

▶

# 選 Python 當：快速原型、團隊 Python 經驗、開發速度優先、Serverless
# 選 Rust (Axum+SQLite) 當：高吞吐/低延遲、記憶體受限、編譯期安全
# 選 Rust+sled+Redis 當：極致效能 (~37x Python)、快取+反向代理

Rust vs Python 對比報告 sled+Redis+Nginx 對比報告 Rust 軟體工程

AI 協作開發

六層 AI 協作工程，從基礎到進階：

Prompt 工程

▶

提示詞設計與最佳化，讓 AI 精確理解意圖。

# 好的 Prompt: 角色 + 任務 + 格式 + 約束
# 1. 角色定義：你是一位 Rust 系統程式專家
# 2. 任務描述：實作一個 lock-free 佇列
# 3. 輸出格式：提供完整程式碼和測試
# 4. 約束條件：unsafe code 需附 safety 註解

wiki/Prompt工程.md

Context 工程

▶

上下文管理策略，確保 AI 掌握足夠背景資訊。

# 結構化 Context 提供
# 1. 專案結構 + 檔案內容
# 2. 編碼約定與風格指南
# 3. 相關 issue / PR 討論
# 4. 測試案例與預期行為

wiki/Context工程.md

Harness 工程

▶

設計約束與驗證系統，確保 AI 輸出符合預期。

# Harness 六大元件
# 1. AGENTS.md — 專案操作手冊
# 2. Skill 文件 — 領域知識編碼
# 3. 測試框架 — 自動驗證
# 4. Lint 規則 — 風格強制
# 5. CI pipeline — 回歸防護
# 6. Code Review — 人類把關

wiki/Harness工程.md

Skill 文檔

▶

OpenCode 領域知識擴充機制。

# Skill = 領域知識包
# SKILL.md 定義: 描述 + 觸發詞 + 工作流程
# 安裝: skill add <url>
# 範例: fastapi-expert, c-pro, test-script-generator

wiki/Skill文檔.md

Loop 工程

▶

多層反饋迴圈的設計與管理，形成自我改善系統。

# 三層 Loop
# 底層：編輯 → 測試 → 修正（秒級）
# 中層：程式碼 → 測試 → Lint → 修復 → 重測（分鐘級）
# 頂層：開發 → Review → CI → 部署 → 監控（小時級）

wiki/Loop工程.md

Agentic 工程

▶

自主 AI 智慧體的設計與建構。

# Agent 層級
# L0: 純人工（無 AI）
# L1: AI 輔助（Copilot 補全）
# L2: AI 驅動（OpenCode 執行任務）
# L3: 端到端 Agent（自主規劃+執行）

wiki/Agentic工程.md

人機協作模式

▶

人類與 AI 智慧體的分工協作模式。

# 五種協作模式
# 1. AI 提供建議，人類決定
# 2. AI 實作功能，人類驗收
# 3. AI 修復 bug，人類審查
# 4. AI 撰寫測試，人類確認
# 5. AI 端到端任務，人類驗收

wiki/人機協作模式.md

ccc 開發約定

▶

所有專案的編碼標準，強調測試、品質和 KISS 原則：

# 1. 詳細單元測試 + 系統測試（pytest / cargo test）
# 2. 網站：CLI → REST API → React 前端
# 3. test.sh 統一測試入口（set -x）
# 4. Lint 檢查（python → ruff / rust → clippy）
# 5. KISS 原則、相對路徑、_doc/vx.y.md 規劃

code/ccc_code_skill.md E2E 測試詳解 Rust 測試詳解

測試策略

測試金字塔是測試策略的核心指導原則：

E2E 測試 (Playwright) — 慢、貴、少

整合測試 (API/DB) — 中等

單元測試 (pytest / cargo test) — 快、便宜、多

pytest (Python)

▶

Python 專案使用 pytest 作為測試框架：

import pytest
def test_add():
    assert add(2, 3) == 5
def test_divide_by_zero():
    with pytest.raises(ValueError):
        divide(1, 0)
# 執行: python -m pytest 或 pytest

wiki/測試.md todo/test_cli.py todo/test_api.py

Playwright E2E

▶

使用 Playwright 進行端到端測試，模擬真實用戶操作：

from playwright.sync_api import sync_playwright
def test_blog_homepage():
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page()
        page.goto("http://localhost:3000")
        assert page.title() == "部落格"
        browser.close()

wiki/E2E測試.md todo/test_e2e.py

cargo test (Rust)

▶

Rust 內建測試框架，支援單元測試、整合測試、文件測試：

use std::process::Command;
#[test]
fn test_add() {
    let out = todo(&["add", "hello"], &fresh_db());
    assert!(out.contains("Added: #1"), "got: {}", out);
}
// 執行: cargo test
// 過濾: cargo test test_add
// stdout: cargo test -- --nocapture

wiki/Rust測試.md todo-rust/tests/cli_test.rs

test.sh 腳本

▶

每個專案必須有 test.sh 作為統一測試入口：

# Python 專案
#!/bin/bash
set -x
pytest -v
ruff check .
# Rust 專案
#!/bin/bash
set -x
cargo test
cargo clippy

API 設計

根據 ccc_code_skill.md，寫網站的正確順序是：CLI → REST API → React 前端，確保每個層級可獨立測試和驗證。

wiki/API設計.md

Git 風格 CLI

▶

使用 cmd op args 模式，類似 Git 的命令列介面：

# CLI 設計範例 (todo app)
$ todo add "完成作業"
# ➜ Added: #1 完成作業
$ todo list
# ➜ 1. 完成作業
$ todo done 1
# ➜ Done: #1 完成作業

todo/cli.py

REST API

▶

FastAPI / Axum 提供的 RESTful API：

# REST API 端點
GET    /api/todos      # 列表
POST   /api/todos      # 新增 {text}
PATCH  /api/todos/{id}  # 更新 {text, done}
DELETE /api/todos/{id}  # 刪除

todo/api.py todo-rust/api.rs

React 前端

▶

使用 Vite + React 建置的前端介面：

// React 元件範例
function TodoApp() {
  const [todos, setTodos] = useState([]);
  const [text, setText] = useState("");
  return (
    <div>
      <input value={text} onChange={e => setText(e.target.value)} />
      <button onClick={addTodo}>Add</button>
    </div>
  );
}

todo/frontend/

Git 工作流程

本課程使用 GitHub Flow 搭配 AI 協作：

# GitHub Flow + AI
# 1. 從 main 開 feature branch
# 2. AI 在 feature branch 開發 + 測試
# 3. AI 提交 PR（含測試結果）
# 4. 人類 Code Review
# 5. Merge 到 main → 自動部署

CI/CD

每次推送程式碼自動觸發建構、測試和部署：

GitHub Actions

▶

# .github/workflows/ci.yml
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-python@v5
  - run: pip install -r requirements.txt
  - run: pytest
  - run: ruff check .

三種部署路由

▶

# Git-SCM (Vercel/Render)
#   git push → 自動部署 # 適合 server 專案
# Pages-Static (GitHub Pages)
#   docs/html/ 直接部署   # 適合靜態網站
# Pages-SPA (Cloudflare Pages)
#   build → deploy        # 適合前端 SPA

軟體架構

架構設計遵循 SOLID 原則和 KISS 原則：

# 分層架構 (Layered Architecture)
# ┌──────────┐
# │  React   │  ← 前端展示層
# ├──────────┤
# │ FastAPI  │  ← API 層 (REST)
# │ Axum     │
# ├──────────┤
# │  CLI     │  ← 命令列層
# ├──────────┤
# │ SQLite   │  ← 資料層
# │ sled     │
# └──────────┘

人機協作模式

單人 + AI

▶

一人開發者搭配 AI 助手，涵蓋整個開發生命週期：

# 開發循環
# 1. 規劃 + Prompt 設計
# 2. AI 產生程式碼 + 測試
# 3. 人類驗證結果
# 4. CI 自動驗證
# 5. 部署上線

團隊合作

▶

團隊中每個成員皆配備 AI 助手：

# 團隊協作模式
# • AGENTS.md — 每人知道如何操作專案
# • 測試覆蓋 — AI 修改後回歸保障
# • PR Review — 人類最終把關
# • CI/CD — 自動化驗證流程

營運與商業

金流整合

▶

第三方支付、信用卡收款、訂閱制金流與對帳。國際市場以 Stripe 為核心，輔以 Stripe Atlas 一站式公司設立。

# 金流選擇比較
# Stripe    — 國際市場 (135+ 貨幣)，API 最優，手續費 2.9%+$0.30
# Stripe Atlas — 美國 Delaware C-Corp 公司 + 美國銀行帳戶 + Stripe 帳號
# 綠界      — 台灣市場，多元收款方式，手續費 ~2.75%
# Pay4      — 自建引擎，零手續費，需自行維護

wiki/金流整合.md wiki/公司登記與開業.md

公司登記與開業

▶

台灣或美國公司設立。國際團隊首選 Stripe Atlas（Delaware C-Corp），15 分鐘線上完成。

# 台灣公司（軟體業常見：有限公司）
# 1. 名稱預查 → 2. 銀行籌備戶 → 3. 會計師驗資
# 4. 送件經濟部 → 5. 國稅局登記 → 6. 勞健保投保

# 美國公司（Stripe Atlas，Delaware C-Corp）
# 1. 填寫 Stripe Atlas 申請（15 分鐘）
# 2. 取得 EIN（雇主識別號碼，聯邦稅務用）
# 3. 開設 Mercury / Brex 企業銀行帳戶
# 4. 取得 Stripe 帳號（可直接收款）
# 5. 每年 Filing 報告 + 聯邦/州稅申報

wiki/公司登記與開業.md Stripe Atlas

上線營運

▶

上線前檢查清單、營運週期、常見問題處理。國際市場需額外考量跨國稅務、多幣別、GDPR 合規。

# 通用檢查
# □ 功能測試 + 壓力測試
# □ SSL/TLS + DNS 設定
# □ 日誌與監控 (Sentry / Grafana)
# 國際市場額外項目
# □ Stripe 收款設定（135+ 貨幣自動結匯）
# □ 跨境稅務（美國聯邦/州稅、VAT、GST）
# □ GDPR / CCPA 隱私權條款
# □ 多語言錯誤頁面 + 客服管道

wiki/上線營運.md