creating-copilot-packages

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Creating GitHub Copilot Packages

创建GitHub Copilot 配置包

Overview

概述

GitHub Copilot uses natural language markdown instructions. Repository-wide instructions use plain markdown with NO frontmatter. Path-specific instructions use YAML frontmatter with

applyTo

field.

GitHub Copilot 使用自然语言Markdown指令。仓库级指令使用纯Markdown格式，无需前置元数据（frontmatter）。路径特定指令则需要包含

applyTo

字段的YAML前置元数据。

Package Types

配置包类型

Type	File Location	Frontmatter
Repository-wide	`.github/copilot-instructions.md`	None (plain markdown)
Path-specific	`.github/instructions/*.instructions.md`	Required ( `applyTo` field)

类型	文件位置	前置元数据
仓库级	`.github/copilot-instructions.md`	无（纯Markdown）
路径特定	`.github/instructions/*.instructions.md`	必填（含 `applyTo` 字段）

Quick Reference

快速参考

Repository-Wide (No Frontmatter)

仓库级（无前置元数据）

markdown

undefined

markdown

undefined

API Development Guidelines

API开发指南

Follow REST best practices when developing API endpoints.

开发API端点时遵循REST最佳实践。

Principles

原则

Use semantic HTTP methods (GET, POST, PUT, DELETE)
Return appropriate status codes
Include error messages in response body

undefined

使用语义化HTTP方法（GET、POST、PUT、DELETE）
返回合适的状态码
在响应体中包含错误信息

undefined

Path-Specific (With Frontmatter)

路径特定（含前置元数据）

yaml

---
applyTo: "src/api/**/*.ts"  # REQUIRED
excludeAgent: "code-review"  # Optional
---

yaml

---
applyTo: "src/api/**/*.ts"  # 必填
excludeAgent: "code-review"  # 可选
---

Creating Repository-Wide Instructions

创建仓库级指令

File:

.github/copilot-instructions.md

Plain markdown with NO frontmatter:

markdown

undefined

文件：

.github/copilot-instructions.md

使用纯Markdown格式，不能包含前置元数据：

markdown

undefined

TaskManager Development Guidelines

TaskManager开发指南

Architecture

架构

Frontend

前端

React 18 with TypeScript
Vite for build tooling
Zustand for state management
Tailwind CSS for styling

React 18 + TypeScript
使用Vite作为构建工具
使用Zustand进行状态管理
使用Tailwind CSS做样式开发

Backend

后端

Node.js with Express
PostgreSQL with Prisma ORM
JWT for authentication

Node.js + Express
PostgreSQL + Prisma ORM
使用JWT进行身份认证

Coding Conventions

编码规范

Use TypeScript strict mode
Functional components with hooks
Colocate tests with source files
Use Zod for runtime validation

启用TypeScript严格模式
使用函数式组件+Hooks
测试文件与源码文件放在同一目录
使用Zod进行运行时校验

Testing

测试

Use Vitest for unit tests
Aim for 80% coverage on new code
Mock external dependencies

使用Vitest编写单元测试
新代码的测试覆盖率目标为80%
对外部依赖进行Mock

Examples

示例

```typescript // Good: RESTful endpoint app.get('/api/users', async (req, res) => { try { const users = await db.users.findAll(); res.json({ users }); } catch (error) { res.status(500).json({ error: 'Failed to fetch users' }); } }); ```

undefined

```typescript // 推荐：RESTful端点 app.get('/api/users', async (req, res) => { try { const users = await db.users.findAll(); res.json({ users }); } catch (error) { res.status(500).json({ error: '获取用户列表失败' }); } }); ```

undefined

Creating Path-Specific Instructions

创建路径特定指令

File:

.github/instructions/api-endpoints.instructions.md

REQUIRED: File name must end with

.instructions.md

文件：

.github/instructions/api-endpoints.instructions.md

必填：文件名必须以

.instructions.md

结尾

Single Pattern

单一匹配规则

markdown

---
applyTo: "app/models/**/*.rb"
---

markdown

---
applyTo: "app/models/**/*.rb"
---

Model Guidelines

模型开发指南

These rules apply only to Ruby model files.

这些规则仅适用于Ruby模型文件。

Conventions

规范

Use ActiveRecord validations
Define associations explicitly
Add database indexes for foreign keys

undefined

使用ActiveRecord校验
显式定义关联关系
为外键添加数据库索引

undefined

Multiple Patterns (Comma-Separated)

多匹配规则（逗号分隔）

markdown

---
applyTo: "**/*.ts,**/*.tsx"
---

markdown

---
applyTo: "**/*.ts,**/*.tsx"
---

TypeScript Guidelines

TypeScript开发指南

These rules apply to all TypeScript files.

这些规则适用于所有TypeScript文件。

Type Safety

类型安全

Always define explicit types for function parameters
Avoid using
```
any
```
type
Use
```
unknown
```
instead of
```
any
```
for truly unknown types

undefined

始终为函数参数定义显式类型
避免使用
```
any
```
类型
对于真正未知的类型，使用
```
unknown
```
替代
```
any
```

undefined

Multiple Patterns (Array)

