> For AI agents: the complete documentation index is available at https://nhanbe.id.vn/llms.txt, the full documentation bundle is available at https://nhanbe.id.vn/llms-full.txt.

# GitHub Copilot trong VS Code

Mở một repo lạ, chạy thử, gặp lỗi. Việc đầu tiên thường là đọc code để hiểu luồng chạy. Copilot trong VS Code giúp được ở đúng những bước đó.

Note này gom lại những tính năng tôi thấy hữu ích cho hai việc: hiểu codebase và debug. Phần Agents window nằm ở cuối.

## Cài Đặt Nhanh

Cài extension **GitHub Copilot** và đăng nhập bằng tài khoản GitHub. Chat view mở bằng `Ctrl+Alt+I`.

Vài phím hay dùng:

| Phím         | Việc                                 |
| ------------ | ------------------------------------ |
| `Tab`        | Nhận inline suggestion               |
| `Ctrl+I`     | Inline chat trên đoạn code đang chọn |
| `Ctrl+Alt+I` | Mở Chat view                         |

## Đọc Hiểu Codebase

Repo lạ thì đừng hỏi chung chung. Hỏi theo luồng, và gắn đúng context.

```text
Giải thích luồng login từ lúc nhận request đến khi trả token.
Bắt đầu từ #file:src/auth/login.ts. Chưa sửa gì.
```

Dùng `#` để gắn context trực tiếp trong prompt: `#file`, `#selection`, `#codebase`. Dán URL của issue hoặc pull request vào prompt cũng được, nó tự thành attachment.

Với việc lớn, chuyển sang chế độ **Plan** trước. Agent sẽ đọc code, đưa ra kế hoạch, và chưa đụng vào file nào. Đọc plan xong chỉnh vài chỗ rồi mới cho chạy. Đỡ tốn công hơn nhiều so với review một diff dài.

Mỗi lần agent sửa file đều có **checkpoint**. Thử hướng sai thì quay lại ngay từ cuộc hội thoại.

## Dạy Copilot Về Repo

Agent làm tốt hay dở phần lớn do context. Có vài file đặt trong `.github/` để cố định context đó.

```text title="Cấu trúc thư mục"
.github/
├── copilot-instructions.md        # luật chung cho cả repo
├── instructions/
│   └── tests.instructions.md      # luật theo glob, ví dụ **/*.test.ts
├── prompts/
│   └── review-pr.prompt.md        # prompt dùng lại, gọi bằng /review-pr
├── agents/
│   └── reviewer.agent.md          # custom agent với tool riêng
└── skills/
    └── some-skill/
        └── SKILL.md               # nạp khi task cần
```

```md title=".github/instructions/tests.instructions.md"
---
applyTo: '**/*.test.ts'
description: 'Quy ước viết unit test'
---

- Dùng Vitest, không dùng Jest.
- Mỗi test chỉ assert một hành vi.
```

`copilot-instructions.md` luôn được nạp, nên giữ ngắn. Chỉ ghi những thứ agent hay làm sai. Luật theo ngôn ngữ hoặc thư mục thì để vào `*.instructions.md` với `applyTo`.

:::tip\[Giữ instruction ngắn]
File dài mấy trăm dòng thường bị bỏ qua một nửa. Agent sai cùng một lỗi hai lần thì hãy thêm luật.
:::

## Debug Với Copilot

Đây là phần có nhiều thay đổi nhất. Copilot không chỉ giải thích lỗi nữa. Nó có thể tái hiện, sửa và kiểm chứng.

### Từ Lỗi Có Sẵn

Những chỗ có thể bấm ngay:

- **Quick Fix** (bóng đèn) trên đường gạch đỏ, chọn **Fix using Copilot**.
- **Test Explorer**: rê chuột lên test fail, chọn nút sửa lỗi test.
- **Terminal**: bôi đen đoạn lỗi rồi mở chat, nó tự lấy phần bôi đen làm context.

Cách này hợp với lỗi nhỏ, rõ ràng. Còn bug logic thì cần quy trình khác.

### Quy Trình Cho Bug Logic

VS Code có hẳn một tutorial sửa bug phân trang bằng agent. Tôi giữ lại khung của nó vì áp dụng được cho hầu hết bug:

1. **Tái hiện trước.** Nhờ agent viết một test fail đúng theo bug report.
2. **Tìm nguyên nhân.** Đọc code theo luồng, chưa sửa.
3. **Sửa tối thiểu.** Chỉ đụng phần gây lỗi.
4. **Chạy lại toàn bộ test.** Test mới phải pass, test cũ không được vỡ.

```text
API /issues?page=2 đang bỏ sót bản ghi ở ranh giới trang.
1. Viết một test fail tái hiện lỗi này, chưa sửa code.
2. Chỉ ra nguyên nhân.
3. Sửa tối thiểu, rồi chạy lại toàn bộ test.
```

Bước 1 là bước dễ bị bỏ. Không có test fail thì không biết bản sửa có thật sự đúng không.

### Browser Tools: Debug Frontend

Agent có thể tự mở app trong integrated browser, thao tác, đọc console error, chụp screenshot, rồi sửa và kiểm tra lại. Không cần cài MCP server ngoài.

```text
Chạy app, mở trong browser, thử luồng đăng ký.
Sửa mọi lỗi tìm thấy và xác nhận lại trước khi dừng.
```

