第 11 課：自訂指令 — 根據您的程式設計風格教授 AI

使用 GitHub Copilot 進行 Vibe 編碼：從基礎知識到高級

第 4 部分：自訂和擴充 Copilot

亞洲開發網

1. 什麼是定制指令？

自訂指令是 靜態規則 您為 Copilot 編寫的檔案會自動套用到 每一次互動 在項目中。不必在每次提示時重複約定，只需寫一次，Copilot 就會遵循它。

Không có instructions:
  Prompt: "Create a function to validate email"
  → AI dùng style riêng, có thể khác conventions của bạn

Có instructions:
  Prompt: "Create a function to validate email"
  → AI tự động tuân theo: TypeScript strict, Zod validation,
    custom error class, JSDoc comments, đặt tên theo camelCase

2. 自訂指令的類型

2.1.專案級： .github/copilot-instructions.md

申請 整個專案，透過 Git 與整個團隊分享：

# Project Coding Guidelines

## Tech Stack
- Next.js 15 with App Router
- TypeScript 5.x (strict mode)
- Prisma ORM with PostgreSQL
- NextAuth v5 for authentication
- Zod for validation
- TailwindCSS for styling

## Code Style
- Use functional components with arrow functions
- Prefer `const` over `let`, never use `var`
- Use TypeScript strict mode, no `any` type
- Use named exports, not default exports
- Error handling with custom AppError class

## Naming Conventions
- Files: kebab-case (user-service.ts)
- Components: PascalCase (UserProfile.tsx)
- Functions/variables: camelCase
- Constants: UPPER_SNAKE_CASE
- Database tables: snake_case
- API routes: kebab-case (/api/user-profiles)

## Testing
- Use Vitest for unit tests
- Test files alongside source: `*.test.ts`
- Use describe/it blocks with clear descriptions
- Mock external dependencies, not internal modules

## API Conventions
- RESTful endpoints with proper HTTP methods
- Response format: { data, error, meta }
- Pagination: cursor-based with `nextCursor`
- Error responses: { error: { code, message, details } }

## Git
- Conventional commits: feat|fix|docs|refactor|test(scope): message
- Branch names: feature/xxx, fix/xxx, docs/xxx

2.2.文件類型特定： .說明.md

申請 特定文件類型 基於 適用於 圖案：

<!-- .github/instructions/react-components.instructions.md -->
---
applyTo: "src/components/**/*.tsx"
---
# React Component Guidelines

- Use arrow function components
- Props interface named `{ComponentName}Props`
- Destructure props in function parameter
- Use `cn()` utility for conditional classNames
- Memoize with React.memo only when necessary
- Extract hooks logic to custom hooks in src/hooks/

<!-- .github/instructions/api-routes.instructions.md -->
---
applyTo: "src/app/api/**/*.ts"
---
# API Route Guidelines

- Always validate request body with Zod
- Use try-catch with AppError for error handling
- Return proper HTTP status codes
- Include rate limiting middleware
- Log all requests with structured logging

2.3.用戶級指令

申請 每個項目 在您的電腦上（VS Code 設定）：

{
  "github.copilot.chat.codeGeneration.instructions": [
    { "text": "Always use TypeScript, never plain JavaScript" },
    { "text": "Prefer functional programming patterns" },
    { "text": "Include error handling in every function" }
  ]
}

3.使用/init自動建立指令

不要從頭開始編寫，而是運行 /初始化 在聊天視圖中：

1. Copilot 掃描整個程式碼庫
2. 檢測模式、約定、技術堆疊
3. 創建 .github/copilot-instructions.md 基於當前代碼
4. 你回顧並調整

// Trong Chat view:
/init

// Copilot output:
"I've analyzed your codebase and created .github/copilot-instructions.md
with the following conventions detected:
- Next.js 15 App Router with TypeScript
- Prisma ORM patterns...
- Testing with Vitest...
Please review and adjust as needed."

4. 有效的結構指令

✅ 做：

• 簡短而具體：「使用 Zod 進行驗證」比「確保正確驗證」更好
• 可操作的規則：AI可以立即跟隨
• 參考文件：“遵循 src/services/UserService.ts 中的模式”
• 按部分劃分：樣式、測試、API、Git

❌ 不要：

• 太長: > 2000 字浪費了上下文窗口
• 太一般了：「編寫乾淨的程式碼」——人工智慧不知道「乾淨」在你的上下文中意味著什麼
• 自相矛盾：“使用類別”+“使用函數式程式設計”
• 過時的: 指令與目前程式碼不匹配

5. 團隊須知

當作為一個團隊工作時，承諾 .github/copilot-instructions.md 轉到倉庫：

project/
├── .github/
│   ├── copilot-instructions.md      ← Main instructions
│   ├── instructions/
│   │   ├── react.instructions.md    ← React-specific
│   │   ├── api.instructions.md      ← API-specific
│   │   └── testing.instructions.md  ← Testing-specific
│   ├── prompts/
│   │   ├── new-feature.prompt.md    ← Prompt templates
│   │   └── code-review.prompt.md
│   └── agents/
│       └── Reviewer.agent.md        ← Custom agents

當每個成員使用Copilot時， 所有人都收到相同的指示 → 程式碼更加一致。

6.練習練習

1. 運行 /初始化 在目前專案中
2. 查看產生的說明文件
3. 附加：命名約定、錯誤處理策略、測試方法
4. 創建一個 .說明.md 對於特定文件類型（元件或 API）
5. 測試：提示建立程式碼→查看AI是否遵循指令

七、總結

類型	文件	適用範圍
專案級	.github/copilot-instructions.md	整個項目，透過 Git 分享
文件類型	.github/說明/*.instructions.md	特定檔案模式 (applyTo)
使用者級	VS 代碼設定	設備上的每個項目

自訂指令是 一次性投資 幫助後續的每個提示給出更好的結果。下一首歌曲將是翻唱歌曲 客製化代理和代理技能 — 為每項任務創建專門的人工智慧。