-
Notifications
You must be signed in to change notification settings - Fork 0
airules.md
v0.8.5+此套件為 HypGo v0.8.5 新增功能,v0.8.1 版本不包含。
自動生成主流 AI 編碼工具的配置檔,讓 Codex、Gemini、Cursor、Windsurf、GitHub Copilot 等工具在開啟 HypGo 專案時,立刻理解框架慣例,省下大量 token。
每個 AI 編碼工具都有自己的專案配置檔格式:
| 工具 | 配置檔 |
|---|---|
| Codex CLI / Cursor / Aider / OpenHands | AGENTS.md |
| Google Gemini CLI / AI Studio | GEMINI.md |
| GitHub Copilot | .github/copilot-instructions.md |
| Cursor(新格式) | .cursor/rules/*.mdc |
| Windsurf | .windsurf/rules/*.md |
沒有這些檔案時,AI 工具每次都從零開始理解你的專案 — 不知道要用 router.Schema() 註冊路由、不知道有 Error Catalog、不知道可以用 contract.TestAll() 驗證。
hyp ai-rules 一鍵生成所有配置檔,內容統一、自動維護。
# 生成所有 AI 工具配置檔 hyp ai-rules # 只生成特定工具的配置檔 hyp ai-rules --only agents,gemini # 預覽不寫入(dry-run) hyp ai-rules --dry-run # 指定專案根目錄 hyp ai-rules --dir ./myproject
import ( "github.com/maoxiaoyue/hypgo/pkg/airules" "github.com/maoxiaoyue/hypgo/pkg/manifest" ) // 準備 manifest(可為 nil,靜態慣例仍會生成) m := &manifest.Manifest{ Routes: []manifest.RouteManifest{ {Method: "POST", Path: "/api/users", Summary: "Create user"}, }, } // 生成所有配置檔到專案根目錄 targets := airules.AllTargets() results, err := airules.GenerateAll(".", targets, m, false) // 只生成特定工具 targets = airules.FilterTargets(airules.AllTargets(), "agents,gemini") results, err = airules.GenerateAll(".", targets, m, false)
放在專案根目錄。被最多工具支援(Codex CLI、Cursor、Continue.dev、Aider、OpenHands)。
AGENTS.md
├── Framework 框架名稱、版本、Go 版本
├── Project Structure 目錄結構說明
├── Key Conventions Schema-first / Typed Errors / Contract Testing
├── Build & Test go build / go test 指令
├── AI Collaboration 先讀 .hyp/context.yaml、hyp impact、hyp chkcomment
└── Current Routes 從 manifest 動態注入的路由表(如有)
格式與 AGENTS.md 相同,放在專案根目錄。Google Gemini CLI 和 AI Studio 原生讀取。
格式與 AGENTS.md 相同,放在 .github/ 目錄下。GitHub Copilot(VS Code、JetBrains)讀取。
Cursor 新格式,含 frontmatter:
--- description: HypGo framework conventions and AI collaboration rules globs: "**/*.go" alwaysApply: true ---
alwaysApply: true 確保每次開啟 Go 檔案時都會載入規則。
Windsurf 格式。內容與其他工具相同,但自動控制在 6,000 字元以內(Windsurf 單檔限制)。超過時會截斷路由表。
如果專案根目錄下存在 .hyp/context.yaml(由 hyp context 或 AutoSync 自動生成),hyp ai-rules 會讀取其中的路由資訊並注入到配置檔中:
## Current Routes | Method | Path | Summary | |--------|------|---------| | GET | /health | Health check | | POST | /api/users | Create user | | GET | /api/users/:id | Get user by ID |
這讓 AI 工具不只知道框架慣例,還知道專案目前有哪些 API。
建議工作流程:
# 1. 先生成 manifest hyp context -o .hyp/context.yaml # 2. 再生成 AI 配置檔(會包含路由資訊) hyp ai-rules
所有自動生成的檔案都含有標記:
<!-- auto-generated by hyp ai-rules -->覆蓋規則:
| 檔案狀態 | 行為 |
|---|---|
| 不存在 | 建立新檔案 |
| 存在且有標記 | 覆蓋(更新內容) |
| 存在但無標記 | 跳過(保護手動修改的版本) |
如果你手動建立了 AGENTS.md 並想讓 hyp ai-rules 接管,只需在檔案開頭加入 <!-- auto-generated by hyp ai-rules -->。
func AllTargets() []Target
回傳所有支援的 AI 工具配置檔目標(5 個)。
func FilterTargets(targets []Target, names string) []Target
根據逗號分隔的名稱過濾目標。空字串表示全部。
可用名稱:agents、gemini、copilot、cursor、windsurf
func GenerateAll(dir string, targets []Target, m *manifest.Manifest, dryRun bool) ([]Result, error)
在指定目錄下生成配置檔。m 可為 nil(只生成靜態慣例)。dryRun 為 true 時不寫入檔案,Result 中包含預覽內容。
type Result struct { Path string // 檔案路徑 Status Status // created / skipped / dry-run / error Message string // 錯誤或跳過原因 Content string // dry-run 時的預覽內容 }
hyp context → 生成 .hyp/context.yaml(專案結構 manifest)
hyp ai-rules → 讀取 manifest + 生成 AI 工具配置檔
↓
AGENTS.md / GEMINI.md / copilot-instructions.md / .cursor / .windsurf
↓
AI 工具開啟專案 → 立刻知道 HypGo 慣例 → 省下 token
CLAUDE.md 不在生成範圍內(使用者手動維護),但 Claude Code 也會讀取 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