-
Notifications
You must be signed in to change notification settings - Fork 0
airules_en.md
v0.8.5+This package is a new feature added in HypGo v0.8.5 and is not available in v0.8.1.
Automatically generates configuration files for mainstream AI coding tools, enabling Codex, Gemini, Cursor, Windsurf, GitHub Copilot, and other tools to immediately understand framework conventions when opening a HypGo project, saving significant tokens.
Each AI coding tool has its own project configuration file format:
| Tool | Configuration File |
|---|---|
| Codex CLI / Cursor / Aider / OpenHands | AGENTS.md |
| Google Gemini CLI / AI Studio | GEMINI.md |
| GitHub Copilot | .github/copilot-instructions.md |
| Cursor (new format) | .cursor/rules/*.mdc |
| Windsurf | .windsurf/rules/*.md |
Without these files, AI tools start from scratch understanding your project every time -- they don't know to use router.Schema() to register routes, don't know about the Error Catalog, and don't know they can use contract.TestAll() for validation.
hyp ai-rules generates all configuration files with one command, with unified content and automatic maintenance.
# Generate all AI tool configuration files hyp ai-rules # Generate only specific tool configuration files hyp ai-rules --only agents,gemini # Preview without writing (dry-run) hyp ai-rules --dry-run # Specify project root directory hyp ai-rules --dir ./myproject
import ( "github.com/maoxiaoyue/hypgo/pkg/airules" "github.com/maoxiaoyue/hypgo/pkg/manifest" ) // Prepare manifest (can be nil, static conventions will still be generated) m := &manifest.Manifest{ Routes: []manifest.RouteManifest{ {Method: "POST", Path: "/api/users", Summary: "Create user"}, }, } // Generate all configuration files in the project root directory targets := airules.AllTargets() results, err := airules.GenerateAll(".", targets, m, false) // Generate only specific tools targets = airules.FilterTargets(airules.AllTargets(), "agents,gemini") results, err = airules.GenerateAll(".", targets, m, false)
Placed in the project root directory. Supported by the most tools (Codex CLI, Cursor, Continue.dev, Aider, OpenHands).
AGENTS.md
├── Framework Framework name, version, Go version
├── Project Structure Directory structure description
├── Key Conventions Schema-first / Typed Errors / Contract Testing
├── Build & Test go build / go test commands
├── AI Collaboration Read .hyp/context.yaml first, hyp impact, hyp chkcomment
└── Current Routes Route table dynamically injected from manifest (if available)
Same format as AGENTS.md, placed in the project root directory. Natively read by Google Gemini CLI and AI Studio.
Same format as AGENTS.md, placed in the .github/ directory. Read by GitHub Copilot (VS Code, JetBrains).
Cursor new format, with frontmatter:
--- description: HypGo framework conventions and AI collaboration rules globs: "**/*.go" alwaysApply: true ---
alwaysApply: true ensures the rules are loaded every time a Go file is opened.
Windsurf format. Content is the same as other tools, but automatically kept within 6,000 characters (Windsurf single-file limit). Route tables are truncated when exceeded.
If .hyp/context.yaml exists in the project root directory (generated by hyp context or AutoSync), hyp ai-rules reads route information from it and injects it into configuration files:
## Current Routes | Method | Path | Summary | |--------|------|---------| | GET | /health | Health check | | POST | /api/users | Create user | | GET | /api/users/:id | Get user by ID |
This lets AI tools know not only framework conventions, but also which APIs the project currently has.
Recommended workflow:
# 1. Generate manifest first hyp context -o .hyp/context.yaml # 2. Then generate AI configuration files (will include route information) hyp ai-rules
All auto-generated files contain a marker:
<!-- auto-generated by hyp ai-rules -->Overwrite rules:
| File Status | Behavior |
|---|---|
| Does not exist | Create new file |
| Exists with marker | Overwrite (update content) |
| Exists without marker | Skip (protect manually modified version) |
If you manually created AGENTS.md and want hyp ai-rules to take over, simply add <!-- auto-generated by hyp ai-rules --> at the beginning of the file.
func AllTargets() []Target
Returns all supported AI tool configuration file targets (5 total).
func FilterTargets(targets []Target, names string) []Target
Filters targets by comma-separated names. Empty string means all.
Available names: agents, gemini, copilot, cursor, windsurf
func GenerateAll(dir string, targets []Target, m *manifest.Manifest, dryRun bool) ([]Result, error)
Generates configuration files in the specified directory. m can be nil (only static conventions are generated). When dryRun is true, files are not written and Result contains preview content.
type Result struct { Path string // File path Status Status // created / skipped / dry-run / error Message string // Error or skip reason Content string // Preview content during dry-run }
hyp context -> Generates .hyp/context.yaml (project structure manifest)
hyp ai-rules -> Reads manifest + generates AI tool configuration files
|
AGENTS.md / GEMINI.md / copilot-instructions.md / .cursor / .windsurf
|
AI tool opens project -> Immediately knows HypGo conventions -> Saves tokens
CLAUDE.md is not in the generation scope (maintained manually by the user), but Claude Code also reads AGENTS.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