Skip to content

harness.md

Jump to bottom
maoxiaoyue edited this page May 22, 2026 · 1 revision

HypGo 與 Harness 工程

HypGo 是一個在 Go 應用層實踐 Harness 工程理念的框架。 Harness 解決「如何交付」，HypGo 解決「如何開發出值得交付的東西」——兩者共用同一套工程哲學，只是作用的層級不同。

什麼是 Harness 工程？

Harness 作為一個平台，體現了一套現代軟體工程實踐：

工程實踐 核心理念
Contract-first 先定義合約，再實作，驗證實作是否符合合約
Test Intelligence 測試不靠人寫，系統自動知道要跑哪些、怎麼跑
Change Intelligence 任何改動前，先知道影響範圍
Developer Portal 讓開發者在一個地方理解整個系統的結構
AI-Assisted Development AI 輔助生成、驗證、解釋工程產物
Reliability Engineering 系統健康狀態隨時可見，主動發現問題
Database Lifecycle 資料庫 schema 變更可追蹤、可自動化

Harness 平台在基礎設施層（Pipeline、部署、監控）實踐這套理念。
HypGo 在 Go 應用層做同樣一件事。

HypGo 實踐了哪些 Harness 工程

Harness 工程實踐              HypGo 的應用層實作
─────────────────────────────────────────────────────
Contract-first          →    Schema-first 路由 + Contract Testing
Test Intelligence       →    contract.TestAll() 自動生成測試
Change Intelligence     →    hyp impact 靜態影響分析
Developer Portal        →    hyp context / AutoSync Manifest
AI-Assisted Development →    hyp ai-rules + Annotation Protocol
Reliability Engineering →    /_debug/state 診斷端點
Database Lifecycle      →    hyp migrate diff SQL 自動生成

Human Inside — 自動化的前提是人的判斷

Harness 工程與 HypGo 共用一個更根本的設計信念：

自動化負責執行機械性工作，人類判斷負責定義「什麼才算對」。

這不是「AI 取代人」，也不是「人工監控機器」——而是人的業務判斷被結構化地嵌入系統之中，成為自動化流程的基準與邊界。

在 Harness 平台層

Harness 的自動化不會無限延伸——它在幾個關鍵點刻意留給人決策：

決策點 為什麼是人？
SLO 定義（99.9% vs 99.99%） 業務可接受的風險，只有人知道
Feature Flag 控制（推出給哪些用戶） 商業策略判斷，不能自動化
Deployment Approval Gate 生產環境變更的最後把關
Change Freeze Window 哪些時段不能部署，由業務決定
Error Budget Policy 燒完 budget 要不要停止部署，是風險偏好

Harness 自動化做的是「按照人定義的規則執行」，不是「代替人定規則」。

在 HypGo 應用層

HypGo 的分工方式完全相同，只是作用在程式碼層級：

      你（人）                AI                  框架
       │                      │                    │
       ├─ 定義 Schema ────────→│                    │
       │  （業務合約）          │                    │
       ├─ 寫 @ai:constraint ──→│                    │
       │  （業務規則）          │                    │
       ├─ 定義 Error Catalog ─→│                    │
       │  （錯誤語言）          │                    │
       │                      ├─ 生成 Handler ─────→│
       │                      │  （機械實作）        ├─ Contract 驗證
       │                      │                    │  （符合人定的合約？）
       ←──── 審閱業務邏輯 ──────┤                    ├─ ✅ 通過
       │  （不是語法，是意圖）   │                    └─ ❌ 回饋 AI 修正
       └─ Done ✅              │

人決策的三件事，對應三個工具：

人的決策 HypGo 工具 說明
這個 API 的輸入/輸出長什麼樣 r.Schema(Input, Output) 業務資料結構，AI 無法自行決定
這個 API 有哪些業務規則 // @ai:constraint max=100 業務約束，從需求文件來，不從程式碼推導
系統的錯誤語言是什麼 errors.Define("E1001", 404, ...) 錯誤碼代表業務語意，必須人工設計

這三件事決定了 Contract Testing 的驗證標準、AI 生成程式碼的品質邊界，以及整個系統的業務語言。它們不能被自動化，因為它們本身就是業務判斷的結晶。

為什麼叫 Human Inside？

傳統的「AI 輔助開發」容易落入兩個極端：

  • 過度自動化：AI 從散落的程式碼推斷業務意圖 → 語法正確，業務錯誤
  • 過度手動：開發者什麼都寫 → 速度慢，重複工作多

HypGo（和 Harness）選擇第三條路：把人的判斷結構化地放在系統的核心位置，讓自動化圍繞它展開。

❌ 錯誤模式：Human → AI → 產出（人在最外層，AI 黑盒決定一切）
❌ 錯誤模式：Human → Human → Human（完全手動，AI 沒有用武之地）
✅ HypGo 模式：Human（定義合約）→ AI（實作）→ 框架（驗證合約）→ Human（審閱業務邏輯）

