Auto Path Header: Tiện ích VSCode giúp AI và lập trình viên không bị lạc trong dự án

Bạn đã bao giờ mở một file mã nguồn và tự hỏi: "File này nằm ở đâu trong cấu trúc dự án?" chưa? Hoặc khi bạn sao chép một đoạn code để nhờ trợ lý AI hỗ trợ, nó lại đưa ra lời khuyên về utils.js chung chung mà không hiểu đó thực chất là src/features/auth/utils.js chứ không phải src/shared/utils.js?

Tôi gặp phải vấn đề này liên tục, đặc biệt là khi dự án phát triển đến hàng trăm file, khi phải làm việc đồng thời với nhiều file có tên giống nhau, hoặc khi cố gắng giải thích ngữ cảnh của một task cho AI.

Đó là lý do tôi tạo ra Auto Path Header — một tiện ích mở rộng cho VSCode tự động thêm đường dẫn của file trực tiếp vào dòng đầu tiên của mỗi file mã nguồn.

Demo Auto Path Header

Vấn đề: Mất ngữ cảnh

Hãy tưởng tượng một kịch bản điển hình. Bạn đang mở 15 tab trên VSCode. Trong đó có ba file tên là index.ts và hai file tên là utils.js. Bạn chuyển đổi qua lại giữa chúng và mỗi lần đều phải nhìn lên thanh breadcrumbs (đường dẫn) ở trên cùng hoặc di chuột vào tab để hiểu mình đang ở đâu.

Tệ hơn nữa — bạn sao chép code vào ChatGPT hoặc Claude để nhờ hỗ trợ tái cấu trúc (refactoring). AI chỉ nhìn thấy:

export function validateUser(user) {
  // ...
}

Và nó bắt đầu đưa ra những lời khuyên chung chung, không hiểu rằng đây là một file thuộc module xác thực (authentication module), vốn phải hoạt động với các kiểu dữ liệu và dependencies cụ thể của dự án bạn.

Giải pháp: Đường dẫn ngay trong file

Auto Path Header tự động thêm một dòng comment chứa đường dẫn đầy đủ của file vào ngay đầu trang:

// src/features/auth/validators/user.validator.js

export function validateUser(user) {
  // ...
}

Đơn giản? Có. Hiệu quả? Chắc chắn rồi.

Cách nó hoạt động trong thực tế

Tình huống 1: Điều hướng trong dự án lớn

Bạn đang làm việc trên kiến trúc microservices. Dự án của bạn có:

• services/user/api/routes/index.ts
• services/order/api/routes/index.ts
• services/payment/api/routes/index.ts

Khi mở một file, bạn sẽ ngay lập tức thấy mình đang ở đâu mà không cần nhìn vào thanh điều hướng hay tab. Thông tin nằm ngay trước mắt.

Tình huống 2: Review code với AI

Bạn sao chép code để nhờ AI review:

// backend/src/modules/payments/services/stripe.service.ts

import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class StripeService {
  constructor(private config: ConfigService) {}

  async createPayment(amount: number) {
    // implementation
  }
}

AI ngay lập tức hiểu được:

• Đây là code backend, không phải frontend.
• Đây là module thanh toán (payments).
• Đây là service dùng để làm việc với Stripe.
• Dự án sử dụng NestJS.

Ngữ cảnh đã đầy đủ. Lời khuyên sẽ chính xác. Không còn những câu hỏi "file này để làm gì?" hay "đây là cho client hay server?".

Tình huống 3: Làm việc với các file tương tự

Dự án của bạn có nhiều file cấu hình:

• config/database.config.ts
• config/redis.config.ts
• config/auth.config.ts
• tests/config/database.config.ts

Nếu không có đường dẫn trong file, sự nhầm lẫn là điều khó tránh khỏi. Với Auto Path Header, mọi thứ đều đúng vị trí của nó.

Tối ưu hóa cho Trợ lý AI

Phát triển phần mềm hiện đại ngày càng phụ thuộc vào các trợ lý AI. Tuy nhiên, khi bạn sao chép code vào một LLM bên ngoài (như ChatGPT, Claude), nó sẽ mất ngữ cảnh của dự án.

Các trợ lý nội bộ như Cursor có thể giải quyết vấn đề này vì chúng nhìn thấy cây thư mục, nhưng các công cụ bên ngoài thì không.

Lưu ý quan trọng: Cursor và Copilot Chat tự nhìn thấy cấu trúc cây thư mục (project tree), nên chúng không cần đường dẫn trong file.

Tuy nhiên, tiện ích này rất hữu ích cho bạn (khi đọc code) và cho các LLM bên ngoài (ChatGPT, Claude).

Điều này có ý nghĩa gì trong thực tế?

Khi không có đường dẫn:

export const config = {
  port: 3000
}

AI nghĩ: "Ok, đây là một file config nào đó. Tôi sẽ đưa ra lời khuyên chung chung."

