AI Instruction Standards

AI 指令檔案標準指南

語言: English | 繁體中文

版本: 2.0.0 最後更新: 2026-04-28 適用範圍: 所有主流 AI 輔助編程工具

核心標準: 本技能實作 AI 指令檔案標準。完整方法論文件請參閱核心標準。

AI 技能層級

本技能是三層 AI 協作系統的一部分：

目的

本技能協助建立和維護 AI 指令檔案，適當區分通用標準與專案特定配置，適用於所有主流 AI 輔助編程工具。

快速參考

支援的 AI 工具（2026-04-28 更新）

CLI / Agent 型（終端機代理）

AI-native IDE / 編輯器整合

⚠️ Cursor：.cursorrules 已棄用 — 請遷移至 .cursor/rules/*.mdc

跨工具通用標準：AGENTS.md

AGENTS.md 正成為事實上的跨工具指令標準：

支援的工具：Gemini CLI、OpenAI Codex CLI、OpenCode、GitHub Copilot、Windsurf、Cursor 不支援的工具：Claude Code（使用 CLAUDE.md）、Cline（使用 .clinerules）

建議：多工具專案使用 AGENTS.md 作為通用基準，再為各工具添加特定檔案（Skills、Workflows、Prompts）。

核心原則：通用 vs 專案特定

建議配置

# [專案名稱] - AI 指令

## 通用標準
<!-- 適用於任何專案的規則 -->
- Commit 訊息格式
- 程式碼審查清單
- 測試標準
- 反幻覺規則

---

## 專案特定配置
<!-- 此專案獨有的設定 -->

### 技術棧
[你的技術在此]

### 快速命令
[你的建置/測試/部署命令]

### 檔案結構
[你的專案結構]

各工具設定指南

Claude Code

CLAUDE.md                        # 主要指令（階層式：全域 → 專案 → 子目錄）
.claude/rules/                   # Glob 範圍的附加規則
.claude/skills/{name}/SKILL.md   # 自訂斜線命令 → /{name}
.claude/agents/{name}.md         # 子代理定義

Gemini CLI

GEMINI.md                          # 主要指令
.gemini/commands/{name}.toml       # 自訂斜線命令 → /{name}
.gemini/agents/{name}.yaml         # 子代理定義

.gemini/commands/review.toml 範例：

description = "執行程式碼審查清單"
prompt = "審查以下變更：!{git diff HEAD}"

OpenAI Codex CLI

AGENTS.md                  # 主要指令（從 Git root 到 cwd 逐層讀取）
AGENTS.override.md         # 暫時覆蓋（最高優先級）
~/.codex/AGENTS.md         # 全域備援
.codex/agents/             # 自訂代理定義

OpenCode

AGENTS.md                       # 主要（自動識別）
CLAUDE.md                       # 同樣識別（遷移相容性）
.opencode/agents/               # 自訂代理定義
opencode.json (instructions)    # Glob 模式檔案引用

Cursor

.cursor/rules/                  # MDC 格式規則（取代 .cursorrules）
  {name}.mdc                    # Frontmatter: description, globs, alwaysApply
AGENTS.md                       # 也支援（代理上下文）

MDC frontmatter 範例：

---
description: "TypeScript 編碼標準"
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---

遷移指引：若有 .cursorrules，請將內容移至 .cursor/rules/*.mdc。

GitHub Copilot

.github/copilot-instructions.md         # 永遠啟用，所有對話
.github/instructions/*.instructions.md  # 條件式，Glob 範圍（applyTo frontmatter）
.github/prompts/*.prompt.md             # 可重用模板 → /{name} 斜線命令
.github/agents/*.agent.md               # 自訂代理，精細工具存取控制
AGENTS.md                               # 也被識別

Windsurf

.windsurfrules                   # 專案規則（可 Git 共享）
.windsurf/rules/*.md             # MDC frontmatter 結構化規則
.windsurf/workflows/*.md         # 可重用任務序列 → /{name}
AGENTS.md                        # 也被識別

Workflow 範例（.windsurf/workflows/review.md）：

執行程式碼審查：
1. 執行 `git diff HEAD`
2. 檢查 BLOCKING 問題（安全性、正確性）
3. 檢查 IMPORTANT 問題（設計、測試）
4. 以 BLOCKING/IMPORTANT/SUGGESTION 前綴輸出發現

多工具專案配置

當專案使用多個 AI 工具時：

project/
├── AGENTS.md                            # 通用基準（跨工具）
├── CLAUDE.md                            # Claude Code（擴展 AGENTS.md）
├── GEMINI.md                            # Gemini CLI
├── .cursor/rules/
│   └── standards.mdc                    # Cursor
├── .windsurf/
│   └── workflows/                       # Windsurf Workflows
│       ├── review.md
│       └── checkin.md
└── .github/
    ├── copilot-instructions.md          # Copilot 永遠啟用
    └── prompts/
        └── review.prompt.md             # Copilot 斜線命令

最佳實踐：將通用內容寫在 AGENTS.md 一次，從各工具特定檔案引用，避免重複。

內容指南

通用內容（保持通用）

通用區段應避免：

• 特定命令（npm test、pytest）
• 固定路徑（cli/src/、/var/www/）
• 版本號（Node.js 18、Python 3.11）
• 專案名稱和 URL

專案特定內容

維護檢查清單

提交 AI 指令檔案變更前：

• 通用區段不包含專案特定的路徑、命令或版本
• 專案特定區段有明確標記
• 標準文件的交叉引用正確
• 格式與現有區段一致
• 若使用 Cursor：.cursorrules 已遷移至 .cursor/rules/*.mdc
• 若為多工具專案：AGENTS.md 已涵蓋通用基準

配置偵測

偵測順序

1. 檢查是否存在 CLAUDE.md、AGENTS.md、GEMINI.md 或等效檔案
2. 偵測使用中的 AI 工具（檢查 .cursor/、.windsurf/、.github/copilot-instructions.md 等）
3. 分析內容結構是否區分通用/專案特定
4. 若未找到，建議建立結構化 AI 指令檔案

首次設定

若未找到 AI 指令檔案：

1. 詢問：「此專案沒有 AI 指令檔案。你使用哪些 AI 工具？」
2. 多工具專案推薦 AGENTS.md 作為基準，純 Claude Code 使用 CLAUDE.md
3. 確定專案類型和技術棧
4. 產生包含適當區段的範本
5. 若包含敏感資訊，新增到 .gitignore

相關標準

• AI 指令檔案標準 - 核心標準
• 文件撰寫標準 - 撰寫指南
• 反幻覺規範 - AI 準確性規則
• AI 友善架構 - 上下文優化

版本歷史

授權

本技能以 CC BY 4.0 授權發布。

來源: universal-dev-standards

Next Steps Guidance

After /ai-instruction-standards completes, suggest:

• Create or update project's CLAUDE.md / AGENTS.md ⭐ Recommended — Apply standards immediately
• Run /ai-friendly-architecture to optimize AI collaboration at the architecture level
• Run /ai-collaboration to review AI behavior guidelines

Related Standards

• AI Instruction File Standards - Core standard
• Documentation Writing Standards - Writing guidelines
• Anti-Hallucination Guidelines - AI accuracy rules
• AI-Friendly Architecture - Context optimization

Version History

License

This skill is released under CC BY 4.0.

Source: universal-dev-standards