多匹配规则（数组形式）

markdown

---
applyTo:
  - "src/api/**/*.ts"
  - "src/services/**/*.ts"
---

markdown

---
applyTo:
  - "src/api/**/*.ts"
  - "src/services/**/*.ts"
---

API Endpoint Guidelines

API端点开发指南

These rules apply only to API files.

这些规则仅适用于API相关文件。

Requirements

要求

All endpoints must have error handling
Use async/await for database calls
Log all errors with structured logging
Validate input with Zod schemas

所有端点必须包含错误处理
数据库调用使用async/await
使用结构化日志记录所有错误
使用Zod Schema校验输入

Example

示例

```typescript import { z } from 'zod';

const createUserSchema = z.object({ name: z.string().min(1), email: z.string().email(), });

app.post('/api/users', async (req, res) => { try { const data = createUserSchema.parse(req.body); const user = await db.users.create(data); res.status(201).json({ user }); } catch (error) { if (error instanceof z.ZodError) { return res.status(400).json({ error: error.errors }); } logger.error('Failed to create user', { error }); res.status(500).json({ error: 'Internal server error' }); } }); ```

undefined

```typescript import { z } from 'zod';

const createUserSchema = z.object({ name: z.string().min(1), email: z.string().email(), });

app.post('/api/users', async (req, res) => { try { const data = createUserSchema.parse(req.body); const user = await db.users.create(data); res.status(201).json({ user }); } catch (error) { if (error instanceof z.ZodError) { return res.status(400).json({ error: error.errors }); } logger.error('创建用户失败', { error }); res.status(500).json({ error: '内部服务器错误' }); } }); ```

undefined

ApplyTo Patterns

ApplyTo匹配规则

Common Glob Patterns

常用Glob匹配模式

yaml

undefined

yaml

undefined

All TypeScript files

所有TypeScript文件

applyTo: "**/*.ts"

React components

React组件

applyTo: "src/**/*.{tsx,jsx}"

API routes

API路由

applyTo: "src/api/**/*.ts"

Test files

测试文件

applyTo: "**/*.test.ts"

All files (any of these work)

所有文件（以下写法均可）

applyTo: "" applyTo: "*" applyTo: "/*"

Multiple patterns (array)

多匹配规则（数组形式）

applyTo:

"src/api/**/*.ts"
"src/services/**/*.ts"
"src/routes/**/*.ts"

undefined

applyTo:

"src/api/**/*.ts"
"src/services/**/*.ts"
"src/routes/**/*.ts"

undefined

ExcludeAgent Field

ExcludeAgent字段

Control which Copilot agent uses the instructions:

控制哪些Copilot Agent会使用这些指令：

Coding Agent Only

仅适用于编码Agent

markdown

---
applyTo: "**"
excludeAgent: "code-review"
---

markdown

---
applyTo: "**"
excludeAgent: "code-review"
---

Coding Agent Only Instructions

仅编码Agent适用的指令

These instructions are only used by the Copilot coding agent.

Focus on implementation patterns
Suggest modern syntax alternatives
Optimize for readability in generated code

undefined

这些指令仅会被Copilot编码Agent使用。

聚焦于实现模式
推荐现代语法替代方案
优化生成代码的可读性

undefined

Code Review Only

仅适用于代码评审Agent

markdown

---
applyTo: "**/*.test.ts"
excludeAgent: "coding-agent"
---

markdown

---
applyTo: "**/*.test.ts"
excludeAgent: "coding-agent"
---

Code Review Only Instructions

仅代码评审Agent适用的指令

These instructions are only used by Copilot code review.

Verify test coverage is adequate
Check for proper assertions
Ensure tests are not flaky

undefined

这些指令仅会被Copilot代码评审Agent使用。

验证测试覆盖率是否足够
检查断言是否合理
确保测试用例不存在不稳定问题

undefined

Content Format

内容格式

Natural language markdown with:

Clear headings: Organize with H1/H2
Bullet points: For lists of rules
Code examples: Show concrete patterns
Plain language: Write for human readability
Actionable guidance: Specific, not generic

使用自然语言Markdown，包含：

清晰的标题：使用H1/H2层级组织内容
项目符号：用于列出规则列表
代码示例：展示具体的代码模式
简洁语言：以人类易读的方式编写
可执行的指导：具体明确，而非泛泛而谈

Example: Testing Standards

示例：测试标准

markdown

---
applyTo: "**/*.test.ts"
---

markdown

---
applyTo: "**/*.test.ts"
---

Testing Standards

测试标准

All tests use Jest and React Testing Library.

所有测试使用Jest和React Testing Library。

Component Tests

组件测试

Test user interactions, not implementation
Use
```
screen.getByRole
```
over
```
getByTestId
```
Mock external dependencies
Test accessibility (ARIA roles)

测试用户交互，而非内部实现
使用
```
screen.getByRole
```
替代
```
getByTestId
```
Mock外部依赖
测试可访问性（ARIA角色）

Example

示例

