人機協作開發實戰指南

HypGo Framework — AI-Human Collaborative Development Guide 版本：0.8.1 | 2026-03

寫給開發者的話

這篇文檔不講理論，只講「你下一步該做什麼」。

如果你剛接觸 HypGo，或者你已經在用但覺得 AI 協作的效果不如預期，這篇文檔會建議你：怎麼準備材料、怎麼下指令、怎麼讓 AI 少犯錯。

核心觀念只有一個：你給 AI 的資訊品質，決定了 AI 產出的程式碼品質。 HypGo 的工具鏈就是幫你用最少的力氣，準備最高品質的資訊。

第一章：從哪裡開始？先做什麼？

1.1 第一件事：建立專案骨架

# 純 API 專案（推薦起手）
hyp api myservice && cd myservice && go mod tidy

# 全棧專案（含前端模板）
hyp new myapp && cd myapp && go mod tidy

1.2 第二件事：寫好 Schema，而不是 Handler

很多人的直覺是先寫 handler，再補文檔。在 HypGo 中，順序反過來：

❌ 先寫 handler → 再寫測試 → 再寫文檔 → AI 不知道你在幹嘛
✅ 先寫 Schema → AI 幫你寫 handler → Contract 自動驗證 → 你審核業務邏輯

Schema 是整個人機協作的起點。沒有 Schema，Manifest 是空的，Contract Testing 無法運作，AI 生成的程式碼沒有依據。

1.3 第三件事：生成 Manifest 和 AI 配置檔

Schema 寫好、server 跑起來之後，立刻執行：

# 生成專案快照（AI 的「地圖」）
hyp context -o .hyp/context.yaml

# 生成所有 AI 工具的配置檔
hyp ai-rules

這兩步做完後，無論開發者用哪個 AI 工具（Claude Code、Cursor、Copilot、Gemini、Codex），AI 都會自動讀取配置檔，立刻知道你的專案用了 HypGo、有哪些路由、該用什麼慣例。

1.4 命令執行順序速查表

順序	命令	目的	何時執行
1	`hyp api myservice`	建立專案	一次
2	寫 Schema 路由	定義 API 合約	每次新增路由
3	`hyp run`	啟動（AutoSync 自動生成 manifest）	開發時
4	`hyp context -o .hyp/context.yaml`	手動更新 manifest	Schema 變更後
5	`hyp ai-rules`	生成 AI 工具配置檔	路由變更後、新成員加入時
6	`hyp chkcomment <file>`	檢查註解完整性	寫完程式碼後
7	`hyp impact <file>`	分析修改影響	改共用套件前
8	`hyp migrate diff`	產生 DB migration SQL	Model 變更後

1.5 你該準備哪些材料給 AI？

你不需要把所有原始碼丟給 AI。HypGo 幫你把資訊壓縮到幾個關鍵檔案：

材料	檔案	Token 成本預估	包含什麼
必備	`.hyp/context.yaml`	~500	所有路由、型別、server 設定
必備	`AGENTS.md` 或 `CLAUDE.md`	~300	框架慣例、Build/Test 指令
按需	單一 Schema 定義	~50	特定路由的 Input/Output struct
按需	Error Catalog 節錄	~30	已定義的錯誤碼清單
按需	`hyp impact` 輸出	~50	修改影響範圍

關鍵原則：讓 AI 先讀 manifest，再讀你的需求。不要讓 AI 自己去翻原始碼。

第二章：如何開始一個新功能？

2.1 實戰範例：新增「訂單」功能

假設你要新增一組訂單 API（建立訂單、查詢訂單、列出訂單）。以下是推薦的步驟：

步驟一：定義 Struct（你來）

// app/models/order.go

type CreateOrderReq struct {
    UserID    int     `json:"user_id"`
    ProductID int     `json:"product_id"`
    Quantity  int     `json:"quantity"`
    Note      string  `json:"note,omitempty"`
}

type OrderResp struct {
    ID        int     `json:"id"`
    UserID    int     `json:"user_id"`
    ProductID int     `json:"product_id"`
    Quantity  int     `json:"quantity"`
    Total     float64 `json:"total"`
    Status    string  `json:"status"`
    CreatedAt string  `json:"created_at"`
}

步驟二：定義 Schema 路由（你來）

// app/controllers/order.go

