TechSummary 2025-09-03
· 閱讀時間約 18 分鐘
🤖 撰寫 Copilot 自訂指令的 5 個技巧
- Copilot 指令文件 (
copilot-instructions.md) 至關重要，它能為 Copilot 提供專案的必要上下文，如同新人入職時的背景知識，有助於避免混淆和錯誤。 - 專案概覽： 指令文件應以專案的「電梯簡報」開頭，簡潔描述應用程式的目標、受眾和主要功能。
# Contoso Companions
This is a website to support pet adoption agencies. Agencies are onboarded into the application, where they can manage their locations, available pets, and publicize events. Potential adoptors can search for pets available in their area, discover agencies, and submit adoption applications. - 技術棧識別： 明確列出專案使用的後端、前端技術、API 和測試套件，並可簡要說明其用途，幫助 Copilot 理解開發環境。
## Tech stack in use
### Backend
- Flask is used for the API
- Data is stored in Postgres, with SQLAlchemy as the ORM
- There are separate database for dev, staging and prod
- For end to end testing, a new database is created and populated,
then removed after tests are complete
### Frontend
- Astro manages the core site and routing
- Svelte is used for interactivity
- TypeScript is used for all front-end code
### Testing
- Unittest for Python
- Vitest for TypeScript
- Playwright for e2e tests - 編碼規範： 詳述專案的編碼風格、標準和測試要求，例如型別提示、分號使用、單元測試和端對端測試的規定等，這部分可獨立成區塊。
## Project and code guidelines
- Always use type hints in any language which supports them
- JavaScript/TypeScript should use semicolons
- Unit tests are required, and are required to pass before PR
- Unit tests should focus on core functionality
- End-to-end tests are required
- End-to-end tests should focus on core functionality
- End-to-end tests should validate accessibility
- Always follow good security practices
- Follow RESTful API design principles
- Use scripts to perform actions when available - 專案結構說明： 描述專案的文件夾結構及其內容，可幫助 Copilot 快速定位並理解各部分功能。
## Project structure
- server/ : Flask backend code
- models/ : SQLAlchemy ORM models
- routes/ : API endpoints organized by resource
- tests/ : Unit tests for the API
- utils/ : Utility functions and helpers, including database calls
- client/ : Astro/Svelte frontend code
- src/components/ : Reusable Svelte components
- src/layouts/ : Astro layout templates
- src/pages/ : Astro pages and routes
- src/styles/ : CSS stylesheets
- scripts/ : Development, deployment and testing scripts
- docs/ : Project documentation to be kept in sync at all times - 指向可用資源： 列出專案中可用的腳本或工具，如開發、部署和測試腳本，或特定的 MCP 伺服器，以提高 Copilot 的準確性和速度。
## Resources
- scripts folder
- start-app.sh : Installs all libraries and starts the app
- setup-env.sh : Installs all libraries
- test-project.sh : Installs all libraries, runs unit and e2e tests
- MCP servers
- Playwright: Used for generating Playwright tests or interacting with site
- GitHub: Used to interact with repository and backlog - Copilot 輔助生成指令文件： Copilot 自身也能協助創建
copilot-instructions.md文件，提供標準化的提示範本，幫助開發者釐清專案目標。Your task is to "onboard" this repository to a coding agent by adding a .github/copilot-instructions.md file. It should contain information describing how the agent, seeing the repo for the first time, can work most efficiently.
...
## Guidance
Ensure you include the following:
- A summary of what the app does.
- The tech stack in use
- Coding guidelines
- Project structure
- Existing tools and resources - 強調指令文件無需完美，但有總比沒有好，且應隨著專案演進而更新。
