GitHub Copilot Custom Instructions Complete Guide - Practical Approaches to Optimize Team Development¶

# ❌ Not Recommended: Direct large context description
Coding Standards:
1. Use camelCase for variables
2. Function names start with verbs
3. Use PascalCase for class names
4. Indent with 2 spaces
5. Use double quotes for string literals
6. Don't omit semicolons
... (extensive detailed conventions continue)

# ✅ Recommended: Leverage reference patterns
Refer to [coding-standards.md](./docs/coding-standards.md) for coding conventions.
Follow [debugging-guide.md](./docs/debugging-guide.md) for debugging procedures.
Check [api-design.md](./docs/api-design.md) for API design policies.

project-root/
├── .github/
│   ├── copilot-instructions.md      # Main custom instructions
│   └── instructions/                # Additional instruction files
│       ├── frontend.instructions.md
│       ├── backend.instructions.md
│       └── testing.instructions.md
├── docs/
│   ├── coding-standards.md          # Detailed coding standards
│   ├── debugging-guide.md           # Debugging procedures
│   ├── api-design.md               # API design guidelines
│   ├── deployment-guide.md         # Deployment procedures
│   └── troubleshooting.md          # Troubleshooting
└── README.md

# Project Development Guidelines

## Basic Policy
This project is built with Next.js + TypeScript + Tailwind CSS.

## Reference Documents
- Coding Standards: [docs/coding-standards.md](./docs/coding-standards.md)
- API Design Policy: [docs/api-design.md](./docs/api-design.md)
- Testing Strategy: [docs/testing-strategy.md](./docs/testing-strategy.md)
- Deployment Procedures: [docs/deployment-guide.md](./docs/deployment-guide.md)

## Technology Stack Specific Instructions
- Use TypeScript in strict mode
- Avoid abbreviations in Tailwind CSS class names, use clear ones
- Always specify proper dependency arrays for React Hooks
- Always implement error handling

## File Naming and Directory Structure
- Component files: PascalCase.tsx
- Utility files: camelCase.ts
- Constant files: UPPER_SNAKE_CASE.ts

# Providing graduated detail levels

## Level 1: Immediately necessary information
- Technology: React 18 + TypeScript + Vite
- Package Manager: pnpm (npm/yarn prohibited)
- Code Formatter: Prettier + ESLint

## Level 2: Detailed Guidelines
- Detailed coding standards: [docs/detailed-coding-standards.md](./docs/detailed-coding-standards.md)
- Architecture design: [docs/architecture-guide.md](./docs/architecture-guide.md)

## Level 3: Special Case Handling
- Performance optimization: [docs/performance-guide.md](./docs/performance-guide.md)
- Security guidelines: [docs/security-guidelines.md](./docs/security-guidelines.md)

# Role-separated instructions

## Frontend Development
Refer to [#file:./instructions/frontend.instructions.md](./instructions/frontend.instructions.md)

## Backend Development
Refer to [#file:./instructions/backend.instructions.md](./instructions/backend.instructions.md)

## DevOps & Infrastructure
Refer to [#file:./instructions/devops.instructions.md](./instructions/devops.instructions.md)

# Project-specific short-term context
- Current sprint goal: Authentication feature implementation
- Priority bugs: [docs/current-issues.md](./docs/current-issues.md)

# Long-term project policies
- Product strategy: [docs/product-strategy.md](./docs/product-strategy.md)
- Technical debt handling: [docs/technical-debt.md](./docs/technical-debt.md)

# New Engineer Onboarding

## 🚀 Essential Initial Reading
1. [Project Overview](./docs/project-overview.md) - Complete project understanding in 10 minutes
2. [Development Environment Setup](./docs/setup-guide.md) - Complete environment setup procedures
3. [Coding Standards](./docs/coding-standards.md) - Minimum rules to follow

## 🔧 Daily Development References
- [Debugging Procedures](./docs/debugging-guide.md) - Investigation methods when issues occur
- [Testing Methods](./docs/testing-guide.md) - Local and CI testing procedures
- [Release Process](./docs/release-process.md) - Deployment and release workflow

## 💬 Q&A References
- [FAQ](./docs/faq.md) - Frequently asked questions and answers
- [Troubleshooting](./docs/troubleshooting.md) - Known issues and solutions

# Team Development Guidelines

## 🔄 Development Flow
1. Before implementation: Create [Feature Design Template](./docs/templates/feature-design.md)
2. Code implementation: Follow [Coding Standards](./docs/coding-standards.md)
3. Test creation: Based on [Testing Strategy](./docs/testing-strategy.md)
4. Review request: Check [Review Guidelines](./docs/review-guidelines.md)

## 🚨 Emergency Response
- Production incidents: [Incident Response Procedures](./docs/incident-response.md)
- Security issues: [Security Incident Procedures](./docs/security-incident.md)

# Effective instruction examples

## Technology Choice Instructions
- Use Prisma ORM for database queries (avoid raw SQL)
- Use Zustand for state management (don't use Redux)
- Implement UI components based on shadcn/ui

## File Output Instructions
- Always specify target file names when outputting code
- When multiple files need changes, display them separately by file

## Error Handling Instructions
- Ask clear questions instead of guessing when uncertain
- Follow [Debug Guide](./docs/debugging-guide.md) procedures when errors occur

## Reference Documents
- Detailed API specification: [api-spec.yaml](./docs/api-spec.yaml)
- Design system: [design-system.md](./docs/design-system.md)

# Problematic examples

## External Resource Dependencies (avoid)
- Refer to style guide at https://external-site.com/styleguide
- Follow styleguide.md in external my-org/my-repo repository

## Vague Instructions (avoid)
- "Answer in friendly colleague style"
- "Answer within 1000 characters"
- "Use words no longer than 12 characters"

## Context Overload (avoid)
Directly writing extensive coding standards, API specifications, design documents...

{
  "github.copilot.chat.codeGeneration.useInstructionFiles": true,
  "github.copilot.chat.codeGeneration.instructions": [
    "Project-specific supplementary instructions",
    "Special local environment settings"
  ],
  "chat.instructionsFilesLocations": {
    ".github/instructions/**/*.instructions.md": true,
    "docs/instructions/**/*.md": true
  }
}

#!/bin/sh
# .git/hooks/pre-commit

# Check for custom instruction file changes
if git diff --cached --name-only | grep -q "copilot-instructions.md"; then
    echo "📝 Copilot instructions updated. Team notification recommended."
fi

# Instruction Improvement Cycle

## Monthly Review
- [ ] Reflect new technologies/tools added
- [ ] Collect and address team feedback
- [ ] Verify currency of reference documents

## Quarterly Review
- [ ] Reflect project policy changes
- [ ] Organize infrequently used instructions
- [ ] Consider introducing new best practices