r.Schema(schema.Route{
    Method:  "POST",
    Path:    "/api/orders",
    Summary: "建立訂單",
    Tags:    []string{"orders"},
    Input:   CreateOrderReq{},
    Output:  OrderResp{},
    Responses: map[int]schema.ResponseSchema{
        201: {Description: "Order created"},
        400: {Description: "Invalid input"},
    },
}).Handle(createOrderHandler)

r.Schema(schema.Route{
    Method:  "GET",
    Path:    "/api/orders/:id",
    Summary: "查詢單筆訂單",
    Tags:    []string{"orders"},
    Output:  OrderResp{},
}).Handle(getOrderHandler)

步驟三：告訴 AI 幫你作（AI 進行）

請根據 .hyp/context.yaml 中的 schema，實作 createOrderHandler 和 getOrderHandler。
使用 errors.Define 定義錯誤碼（E3001 起跳），
用 Bun ORM 存取資料庫。

AI 會看到 manifest 裡的 Input/Output 型別，直接生成符合合約的 handler。

步驟四：驗證（自動）

// app/controllers/order_test.go
func TestOrderContracts(t *testing.T) {
    contract.TestAll(t, router)
}

一行就驗證了所有 schema 路由的 Input/Output 合約。

2.2 為什麼是這個順序？

你定義「什麼」（Schema） → AI 實作「怎麼做」（Handler） → Contract 驗證「對不對」

這個順序最大化了人機協作的效率：

你擅長的事：決定 API 長什麼樣、業務邏輯是什麼
AI 擅長的事：把你的定義轉成 boilerplate 程式碼
框架擅長的事：自動驗證 AI 的產出符合你的定義

第三章：Schema、Manifest、Router、Contract — 誰最重要？

3.1 四者的關係圖

Schema（定義合約）
  │
  ├──→ Router（註冊路由 + Schema metadata）
  │         │
  │         └──→ Manifest（專案快照，給 AI 讀）
  │
  └──→ Contract（根據 Schema 自動驗證 Handler）

3.2 重要性排名

排名	元件	影響範圍	為什麼
1	Schema	全局	它是其他三者的基礎。沒有 Schema，Manifest 是空的、Contract 無法驗證、Router 退化為傳統路由
2	Contract	品質保證	Schema 寫好但不驗證，等於沒寫。Contract 是閉環的「最後一哩路」
3	Manifest	AI 效率	有了 Schema，Manifest 是自動產出的。它影響的是 AI 的理解速度和準確度
4	Router	運行時	Router 本身是基礎設施，Schema 路由和傳統路由都能用，差別在於有沒有攜帶 metadata

一句話總結：Schema 是源頭，Contract 是驗證，Manifest 是傳遞，Router 是載體。

3.3 Schema：怎麼寫好？

Schema 的品質直接決定了 AI 生成程式碼的品質。以下是實戰建議：

必填欄位

r.Schema(schema.Route{
    Method:  "POST",          // ← 必填：HTTP 方法
    Path:    "/api/users",    // ← 必填：路由路徑
    Summary: "建立使用者",     // ← 強烈建議：一句話說明，AI 靠這個理解意圖
    Input:   CreateUserReq{}, // ← 強烈建議：Input struct，Contract 用它驗證請求
    Output:  UserResp{},      // ← 強烈建議：Output struct，Contract 用它驗證回應
}).Handle(handler)

選填但有價值的欄位

r.Schema(schema.Route{
    // ...必填欄位...

    Tags:        []string{"users", "admin"},  // AI 可以按模組理解路由
    Description: "建立新使用者帳號，需要 admin 權限",  // 更詳細的說明

    Responses: map[int]schema.ResponseSchema{
        201: {Description: "User created successfully"},
        400: {Description: "Validation error"},
        409: {Description: "Email already exists"},
    },

    Params: []schema.ParamSchema{
        {Name: "id", In: "path", Required: true, Type: "int"},
    },
}).Handle(handler)

Schema 品質檢查清單

項目	好的做法	差的做法
Summary	`"建立使用者"`	`""` （空的，AI 不知道這路由幹嘛）
Input	`CreateUserReq{}` （明確的 struct）	`nil` （AI 無法知道要傳什麼）
Output	`UserResp{}` （明確的 struct）	`nil` （Contract 無法驗證回應）
Tags	`[]string{"users"}` （分類清楚）	`nil` （Manifest 裡看不出模組劃分）
Responses	列出 201/400/409	不寫（AI 猜不到錯誤情境）

