前言

使用 GitHub Copilot 的開發者們，有沒有在專案中建立 .github/copilot-instructions.md 的檔案？

這個檔案可以幫助你將 Copilot 自定義為專案專用，讓它變得更聰明、更便利地被使用。
本文將介紹這個強大功能及其具體的使用方法。

copilot-instructions.md 的介紹

簡單來說，它是 GitHub Copilot 版本的 CLAUDE.md。
也就是說，這是一份給 GitHub Copilot 的指示書。

這個檔案作為 GitHub Copilot 在處理使用者指示前優先讀取的指示書發揮作用。
不需要特別的設置，只需將它放在專案的 .github 目錄下，命名為 copilot-instructions.md 即可識別。

因為 Copilot 會先讀取這份指示書再回應使用者的指示，所以指示書越詳細，就越容易獲得符合專案上下文的理想回應。

某個 Speaker Deck 中提到了 AI：

沒有上下文的 AI 像那天短期來的臨時工（雖然優秀）

透過 copilot-instructions.md 為專案提供明確的上下文，我們可以將這位「優秀的臨時工」培養成「值得信賴的專屬助理」。

建立 copilot-instructions.md

只需在專案的 .github 目錄下建立 copilot-instructions.md。

在 VS Code 等編輯器中，可能會像圖片一樣顯示專用的 Copilot 圖標（視擴展功能的設定而定）。

此外，當在 VS Code 中開啟 GitHub Copilot Chat，使用 New Chat（或 / 命令）時，也可以透過顯示的「指示的生成」（@workspace /new）的連結來創建。

每個項目應該寫什麼？

作為專案的「使用說明書」，建議涵蓋以下幾個項目。

1. 前提條件

定義給 AI 的基本指示。
例如：「回覆必須使用中文」、「在進行大規模改動（例如：超過 200 行）之前，請先提議變更計畫」。
這樣可以防止意外生成大量的程式碼，也避開突然用英文回覆的情況。

2. 應用程式概述

簡短地描述這個專案的應用程式是為了什麼，包含目的和主要功能。
AI 理解專案的全貌將減少無謂的檔案搜尋，進而導致更準確的回答。

3. 技術堆疊（生態系統）

明確列出使用的語言、框架、主要函式庫及其版本。
這樣可以防止 Copilot 自作主張隨意 import 不在專案中的函示庫或提議過時的語法。

4. 目錄結構

解釋主要目錄及各自的角色。
例如，「在 src/features 裡按功能區分，src/shared 裡則放置共用元件」。這樣 Copilot 就能在適當的位置建立和建議新檔案。

5. 架構與設計指引

列出專案採用的設計指引（例如：MVVM、Atomic Design、Clean Architecture 等）。
如果不定義這些，AI 可能會生成與現有設計不一致的程式碼，這在團隊開發中特別重要。

6. 測試方針

傳達使用的測試框架（如：Vitest、Jest、RSpec 等）和測試的撰寫方針（例如：「測試程式碼放在 __tests__ 目錄下」、「目標覆蓋率 80%」等）。
如同著名的引用「遺留程式碼本質上無測試的程式碼」，測試非常重要。

7. 反模式

不只是「我希望這樣寫」的指示，「我希望不要這樣寫」的規則也很有幫助。
例如，明確指出「禁止使用 default export」、「原則上不使用 any 型別」等專案特定的禁止事項。

例子

這裡介紹一個虛構的任務管理應用程式「TooMe's Task App」，提供兩個具體的 copilot-instructions.md 例子。
非常長。

例1: 使用 React 的 Web 應用

<details>
<summary>例1: 使用 React 的 Web 應用 (點擊展開)</summary>

# TooMe's Task App (Web) 的 Copilot 指示

## 此文件的介紹
- 本文件是為了幫助 GitHub Copilot 和各種 AI 工具更容易理解此倉庫的上下文。
- 在實施新功能時，請以這裡示範的技術選擇、設計方針和模組結構為前提。
- 若有不確定之處，請探索倉庫的檔案，並詢問使用者「這是這樣的意思嗎？」

## 前提條件
- 回應必須使用中文。
- 在進行變更時，如果變更量有可能超過 200 行，請事先確認「這個指示的變更量可能會超過 200 行，您是否要執行？」
- 對於大的變更，首先制定計畫，然後告訴使用者「我打算這樣進行計畫。」如果使用者要求修正計畫，請進行調整後再提議。

## 應用概述

**TooMe's Task App (Web)** 是一個整合任務管理與排程管理的 Web 應用程式。