Một vòng điển hình: chạy dev server, mở trang, đọc console và screenshot, sửa, lặp lại. Bạn xem được từng tool call (`openBrowserPage`, `readPage`, `clickElement`, `screenshotPage`...) ngay trong chat. Khi flow phức tạp, nó còn chạy được đoạn Playwright qua `runPlaywrightCode`.

Câu cuối của prompt quan trọng: nói rõ kết quả mong đợi, và bảo nó verify.

### Khi Chính Agent Làm Sai

Đôi khi agent bỏ qua instruction, sửa nhầm file, hoặc không thấy file nó cần. Lúc này cần nhìn xem nó đã làm gì.

Bật **Agent Debug Logs**:

```json title="settings.json"
{
  "github.copilot.chat.agentDebugLog.enabled": true
}
```

Rồi mở bằng menu `...` của Chat view, hoặc Command Palette: `Developer: Open Agent Debug Log`. Panel có ba góc nhìn:

- **Logs**: timeline các tool call, LLM request, prompt file được nạp, lỗi.
- **Summary**: tổng số tool call, token, lỗi, thời gian.
- **Agent Flow Chart**: các agent và subagent chuyển việc cho nhau thế nào.

Kèm theo là lệnh `/troubleshoot`, dùng để hỏi ngược lại chính log:

```text
/troubleshoot liệt kê các đường dẫn bạn đã thử nạp customization
/troubleshoot lượt trả lời trước sửa một file không ai yêu cầu, tại sao?
```

:::warning\[Log có thể chứa dữ liệu nhạy cảm]
Log chứa source code và có thể cả API key. Kiểm tra trước khi gửi cho ai. Mặc định log cũng không giữ lại sau khi tắt VS Code, trừ khi bạn bật file logging.
:::

## Review Và Commit

Trong Source Control có nút sparkle để sinh commit message từ diff. Muốn review trước khi commit thì hỏi thẳng trong chat:

```text
Review các thay đổi hiện tại. Tìm bug, thiếu test, và chỗ ảnh hưởng đến API cũ.
Chỉ liệt kê, không sửa.
```

Cho nó chạy với cùng một repo nhưng một **custom agent** chỉ có tool đọc (`reviewer.agent.md`). Khi đó chắc chắn không file nào bị sửa.

## Việc Dài Hơi: Subagents, Automations, MCP

Một số việc không nên nhét hết vào một chat.

**Subagents.** Agent chính giao phần nghiên cứu hoặc việc phụ cho agent con, mỗi con có context riêng. Chat chính không bị đầy bởi log tìm kiếm.

**Automations.** Chạy một prompt theo lịch (theo giờ, ngày, tuần) trong Agents window. Hợp với việc lặp lại như kiểm tra dependency cũ.

**MCP.** Nối agent với thứ ngoài editor, ví dụ GitHub. Thêm bằng `MCP: Add Server`. Có thể lưu vào `~/.copilot/mcp-config.json` (dùng chung mọi workspace) hoặc `.mcp.json` ở root repo.

```json title=".mcp.json"
{
  "servers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}
```

:::warning\[MCP server chạy code trên máy bạn]
Chỉ thêm server từ nguồn bạn tin.
:::

## Agents Window

Agents window là cửa sổ VS Code riêng, nằm cạnh cửa sổ editor. Editor dùng khi bạn tự viết code. Agents window dùng khi bạn giao việc rồi theo dõi.

Mở bằng một trong các cách sau:

- Nút **Open in Agents** trên title bar.
- Command Palette: `Chat: Open Agents window`.
- Terminal: `code --agents`.

Mỗi **session** là một đơn vị công việc có trạng thái riêng. Có panel Changes để xem diff, Files để duyệt workspace, terminal và browser gắn theo từng session.

Bắt đầu bằng `Ctrl+N`, chọn folder hoặc repo, gõ prompt. Nhấn `Alt+Enter` để chạy nền mà không rời session hiện tại.

Phần thú vị nhất là **isolation**. Chọn worktree thì mỗi session có branch, thay đổi và PR riêng. Hai agent chạy song song trên cùng một checkout sẽ giẫm lên nhau, nên worktree gần như bắt buộc khi chạy nhiều session.

```json title="settings.json"
{
  "git.worktreeSymlinkFolders": ["node_modules"]
}
```

Setting thử nghiệm này tạo symlink các folder ignored (như `node_modules`) khi VS Code tạo worktree mới. Đỡ phải cài lại dependency mỗi lần. Đổi lại, các worktree dùng chung một thư mục, nên đổi dependency ở một nơi sẽ ảnh hưởng nơi khác.

Còn vài thứ khác cũng nằm ở đây: chạy session trong Dev Container, trên remote host, hoặc nhiều chat cùng một session với mỗi chat một worktree. Phần lớn còn đang thử nghiệm, nên tôi chưa ghi chi tiết.

## Kết

Với codebase lạ, gắn đúng context và dùng Plan trước. Với bug, bắt đầu bằng một test fail. Với agent làm sai, đọc log thay vì đoán.

Còn instructions trong `.github/` là thứ nên làm sớm nhất. Nó áp dụng cho mọi tính năng ở trên.

## Tham khảo

- [VS Code release notes](https://code.visualstudio.com/updates)
- [Tutorial: Fix an API bug with an agent](https://code.visualstudio.com/docs/copilot/guides/debug-with-copilot)
- [Browser tools](https://code.visualstudio.com/docs/agents/run/browser-tools)
- [Agents window](https://code.visualstudio.com/docs/agents/run/agents-window)