3.4 Manifest：怎麼寫？

你不需要手動寫 Manifest。 它是自動生成的。

# 方法一：手動生成
hyp context -o .hyp/context.yaml

# 方法二：自動生成（Server.Start() 時 AutoSync 會寫入 .hyp/context.yaml）
hyp run

Manifest 的品質取決於你的 Schema 品質。Schema 寫得好，Manifest 就包含完整的路由、型別和描述。Schema 是空的，Manifest 就只有 server 設定。

唯一要做的事：確保 .hyp/context.yaml 被加入版本控制（或者加入 .gitignore 讓每次啟動自動生成，取決於你的偏好）。

3.5 Contract：怎麼寫？

最簡單的用法（推薦起手）

func TestAllContracts(t *testing.T) {
    // 建立你的 router（含所有 Schema 路由）
    r := setupRouter()

    // 一行測試所有 schema 路由
    contract.TestAll(t, r)
}

TestAll 會自動：

遍歷 Schema Registry 中所有路由
為 Input struct 生成最小有效的 JSON（數字填 0，字串填 "test"）
發送 HTTP 請求
驗證回應狀態碼（POST → 201、DELETE → 204、其他 → 200）
驗證回應 body 符合 Output struct 的欄位

手動測試特定路由

contract.Test(t, r, contract.TestCase{
    Route:        "POST /api/users",
    Input:        `{"name":"alice","email":"[email protected]"}`,
    ExpectStatus: 201,
    ExpectSchema: true,  // 驗證回應符合 UserResp schema
})

純路由存在性測試

// 不驗證 schema，只驗證路由存在且回傳正確狀態碼
contract.TestRoute(t, r, "GET", "/health", 200)

3.6 Router：傳統路由 vs Schema 路由

兩者可以並存，你不需要一次全部遷移：

// 傳統路由 — 簡單、快速，但 AI 看不到 metadata
r.GET("/health", healthHandler)
r.POST("/webhook", webhookHandler)

// Schema 路由 — 多寫幾行，但 AI 可以理解、Contract 可以驗證
r.Schema(schema.Route{
    Method:  "POST",
    Path:    "/api/users",
    Summary: "建立使用者",
    Input:   CreateUserReq{},
    Output:  UserResp{},
}).Handle(createUserHandler)

什麼時候該用 Schema 路由？

場景	建議
對外 API（供前端或第三方呼叫）	一定要用 Schema
會請 AI 幫忙實作的路由	一定要用 Schema
內部健康檢查、webhook	傳統路由即可
靜態檔案路由	傳統路由即可

第四章：`hyp generate` 在哪些場景有利？

4.1 generate 做了什麼？

hyp generate controller user    → app/controllers/user.go
hyp generate model order        → app/models/order.go
hyp generate service payment    → app/services/payment.go

生成的程式碼不是空殼 — 它自動整合了 HypGo 的慣例：

Controller：包含 router.Schema() 註冊、errors.Define() 錯誤碼定義、CRUD handler 骨架
Model：包含 Bun ORM struct tags（bun:"table:users"）
Service：包含 Error Catalog 整合、介面定義

4.2 generate 有利的場景

場景	為什麼有利	具體效果
專案初期快速搭建	一次生成 5-10 個 CRUD 資源的骨架	省去重複的 boilerplate，幾分鐘就有完整的 API 結構
新成員加入團隊	生成的程式碼就是「範例」	新人一看就知道 Schema 怎麼寫、Error 怎麼定義
AI 互動的起點	生成骨架後讓 AI 填充業務邏輯	AI 有了正確的結構，不會自行發明不符慣例的寫法
保持一致性	所有資源都用相同模板	團隊不會出現「每個人寫法不同」的問題

4.3 generate 不適合的場景

場景	原因	替代方案
複雜的自訂路由邏輯	模板是通用的，無法涵蓋特殊需求	手動寫 Schema + 讓 AI 實作
已有大量既有程式碼	generate 只建立新檔案，不能整合進既有結構	手動添加 Schema 到現有 handler
非 CRUD 的場景（WebSocket、串流）	模板針對 REST CRUD 設計	手動實作

4.4 推薦的 generate 工作流

# 1. 批量生成資源骨架
hyp generate controller user
hyp generate controller product
hyp generate controller order
hyp generate model user
hyp generate model product
hyp generate model order

# 2. 調整 Schema 定義（加入正確的 Input/Output struct）

