人機協作開發實戰指南

寫給開發者的話

第一章:從哪裡開始?先做什麼?

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

# 純 API 專案(推薦起手)
hyp api myservice && cd myservice && go mod tidy
# 全棧專案(含前端模板)
hyp new myapp && cd myapp && go mod tidy

1.2 第二件事:寫好 Schema,而不是 Handler

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

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

# 生成專案快照(AI 的「地圖」)
hyp context -o .hyp/context.yaml
# 生成所有 AI 工具的配置檔
hyp ai-rules

1.4 命令執行順序速查表

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

第二章:如何開始一個新功能?

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

步驟一:定義 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 存取資料庫。

步驟四:驗證(自動)

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

2.2 為什麼是這個順序?

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

第三章:Schema、Manifest、Router、Contract — 誰最重要?

3.1 四者的關係圖

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

3.2 重要性排名

3.3 Schema:怎麼寫好?

必填欄位

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 品質檢查清單

3.4 Manifest:怎麼寫?

# 方法一:手動生成
hyp context -o .hyp/context.yaml
# 方法二:自動生成(Server.Start() 時 AutoSync 會寫入 .hyp/context.yaml)
hyp run

3.5 Contract:怎麼寫?

最簡單的用法(推薦起手)

func TestAllContracts(t *testing.T) {
 // 建立你的 router(含所有 Schema 路由)
 r := setupRouter()
 // 一行測試所有 schema 路由
 contract.TestAll(t, r)
}

手動測試特定路由

contract.Test(t, r, contract.TestCase{
 Route: "POST /api/users",
 Input: `{"name":"alice","email":"alice@example.com"}`,
 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)

第四章: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

4.2 generate 有利的場景

4.3 generate 不適合的場景

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 下指令的模板

請先讀取 .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 有什麼不同?

Q: 我已經有 Swagger/OpenAPI 了,還需要 Schema 嗎?

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

Q: 我的專案很小(3-5 個路由),值得用 Schema 嗎?

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

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

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