theory_en.md - maoxiaoyue/hypgo GitHub Wiki

AI-Human Collaborative Design Patterns: Theory and Vision

HypGo Framework โ€” AI-Human Collaborative Design Patterns Version: 0.8.1 | March 2026

Introduction

This document is not a user manual. It is a design philosophy. It records the design patterns that emerged as HypGo evolved into an AI-human collaborative framework, the theoretical reasoning behind them, and a vision for the future of software development.

We believe: the role of frameworks is changing. Frameworks used to serve one audience: developers who write code. Now they must simultaneously serve developers who write code and AI that understands code. This is not about adding AI features โ€” it is about fundamentally rethinking the information architecture of a framework.

Part I: Problem Definition

1.1 The Bottleneck Is Context, Not Intelligence

Modern LLMs can write high-quality code. But in real projects, the primary obstacle is not "can't write" but "doesn't know what to write." Specifically:

Context Acquisition Cost: Every AI interaction consumes tokens to understand project structure. A mid-size Go project (50 files, 10,000 lines) may require 5,000-15,000 tokens just to understand the API surface โ€” tokens spent on comprehension, not production.

Context Quality: Even after reading all files, inferring complete API behavior from scattered handler functions is a lossy process. AI may miss middleware side effects, misunderstand naming conventions, or not know about business-level constraints.

Validation Gap: AI generates code โ€” how do you know it's correct? Traditional flow relies on human code review, which requires understanding both "what AI should have done" and "what AI actually did."

1.2 Redefining Framework Responsibilities

Traditional: Developer โ†’ writes code โ†’ framework executes

AI era: AI understands project โ†’ AI generates code โ†’ framework validates โ†’ developer reviews

The framework is no longer just an "execution engine." It is simultaneously:

  1. Information provider โ€” helps AI understand the project quickly
  2. Contract definer โ€” defines what "correct" means
  3. Validation executor โ€” automatically checks AI output

Part II: Six Design Patterns

Pattern 1: Metadata-First Registration

Problem: Traditional route registration only records path-to-function mapping. AI must read entire handler implementations to understand behavior.

Solution: Route registration carries structured metadata describing route semantics.

Principle: Declarative over inferential. Explicit Input/Output types instead of AI guessing from code. Non-invasive โ€” schema routes coexist with traditional routes.

Theory: Inverts the Swagger approach. Swagger generates docs from code (code-first, may desync). HypGo defines contracts at registration time (schema-first, cannot desync).

Pattern 2: Project Manifest

Problem: AI re-explores project structure every conversation, consuming massive tokens.

Solution: Framework auto-generates a machine-readable project snapshot. AI reads one file to understand everything.

Theory: Manifest is a "compressed representation" of the project. 50 routes may have 10,000 lines of handler code (~30,000 tokens), but the manifest is ~200 lines (~600 tokens). Compression ratio ~50:1. This is not lossy โ€” the manifest contains all structural information AI needs for correct decisions.

Pattern 3: Contract-Driven Validation

Problem: How to automatically verify AI-generated handlers meet expectations?

Solution: Schema doubles as executable contract. Framework validates handlers against schema automatically.

Theory: Applies Contract Testing (like Pact for microservices) to the AI-human interface. Schema is the "contract" between AI and handler. Key insight: AI doesn't need to guarantee "internal logic is correct" (that's the human's job) โ€” it only needs to guarantee "interface matches contract" (types and status codes). Contract Testing verifies exactly this.

Pattern 4: Structural Annotation

Problem: Code comments are free text. AI cannot reliably extract structured constraints.

Solution: Standardized // @ai: prefix annotations that AI can parse directly.

Theory: Borrows from Java Annotations and Python Decorators, but deliberately uses comments (not code). Removing all @ai: annotations has zero effect on program behavior โ€” they are progressive, non-invasive, and cross-language portable.

Pattern 5: Impact-Aware Modification

Problem: AI modifying a file doesn't know how many downstream modules are affected.

Solution: Framework provides import graph analysis. Before modifying, show impact scope with quantified risk levels.

Theory: Change Impact Analysis has decades of software engineering history. HypGo integrates it into AI workflow: AI runs hyp impact before modifying, uses risk level to decide between "modify directly" or "ask human first."

Pattern 6: Zero-Cost Abstraction for AI

Problem: Will AI collaboration features slow down production?

Solution: All AI collaboration mechanisms execute at startup or during development, never on the request hot path.

Theory: Borrows C++'s "zero-cost abstraction" philosophy. If you don't use Schema(), route performance is identical to traditional frameworks. If you use Schema(), per-request performance is still identical โ€” metadata is only accessed at startup and during testing.

Part III: Closed-Loop Architecture

The six patterns form a closed loop:

Schema-first Registration
    โ†’ Manifest Auto-Generation โ†’ AI Reads
        โ†’ AI Understands Project โ†’ AI Generates Code
            โ†’ Contract Testing Validates
                โ†’ Pass: merge
                โ†’ Fail: AI fixes โ†’ Impact Analysis โ†’ back to start

Key properties: Automated (no human intervention from schema to validation), incremental (only process changes), traceable (every failure has clear upstream cause).

Part IV: Relationship to Existing Methodologies

TDD: Contract Testing complements TDD. Contracts verify "interface correctness" (types, status codes). TDD verifies "business logic correctness" (calculations, edge cases). They are complementary.

DDD: Schema-first routes and Typed Error Catalog share DDD's Ubiquitous Language concept. Difference: DDD serves team communication; HypGo serves AI-human communication. Both can unify โ€” a good Schema definition is simultaneously good DDD language.

Design by Contract (Meyer, 1986): HypGo's Contract Testing is its modern AI-context implementation. Precondition = Input Schema. Postcondition = Output Schema + Status Code. Invariant = @ai:constraint annotations.

Part V: Future Vision

From "AI-Assisted" to "AI-Led"

Current: Human decides what โ†’ AI executes โ†’ Human verifies. Next: AI proposes โ†’ Human reviews โ†’ AI executes. Frameworks need "intent inference" capabilities โ€” Tags for business module detection, @ai:owner for responsibility, Impact risk levels for auto-deciding human confirmation needs.

Cross-Project Knowledge Transfer

Manifest format is standardized. An AI that understands Project A's manifest can understand Project B's at near-zero cost. AI can transfer "architectural knowledge" between projects.

Adaptive Security Levels

Future: Framework auto-selects middleware chains based on @ai:security annotations โ€” public routes skip auth, authenticated routes require JWT, admin routes require JWT + role check. No manual middleware configuration.

Conclusion

HypGo's collaborative design patterns are not "AI features" โ€” they are a redesign of information architecture.

The core insight: code is for machines to execute, but the cost of understanding code is borne by humans (and AI). Frameworks can reduce this understanding cost by placing structured metadata alongside code.

The six patterns' essence:

  1. Metadata-First โ€” reduces comprehension cost
  2. Manifest โ€” reduces exploration cost
  3. Contract โ€” reduces validation cost
  4. Annotation โ€” reduces constraint discovery cost
  5. Impact โ€” reduces risk assessment cost
  6. Zero-Cost โ€” none of the above increases runtime cost

When all six costs approach zero, AI-human collaboration transitions from "AI helps you write code" to humans and AI jointly maintaining a continuously evolving system.

HypGo ยท AI-Human Collaborative Design Patterns ยท March 2026