```typescript test('submits form when valid', async () => { render(<LoginForm />);

await userEvent.type(screen.getByLabelText('Email'), 'test@example.com'); await userEvent.type(screen.getByLabelText('Password'), 'password123'); await userEvent.click(screen.getByRole('button', { name: 'Login' }));

expect(mockLogin).toHaveBeenCalledWith({ email: 'test@example.com', password: 'password123', }); }); ```

undefined

```typescript test('表单验证通过后提交', async () => { render(<LoginForm />);

await userEvent.type(screen.getByLabelText('邮箱'), 'test@example.com'); await userEvent.type(screen.getByLabelText('密码'), 'password123'); await userEvent.click(screen.getByRole('button', { name: '登录' }));

expect(mockLogin).toHaveBeenCalledWith({ email: 'test@example.com', password: 'password123', }); }); ```

undefined

Example: Database Patterns

示例：数据库模式

markdown

---
applyTo:
  - "src/db/**/*.ts"
  - "src/repositories/**/*.ts"
---

markdown

---
applyTo:
  - "src/db/**/*.ts"
  - "src/repositories/**/*.ts"
---

Database Access Patterns

数据库访问模式

We use Prisma ORM with PostgreSQL.

我们使用Prisma ORM与PostgreSQL。

Query Guidelines

查询指南

Always use transactions for multi-step operations
Use
```
select
```
to limit returned fields
Include proper indexes
Handle unique constraint violations

多步骤操作始终使用事务
使用
```
select
```
限制返回字段
添加合适的索引
处理唯一约束冲突

Example

示例

```typescript // Good: Transaction with error handling async function transferFunds(fromId: string, toId: string, amount: number) { try { await prisma.$transaction(async (tx) => { await tx.account.update({ where: { id: fromId }, data: { balance: { decrement: amount } }, });

  await tx.account.update({
    where: { id: toId },
    data: { balance: { increment: amount } },
  });
});

} catch (error) { if (error.code === 'P2025') { throw new Error('Account not found'); } throw error; } } ```

undefined

```typescript // 推荐：带错误处理的事务 async function transferFunds(fromId: string, toId: string, amount: number) { try { await prisma.$transaction(async (tx) => { await tx.account.update({ where: { id: fromId }, data: { balance: { decrement: amount } }, });

  await tx.account.update({
    where: { id: toId },
    data: { balance: { increment: amount } },
  });
});

} catch (error) { if (error.code === 'P2025') { throw new Error('账户不存在'); } throw error; } } ```

undefined

Common Mistakes

常见错误

Mistake	Fix
Frontmatter in repo-wide	Repository-wide uses NO frontmatter
Missing .instructions.md suffix	Path-specific files must end with `.instructions.md`
Missing applyTo field	Path-specific requires `applyTo` in frontmatter
Generic advice	Focus on project-specific patterns
No code examples	Show concrete patterns from your project

错误	修复方案
仓库级指令中包含前置元数据	仓库级指令不能包含前置元数据
缺少.instructions.md后缀	路径特定文件必须以 `.instructions.md` 结尾
缺少applyTo字段	路径特定指令的前置元数据中必须包含 `applyTo` 字段
通用化建议	聚焦于项目特定的代码模式
无代码示例	展示项目中的具体代码模式

Validation

验证

Schema location:

/Users/khaliqgant/Projects/prpm/app/packages/converters/schemas/copilot.schema.json

Documentation:

/Users/khaliqgant/Projects/prpm/app/packages/converters/docs/copilot.md

Schema路径：

/Users/khaliqgant/Projects/prpm/app/packages/converters/schemas/copilot.schema.json

文档路径：

/Users/khaliqgant/Projects/prpm/app/packages/converters/docs/copilot.md

Best Practices

最佳实践

Be specific: Generic advice is less useful than project-specific patterns
Show examples: Code samples are more effective than descriptions
Keep it short: Copilot processes limited context
Natural language: Write as you would explain to a developer
Update regularly: Keep instructions in sync with codebase
Granular targeting: Use path-specific for different contexts
Descriptive filenames: Use clear names like
```
api-endpoints.instructions.md
```

具体明确：项目特定的模式比通用建议更有用
展示示例：代码示例比文字描述更有效
保持简洁：Copilot处理的上下文有限
自然语言：以向开发者解释的语气编写
定期更新：保持指令与代码库同步
精准定位：对不同场景使用路径特定指令
文件名清晰：使用如
```
api-endpoints.instructions.md
```
这类明确的文件名

Storage Locations

存储位置

Instructions can be stored in multiple locations:

Repository:
```
.github/copilot-instructions.md
```
(repository-wide)
Repository:
```
.github/instructions/*.instructions.md
```
(path-specific)
Team Dashboard: Created via Copilot Dashboard for team sharing

Remember: Repository-wide uses NO frontmatter. Path-specific requires

applyTo

field and

.instructions.md

suffix.

指令可以存储在多个位置：

代码仓库：
```
.github/copilot-instructions.md
```
（仓库级）
代码仓库：
```
.github/instructions/*.instructions.md
```
（路径特定）
团队仪表盘：通过Copilot Dashboard创建，用于团队共享

注意：仓库级指令不能包含前置元数据。路径特定指令必须包含

applyTo

字段，且文件后缀为

.instructions.md

。