### 主要功能
- **任務管理**: 創建、編輯、刪除及完成管理 Todo 列表
- **Google 日曆整合**: 與 Google 日曆同步，實現所有任務和日程的集中管理
- **推播通知**: 通過 Web Push API 提供排程通知
- **提醒功能**: 在指定時間提醒任務和安排
- **類別管理**: 將任務按類別分類
- **重複任務**: 設置日次、週次和月次的重複任務
- **響應式設計**: 支援桌面、平板及手機

## 技術堆疊概述
- **語言**: TypeScript 5.x
- **框架**: React 18.x
- **建置工具**: Vite 5.x
- **包管理器**: pnpm（或 npm/yarn）
- **狀態管理**: Zustand + React Query (TanStack Query)
- **路由**: React Router v6
- **樣式**: Tailwind CSS + CSS Modules（必要時）
- **UI 元件**: Radix UI (Headless UI) + 自訂設計系統
- **表單管理**: React Hook Form + Zod (驗證)
- **API 通信**: Axios + React Query
- **認證**: Firebase Authentication (Google Sign-In)
- **後端**: Firebase (Firestore, Functions, Hosting)
- **通知**: Firebase Cloud Messaging (FCM) + Web Push API
- **測試**: Vitest + React Testing Library + MSW (Mock Service Worker)
- **檢查器/格式化工具**: ESLint + Prettier
- **型別檢查**: TypeScript 嚴格模式

## 專案結構和角色

本應用採用基於功能的目錄結構，實現關切的分離和擴展性。

src/
├── app/ # 應用程式的進入點
│ ├── App.tsx # 根組件
│ ├── routes.tsx # 路由定義
│ └── providers.tsx # 全局提供者
├── features/ # 按功能分類的模組
│ ├── task/ # 任務管理功能
│ │ ├── components/ # 任務相關元件
│ │ ├── hooks/ # 任務相關的自訂 Hook
│ │ ├── stores/ # 任務狀態管理 (Zustand)
│ │ ├── api/ # 任務 API 呼叫
│ │ ├── types/ # 任務型別定義
│ │ └── utils/ # 任務工具函數
│ ├── calendar/ # 日曆功能
│ ├── reminder/ # 提醒功能
│ ├── auth/ # 認證功能
│ └── settings/ # 設定功能
├── shared/ # 共用模組
│ ├── components/ # 共用 UI 元件
│ │ ├── ui/ # 基本 UI 組件 (按鈕、輸入框等)
│ │ ├── layout/ # 布局組件
│ │ └── feedback/ # 反饋 (Toast、Modal 等)
│ ├── hooks/ # 共用自訂 Hook
│ ├── utils/ # 工具函數
│ ├── types/ # 共用型別定義
│ ├── constants/ # 常數定義
│ └── api/ # API 客戶端設定
├── lib/ # 外部函式庫的包裝
│ ├── firebase/ # Firebase 設定
│ ├── google-calendar/ # Google Calendar API
│ └── notification/ # 通知相關
├── styles/ # 全局樣式
│ ├── globals.css # 包含 Tailwind 設定
│ └── themes/ # 主題定義
└── tests/ # 測試工具
├── mocks/ # 模擬資料
├── setup.ts # 測試設置
└── utils.tsx # 測試助手

## 架構指引

### 元件設計
- **部分採用 Atomic Design**: 將基本元件放在 `shared/components/ui`，功能專用的元件放在對應的功能內
- **組合模式**: 將小型元件組合構建複雜的 UI
- **容器/顯示模式**: 將邏輯和顯示分離 (透過 hooks 提取邏輯)

### 狀態管理方針
- **本地狀態**: 使用 `useState` / `useReducer` 來管理
- **全局狀態**: 通過 Zustand 來管理 (例如：使用者資訊、UI 狀態)
- **伺服器狀態**: 使用 React Query 來管理 (API 資料的快取和同步)
- **表單狀態**: 使用 React Hook Form 來管理

### 數據流
1. **UI → Hook**: 將使用者操作通知給自訂 Hook
2. **Hook → API（React Query）**: API 呼叫透過 React Query 來包裝
3. **API → Hook → UI**: 獲取資料並快取以反映到 UI 上
4. **樂觀更新**: 透過 React Query 的 `onMutate` 立即更新 UI

## 目錄與檔案命名規則

### 元件
- **檔名**: PascalCase (例如: `TaskList.tsx`, `TaskCard.tsx`)
- **目錄**: kebab-case (例如: `task-list/`, `calendar-view/`)
- **index.ts**: 放在每個目錄內，以集中匯出到外部

### Hook
- **檔名**: camelCase + `use` 前綴 (例如: `useTaskList.ts`, `useAuth.ts`)

