-
Notifications
You must be signed in to change notification settings - Fork 0
docs\en\harness_en.md
HypGo is a Go framework that practices Harness engineering principles at the application layer. Harness solves "how to deliver." HypGo solves "how to build something worth delivering." Both share the same engineering philosophy — they just operate at different layers.
Harness, as a platform, embodies a set of modern software engineering practices:
| Engineering Practice | Core Idea |
|---|---|
| Contract-first | Define the contract first, implement second, then verify the implementation against the contract |
| Test Intelligence | Tests aren't written by hand — the system knows what to run and when |
| Change Intelligence | Before any change lands, understand its blast radius |
| Developer Portal | One place for developers to understand the entire system's structure |
| AI-Assisted Development | AI helps generate, validate, and explain engineering artifacts |
| Reliability Engineering | System health is always visible; problems are found proactively |
| Database Lifecycle | Schema changes are tracked, auditable, and automatable |
Harness practices this set of principles at the infrastructure layer — pipelines, deployments, monitoring.
HypGo does the same thing at the Go application layer.
Harness Engineering Practice HypGo's Application-Layer Implementation
──────────────────────────────────────────────────────────────────────────
Contract-first → Schema-first routes + Contract Testing
Test Intelligence → contract.TestAll() auto-generates tests
Change Intelligence → hyp impact static analysis
Developer Portal → hyp context / AutoSync Manifest
AI-Assisted Development → hyp ai-rules + Annotation Protocol
Reliability Engineering → /_debug/state diagnostic endpoint
Database Lifecycle → hyp migrate diff SQL auto-generation
Harness engineering and HypGo share a more fundamental design belief:
Automation handles mechanical execution. Human judgment defines what "correct" means.
This isn't "AI replaces humans" — and it isn't "humans supervise machines" either. It's about structurally embedding human business judgment into the system itself, where it becomes the baseline and boundary for all automation.
Harness automation doesn't extend indefinitely. It deliberately preserves human decision-making at a handful of critical checkpoints:
| Decision Point | Why It Stays Human |
|---|---|
| SLO Definition (99.9% vs 99.99%) | Acceptable business risk — only humans can weigh this |
| Feature Flag Control (who gets the rollout) | Commercial strategy — cannot be automated away |
| Deployment Approval Gate | The final human checkpoint before production changes |
| Change Freeze Windows | Which periods are off-limits for deploys — a business call |
| Error Budget Policy | Whether to freeze deploys when budget burns out — a risk preference |
Harness automation executes according to rules humans define. It does not replace humans in defining those rules.
HypGo's division of labor is identical — just applied at the code level:
You (Human) AI Framework
│ │ │
├─ Define Schema ──────→│ │
│ (business contract) │ │
├─ Write @ai:constraint→│ │
│ (business rules) │ │
├─ Define Error Catalog→│ │
│ (error vocabulary) │ │
│ ├─ Generate Handler ─→│
│ │ (mechanical impl) ├─ Contract validation
│ │ │ (does it match your contract?)
←── Review business logic ──────────────────│ ├─ ✅ Pass
│ (intent, not syntax) │ └─ ❌ Feed back to AI
└─ Done ✅ │
Three human decisions, three tools:
| Human Decision | HypGo Tool | Why It Can't Be Automated |
|---|---|---|
| What data goes in and comes out | r.Schema(Input, Output) |
Business data structures — AI cannot determine these from requirements alone |
| What business rules apply | // @ai:constraint max=100 |
Business constraints come from requirements, not inferred from code |
| What the system's error vocabulary is | errors.Define("E1001", 404, ...) |
Error codes carry business semantics — they must be designed, not generated |
These three decisions set the validation standard for Contract Testing, the quality boundary for AI-generated code, and the business language of the entire system. They cannot be automated, because they are the crystallized form of human business judgment.
AI-assisted development often falls into two traps:
- Over-automation: AI infers business intent from scattered code → syntactically correct, semantically wrong
- Over-manual: Developers write everything → slow, repetitive, error-prone
HypGo (and Harness) take a third path: structurally place human judgment at the core, and let automation build around it.
❌ Wrong: Human → AI → Output
(human at the edge, AI as a black box deciding everything)
❌ Wrong: Human → Human → Human
(fully manual, AI has no meaningful role)
✅ HypGo: Human (define contract) → AI (implement) → Framework (verify contract) → Human (review business logic)
The developer's role shifts from "write every line of implementation" to "design every business contract" — less mechanical work, more intentional design.
Harness's Contract-first principle: define the contract between services first, implement second, then verify the implementation matches the contract.
HypGo brings this principle down to the Go API development layer:
// 1. Define the contract (you) r.Schema(schema.Route{ Method: "POST", Path: "/api/orders", Summary: "Create an order", Input: CreateOrderReq{}, // ← contract: requests must look like this Output: OrderResp{}, // ← contract: responses must look like this Responses: map[int]schema.ResponseSchema{ 201: {Description: "Order created"}, }, }).Handle(createOrderHandler) // 2. AI implements the Handler (AI) // 3. Framework automatically validates the contract (framework) contract.TestAll(t, router) // → auto-generates test data, sends requests, validates Input/Output structure // → zero handwritten test cases required
Schema is the contract. Contract Testing is the contract verifier. This is Harness Contract-first implemented directly at the Go framework layer.
Harness Test Intelligence gives the CI system the ability to "know which tests this change requires" — test selection is decided by the system, not by human judgment.
HypGo does the same thing one level earlier: test content is generated by the system, not written by humans.
Harness Test Intelligence:
Analyze diff → decide which tests to run → submit that test set to CI
Key question: which tests need to run?
HypGo contract.TestAll():
Read Schema Registry → auto-generate test data for every route → execute validation
Key question: where do the tests come from?
The two work in sequence, not in conflict:
Harness CI triggers
→ Test Intelligence selects the jobs to run
→ go test runs (including HypGo's auto-generated contract tests)
→ results reported back to Harness
Harness Change Intelligence lets teams trace — after a deployment — which version introduced a problem.
HypGo's hyp impact shifts this capability earlier, to the pre-commit stage, performing static analysis on Go import graphs:
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: code already deployed → what did this version affect?
HypGo hyp impact: before committing → what will this change affect?
Same engineering principle, operating at different points on the timeline.
Harness IDP (Internal Developer Portal) gives developers a single entry point to understand the entire organization's service catalog.
HypGo's Manifest system does the same thing — but for an audience of AI tools:
hyp context # outputs .hyp/context.yaml hyp context -f json # JSON format
# .hyp/context.yaml — AI reads this to understand your project version: "1.0" framework: HypGo server: addr: ":8080" protocol: http2 routes: - method: POST path: /api/users summary: "Create a user" input_type: CreateUserRequest output_type: UserResponse handler_names: ["controllers.(*UserController).Create"]
AutoSync keeps context.yaml in sync with code every time the server starts — no manual maintenance required.
Harness IDP: helps human developers understand "what services exist across the org"
HypGo Manifest: helps AI understand "what this Go project's API structure looks like"
The two can integrate: HypGo Manifest becomes the API metadata source for a single service within Harness IDP.
Harness AIDA enables AI to understand Harness Pipelines — helping generate and debug Pipeline YAML.
HypGo's AI collaboration toolchain enables AI tools (Claude, Cursor, Copilot) to understand your Go project conventions:
hyp ai-rules # generates: # CLAUDE.md ← Claude Code config # .cursorrules ← Cursor config # .github/copilot-instructions.md ← GitHub Copilot config # .continue/config.json # .aider.conf.yml
The Annotation Protocol additionally embeds business constraints directly in code — AI reads the annotations and understands the rules without having to infer them from implementation:
// @ai:constraint max_items=100 // @ai:security requires_auth // @ai:deprecated use CreateOrderV2 instead func CreateOrder(c *context.Context) { // ... }
Harness AIDA: helps AI work with the Harness platform
HypGo AI toolchain: helps AI work on your Go application
Harness SRM (Service Reliability Management) tracks SLOs and Error Budgets in production, surfacing problems before they affect users.
HypGo's diagnostic endpoint brings the "system state always visible" principle into the development and debugging phase:
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 }
}One request, and AI has a complete system snapshot — no need to comb through logs.
Harness SRM: production → SLO monitoring, Error Budget, alerts
HypGo diagnostic endpoint: development/debugging → single-shot snapshot, AI-readable system state
Harness DB DevOps integrates with Liquibase and Flyway to track migration history, binding database changes to deployments — safe, auditable, and reversible.
HypGo addresses the earliest stage of that chain: automatically deriving which SQL changes are needed from Go Model struct definitions:
# Developer adds two fields to the 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 # save snapshot as the baseline for the next diff
HypGo hyp migrate diff: Go struct → generates SQL migration script
Harness DB DevOps: SQL migration → safely deployed to production
HypGo's output is Harness DB DevOps's input.
┌──────────────────────────────────────────────────────────┐
│ Harness Platform Layer │
│ │
│ CI Pipeline → CD Deploy → SRM Monitor → Feature Flags │
│ │
│ Test Intelligence Change Intelligence DB DevOps │
└──────────────────────────┬───────────────────────────────┘
│ go test / SQL / Docker image
┌──────────────────────────▼───────────────────────────────┐
│ HypGo Application Layer │
│ │
│ Schema-first routes Contract Testing │
│ hyp context hyp ai-rules │
│ hyp impact hyp migrate diff │
│ /_debug/state Annotation Protocol │
│ │
│ → Makes the code entering the Harness Pipeline │
│ reliable in the first place │
└──────────────────────────────────────────────────────────┘
Harness engineering presupposes: the code entering the pipeline must already be high quality. HypGo owns that layer.
Developer
├─ Define Schema (the contract)
├─ hyp context → AI reads manifest, understands the project
├─ AI generates Handler
├─ contract.TestAll() → contract validation passes
├─ hyp impact → blast radius confirmed acceptable
├─ hyp migrate diff → SQL migration generated
└─ git push
Harness Pipeline
├─ Test Intelligence: selects which test jobs to run
├─ go test (including contract.TestAll): contract validation
├─ STO: security scanning
├─ DB DevOps: executes migration SQL
├─ CD: Blue/Green deployment
└─ SRM: SLO monitoring, confirms new version is stable
HypGo is not a Harness competitor, and not merely a Harness complement — it is the concrete method for practicing Harness engineering principles inside your Go application code.
| Harness Engineering Practice | Harness Platform Does | HypGo Framework Does |
|---|---|---|
| Human Inside | SLO / Approval Gates / Feature Flags | Schema / @ai:constraint / Error Catalog |
| Contract-first | Pipeline contract validation | Schema + Contract Testing |
| Test Intelligence | CI smart test selection | Auto-generated test data |
| Change Intelligence | Post-deploy impact tracing | Pre-commit static impact analysis |
| Developer Portal | IDP service catalog | AI-readable Manifest |
| AI Assistance | AIDA Pipeline assistance | ai-rules + Annotation Protocol |
| Reliability | SRM / SLO monitoring | Diagnostic endpoint snapshot |
| DB Lifecycle | DB DevOps deployment | struct → SQL auto-generation |
If you believe in Harness's engineering philosophy, HypGo is the way to bring that philosophy into your Go code.
Both keep humans at the critical decision points and let automation do the rest.
HypGo · v0.8.5 · harness_en.md
設計文件
套件
- config — 設定
- context — 請求上下文
- router — 路由器
- server — 伺服器
- middleware — 中介層
- websocket — WebSocket
- hidb — 資料庫 ORM
- hidb/cassandra — Cassandra
- logger — 日誌
- json — JSON 處理
- grpc — gRPC
AI 協作工具鏈
- schema — Schema-first 路由
- manifest — 專案 Manifest
- contract — Contract Testing
- errors — Typed Error Catalog
- migrate — Migration Diff
- scaffold — 智慧 Scaffold
- airules — AI Rules
CLI 命令
- hyp 總覽
- hyp new
- hyp api
- hyp run
- hyp restart
- hyp generate
- hyp migrate
- hyp context
- hyp ai-rules
- hyp chkcomment
- hyp impact
- hyp docker
- hyp health
- hyp version
- hyp difflog
Design Docs
Packages
- config — Configuration
- context — Request Context
- router — Router
- server — Server
- middleware — Middleware
- websocket — WebSocket
- hidb — Database ORM
- hidb/cassandra - Cassandra 5.0
- logger — Logger
- json — JSON
- grpc — gRPC
AI Collaboration Toolchain
- schema — Schema-first Routing
- manifest — Project Manifest
- contract — Contract Testing
- errors — Typed Error Catalog
- migrate — Migration Diff
- scaffold — Smart Scaffold
- airules — AI Rules
CLI Commands