Bài 11: Custom Instructions — Dạy AI theo coding style của bạn

Vibe Coding với GitHub Copilot: Từ Cơ bản đến Nâng cao

Phần 4: Customize & Extend Copilot

xdev.asia

1. Custom Instructions là gì?

Custom Instructions là các quy tắc tĩnh mà bạn viết để Copilot tự động áp dụng cho mọi tương tác trong project. Thay vì phải nhắc lại conventions mỗi lần prompt, bạn viết một lần và Copilot tuân theo.

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. Các loại Custom Instructions

2.1. Project-level: .github/copilot-instructions.md

Áp dụng cho toàn bộ project, chia sẻ qua Git cho cả team:

# 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. File-type specific: .instructions.md

Áp dụng cho file types cụ thể dựa trên applyTo pattern:

<!-- .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. User-level instructions

Áp dụng cho mọi project trên máy bạn (VS Code Settings):

{
  "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. Dùng /init để tự động tạo Instructions

Thay vì viết từ đầu, chạy /init trong Chat view:

1. Copilot scan toàn bộ codebase
2. Phát hiện patterns, conventions, tech stack
3. Tạo .github/copilot-instructions.md dựa trên code hiện tại
4. Bạn review và điều chỉnh

// 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. Cấu trúc Instructions hiệu quả

✅ DO:

• Ngắn gọn, cụ thể: "Use Zod for validation" tốt hơn "Make sure to validate properly"
• Actionable rules: AI có thể follow ngay
• Reference files: "Follow pattern in src/services/UserService.ts"
• Chia theo section: Style, Testing, API, Git

❌ DON'T:

• Quá dài: > 2000 words làm tốn context window
• Quá chung chung: "Write clean code" — AI không biết "clean" nghĩa gì trong context bạn
• Contradictory: "Use classes" + "Use functional programming"
• Outdated: instructions không match code hiện tại

5. Instructions cho Team

Khi làm team, commit .github/copilot-instructions.md vào repo:

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

Khi mọi thành viên dùng Copilot, tất cả nhận cùng instructions → code nhất quán hơn.

6. Bài tập thực hành

1. Chạy /init trong project hiện tại
2. Review file instructions được tạo
3. Bổ sung: naming conventions, error handling strategy, testing approach
4. Tạo một .instructions.md cho file-type cụ thể (components hoặc API)
5. Test: prompt tạo code → xem AI có follow instructions không

7. Tổng kết

Loại	File	Scope
Project-level	.github/copilot-instructions.md	Toàn project, shared qua Git
File-type	.github/instructions/*.instructions.md	Specific file patterns (applyTo)
User-level	VS Code Settings	Mọi project trên máy

Custom Instructions là đầu tư một lần giúp mọi prompt sau đó cho kết quả tốt hơn. Bài tiếp theo sẽ cover Custom Agents & Agent Skills — tạo AI chuyên biệt cho từng task.