### 工具函數
- **檔名**: camelCase (例如: `formatDate.ts`, `validateEmail.ts`)

### 型別定義
- **檔名**: camelCase 或 PascalCase (例如: `task.types.ts`, `Task.ts`)
- **型別名稱**: PascalCase (例如: `Task`, `User`, `ApiResponse<T>`)

## UI 實作指導

### 元件設計原則
- **單一責任**: 每個元件只承擔一個責任
- **Props 的型別定義**: 所有 props 都要明確型別
- **避免預設匯出**: 使用命名匯出，以便後續重構
- **children 模式**: 在需要時使用 `children` 來增加靈活性

### 樣式
- **基於 Tailwind CSS**: 使用實用優先的方式
- **定義共用樣式**: 在 `styles/globals.css` 中定義自訂的實用程序類
- **使用 CSS Modules**: 只有當元件需要複雜的獨特樣式時才使用
- **響應式支援**: 利用 Tailwind 的斷點標籤 (`sm:`, `md:`, `lg:`)

### 可及性 (a11y)
- **語意化 HTML**: 使用適當的 HTML 標籤 (`<button>`、`<nav>`、`<main>` 等)
- **aria 屬性**: 根據需要添加 `aria-label`, `aria-describedby` 等
- **鍵盤操作**: 確保所有操作都可以透過鍵盤執行
- **聚焦管理**: 使用 `focus-visible` 應用適當的聚焦樣式

### 性能最佳化
- **React.memo**: 避免不必要的重渲染
- **useMemo / useCallback**: 防止高開銷的計算或函式的再生成
- **代碼拆分**: 使用 React.lazy + Suspense 做延遲加載
- **圖像最佳化**: 使用 WebP 格式，適當大小，並進行延遲加載

## 狀態管理的實作指南

### Zustand 的使用