開發者從「寫每一行實作」升級為「定義每一個業務合約」——更少的機械工作，更多的業務設計。

逐項說明

Contract-first → Schema-first + Contract Testing

Harness 的 Contract-first 理念是：先定義服務間的合約，再實作，驗證實作符合合約。

HypGo 把這個理念落地到 Go 的 API 開發層：

// 1. 先定義合約（你）
r.Schema(schema.Route{
    Method:  "POST",
    Path:    "/api/orders",
    Summary: "建立訂單",
    Input:   CreateOrderReq{},    // ← 合約：請求必須長這樣
    Output:  OrderResp{},         // ← 合約：回應必須長這樣
    Responses: map[int]schema.ResponseSchema{
        201: {Description: "Order created"},
    },
}).Handle(createOrderHandler)

// 2. AI 實作 Handler（AI）

// 3. 框架自動驗證合約（框架）
contract.TestAll(t, router)
// → 自動生成測試資料、發送請求、驗證 Input/Output 結構
// → 不需要手寫任何測試 case

Schema 就是合約。Contract Testing 就是合約驗證器。這是 Harness Contract-first 在 Go 框架層的直接實作。

Test Intelligence → contract.TestAll()

Harness Test Intelligence 讓 CI 系統「知道這次變更需要跑哪些測試」，測試選擇由系統決定，不靠人工判斷。

HypGo 在更早的一個層次做同樣的事：測試內容由系統生成，不靠人工撰寫。

Harness Test Intelligence：
  分析 diff → 決定跑哪些測試 → 提交這批測試給 CI 執行
  重點：哪些測試要跑？

HypGo contract.TestAll()：
  讀 Schema Registry → 自動生成每條路由的測試資料 → 執行驗證
  重點：測試從哪裡來？

兩者不衝突，而是串聯：

Harness CI 觸發
  → 用 Test Intelligence 選出需要跑的 job
    → 跑 go test（內含 HypGo 自動生成的 contract 測試）
      → 結果回報給 Harness

Change Intelligence → hyp impact

Harness Change Intelligence 讓團隊在部署後知道「哪個版本帶入了問題」。

HypGo 的 hyp impact 把這個能力前移到提交前，在靜態分析層做 Go 程式碼的影響範圍計算：

hyp impact pkg/contract/validate.go

# Impact Analysis: pkg/contract/validate.go
# Package: pkg/contract
#
# Direct dependents (import this package):
#   → pkg/errors
#   → pkg/scaffold
#
# Affected tests:
#   → pkg/contract/*_test.go  (24 tests)
#   → pkg/errors/*_test.go    (19 tests)
#   Total: 43 tests
#
# Risk: MEDIUM (2 packages depend on this)
Harness Change Intelligence：程式碼已部署 → 這個版本的變更影響了什麼？
HypGo hyp impact：          程式碼提交前 → 這個改動會波及哪些地方？

同一個工程理念，作用在不同的時間軸上。

Developer Portal → hyp context / AutoSync

Harness IDP（Internal Developer Portal）讓開發者用一個入口理解整個組織的服務目錄。

HypGo 的 Manifest 系統做同一件事，但目標受眾是 AI：

hyp context             # 輸出 .hyp/context.yaml
hyp context -f json     # JSON 格式
# .hyp/context.yaml — AI 讀這個來理解你的專案
version: "1.0"
framework: HypGo
server:
  addr: ":8080"
  protocol: http2
routes:
  - method: POST
    path: /api/users
    summary: "建立使用者"
    input_type: CreateUserRequest
    output_type: UserResponse
    handler_names: ["controllers.(*UserController).Create"]

Server 啟動時自動同步（AutoSync），context.yaml 永遠與程式碼一致。

Harness IDP：讓人類開發者理解「整個組織有哪些服務」
HypGo Manifest：讓 AI 理解「這個 Go 專案的 API 結構」

兩者可以整合：HypGo Manifest 作為 Harness IDP 中單一服務的 API 元資料來源。

AI-Assisted Development → hyp ai-rules + Annotation Protocol

Harness AIDA 讓 AI 能理解 Harness Pipeline，幫助生成和除錯 Pipeline YAML。

HypGo 的 AI 協作工具讓各種 AI 工具（Claude、Cursor、Copilot）能理解你的 Go 專案慣例：

hyp ai-rules
# 生成：
# CLAUDE.md           ← Claude Code 設定
# .cursorrules        ← Cursor 設定
# .github/copilot-instructions.md
# .continue/config.json
# .aider.conf.yml

同時，Annotation Protocol 讓業務約束直接寫在程式碼中，AI 讀註解就能理解限制：

// @ai:constraint max_items=100
// @ai:security requires_auth
// @ai:deprecated use CreateOrderV2 instead
func CreateOrder(c *context.Context) {
    // ...
}
Harness AIDA：讓 AI 幫你用 Harness 平台
HypGo AI 工具：讓 AI 幫你開發 Go 應用

Reliability Engineering → /_debug/state