Khi có đường dẫn:

// apps/api-gateway/config/server.config.js

export const config = {
  port: 3000
}

AI hiểu: "Đây là config của API Gateway. Cổng 3000 có thể xung đột với các dịch vụ khác. Cần kiểm tra docker-compose và đề xuất chuyển nó sang biến môi trường."

Sự khác biệt là rất lớn.

Các tính năng nổi bật

Cập nhật tự động

Bạn đã đổi tên thư mục? Di chuyển file? Đường dẫn sẽ tự động cập nhật ngay sau khi đổi tên.

Hỗ trợ mọi ngôn ngữ lập trình

Tiện ích này biết cú pháp comment của hầu hết các ngôn ngữ lập trình. Bạn có thể tùy chỉnh định dạng comment cho bất kỳ loại file nào thông qua cài đặt customTemplatesByExtension:

{
  "autoPathHeader.customTemplatesByExtension": {
    ".anyExt": "anyExt file path: {path|toUpperCase}",
    ".ts": "// 📁 {path}",
    ".tsx": "// ⚛️ {path} → {filename}",
    ".py": "# 🐍 {filename} ({path})",
    ".env": "# 🔐 {path}",
    ".env.local": "# LOCAL OVERRIDE — {path}",
    ".test.ts": "// 🧪 TEST: {path}",
    "Dockerfile.dev": "# DEV BUILD: {absolutePath|unix|toUpperCase}",
    ".txt": "# TEXT FILE: {path}",
    ".log": "// LOG FILE: {path|toLowerCase}"
  }
}

Các bộ lọc như unix, toLowerCase, toUpperCase đều được hỗ trợ.

Hoạt động ngầm

• Đường dẫn được tự động thêm vào đầu file.
• Tự động cập nhật khi đổi tên file hoặc thư mục.
• Hỗ trợ nhiều định dạng comment tùy theo ngôn ngữ.
• Bạn có thể giới hạn vị trí xuất hiện của header.

Đối với các file đã có sẵn, bạn có thể chèn đường dẫn thủ công bằng cách: Ctrl+Shift+P → Auto Path Header: Insert Path Comment

Các trường hợp sử dụng thực tế

Monorepositories

Trong một monorepo với hàng chục package và module chia sẻ, đường dẫn trong file trở nên cực kỳ cần thiết. Bạn thấy ngay lập tức code nằm trong package nào:

// packages/ui-kit/src/components/Button/Button.tsx
// so với
// apps/web-app/src/components/Button/Button.tsx

Hai component Button, hai ngữ cảnh hoàn toàn khác nhau.

Microservices

Khi bạn có 5–10 dịch vụ với cấu trúc tương tự, đường dẫn giúp bạn không bị lạc:

// services/user-service/src/api/controllers/user.controller.js
// services/auth-service/src/api/controllers/user.controller.js

Học tập và hội nhập (Onboarding)

Một lập trình viên mới mở dự án. Mỗi file chứa một gợi ý về vị trí của nó. Nó giống như một bản đồ tích hợp của dự án.

Tài liệu và hướng dẫn

Viết bài kỹ thuật hoặc hướng dẫn? Các ví dụ code có đường dẫn sẽ giúp người đọc hiểu ngay cấu trúc dự án.

Cấu hình

Sau khi cài đặt, tiện ích hoạt động ngay lập tức. Mặc định, các cài đặt sau được bật:

{
  "autoPathHeader.updateOnRename": true,
  "autoPathHeader.updateOnRenameRecursive": true
}

Đổi tên thư mục profile thành user-profile? Header sẽ tự động cập nhật trong tất cả 20 file bên trong. Bạn không còn cần sửa comment thủ công nữa.

Cài đặt linh hoạt:

{
  "autoPathHeader.allowedOnlyDirectories": [
    "src",
    "**/utils",
    "src/**/*.ts"
  ],
  "autoPathHeader.ignoredDirectories": [
    "temp",
    "**/node_modules",
    "dist/*"
  ]
}

Khi nào KHÔNG nên dùng?

Tiện ích này rất hữu ích, nhưng không dành cho mọi trường hợp:

• Dự án nhỏ (3–10 file): Đường dẫn quá rõ ràng, không cần comment.
• Public npm packages: Đường dẫn của nhà phát triển có thể bị đưa vào production (nếu không cấu hình ignore).
• Linter quá nghiêm ngặt: Một số công cụ cấm comment ở đầu file.
• File có shebang (#!/usr/bin/env node): Comment phải được đặt sau dòng này.

Kết luận

Auto Path Header là một tiện ích nhỏ giải quyết vấn đề lớn về mất ngữ cảnh. Nó hữu ích cho cả lập trình viên (điều hướng), AI (lời khuyên chính xác), và cả đội ngũ (onboarding, PR, tài liệu).

Hãy cài đặt và cấu hình theo ý bạn — và quên đi câu hỏi "file này nằm ở đâu?".