cmd/airules — 跨 AI 工具配置檔生成

自動生成主流 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 一鍵生成所有配置檔，內容統一、自動維護。

快速上手

CLI 使用

# 生成所有 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)

生成的檔案

AGENTS.md

放在專案根目錄。被最多工具支援（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 動態注入的路由表（如有）

GEMINI.md

格式與 AGENTS.md 相同，放在專案根目錄。Google Gemini CLI 和 AI Studio 原生讀取。

.github/copilot-instructions.md

格式與 AGENTS.md 相同，放在 .github/ 目錄下。GitHub Copilot（VS Code、JetBrains）讀取。

.cursor/rules/hypgo.mdc

Cursor 新格式，含 frontmatter：

---
description: HypGo framework conventions and AI collaboration rules
globs: "**/*.go"
alwaysApply: true
---

alwaysApply: true 確保每次開啟 Go 檔案時都會載入規則。

.windsurf/rules/hypgo.md

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 -->。

API 參考

AllTargets()

func AllTargets() []Target

回傳所有支援的 AI 工具配置檔目標（5 個）。

FilterTargets()

func FilterTargets(targets []Target, names string) []Target

根據逗號分隔的名稱過濾目標。空字串表示全部。

可用名稱：agents、gemini、copilot、cursor、windsurf

GenerateAll()

func GenerateAll(dir string, targets []Target, m *manifest.Manifest, dryRun bool) ([]Result, error)

在指定目錄下生成配置檔。m 可為 nil（只生成靜態慣例）。dryRun 為 true 時不寫入檔案，Result 中包含預覽內容。

Result

type Result struct {
    Path    string  // 檔案路徑
    Status  Status  // created / skipped / dry-run / error
    Message string  // 錯誤或跳過原因
    Content string  // dry-run 時的預覽內容
}

與其他 AI 協作功能的關係

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。