Harness SRM（Service Reliability Management）在生產環境追蹤 SLO、Error Budget，讓問題在影響到使用者之前被發現。

HypGo 的診斷端點把「系統狀態可見」的理念帶進開發與除錯階段：

GET /_debug/state
Authorization: Bearer <token>
{
  "goroutines": 42,
  "memory": { "alloc_mb": 18.3, "gc_cycles": 7 },
  "routes": [
    { "method": "POST", "path": "/api/users", "schema": true }
  ],
  "redis": { "connected": true, "latency_ms": 1.2 },
  "db": { "master": "ok", "replicas": 2 }
}

一個請求，AI 就能取得完整的系統快照，不需要到處翻 log。

Harness SRM：生產環境 → SLO 監控、Error Budget、告警
HypGo 診斷端點：開發 / 除錯 → 單次快照、AI 可讀的系統狀態

Database Lifecycle → hyp migrate diff

Harness DB DevOps 整合 Liquibase / Flyway，讓資料庫變更與 deployment 綁定、可追蹤、可回滾。

HypGo 解決這條鏈上的最前端問題：從 Go Model struct 自動推導出需要哪些 SQL 變更：

# 開發者修改了 User struct，加了兩個欄位
hyp migrate diff

# 輸出：
# [up]
# ALTER TABLE "users" ADD COLUMN "bio" TEXT;
# ALTER TABLE "users" ADD COLUMN "avatar_url" TEXT;
#
# [down]
# ALTER TABLE "users" DROP COLUMN "bio";
# ALTER TABLE "users" DROP COLUMN "avatar_url";

hyp migrate snapshot    # 儲存快照，作為下次 diff 的基準
HypGo hyp migrate diff：Go struct → 生成 SQL migration 腳本
Harness DB DevOps：      SQL migration → 安全部署到生產環境

HypGo 的輸出是 Harness DB DevOps 的輸入。

層級分工

┌─────────────────────────────────────────────────────┐
│                   Harness 平台層                      │
│                                                     │
│  CI Pipeline  →  CD 部署  →  SRM 監控  →  Feature Flags │
│                                                     │
│  Test Intelligence   Change Intelligence   DB DevOps │
└─────────────────────────┬───────────────────────────┘
                          │ go test / SQL / Docker image
┌─────────────────────────▼───────────────────────────┐
│                   HypGo 應用框架層                    │
│                                                     │
│  Schema-first 路由    Contract Testing               │
│  hyp context          hyp ai-rules                  │
│  hyp impact           hyp migrate diff              │
│  /_debug/state        Annotation Protocol           │
│                                                     │
│  → 讓「進入 Harness Pipeline 的程式碼」本身更可靠     │
└─────────────────────────────────────────────────────┘

Harness 工程的前提是：進入 Pipeline 的程式碼本身必須是高品質的。HypGo 負責這一層。

整合流程

開發者
  ├─ 定義 Schema（合約）
  ├─ hyp context → AI 讀 manifest 理解專案
  ├─ AI 生成 Handler
  ├─ contract.TestAll() → 合約驗證通過
  ├─ hyp impact → 確認影響範圍可接受
  ├─ hyp migrate diff → 生成 SQL migration
  └─ git push

Harness Pipeline
  ├─ Test Intelligence：選出需要跑的測試 job
  ├─ go test（含 contract.TestAll）：合約驗證
  ├─ STO：Security 掃描
  ├─ DB DevOps：執行 migration SQL
  ├─ CD：Blue/Green 部署
  └─ SRM：SLO 監控，確認新版本穩定

摘要

HypGo 不是 Harness 的競品，也不只是 Harness 的補充工具——HypGo 是在 Go 應用框架層實踐 Harness 工程理念的具體方法。

Harness 工程實踐 Harness 平台做法 HypGo 框架做法
Human Inside SLO / Approval Gate / Feature Flag Schema / @ai:constraint / Error Catalog
Contract-first Pipeline 合約驗證 Schema + Contract Testing
Test Intelligence CI 智慧選測試 自動生成測試資料
Change Intelligence 部署後影響追蹤 提交前靜態影響分析
Developer Portal IDP 服務目錄 AI-readable Manifest
AI Assistance AIDA Pipeline 輔助 ai-rules + Annotation
Reliability SRM / SLO 監控 診斷端點快照
DB Lifecycle DB DevOps 部署 struct → SQL 自動生成

如果你認同 Harness 的工程哲學，HypGo 就是把這套哲學帶進你的 Go 程式碼的方式。
兩者都把人放在最關鍵的決策點上，讓自動化做剩下的事。

HypGo · v0.8.5 · harness.md

由 台灣卯小月 用 ❤️ 製作 · MIT License And Wiki is written by Claude

HypGo

繁體中文 | English

中文文件

設計文件

套件

AI 協作工具鏈

CLI 命令

English Docs

Design Docs

Packages

AI Collaboration Toolchain

CLI Commands

Clone this wiki locally