Giới thiệu
Nói thật, điều khiến tôi cảm thấy khó chịu mỗi khi sử dụng công cụ AI là phải liên tục giải thích về quy ước dự án, phong cách code và công nghệ sử dụng. Giống như phải giải thích "Tôi là ai?" cho một đồng nghiệp hay quên mỗi ngày, không chỉ lãng phí thời gian mà còn dễ dẫn đến sai sót.
Đó là lúc tôi phát hiện ra tính năng ẩn của Gemini CLI - tệp GEMINI.md. Thoạt nhìn, nó chỉ là một tệp Markdown bình thường, nhưng thực tế đây là "hệ thống ghi nhớ" của Gemini CLI. Chỉ cần viết các quy tắc dự án vào tệp này, AI sẽ ghi nhớ sở thích của bạn, và mã, tài liệu, thậm chí cả mô tả PR được tạo ra sẽ phù hợp với phong cách dự án.
Mẹo nhỏ: Không nên viết thông tin nhạy cảm như API Key hoặc mật khẩu vào đây. Sử dụng biến môi trường hoặc quản lý bí mật sẽ an toàn hơn.
Giờ đây, bạn không cần phải giải thích lại dự án cho AI, và có thể dành thời gian đó để viết code hoặc tập trung vào thiết kế logic!
Một、GEMINI.md là gì?
Nói đơn giản, GEMINI.md là "sổ tay hướng dẫn dự án" cho AI. Những thông tin bạn có thể truyền đạt cho AI qua tệp này:
- Quy ước coding và best practices của dự án
- Sở thích về phong cách code
- Thư viện và framework thường dùng
- Bối cảnh dự án và logic nghiệp vụ
Ví dụ, khi tôi sử dụng trong dự án React + TypeScript, tôi viết tất cả quy tắc đặt tên component, phương pháp quản lý state, yêu cầu về test coverage, và AI sẽ tạo ra code gần như không cần chỉnh sửa.
Kinh nghiệm: Tôi viết rõ ràng các quy tắc "bắt buộc" và đánh dấu các "sở thích" là tùy chọn. Điều này giúp AI không bị lúng túng khi tạo code.
Cách hoạt động
Gemini CLI tự động tìm kiếm tệp GEMINI.md khi khởi động và tải nội dung của nó làm ngữ cảnh (hay "bộ nhớ" của AI). Việc tìm kiếm được thực hiện đệ quy, từ thư mục hiện tại lên đến thư mục gốc của dự án, và tất cả các tệp GEMINI.md được tìm thấy sẽ được tích hợp. Trong đó, cài đặt gần với thư mục hiện tại hơn sẽ có độ ưu tiên cao hơn.
Ví dụ thực tế: Việc thư mục con có độ ưu tiên cao rất quan trọng vì một số module cụ thể cần các quy tắc đặc biệt mà không ảnh hưởng đến quy ước chung của toàn dự án.
Hai、Cài đặt phân tầng — Giúp AI hiểu sâu hơn về dự án
Hệ thống cài đặt 3 tầng
Gemini CLI hỗ trợ cài đặt GEMINI.md phân tầng, được phân loại từ độ ưu tiên thấp đến cao như sau:
- Cài đặt toàn cục:
~/.gemini/GEMINI.md(quy tắc chung áp dụng cho tất cả dự án) - Cài đặt dự án: Các tệp
GEMINI.mdnằm giữa thư mục hiện tại và thư mục gốc của dự án - Cài đặt thư mục con: Hướng dẫn dành riêng cho component hoặc module cụ thể (ghi đè cục bộ)
Ví dụ cài đặt thực tế
Dưới đây là ba ví dụ về các tầng mà tôi thường sử dụng trong nhiều dự án:
-
Cài đặt toàn cục (
~/.gemini/GEMINI.md):# Cài đặt môi trường phát triển của tôi ## Quy ước coding chung - Bao gồm comment chi tiết trong tất cả code - Sử dụng camelCase cho tên hàm - Ưu tiên TypeScript hơn JavaScript - Sử dụng khối try-catch cho xử lý lỗi ## Công nghệ ưa thích - Frontend: React + TypeScript + Tailwind CSS - Backend: Node.js + Express + MongoDB - Testing: Jest + React Testing Library
Kinh nghiệm: Đặt "phong cách/sở thích" ít thay đổi ở mức toàn cục sẽ giúp bạn không phải viết lại nhiều lần trong từng dự án.
-
Cài đặt thư mục gốc dự án (
./GEMINI.md):# Dự án trang thương mại điện tử ## Tổng quan dự án Đây là trang thương mại điện tử dựa trên kiến trúc microservice, bao gồm các chức năng chính như quản lý người dùng, quản lý sản phẩm, xử lý đơn hàng. ## Quy ước riêng của dự án - API tuân theo thiết kế RESTful - Sử dụng Prisma ORM cho tất cả thao tác cơ sở dữ liệu - Component frontend hỗ trợ thiết kế responsive - Code liên quan đến thanh toán cần kiểm tra bảo mật bổ sung ## Cấu trúc thư mục -`/src/components/` - React component có thể tái sử dụng -`/src/pages/` - Component cấp trang -`/src/api/` - Định nghĩa API -`/src/utils/` - Hàm tiện ích -
Cài đặt thư mục component (
./src/components/GEMINI.md):# Quy ước phát triển component ## Nguyên tắc thiết kế component - Mỗi component cần có file .stories.js tương ứng - Component hỗ trợ dark mode - Tất cả props cần có định nghĩa kiểu TypeScript - Bao gồm unit test cho component ## Quy ước về style - Sử dụng tên lớp Tailwind CSS - Tránh inline style - Ưu tiên thiết kế responsive
Kinh nghiệm: Quy tắc cục bộ (như trong thư mục component) có độ ưu tiên cao nhất, phù hợp để xử lý các "ngoại lệ" của quy tắc chung.
Ba、Quản lý module hóa — Làm cho cài đặt thanh lịch hơn
Khi dự án trở nên phức tạp, bạn có thể sử dụng cú pháp @file.md để import các tệp Markdown khác và module hóa cài đặt. Điều này giúp GEMINI.md dễ quản lý hơn và thuận tiện cho cộng tác nhóm.
Ví dụ sử dụng cú pháp @import
-
Tệp cài đặt chính (
GEMINI.md):# Dự án full-stack ## Cài đặt cơ bản @./docs/coding-standards.md @./docs/git-workflow.md ## Cài đặt riêng cho công nghệ @./frontend/react-guidelines.md @./backend/api-guidelines.md @./database/schema-guidelines.md -
Quy ước frontend (
./frontend/react-guidelines.md):# Quy ước phát triển React ## Cấu trúc component - Sử dụng function component và Hooks - Custom Hook bắt đầu bằng "use" - Tên file component theo PascalCase ## Quản lý state - useState cho state đơn giản - useReducer cho state phức tạp - Zustand cho state toàn cục
Kinh nghiệm: Đặt quy ước chung trong
docs/, còn quy ước riêng cho module/service trong thư mục con tương ứng. CI cũng có thể đồng bộ chỉ những tệp module cần thiết.
Bốn、Ví dụ thực tế — Từ không đến hợp tác hoàn hảo
Ví dụ 1: Cài đặt dự án React + TypeScript
Tạo dự án và khởi tạo GEMINI.md:
mkdir my-react-app
cd my-react-app
# Tạo tệp cài đặt chính
vim GEMINI.md
Cài đặt dự án đầy đủ:
# Dự án React TypeScript ## Thông tin dự án
- Tên dự án: Ứng dụng Todo hiện đại
- Công nghệ: React 18 + TypeScript + Vite + Tailwind CSS
- Quản lý state: Zustand
- Routing: React Router v6 ## Quy ước phát triển ### Phong cách code
- Thụt lề 2 dấu cách
- Ưu tiên dấu nháy đơn cho chuỗi
- Sử dụng destructuring cho props của component
- Tránh sử dụng kiểu any ### Quy ước component
- File component sử dụng phần mở rộng .tsx
- Tên component theo PascalCase
- Component xuất ra dưới dạng export default
- Mỗi component cần có định nghĩa kiểu tương ứng ### Quy ước style
- Thiết kế style bằng Tailwind CSS
- Ưu tiên thiết kế responsive (mobile first)
- Hỗ trợ dark mode
- Sử dụng biến CSS cho màu chủ đề ### Yêu cầu test
- Mỗi component cần có unit test
- Sử dụng React Testing Library
- Test coverage tối thiểu 80% ## Hướng dẫn riêng cho dự án
- Code được tạo ra bao gồm comment JSDoc chi tiết
- Bao gồm xử lý lỗi trong các lời gọi API
- Sử dụng react-hook-form + zod cho validation form
- Sử dụng React Query cho tất cả thao tác bất đồng bộ
Kinh nghiệm: Càng cụ thể càng tốt. Ví dụ, làm rõ định dạng JSDoc hoặc quy tắc đặt tên tham số sẽ giúp AI tạo ra comment nhất quán hơn.
Ví dụ 2: Cài đặt phân tầng cho dự án full-stack
Trong dự án full-stack phức tạp, sử dụng thư mục gốc làm "hợp đồng" và thực hiện ghi đè cục bộ trong thư mục con:
-
Thư mục gốc dự án (
./GEMINI.md):# Trang thương mại điện tử full-stack ## Kiến trúc dự án - Frontend: Next.js 14 + TypeScript - Backend: Node.js + Express + Prisma - Cơ sở dữ liệu: PostgreSQL - Triển khai: Docker + Kubernetes ## Quy ước chung @./docs/general-guidelines.md @./docs/security-guidelines.md @./docs/performance-guidelines.md ## Cài đặt môi trường - Môi trường phát triển: PostgreSQL cục bộ - Môi trường test: Cơ sở dữ liệu trong bộ nhớ - Môi trường sản xuất: Cơ sở dữ liệu đám mây -
Cài đặt frontend (
./frontend/GEMINI.md):# Quy ước phát triển frontend ## Quy ước riêng cho Next.js - Sử dụng App Router (không phải Pages Router) - Ưu tiên Server Component, Client Component khi cần thiết - Sử dụng component next/image cho hình ảnh - Tối ưu hóa font với next/font ## Quản lý state - State server: TanStack Query - State client: Zustand - State form: React Hook Form -
Cài đặt backend (
./backend/GEMINI.md):# Quy ước phát triển backend ## Thiết kế API - Tuân thủ nghiêm ngặt nguyên tắc RESTful - Sử dụng đặc tả OpenAPI 3.0 - Tất cả API cần validation đầu vào - Phản hồi lỗi sử dụng định dạng thống nhất ## Thao tác cơ sở dữ liệu - Sử dụng Prisma ORM - Bao gồm xử lý lỗi trong tất cả truy vấn - Ghi log cho các thao tác nhạy cảm - Sử dụng transaction cho thao tác phức tạp
Kinh nghiệm: Trong quản lý API, tôi thường kết hợp sử dụng Apidog để duy trì tài liệu và test API. API được định nghĩa trong
GEMINI.mdcủa backend có thể trực tiếp tạo ra tài liệu API và test case trong Apidog, giúp cải thiện đáng kể hiệu quả cộng tác giữa frontend và backend. Thành viên mới trong nhóm cũng có thể bắt đầu làm việc ngay chỉ bằng cách xem tài liệu, không cần hỏi đi hỏi lại về chi tiết API.
Năm、Kỹ thuật nâng cao và best practices
Quản lý ngữ cảnh động
Sử dụng lệnh /memory show để kiểm tra tất cả ngữ cảnh hiện đang được tải:
gemini
> /memory show
Điều này hiển thị nội dung của tất cả tệp GEMINI.md đã được tải, giúp bạn xác minh cài đặt đã chính xác chưa.
Kinh nghiệm: Sau khi thay đổi
GEMINI.md, tôi thường chạy/memory showtrước để xác nhận ngữ cảnh mới đã được tải. Nếu chưa, tôi sẽ kiểm tra cache CLI hoặc khởi động lại phiên.
Cài đặt có điều kiện
Bạn có thể tạo các tệp cài đặt khác nhau tùy theo giai đoạn phát triển:
# Cài đặt giai đoạn phát triển ## Trọng tâm phát triển hiện tại
- Đang phát triển module xác thực người dùng
- Ưu tiên triển khai tính năng, tối ưu hiệu suất sau
- Có thể sử dụng console.log để debug ## Quy tắc tạm thời
- Tạm thời cho phép sử dụng kiểu any (sẽ sửa sau khi hoàn thành phát triển)
- API có thể trả về dữ liệu giả
Kinh nghiệm: Thêm thời hạn hoặc số issue vào "quy tắc tạm thời" để không quên dọn dẹp.
Cài đặt cộng tác nhóm
Mẫu cài đặt chuẩn hóa cho nhóm:
# Quy ước phát triển nhóm v2.1 ## Yêu cầu code review
- Mọi PR cần ít nhất 2 người review
- Tính năng mới cần bao gồm test case
- Thay đổi breaking cần cập nhật tài liệu ## Quy ước commit
- Sử dụng định dạng Conventional Commits
- Message commit bao gồm số issue
- Mỗi commit chỉ chứa một thay đổi logic ## Chiến lược branch
- branch main: code môi trường sản xuất
- branch develop: code môi trường phát triển
- feature/*: branch phát triển tính năng
- hotfix/*: branch sửa lỗi khẩn cấp
Lời khuyên thực tế: Coi
GEMINI.mdnhư một phần thỏa thuận của nhóm, lưu trữ trong repository và bắt buộc review PR. Điều này giúp AI tham khảo quy trình làm việc của nhóm khi tạo mô tả PR, message commit và code.
Sáu、Vấn đề thường gặp và giải pháp
Vấn đề một: Cài đặt không được áp dụng
Triệu chứng: Code do AI tạo ra không tuân theo quy ước trong GEMINI.md
Giải pháp:
- Kiểm tra đường dẫn và tên tệp có chính xác không
- Sử dụng
/memory showđể xác nhận cài đặt đã được tải - Đảm bảo mô tả cài đặt đủ rõ ràng và cụ thể
Kiểm tra thêm: Xác minh tệp có định dạng UTF-8, không có BOM, quyền truy cập chính xác, không có ký tự ẩn ở cuối tệp.
Vấn đề hai: Xung đột cài đặt
Triệu chứng: Cài đặt ở các tầng khác nhau mâu thuẫn nhau
Giải pháp:
- Hiểu thứ tự ưu tiên: Thư mục con > Dự án > Toàn cục
- Sử dụng câu lệnh ghi đè rõ ràng
- Dọn dẹp cài đặt cũ định kỳ
Lời khuyên: Viết "giải thích ghi đè" ở đầu
GEMINI.mdcủa mỗi thư mục con, giải thích tại sao tệp này ghi đè quy tắc cha.
Vấn đề ba: Cài đặt quá phức tạp
Triệu chứng: Tệp GEMINI.md trở nên khó quản lý
Giải pháp:
- Module hóa bằng cú pháp
@import - Refactor định kỳ để đơn giản hóa cài đặt
- Chỉ giữ lại những quy tắc thực sự cần thiết
Tôi thường thực hiện "đánh giá cài đặt" hàng quý để loại bỏ các quy tắc cũ hoặc không còn sử dụng, giảm gánh nặng bảo trì.
Bảy、Kịch bản ứng dụng
Kịch bản một: Cài đặt dự án đa ngôn ngữ
# Dự án full-stack đa ngôn ngữ ## Quy ước riêng cho từng ngôn ngữ ### Backend Python
- Tuân thủ quy ước PEP 8
- Sử dụng type hints
- Docstring theo định dạng Google ### Microservice Go
- Format bằng gofmt
- Không bỏ qua xử lý lỗi
- Thiết kế API theo quy ước của Go ### Frontend TypeScript
- Bật strict mode
- Cấm kiểu any
- Sử dụng ESLint + Prettier
Lời khuyên thực tế: Thêm quy trình lint/format vào pipeline CI/CD cho mỗi ngôn ngữ sẽ làm tăng xu hướng AI tạo ra code tuân thủ các kiểm tra này.
Kịch bản hai: Hỗ trợ refactoring bằng AI
# Dự án refactoring code ## Mục tiêu refactoring
- Chuyển đổi class component sang function component
- Loại bỏ phụ thuộc jQuery, sử dụng JavaScript thuần
- Tối ưu hóa hiệu suất, giảm re-rendering ## Nguyên tắc refactoring
- Không thay đổi chức năng
- Di chuyển dần dần, tránh viết lại quy mô lớn
- Chạy test đầy đủ sau khi refactoring
- Duy trì API hiện có
Lời khuyên thực tế: Làm rõ phạm vi refactoring (danh sách file, yêu cầu unit test) và yêu cầu AI xuất ra thay đổi dưới dạng patch có thể rollback.
Kịch bản ba: Cài đặt tạo tài liệu
# Quy ước tạo tài liệu ## Yêu cầu tài liệu API
- Sử dụng định dạng OpenAPI 3.0
- Bao gồm ví dụ request/response
- Mô tả đầy đủ mã lỗi
- Bao gồm thông tin xác thực ## Yêu cầu tài liệu code
- Thêm JSDoc cho tất cả phương thức public
- Comment chi tiết cho thuật toán phức tạp
- Bao gồm ví dụ sử dụng
- Giải thích kiểu tham số và giá trị trả về
Lời khuyên thực tế: Đính kèm 1-2 ví dụ thực tế (request/response) trong
GEMINI.md, AI sẽ tái sử dụng các mẫu này khi tạo tài liệu, cải thiện chất lượng.
Kết luận
Tệp GEMINI.md không chỉ là một tệp cài đặt đơn thuần mà còn là "hợp đồng" giữa bạn và trợ lý AI. Với cài đặt được thiết kế cẩn thận, bạn có thể:
Mẹo nhỏ: Tôi thường sử dụng Apidog để quản lý tài liệu và test API. Điều này giúp ánh xạ trực tiếp các quy tắc
GEMINI.mdvào quy trình tạo và xác thực API, cải thiện đáng kể hiệu quả phát triển và trải nghiệm cộng tác.
- Tăng hiệu quả phát triển: Không cần giải thích lặp đi lặp lại, AI hiểu trực tiếp yêu cầu của bạn
- Đảm bảo chất lượng code: Cộng tác nhóm suôn sẻ với quy ước thống nhất
- Giảm chi phí học tập: Thành viên mới nhanh chóng hiểu quy ước dự án thông qua cài đặt
- Cá nhân hóa: Trợ lý AI thích ứng hoàn toàn với thói quen phát triển của bạn
Cài đặt GEMINI.md tốt nên:
- Rõ ràng và cụ thể: Tránh mô tả mơ hồ
- Từng bước: Bắt đầu đơn giản và cải thiện dần dần
- Cập nhật thường xuyên: Điều chỉnh cài đặt theo sự phát triển của dự án
- Thỏa thuận nhóm: Mọi thành viên đều hiểu và tuân theo
Hãy tạo tệp GEMINI.md cho dự án của bạn ngay bây giờ! Biến Gemini CLI thành đối tác lập trình thông minh thực sự hiểu bạn!