```typescript
// stores/authStore.ts
import { create } from 'zustand';
import { devtools, persist } from 'zustand/middleware';

interface AuthState {
  user: User | null;
  isAuthenticated: boolean;
  setUser: (user: User | null) => void;
  logout: () => void;
}

export const useAuthStore = create<AuthState>()(
  devtools(
    persist(
      (set) => ({
        user: null,
        isAuthenticated: false,
        setUser: (user) => set({ user, isAuthenticated: !!user }),
        logout: () => set({ user: null, isAuthenticated: false }),
      }),
      { name: 'auth-storage' }
    )
  )
);

React Query 的使用

// api/taskApi.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

export const useTaskList = () => {
  return useQuery({
    queryKey: ['tasks'],
    queryFn: fetchTasks,
    staleTime: 5 * 60 * 1000, // 5分鐘
  });
};

export const useCreateTask = () => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: createTask,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['tasks'] });
    },
  });
};

API 通信與資料管理

Axios 實例的設定

• 在 shared/api/client.ts 創建 axios 實例
• 使用攔截器自動添加認證 token
• 錯誤處理的統一管理

錯誤處理

• API 錯誤: 透過 React Query 的 onError 來處理
• 全局錯誤: 透過錯誤邊界來捕獲
• 用戶反饋: 使用 Toast 通知顯示

資料型別定義

• Zod 優勢: 用於 API 回應的驗證
• TypeScript 型別: 從 Zod 優勢生成型別 (z.infer<typeof schema>)

認證 (Firebase Authentication)

Google Sign-In 流程

1. Firebase SDK 初始化: 在 lib/firebase/config.ts 中設定
2. Google 提供者: 通過 signInWithPopup 登入
3. Token 管理: Firebase 會自動管理，透過 onAuthStateChanged 監視狀態
4. 保存於 Zustand: 將登入使用者資訊儲存於 authStore

認證保護

• ProtectedRoute 元件: 未認證時重定向至登入頁面
• useAuth Hook: 輕鬆獲取認證狀態

Google 日曆整合

OAuth2 流程

1. Google API 客戶端函式庫: 使用 gapi
2. Scope: https://www.googleapis.com/auth/calendar
3. 訪問 token: 需單獨管理，與 Firebase Auth 的 ID token 不同

日曆事件同步

• 定期同步: 使用 setInterval 或 Web Worker 進行定期 polling
• 快取: 透過 React Query 快取事件
• 離線支援: 將同步資料儲存至 IndexedDB

通知功能

Web Push API

• 服務工作者: 使用 public/sw.js 接收通知
• FCM: 通過 Firebase Cloud Messaging 提供推播通知
• 通知許可: 初次訪問時要求許可
• 通知點擊: 轉至特定的任務或事件頁面

提醒排程

• Web Worker: 在背景中執行計時器
• 通知 API: 顯示本地通知
• 重複任務: 解析 cron 格式排程

測試策略

單元測試 (Vitest)

• hooks: 使用 @testing-library/react-hooks 測試
• utils: 測試純函數的邏輯
• stores: 測試 Zustand 儲存的行為及狀態變化

元件測試 (React Testing Library)

• 使用者互動: 使用 fireEvent / userEvent 模擬事件
• 非同步處理: 使用 waitFor 等待非同步渲染
• 模擬: 使用 MSW 模擬 API 回應

E2E 測試 (Playwright / Cypress)

• 主要流程: 測試登入 → 創建任務 → 編輯 → 刪除的流程
• 跨瀏覽器: 在 Chrome、Firefox、Safari 測試

建置與部署

Vite 建置設定

• 環境變數: 在 .env.development、.env.production 中管理
• 代碼分割: 自動優化，但必要時可手動設定
• 資產優化: 圖片、字型優化

Firebase Hosting

• 部署: firebase deploy --only hosting
• 預覽: firebase hosting:channel:deploy preview
• 自訂域名: 在 Firebase 控制台設定

CI/CD (GitHub Actions)

• PR 檢查: 進行 lint、型別檢查、執行測試
• 自動部署: 合併到 main 分支後自動部署到生產環境

程式碼規範與最佳實踐

TypeScript 的規範

• 嚴格模式: 在 tsconfig.json 中設置 strict: true
• 禁止使用 any: 啟用 no-explicit-any 規則
• 型別推論的運用: 避免不必要的型別註解，讓推論接手
• 聯合型別: 明確表達狀態 (例如: type Status = 'idle' | 'loading' | 'success' | 'error')

React 的規範

• 函式元件: 儘量不使用類元件
• hooks 的規則: 僅在頂層呼叫，不可在條件分支中呼叫
• useEffect 的依賴陣列: 準確指明，防止不必要的重新執行
• key prop: 在列表渲染時使用唯一穩定的 key

非同步處理

• async/await: 優先於 Promise 鏈
• 錯誤處理: 確保使用 try-catch 捕獲錯誤
• AbortController: 取消不必要的請求

引入順序

1. React 相關
2. 外部函式庫
3. 內部模組 (features, shared, lib)
4. 型別定義
5. 樣式

import { useState, useEffect } from 'react';
import { useQuery } from '@tanstack/react-query';

import { TaskList } from '@/features/task/components';
import { Button } from '@/shared/components/ui';
import { formatDate } from '@/shared/utils';

import type { Task } from '@/features/task/types';

import styles from './Home.module.css';

註解

• JSDoc: 對複雜的函數加上 JSDoc 註解
• TODO 註解: 對暫時的實作加上 // TODO: 標記
• 註解掉的程式碼: 不需要的程式碼應刪除，保留註解應避免。

反模式

以下模式應該避免。若在現有程式碼中發現，應建議重構。

元件設計

• 龐大元件: 若一個元件超過 200 行，應考慮分割
• Prop Drilling: 深層的 props 傳遞應透過 Context 或狀態管理函式庫解決
• 濫用 useEffect: 資料提取應使用 React Query、事件處理用於 useEffect 的場景應最小化

狀態管理

• 過度的全局狀態: 僅管理真正的全局狀態於 Zustand
• 濫用 useState: 複雜的狀態應由 useReducer 管理
• 直接修改狀態: 應保持不變的更新

性能

• 不必要的重新渲染: 可透過 React DevTools Profiler 測量，必要時進行優化
• 過度優化: 不要隨意使用 useMemo/useCallback，而是進行實際測量
• 龐大的 Bundled 檔案: 利用代碼分割輕量化初次載入

TypeScript

• 濫用 any: 若型別推論困難，使用 unknown 並通過型別保護篩選
• 型別斷言 (as): 盡量減少，確保型別安全
• 濫用可選: 僅在真需時使用 ?

安全性與隱私

• 環境變數: 在 .env 中管理 API 金鑰，並加到 .gitignore
• XSS 對策: 適當地清理使用者輸入，React 的 JSX 會自動進行轉義
• CSRF 防護: 透過 Firebase Authentication 的 token 基礎認證來應對
• HTTPS 通信: 在生產環境務必使用 HTTPS
• CSP (內容安全政策): 設定合適的 CSP 標頭

可及性 (a11y) 指導方針

• 遵循 WCAG 2.1 AA 級別: 努力做到
• 支援螢幕閱讀器: 合理使用 ARIA 屬性
• 鍵盤導航: 支援 Tab、Enter、Escape 鍵的操作
• 顏色對比: 確保 4.5:1 以上的對比比率
• 使用 axe DevTools: 在開發時定期進行檢查

國際化 (i18n)

• react-i18next: 支援多語言
• 語言檔案: public/locales/{lang}/translation.json
• 日期和數字格式: 利用 Intl API
• RTL 支援: 為未來可能的阿拉伯語等考慮

小結

請持續保持這份文件的最新狀態，若有新技術選擇或設計變更，應立即更新。GitHub Copilot 和 AI 工具將透過這份文件，精確理解專案上下文，並提供更合適的程式碼建議。

全團隊遵循這份指導方針，將提高程式碼的一致性與可維護性，新成員的上手也會變得更加順利。

TooMe's Task App (Web) 旨在結合現代 React 開發的最佳實踐，實現具有可擴展性與可維護性的架構。

</details>

## 例2: 使用 Kotlin 的 Android 應用

<details>
<summary>例2: 使用 Kotlin 的 Android 應用 (點擊展開)</summary>

TooMe's Task App (Android) 的 Copilot 指示

此文件的介紹

• 本文件是為了幫助 GitHub Copilot 和各種 AI 工具更容易理解此倉庫的上下文。
• 在實施新功能時，請以這裡示範的技術選擇、設計方針和模組結構為前提。
• 若有不確定之處，請探索倉庫的檔案，並詢問使用者「這是這樣的意思嗎？」

前提條件

• 回應必須使用中文。
• 在進行變更時，如果變更量有可能超過 200 行，請事先確認「這個指示的變更量可能會超過 200 行，您是否要執行？」
• 對於大的變更，首先制定計畫，然後告訴使用者「我打算這樣進行計畫。」如果使用者要求修正計畫，請進行調整後再提議。

應用概述

TooMe's Task App 是一個整合任務管理及排程管理的 Android 應用。

主要功能

• 任務管理: 創建、編輯、刪除及完成管理 Todo 列表
• Google 日曆整合: 與 Google 日曆同步，實現所有任務和日程的集中管理
• 推播通知: 通過 Firebase Cloud Messaging 提供排程通知
• 提醒功能: 在指定時間提醒任務和安排
• 類別管理: 將任務按類別分類
• 重複任務: 設置日次、週次和月次的重複任務

技術堆疊概述

• 語言: Kotlin 2.4.x
• 建構: Android Gradle Plugin 8.2.x / Gradle Version Catalog (gradle/libs.versions.toml) 中集中管理依賴
• 支援的作業系統: Min SDK 26 (Android 8.0)，Target SDK 34，Compile SDK 34
• 依賴注入: Hilt (Dagger Hilt)
• 非同步處理: Kotlin Coroutines + Flow
• 序列化: kotlinx-serialization-json
• 網路: Retrofit + OkHttp + Kotlin Serialization Converter
• 資料庫: Room (SQLite)
• UI: Jetpack Compose
• 導航: Navigation Compose
• 認證: Google Sign-In (用於 Google Calendar API 整合)
• 通知: Firebase Cloud Messaging (FCM) + WorkManager
• 測試: JUnit5 + Kotest + MockK + Turbine

模組結構與角色

本應用採用多模組結構，以實現關切的分離及縮短建置時間。

應用模組

• app: 主要應用模組，管理 Application 類、主要 Activity 和導航圖。

Core 模組群

• core:common: 共用公用程式、擴展函數、常數定義。所有模組皆可引用。
• core:model: 數據模型定義，包括 Entity、DTO 和領域模型。
• core:data: Repository 實作，資料來源（API/DB）的抽象層供 UseCase 層使用。
• core:database: Room 資料庫定義，管理 DAO、Entity 和 Migration。
• core:network: API 通信，設定 Retrofit 客戶端及 API 接口、處理認證。
• core:datastore: 使用 DataStore (Preferences) 進行鍵值型資料持久化，儲存用戶設置等。
• core:design: Compose UI 元件、主題、顏色、排版的定義，基於 Material3。
• core:ui: 共用 Compose UI 部件，畫面模板、通用佈局等。
• core:notification: 通知相關的共用功能，管理 FCM 和 WorkManager 提供的本地通知。
• core:analytics: Firebase Analytics 包裝器，集中管理事件日誌的發送。

Feature 模組群

每個功能都實作為獨立的 feature 模組，採用 MVVM 架構。

• feature:task: 任務列表、創建、編輯和刪除功能。
• feature:calendar: 日曆視圖和 Google 日曆的整合。

  
  </details>

原文出處：https://qiita.com/TooMe/items/873540da84567733d16b