# 3. 更新 manifest
hyp context -o .hyp/context.yaml

# 4. 告訴 AI：「根據 manifest 中的 schema，實作所有 handler 的業務邏輯」

# 5. 跑 Contract Testing 驗證
go test ./app/controllers/... -v

第五章：日常開發的最佳實踐

5.1 每次開發前

# 確保 manifest 是最新的
hyp context -o .hyp/context.yaml

5.2 修改共用套件前

# 先看影響範圍
hyp impact pkg/errors/catalog.go

# 如果風險是 HIGH，跟團隊討論再改
# 如果風險是 LOW/MEDIUM，改完跑受影響的測試
go test ./pkg/errors/... ./pkg/contract/... -v

5.3 寫完程式碼後

# 檢查註解完整性
hyp chkcomment app/controllers/user.go

# 跑 contract 測試
go test ./app/controllers/... -v

# 如果有 model 變更，生成 migration
hyp migrate diff

5.4 給 AI 下指令的模板

以下是經過驗證的、能讓 AI 產出高品質程式碼的提示模板：

新增功能：

請先讀取 .hyp/context.yaml 了解專案結構。
我需要新增一個 [功能名稱] 功能，
Input 是 [StructName]，Output 是 [StructName]。
請使用 router.Schema() 註冊路由，
用 errors.Define() 定義錯誤碼（從 E[xxxx] 開始），
用 Bun ORM 存取資料庫。

修改現有功能：

請先讀取 .hyp/context.yaml，
然後執行 hyp impact [要修改的檔案] 確認影響範圍。
我需要修改 [路由路徑] 的行為：[具體修改]。
修改完後請跑 contract.TestAll() 確認合約沒有被破壞。

排查問題：

請先讀取 .hyp/context.yaml 了解專案結構，
然後看 [問題相關的檔案]。
問題是：[描述問題]。
請用 hyp impact 確認修復不會影響其他模組。

第六章：常見問題

Q: Schema 和普通的 Go doc comment 有什麼不同？

Go doc comment 是自由文本，AI 需要「理解」自然語言。Schema 是結構化的 Go struct，AI 直接讀取欄位名和型別 — 零歧義。

Q: 我已經有 Swagger/OpenAPI 了，還需要 Schema 嗎？

Swagger 是從程式碼「生成」的文檔，可能與程式碼不同步。HypGo Schema 是路由註冊過程的一部分 — 它不可能不同步，因為它就是路由本身。另外，Schema 直接驅動 Contract Testing，Swagger 做不到。

Q: Contract Testing 能取代單元測試嗎？

不能。Contract Testing 驗證的是「介面合約」（型別對不對、狀態碼對不對）。單元測試驗證的是「業務邏輯」（金額算對沒、邊界條件對不對）。兩者互補，缺一不可。

Q: 我的專案很小（3-5 個路由），值得用 Schema 嗎？

值得。寫 Schema 只多 5 行程式碼，但你得到：

contract.TestAll() 自動驗證（省掉手寫測試的時間）
Manifest 包含完整路由資訊（AI 理解更準確）
隨著專案成長，Schema 的價值會指數級增長

Q: `hyp ai-rules` 生成的檔案需要加入 git 嗎？

建議加入。這樣團隊裡每個人用不同的 AI 工具，都能自動讀到相同的慣例。

速查：完整的人機協作迴圈

      你                        AI                       框架
      │                         │                         │
      ├─ 定義 Struct ──────────→│                         │
      ├─ 寫 Schema 路由 ───────→│                         │
      ├─ hyp context ──────────→├─ 讀 manifest ──────────→│
      │                         ├─ 理解 API 結構           │
      ├─ 描述需求 ─────────────→├─ 生成 Handler ─────────→│
      │                         │                         ├─ Contract 驗證
      │                         │                         ├─ ✅ 通過 → 合併
      │                         │                         └─ ❌ 失敗 → 回饋
      │                         ├─ 修正程式碼 ─────────────→│
      │                         │                         ├─ 再次驗證
      ├─ 審核業務邏輯 ←──────────┤                         │
      ├─ hyp chkcomment ───────→│                         │
      ├─ hyp migrate diff ─────→│                         │
      └─ 完成 ✅                 │                         │

記住：你負責「什麼」（Schema），AI 負責「怎麼做」（Handler），框架負責「對不對」（Contract）。

HypGo · AI-Human Collaborative Development Guide · 2026-03