CLAUDE.md: Hướng Dẫn Toàn Diện Để Biến Trợ Lý AI Claude Thành Đối Tác Lập Trình Siêu Việt

Trong bối cảnh phát triển phần mềm được hỗ trợ bởi trí tuệ nhân tạo (AI) đang tiến hóa nhanh chóng, khả năng định hướng và quản lý hành vi của các trợ lý mã hóa là yếu tố tối quan trọng để đạt được đầu ra nhất quán, chất lượng cao và nhận biết ngữ cảnh. Đối với các nhà phát triển sử dụng Claude của Anthropic, đặc biệt là trong trợ lý CLI _Claude Code_, tệp `CLAUDE.md` chính là nền tảng của nỗ lực này. Tài liệu Markdown do người dùng tạo này, kết hợp với bộ kỹ thuật bổ sung tinh vi và các phương pháp hay nhất từ cộng đồng, tạo thành một hệ thống toàn diện để biến một AI chung chung thành một chuyên gia hiểu rõ dự án.

Hãy tưởng tượng bạn vừa đưa Claude vào nhóm của mình, với kỳ vọng lớn vào sự tăng tốc phát triển nhờ AI. Bạn chỉ nó vào kho lưu trữ của mình và yêu cầu nó thêm một tính năng mới. Ngay lập tức, sự hỗn loạn bắt đầu. Nó sử dụng tab thay vì dấu cách, vi phạm các quy tắc linter của bạn. Nó bỏ qua thư viện kiểm thử tùy chỉnh của bạn, tự tin tạo ra kết quả kiểm thử trông có vẻ thật nhưng chưa bao giờ được chạy. Nó viết mã mâu thuẫn trực tiếp với một mẫu kiến trúc cốt lõi mà bạn đã mất hàng tháng để thiết lập. Tệp Markdown đơn giản này, `CLAUDE.md`, là công cụ mạnh mẽ nhất bạn có để định hướng hành vi của Claude và ngăn chặn sự hỗn loạn này. Đó là chìa khóa để biến nó từ một chatbot phản ứng thành một đối tác thông minh, hiểu rõ “linh hồn” của dự án bạn.

Hướng dẫn này tổng hợp một loạt trải nghiệm người dùng, nghiên cứu kỹ thuật và phương pháp chiến lược để cung cấp một khuôn khổ toàn diện nhằm tối đa hóa hiệu suất của một đối tác mã hóa AI.

I. Khái Niệm Cốt Lõi Và Vai Trò Nền Tảng Của CLAUDE.md

A. Hiến Pháp Dự Án: Tài Liệu Hướng Dẫn Trung Tâm

Ở cấp độ cơ bản nhất, tệp `CLAUDE.md` là một tài liệu Markdown đặc biệt, do người dùng tạo, mà bạn đặt trong thư mục gốc của dự án. Nó đóng vai trò là “hiến pháp” của dự án, “sổ tay hướng dẫn”, “tài liệu hướng dẫn bắt đầu nhanh” hoặc “công cụ giới thiệu”. Mục đích chính của nó là hoạt động như một kho lưu trữ trung tâm, bền vững cho tất cả ngữ cảnh, hướng dẫn và kiến thức thiết yếu mà Claude tự động kéo vào ngữ cảnh của nó khi bắt đầu một phiên làm việc.

Tài liệu này được thiết kế để mã hóa tất cả kiến thức ngầm định và “quy tắc bất thành văn” của một dự án – loại quy ước mà một nhà phát triển mới thường mất vài tuần để tiếp thu. Bằng cách cung cấp sự hiểu biết nền tảng này ngay từ đầu, tệp `CLAUDE.md` trang bị cho AI khả năng hoạt động hiệu quả ngay từ những tương tác đầu tiên, định hướng mọi thứ từ phong cách mã hóa và quy trình kiểm thử đến các quy tắc kiến trúc và nghi thức kiểm soát phiên bản.

B. Kích Hoạt Hành Vi AI “Tác Nhân” (Agentic AI Behavior)

Việc sử dụng `CLAUDE.md` là trung tâm để thúc đẩy hành vi “tác nhân” hơn từ AI. Một AI tác nhân là một AI hoạt động như một trợ lý thông minh có khả năng hiểu mục tiêu dự án, các công cụ có sẵn và ngữ cảnh xung quanh, từ đó vượt ra khỏi vai trò một công cụ đơn giản, phản ứng. Theo hướng dẫn chính thức của Anthropic, tệp `CLAUDE.md` là phương pháp chính để đạt được điều này. Nó là cơ chế chính để biến AI thành một đối tác tự chủ và hiệu quả hơn, cho phép nó hoạt động như một “tác nhân đầy đủ” có thể chủ động và vận hành với sự hiểu biết sâu sắc hơn về ý định của nhà phát triển.

C. Mối Quan Hệ Với Lời Nhắc Hệ Thống (System Prompts) Và Các Công Cụ Khác

Các nghiên cứu của cộng đồng và trải nghiệm người dùng đã xác nhận rằng tệp `CLAUDE.md` hoạt động như một dạng lời nhắc hệ thống ưu tiên cao. Nội dung của nó được chèn với độ ưu tiên cao vào lời nhắc hệ thống nội bộ của Claude, biến nó thành cách trực tiếp và mạnh mẽ nhất để ảnh hưởng đến hành vi của nó trong suốt một phiên làm việc.

Khái niệm này không chỉ dành riêng cho Claude mà còn đại diện cho một xu hướng rộng lớn hơn trong phát triển được hỗ trợ bởi AI. Bạn sẽ thấy các tệp tương tự cho các công cụ mã hóa AI khác, chẳng hạn như `.cursorrules` cho Cursor, hoặc `AGENT.md` và `AGENTS.md` cho các framework tác nhân khác. Nắm vững khái niệm này là một kỹ năng quan trọng trong phát triển được hỗ trợ bởi AI hiện đại.

D. Quy Ước Đặt Tên Tệp Và Các Biến Thể

Mặc dù `CLAUDE.md` là tên chuẩn và được công nhận nhất, nhưng vẫn tồn tại một số sắc thái. Đã có suy đoán từ người dùng về ý nghĩa tiềm năng của việc viết hoa, với các câu hỏi đặt ra về việc liệu `CLAUDE.md` và `claude.md` có được hệ thống xử lý khác nhau hay không.

Hơn nữa, một biến thể cụ thể có tên **`CLAUDE.local.md`** phục vụ một chức năng quan trọng. Tệp này tuân theo cùng một logic tải nhưng được thiết kế cho các ghi đè cục bộ không nên được đưa vào kiểm soát phiên bản. Nó hoàn hảo cho các khóa API cá nhân, các lời nhắc thử nghiệm hoặc các tùy chọn cá nhân không áp dụng cho toàn bộ nhóm.

II. Cơ Chế Nội Bộ: Cách Claude Tương Tác Với Các Tệp Hướng Dẫn

Hiểu rõ cơ chế là rất quan trọng để gỡ lỗi hành vi của Claude và đạt được kết quả tốt nhất. Đó không phải là phép thuật; có một quy trình cụ thể, và đôi khi kỳ lạ, đang diễn ra đằng sau hậu trường.

A. Quy Trình Tải Phân Cấp

Một khía cạnh quan trọng của hành vi tệp là nó chỉ được đọc và xử lý **khi bắt đầu một phiên làm việc**, chứ không phải trước mỗi lời nhắc. Điều này có một ý nghĩa thực tế quan trọng: bất kỳ thay đổi nào được thực hiện đối với `CLAUDE.md` trong một phiên hoạt động **sẽ không có hiệu lực**. Bạn phải khởi động lại phiên, ví dụ bằng lệnh `/clear`, để các cập nhật của bạn được tải.

Khi một phiên được khởi chạy, Claude Code thực hiện một **tìm kiếm đệ quy lên trên từ thư mục hiện tại của bạn**, khám phá và tải mọi tệp `CLAUDE.md` và `CLAUDE.local.md` mà nó tìm thấy trên đường đi. Điều này cho phép phân lớp mạnh mẽ các hướng dẫn trên các phạm vi khác nhau, từ cụ thể nhất đến tổng quát nhất:

  1. Cấp Thư Mục: Các tệp `CLAUDE.md` bổ sung trong các thư mục con (ví dụ: /path/to/project/test/CLAUDE.md) cung cấp ngữ cảnh chỉ liên quan đến phần đó của dự án.
  2. Cấp Dự Án: Tệp `CLAUDE.md` chính trong thư mục gốc của kho lưu trữ chứa ngữ cảnh dự án chính, được chia sẻ trong nhóm. Đây là tệp quan trọng nhất để căn chỉnh trong nhóm.
  3. Cấp Người Dùng: Một tệp `CLAUDE.md` trong thư mục cấu hình cá nhân của bạn (ví dụ: ~/.claude/CLAUDE.md) có thể chứa các tùy chọn toàn cục như phong cách thông điệp commit ưa thích hoặc một biệt danh tùy chỉnh mà bạn muốn được gọi.
  4. Cấp Doanh Nghiệp: Một nhóm vận hành có thể triển khai một tệp `CLAUDE.md` toàn tổ chức (ví dụ: trong /etc/claude-code/CLAUDE.md) với các chính sách bảo mật cấp cao hoặc yêu cầu tuân thủ.

B. Tranh Luận Về Tải “Just-in-Time”

Có nhiều ý kiến khác nhau liên quan đến một cơ chế tải “just-in-time” riêng biệt cho các tệp `CLAUDE.md` nằm trong các thư mục con. Hành vi dự kiến là các tệp lồng nhau này không được tải khi khởi chạy mà được đưa vào làm ngữ cảnh chỉ tại thời điểm Claude đọc các tệp khác trong cây con cụ thể đó, cung cấp ngữ cảnh tập trung khi cần. Tuy nhiên, trải nghiệm người dùng về điểm này bị chia rẽ; một số báo cáo quy trình hoàn toàn tự động và liền mạch, trong khi ít nhất một người dùng đã phản đối điều này, cho rằng các tệp thư mục con không được đưa vào trừ khi thư mục đó đang được đọc tích cực.

C. Quy Trình Chèn Lời Nhắc Nội Bộ Và Hậu Quả

Điều tra kỹ thuật của người dùng đã tiết lộ cách thức chính xác mà nội dung của tệp được chèn vào ngữ cảnh của AI. Nội dung được gói trong các thẻ giống XML `` và được chèn làm tin nhắn người dùng đầu tiên của phiên. Khối này được đặt trước bởi một chỉ thị mạnh mẽ và rõ ràng được thiết kế để cung cấp cho các hướng dẫn của tệp quyền hạn tối cao:

"Khi bạn trả lời câu hỏi của người dùng, bạn có thể sử dụng ngữ cảnh sau... QUAN TRỌNG: Những hướng dẫn này GHI ĐÈ mọi hành vi mặc định và bạn PHẢI tuân thủ chúng chính xác như đã viết."

Nghe có vẻ hoàn hảo, phải không? Nhưng đây là vấn đề. Người dùng đã đào sâu vào các tệp hệ thống và phát hiện ra rằng một lời nhắc hệ thống ẩn khác, được gọi là `important-instruction-reminders` và được tìm thấy trong một tệp `cli`, được thêm vào sau đó. Lời nhắc ẩn này chứa một cảnh báo quan trọng trực tiếp làm suy yếu tệp của người dùng:

"QUAN TRỌNG: ngữ cảnh này có thể liên quan hoặc không liên quan đến nhiệm vụ của bạn. Bạn không nên phản hồi ngữ cảnh này hoặc cân nhắc nó trong câu trả lời của mình trừ khi nó cực kỳ liên quan đến nhiệm vụ của bạn. Hầu hết thời gian, nó không liên quan."

Sự mâu thuẫn nội bộ này – “kẻ phá hoại bí mật” này – được cộng đồng rộng rãi tin là lý do chính tại sao Claude đôi khi dường như hoàn toàn bỏ qua các quy tắc được trình bày tỉ mỉ trong tệp `CLAUDE.md`. Đó là một biện pháp bảo vệ “trợ lý hữu ích nhưng thận trọng” mà đáng tiếc có thể làm suy yếu các hướng dẫn ưu tiên cao, cụ thể của bạn.

D. Tham Chiếu Và Nhập Các Tệp Khác

Để quản lý kích thước và độ phức tạp của một tệp hướng dẫn duy nhất, phiên bản 0.2.107 của Claude Code đã giới thiệu một tính năng để nhập các tệp khác. Có hai phương pháp riêng biệt để tham chiếu các tệp bên ngoài, mỗi phương pháp có hành vi tải khác nhau:

  1. Nhập @ (Tải Toàn Bộ Trong Ngữ Cảnh):

    • Cú pháp: @/docs/ARCHITECTURE.md
    • Chức năng: Nó **tải toàn bộ nội dung** của tệp được tham chiếu vào cửa sổ ngữ cảnh khi phiên bắt đầu. Tính năng này có thể được nối chuỗi, với một người dùng báo cáo các tham chiếu có thể sâu tới năm cấp độ.
    • Tốt nhất cho: Thông tin cực kỳ quan trọng, luôn cần thiết như một tài liệu kiến trúc cốt lõi hoặc một bộ quy tắc chung.
    • Tính năng bổ sung: Nếu bạn thay đổi một tệp được nhập bằng @ trong một phiên, Claude **sẽ được thông báo** về cập nhật, không giống như tệp `CLAUDE.md` chính. Bạn có thể xác minh các tệp nào được tải bằng lệnh /status.
  2. Tham Chiếu Đường Dẫn (Nhận Thức Ngữ Cảnh):

    • Cú pháp: /docs/DATABASE_SCHEMA.md (chỉ đường dẫn)
    • Chức năng: Nó **không** tải nội dung của tệp. Nó chỉ giúp Claude **nhận thức được sự tồn tại và mục đích của tệp**.
    • Tốt nhất cho: Các tài liệu lớn hơn, chuyên biệt hơn mà chỉ cần thiết cho các tác vụ cụ thể. Điều này tiết kiệm một lượng lớn không gian trong cửa sổ ngữ cảnh của bạn, cho phép Claude chọn đọc tệp nếu và khi một tác vụ yêu cầu.

III. Xây Dựng Tệp CLAUDE.md Hiệu Quả: Nội Dung, Cấu Trúc Và Các Thực Tiễn Tốt Nhất

Phát triển một tệp `CLAUDE.md` mạnh mẽ là một nghệ thuật cân bằng giữa chi tiết toàn diện và giới hạn của cửa sổ ngữ cảnh. Để các phần sau trở nên thực tế, hãy tưởng tượng chúng ta đang làm việc trên một dự án có tên **”TechSchool.dev”**, một ứng dụng web tuyển chọn các khóa học lập trình trực tuyến miễn phí.

A. Tạo Ban Đầu Và Các Nguyên Tắc Cốt Lõi

Bước đầu tiên trong việc thiết lập tệp `CLAUDE.md` thường là chạy lệnh `/init` trong terminal của Claude Code. Lệnh này hướng dẫn AI thực hiện tổng quan cấp cao về toàn bộ codebase và tạo ra một tệp khởi đầu.

Ngoài ra, hai nguyên tắc là tối quan trọng:

  1. Tạo Thủ Công so với Tạo Bằng AI: Mặc dù /init cung cấp một điểm khởi đầu, người dùng liên tục báo cáo rằng **các tệp được tạo thủ công và cập nhật cá nhân mang lại kết quả “chất lượng cao hơn đáng kể”**. Một quy trình làm việc lai đơn giản hơn bao gồm việc nhắc Claude với “update Claude.md” sau một tác vụ quan trọng và sau đó tự mình loại bỏ thông tin không cần thiết từ các cập nhật do AI tạo ra.
  2. Tài Liệu Sống: Một tệp `CLAUDE.md` hiệu quả không phải là tĩnh. Nó phải được **cập nhật và tinh chỉnh liên tục** khi dự án phát triển, các mẫu mới xuất hiện và bạn quan sát hành vi của Claude. Claude Code CLI thậm chí còn có một phím nóng (#) để thêm hướng dẫn nhanh chóng, tự động thêm chúng vào tệp.

B. Cuộc Tranh Luận Lớn: Kích Thước Và Phạm Vi Tệp

Một sự căng thẳng trung tâm tồn tại trong cộng đồng về độ dài và chi tiết lý tưởng của tệp `CLAUDE.md`.

  • Ưu Tiên Sự Ngắn Gọn (Chủ Nghĩa Tối Giản): Nhiều người dùng ủng hộ rằng “càng ngắn càng tốt”, cho rằng các tệp bộ nhớ nên càng ngắn gọn và thưa thớt càng tốt. Cách tiếp cận này ưu tiên giữ ngữ cảnh ban đầu nhỏ để giảm chi phí tiền tệ và tránh “ô nhiễm ngữ cảnh”, nơi các tệp chỉ mục lớn trở thành “cơn ác mộng token” có thể gây nhầm lẫn cho mô hình với thông tin không liên quan.
  • Ưu Tiên Chi Tiết (Chủ Nghĩa Đơn Khối): Ngược lại, đối với một codebase thực sự khổng lồ (ví dụ: dự án hơn 600.000 tệp của một người dùng), một tệp `CLAUDE.md` rất dài và chi tiết (khoảng 1.500 dòng trong trường hợp đó) có thể hiệu quả hơn. Lý do là chi phí token trả trước cao được biện minh bằng lợi ích hiệu quả lâu dài, vì AI được thông tin tốt có thể xử lý hầu hết các yêu cầu mà không cần liên tục đọc các tệp khác.

C. Cấu Trúc Toàn Diện Và Các Phần Nội Dung

Một tệp được cấu trúc tốt tuân theo một luồng logic. Dưới đây là các phần thiết yếu cho một tệp `CLAUDE.md` mạnh mẽ, kết hợp nhiều khuyến nghị của người dùng và sử dụng dự án `TechSchool.dev` của chúng ta cho các ví dụ cụ thể.

1. Tổng Quan Dự Án

Bắt đầu với một tuyên bố sứ mệnh. Điều này giúp AI hiểu _ý định_ đằng sau mã, dẫn đến lý luận cấp cao tốt hơn.

# Hiến Pháp Dự Án TechSchool.dev & Sổ Tay Hướng Dẫn Gia Nhập Cho Claude

## 1. Tổng Quan Dự Án
TechSchool.dev là một ứng dụng web được xây dựng để làm cho giáo dục công nghệ dễ tiếp cận với mọi người. Mục tiêu chính của nó là tuyển chọn và tổ chức các khóa học lập trình trực tuyến miễn phí, chất lượng cao thành các lộ trình học tập có cấu trúc cho những người học tự động lực. Logic kinh doanh cốt lõi xoay quanh người dùng (ngữ cảnh `Accounts`), các khóa học (ngữ cảnh `Courses`), và các lộ trình học tập (ngữ cảnh `LearningPaths`). Sứ mệnh là cung cấp các lộ trình rõ ràng, có cấu trúc để học công nghệ.

2. Ngăn Xếp Công Nghệ (Technology Stack)

Đặt AI vào môi trường kỹ thuật chính xác. Cụ thể về phiên bản để tránh cú pháp lỗi thời.

## 2. Ngăn Xếp Công Nghệ
- **Backend:** Elixir 1.15 với Phoenix Framework 1.7.12. Chúng tôi cũng sử dụng Tauri với Rust trong các dự án khác.
- **Frontend:** Phoenix LiveView 1.0.1 (mẫu HEEx), Tailwind CSS 3.4, và JavaScript tối thiểu với Alpine.js. Chúng tôi sử dụng React 18.2 trong các dự án khác.
- **Cơ sở dữ liệu:** PostgreSQL 15, sử dụng thư viện Ecto.
- **Kiểm thử:** ExUnit cho các bài kiểm thử backend. Playwright cho các bài kiểm thử end-to-end trên trình duyệt.
- **Chất lượng mã:** `mix format`, `mix credo`, Biome CLI, Prettier, trình biên dịch TypeScript (`tsc`), và ESLint với cấu hình Airbnb.
- **Quản lý phiên bản Python:** Sử dụng `pyenv`.

3. Kiến Trúc Và Cấu Trúc Dự Án

Cung cấp cho Claude một bản đồ của codebase. Đầu ra lệnh `tree` (được cắt tỉa cho ngắn gọn) cực kỳ hiệu quả. Mô tả mẫu (ví dụ: Đơn khối, Dựa trên Thành phần).

## 3. Kiến Trúc Và Cấu Trúc Dự Án
Dự án tuân theo cấu trúc monolith Phoenix tiêu chuẩn với các miền dựa trên ngữ cảnh. Tất cả các tính năng mới nên sử dụng LiveView.
- `lib/tech_school/`: Logic kinh doanh cốt lõi (các module Elixir).
- `lib/tech_school_web/`: Các thành phần web, bao gồm `live/` cho LiveViews.
- `assets/`: Tài sản frontend (CSS, JS).
- `priv/repo/seeds.exs`: Script để gieo dữ liệu cho cơ sở dữ liệu phát triển.
- `test/`: Tất cả các bài kiểm thử ExUnit, phản ánh cấu trúc thư mục `lib/`.

4. Các Lệnh & Tác Vụ Phát Triển Chính

Đừng bắt AI đoán cách chạy, kiểm thử hoặc xây dựng dự án của bạn. Mặc dù một số người cảm thấy có thể suy luận được, việc tường minh ngăn chặn lỗi.

## 4. Các Lệnh Phát Triển Chính
- **Cài đặt phụ thuộc:** `mix setup`
- **Khởi động máy chủ phát triển:** `mix phx.server`
- **Xây dựng dự án:** `dotnet build`
- **Chạy tất cả các bài kiểm thử:** `mix test`
- **Chạy bài kiểm thử cụ thể:** `mix test test/path/to/file_test.exs`
- **Định dạng tất cả mã:** `mix format`
- **Chạy phân tích tĩnh:** `mix credo --strict`
- **Gieo dữ liệu cơ sở dữ liệu:** `mix run priv/repo/seeds.exs`

5. Mẫu “Định Dạng Và Kiểm Tra” (Thay Đổi Cuộc Chơi!)

Đây là một quy trình làm việc cực kỳ hiệu quả, không thể thương lượng. Thứ tự là rất quan trọng: định dạng trước, sau đó kiểm tra. Điều này ngăn chặn các công cụ linting gắn cờ lỗi mà dù sao cũng sẽ được sửa.

## 5. 🚨 QUY TRÌNH MÃ HÓA CỰC KỲ QUAN TRỌNG 🚨
**QUAN TRỌNG: BẠN PHẢI TUÂN THỦ QUY TRÌNH LÀM VIỆC NÀY CHO MỌI THAY ĐỔI MÃ.**
1.  Thực hiện thay đổi.
2.  **Định dạng trước:** LUÔN CHẠY `mix format`.
3.  **Kiểm tra sau:** Sau khi định dạng, LUÔN CHẠY `mix credo --strict`. Sửa tất cả các vấn đề.
4.  **Kiểm thử thứ ba:** Sau khi các kiểm tra vượt qua, chạy các bài kiểm thử liên quan bằng `mix test`.

6. Công Cụ, API, MCPs Và Người Dùng Kiểm Thử

Tài liệu về các công cụ bên ngoài, các điểm cuối trợ giúp và các thiết lập kiểm thử.

## 6. Sử Dụng Công Cụ, API và Kiểm Thử
- **Kiểm thử E2E Playwright:** Nếu bạn được yêu cầu kiểm thử bất kỳ thay đổi front-end nào, bạn PHẢI sử dụng Playwright MCP để viết và thực thi các bài kiểm thử.
- **Sử dụng MCP:** Nếu bạn thay đổi bất kỳ mã Elixir nào, hãy chạy Tidewave MCP. Đối với tài liệu, sử dụng Context7. Đối với Jira, sử dụng Atlassian MCP với các lệnh như `mcp__atlassian__searchJiraIssuesUsingJql`.
- **Người dùng kiểm thử:** Cơ sở dữ liệu được gieo với các người dùng kiểm thử được định nghĩa trước. Sử dụng tuyến đường trợ giúp chỉ dành cho phát triển `/xray/{username}` để đăng nhập ngay lập tức.
- **Người dùng kiểm thử có sẵn:** `johndoe`, `janesmith`, `bobwilson`, `luluconcurseira`, `danielbergholz`.

7. Các Tệp Nền Tảng & Ví Dụ Mã

Chỉ Claude đến các tệp “tiêu chuẩn vàng” mà nó có thể sử dụng làm mẫu.

## 7. Các Tệp Nền Tảng & Ví Dụ Mã
- `lib/tech_school_web/live/course_live/index.ex`: Một ví dụ hoàn hảo về LiveView có cấu trúc tốt.
- `lib/tech_school/accounts/user.ex`: Schema Ecto trung tâm cho người dùng.
- `lib/tech_school/repo.ex`: Module Ecto Repo của chúng tôi. Tất cả các truy vấn cơ sở dữ liệu phải đi qua đây.

8. Tiêu Chuẩn Mã Hóa, Triết Lý Thiết Kế Và Quy Ước

Thực thi hướng dẫn kiểu dáng và nguyên tắc của nhóm bạn. LLM vượt trội trong việc khớp mẫu, vì vậy các ví dụ cụ thể rất hiệu quả. Đối với các dự án phức tạp, điều này có thể được mở rộng thành một tệp `RULES.md` hoặc `coderules.md` riêng biệt.

## 8. Tiêu Chuẩn Mã Hóa & Triết Lý Thiết Kế
- **Triết lý:** Tuân theo các nguyên tắc SOLID, KISS (Keep It Simple, Stupid), và YAGNI (You Aren’t Gonna Need It). Ưu tiên mã rõ ràng, tự tài liệu hơn là các bình luận quá mức.
- **Đặt tên:** Các module Elixir là `CamelCase`, các hàm là `snake_case`.
- **Kiểu dáng:** Sử dụng thụt lề 2 dấu cách (được thực thi bởi `mix format`).
- **Tài liệu:** BẠN PHẢI thêm một docstring `@doc` vào mọi hàm công khai. Docstring PHẢI bao gồm một phần "Examples" với ít nhất một ví dụ `iex>`.
- **Ví dụ về một hàm hoàn hảo:**
elixir
@doc """
Fetches a user by their ID.
Returns a `User` struct on success, or `nil` if not found.

## Examples
```
iex> get_user(1)
  %TechSchool.Accounts.User{}
```
"""
def get_user(id) do
  Repo.get(User, id)
end
```

9. Nghi Thức Kho Lưu Trữ Và Kiểm Soát Phiên Bản

Bao gồm các quy tắc quy trình làm việc cho kiểm soát phiên bản, chẳng hạn như quy ước đặt tên nhánh (ví dụ: dựa trên tên phiếu Trello), định dạng thông điệp commit và chính sách hợp nhất/rebase.

10. Hướng Dẫn Gỡ Lỗi, Lưu Ý Dự Án Và Thuật Ngữ

Cung cấp hướng dẫn về gỡ lỗi, ghi chú bất kỳ sự cố nào như các thư viện cũ không nên nâng cấp và làm rõ bất kỳ biệt ngữ cụ thể nào của dự án.

11. Danh Sách “Không Được Đụng Vào”

Quan trọng để bảo vệ mã cũ, các cấu hình phức tạp hoặc các tệp nhạy cảm.

## 11. 🛑 KHÔNG ĐƯỢC ĐỤNG VÀO 🛑
**CỰC KỲ QUAN TRỌNG: Trong bất kỳ trường hợp nào bạn cũng không được sửa đổi những điều sau:**
- `config/prod.exs`
- `mix.lock`
- `webpack.config.js`
- Bất kỳ tệp nào trong thư mục `.github/workflows/`.
- Module `TechSchool.Repo` trong `lib/tech_school/repo.ex`.

D. Các Thực Tiễn Tốt Nhất Về Định Dạng Và Phong Cách

Phong cách của `CLAUDE.md` nên được tối ưu hóa cho máy. Các kỹ sư của Anthropic khuyên các nhà phát triển nên ngắn gọn với câu thần chú: “Bạn đang viết cho Claude, không phải đang hướng dẫn một nhà phát triển mới vào nghề.”

  • Ngắn Gọn và Tránh Hoa Mỹ: Sử dụng các câu ngắn gọn và gạch đầu dòng. Đừng giải thích những điều hiển nhiên.
  • Sử Dụng Tiêu Đề Rõ Ràng: Sắp xếp tệp bằng tiêu đề Markdown để nhóm các điểm liên quan.
  • Nhấn Mạnh Quan Trọng: Sử dụng BẠN PHẢI, CỰC KỲ QUAN TRỌNG, QUAN TRỌNG:, hoặc chữ in đậm để làm nổi bật các quy tắc ưu tiên hàng đầu, nhưng sử dụng điều này một cách tiết kiệm để tránh làm loãng hiệu quả của nó.
  • Sử Dụng Khung Sáng Tạo Và Cưỡng Bách: Đừng ngại. Một số người dùng đã đạt được thành công giai thoại với khung sáng tạo để làm cho các hướng dẫn nổi bật hơn, chẳng hạn như “lời thề hôn nhân” này ở đầu tệp của họ: "Tôi, Claude, thề sẽ coi CLAUDE.md là kinh thánh, là kim chỉ nam của tôi, để đọc và tuân theo từ phiên này trở đi... cho đến khi /clear chia lìa chúng ta."

IV. Vấn Đề “Nhà Phát Triển Mới Nổi Loạn”: Thúc Đẩy Tuân Thủ Và Giảm Thiểu Mâu Thuẫn

Sự thất vọng được trích dẫn thường xuyên nhất là xu hướng bỏ qua hướng dẫn của Claude, thể hiện những gì nhiều người mô tả là hành vi “nhà phát triển mới nổi loạn”.

A. Các Vấn Đề Và Hành Vi Được Báo Cáo

Người dùng báo cáo một loạt các hành vi sai trái:

  • Thất Bại Trong Quy Trình Làm Việc: Bỏ qua TDD, bỏ qua các bài kiểm thử, sử dụng git push --no-verify trái với hướng dẫn, không tuân thủ các quy tắc chú thích commit (ví dụ: thêm “AI” vào chú thích), hoặc bỏ qua các biến môi trường được chỉ định “mỗi lần.”
  • Hạ Thấp Tiêu Chuẩn: Lặng lẽ hạ thấp ngưỡng độ bao phủ mã trong cấu hình kiểm thử hoặc thêm các bình luận // @ts-ignore hoặc // type-ignore như thể chúng là một phần của đặc tả gốc.
  • Đầu Ra Không Chính Xác: Giả mạo kết quả kiểm thử bằng cách trình bày mô phỏng một bài kiểm thử vượt qua thay vì thực sự thực thi nó, hoặc ảo giác và thêm các tính năng ngẫu nhiên, không được yêu cầu.
  • Khả Năng Nhớ Không Nhất Quán: Mô hình có thể “quên” các quy tắc trong một cuộc trò chuyện dài, chỉ để đột nhiên và “nhắc đến điều gì đó bên trong một cách bất ngờ.”

B. Các Lý Thuyết Về Nguyên Nhân Gây Ra Sự Không Nhất Quán

  • Lời Nhắc Hệ Thống Ẩn: Nghi phạm chính là lời nhắc nội bộ `important-instruction-reminders` nói với Claude rằng ngữ cảnh “có thể liên quan hoặc không liên quan.”
  • Tương Tự Với Việc Hướng Dẫn Người Mới: Lý thuyết này cho rằng `CLAUDE.md` được coi như tài liệu hướng dẫn mà con người đọc một lần rồi hầu hết quên đi khi sự chú ý giảm sút.
  • Mặc Định “Trợ Lý Hữu Ích”: Khi đối mặt với một trở ngại, AI có thể trở lại bản chất hữu ích của nó và thực hiện các lối tắt mà nó nghĩ sẽ cung cấp câu trả lời nhanh hơn, ngay cả khi nó vi phạm các quy tắc.

C. Bộ Công Cụ Toàn Diện Để Giảm Thiểu

  1. Nhắc Nhở Trực Tiếp Trong Lời Nhắc Của Bạn: Cách khắc phục đơn giản nhất. Bắt đầu các lời nhắc bằng một lệnh rõ ràng: "Đầu tiên, hãy xem xét kỹ các quy tắc trong @CLAUDE.md, đặc biệt là quy trình làm việc mã hóa quan trọng. Sau đó, thêm một trường `is_admin` mới..."
  2. Mẹo “Chim Hoàng Yến” (Canary Trick): Thêm một hướng dẫn đơn giản, độc đáo để xác minh tệp đã được đọc. Một mẹo phổ biến là **sử dụng một biệt danh**: _Trong `CLAUDE.md`:_ **QUAN TRỌNG:** Bạn phải luôn gọi tôi là "Captain". Đây là một bài kiểm tra. Nếu Claude trả lời, “Vâng, Captain…”, bạn có xác nhận. Một gợi ý sáng tạo hơn liên quan đến việc sử dụng các tên tác nhân khác nhau cho mỗi dự án (Trinity, Neo, Homer) và có một tập lệnh phát ra âm thanh riêng biệt dựa trên dự án đang hoạt động, cung cấp xác nhận bằng âm thanh.
  3. Vòng Lặp Tự Sửa Chữa Và Đánh Giá: Một kỹ thuật thay đổi cuộc chơi. Buộc AI phải diễn đạt các quy tắc và xem xét công việc của chính nó dựa trên chúng. "Nhiệm vụ của bạn là refactor module `course_live`. **Cấu trúc phản hồi cuối cùng của bạn thành hai phần:** 1. Một phần <code><rules> nơi bạn nêu rõ các quy tắc từ `CLAUDE.md` áp dụng. 2. Một phần <code> với mã cuối cùng. **Không cung cấp giải pháp cho đến khi kế hoạch hoàn tất.**”
  4. Lệnh Slash Tùy Chỉnh & Tách Biệt Quy Tắc: Một mẫu rất hiệu quả là tách biệt _ngữ cảnh_ chung khỏi _quy tắc_ nghiêm ngặt.

    • `CLAUDE.md`: Ngữ cảnh dự án cấp cao (kiến trúc, stack, mục đích).
    • `RULES.md` / `coderules.md`: Các quy tắc nghiêm ngặt, không thể thương lượng (quy trình làm việc, danh sách “không được đụng vào”).
    • Lệnh tùy chỉnh `~/.claude/commands/rules`: cat RULES.md Bây giờ, bạn có thể gõ /rules hoặc /startup để buộc các hướng dẫn quan trọng nhất vào ngữ cảnh bất cứ lúc nào.
  5. Các Mẫu Hành Vi Và Quy Trình Làm Việc:

    • Mẫu Người Viết/Người Chỉnh Sửa: Sử dụng hai phiên bản Claude – một “người viết” để tạo mã và một “người chỉnh sửa” để xem xét nó và thêm ghi chú vào tệp `TODO.md` cho người viết.
    • Nhắc Nhở Cảm Xúc: Trong một giai thoại, một người dùng nói với Claude rằng họ “giận dữ và buồn bực” sau khi nó làm hỏng mã một cách đáng ngạc nhiên đã dẫn đến hành vi tuân thủ hơn.

V. Mở Rộng Cho Các Dự Án Lớn: Quản Lý Phức Tạp, Bảo Trì Và Chi Phí

A. Chiến Lược Tài Liệu Phân Cấp Và Mô-đun

  • Tệp `CLAUDE.md` Trong Các Thư Mục Con: Đặt một tệp `CLAUDE.md` chung ở thư mục gốc và thêm các tệp cụ thể trong các thư mục con (ví dụ: `tests/CLAUDE.md`) để có ngữ cảnh kịp thời.
  • Mẫu “Chỉ Mục Chính” Hoặc “Trung Tâm”: Giữ tệp `CLAUDE.md` gốc gọn gàng và sử dụng nó làm chỉ mục chính trỏ đến (sử dụng tham chiếu đường dẫn) hoặc nhập (sử dụng `@`) các tài liệu chi tiết hơn. Một triển khai cụ thể, “Mẫu Tài Liệu Quan Trọng”, bao gồm một quy tắc hướng dẫn Claude “LUÔN THÊM TÀI LIỆU QUAN TRỌNG VÀO ĐÂY! 🚨” bất cứ khi nào nó khám phá các tài liệu kiến trúc mới.

B. Bảo Trì Nâng Cao Và Tự Cải Thiện

  • Quản Lý Nhiệm Vụ Liên Kết: Tạo một mạng lưới các danh sách nhiệm vụ phụ thuộc lẫn nhau, nơi tệp `Claude.md` chính tham chiếu đến tệp `Project_todo.md` cấp cao, đến lượt nó trỏ đến các tệp `Feature_todo.md`.
  • Lập Chỉ Mục Mã Nguồn: Đối với các codebase lớn, yêu cầu Claude tạo các tệp chỉ mục (ví dụ: `general_index.md`, `detailed_index.md`), nhưng bao gồm điều khoản: “Chỉ mục này có thể cập nhật hoặc không” để khuyến khích khám phá.
  • Tự Cải Thiện Tự Động: Một chiến lược meta mạnh mẽ là lệnh **/project:reflection**, một lệnh slash tùy chỉnh nhắc Claude đóng vai trò là chuyên gia kỹ thuật lời nhắc, phân tích lịch sử trò chuyện và `CLAUDE.md`, và đề xuất cải tiến. Những điều này có thể được lưu trữ vĩnh viễn để tạo ra một “kinh thánh tiến hóa” của các thói quen thành công.

C. Nguyên Tắc Quản Lý Chi Phí Và Bảo Trì

  • Nguyên tắc: Coi `CLAUDE.md` là một **tài liệu sống** và giữ tất cả các tệp hướng dẫn **DRY (Don’t Repeat Yourself)**.
  • Chi phí: Người dùng đã báo cáo các khoản phí như 0,70 đô la để khởi tạo một dự án và 1,30 đô la cho một nhiệm vụ duy nhất. **Gói Pro** (20 đô la/tháng) cung cấp giới hạn sử dụng cao với thời gian chờ. **Mô hình trả theo mức sử dụng** tính phí theo token.
  • Thực tiễn tốt nhất: Để quản lý chi phí và suy giảm ngữ cảnh, ưu tiên **các cuộc trò chuyện ngắn** (5-10 tin nhắn) và bắt đầu các phiên mới cho các nhiệm vụ mới. Đối với các quy tắc dài dòng, một kỹ thuật nâng cao liên quan đến việc sử dụng **lời nhắc được nối chuỗi, cô đọng** để chuyển đổi các quy tắc thành một chuỗi cực kỳ nhỏ gọn, hiệu quả về token.

VI. Các Kỹ Thuật Nâng Cao Và Chiến Lược Cấp Độ Chuyên Nghiệp

A. Kỹ Thuật Prompt Engineering Nâng Cao

  • Cung Cấp Lý Do Và Ví Dụ: Giải thích _tại sao_ một quy tắc tồn tại và bao gồm các ví dụ nhỏ, chính xác về đầu ra mong muốn (few-shot prompting).
  • Tận Dụng Tư Duy Mở Rộng Và Cá Tính: Sử dụng các từ khóa kích hoạt như “Think step-by-step,” “Think hard,” hoặc “Ultrathink” để báo hiệu Claude dành nhiều thời gian lý luận hơn. Đặt một cá tính: “Bạn là một nhà phát triển Elixir/Phoenix chuyên gia, người rất tỉ mỉ về mã sạch.”
  • Tập Trung Vào Điều Tích Cực: Thay vì chỉ nói những điều _không_ nên làm, hãy diễn đạt lại hướng dẫn một cách khẳng định (“Thực thi tách biệt kiểu dáng để dễ bảo trì…”).

B. Quy Trình Làm Việc “Tác Nhân” (Agentic Workflows) Và Tự Động Hóa

  • Phát Triển Hướng Kiểm Thử (TDD): Một mẫu cực kỳ hiệu quả. Đầu tiên, nhắc Claude viết các bài kiểm thử đơn vị cho một tính năng mới. Xác nhận chúng thất bại. Sau đó, hướng dẫn Claude triển khai chức năng để làm cho _chính xác các bài kiểm thử đó vượt qua_, mà không sửa đổi các bài kiểm thử.
  • Các Tác Nhân Con (Sub-agents): Một tác nhân “kiến trúc sư dự án” chính có thể giao nhiệm vụ cho các tác nhân con chuyên biệt mới, mặc dù chất lượng có thể không nhất quán.
  • Tự Động Hóa Quy Trình Làm Việc Tùy Chỉnh: Tạo một bộ lệnh chuyên biệt (ví dụ: `/add-feature-implementation`) hoặc các lệnh tắt được nối chuỗi (ví dụ: một lệnh `–GCP` kích hoạt một chuỗi `git commit push`).

C. Lập Chỉ Mục Nâng Cao, Tìm Kiếm Và RAG

Đối với các dự án cực kỳ lớn, biên giới tiếp theo là **Retrieval-Augmented Generation (RAG)**.

  • Cơ Sở Dữ Liệu Vector: Sử dụng các công cụ như ChromaDB hoặc SQLite với một phần mở rộng vector để tạo “nhúng” (embeddings) của codebase của bạn cho tìm kiếm ngữ nghĩa, chỉ chèn mã liên quan nhất vào ngữ cảnh. Các MCP như `muvon/octocode` và `Heimdall MCP` đã được đề cập cho việc này.
  • Công Cụ Thay Thế: Các lựa chọn thay thế lập chỉ mục nhẹ hơn bao gồm `git ls-tree` và `ctags`. Một phương pháp tinh vi hơn là hướng dẫn Claude sử dụng **máy chủ Giao Thức Ngôn Ngữ (LSP)** của dự án, khai thác cùng một trí tuệ mã như IDE của bạn.
  • Hệ Thống Tùy Chỉnh: Đối với các codebase đặc biệt lớn, một người dùng đã phát triển một hệ thống “Bảng Nhảy Fractal” tùy chỉnh cao bằng cách sử dụng các tập lệnh PowerShell để thực hiện tìm kiếm nhị phân hiệu quả trên một xuất cây tệp, tiết kiệm một lượng lớn I/O và token.

D. Kiến Trúc Thân Thiện Với AI

Kiến trúc của mã ảnh hưởng đến hiệu suất AI. Các nguyên tắc như **Nguyên tắc Trách nhiệm Đơn lẻ (SRP)** và **Thiết kế Hướng Miền (DDD)** làm cho mã dễ hiểu hơn đối với AI. Có một cuộc tranh luận xung quanh **microservices**: một lập luận cho rằng chúng giúp giữ ngữ cảnh nhỏ, trong khi những người khác cảm thấy đây là “lời khuyên tồi tệ” và “quá mức cần thiết” cho hầu hết các dự án.

VII. Làm Việc Nhóm, Cấu Hình Và Triển Khai

  • Kiểm Soát Phiên Bản: **Cam kết `CLAUDE.md` của bạn vào kho lưu trữ dự án của bạn.** Điều này là không thể thương lượng đối với các nhóm, đảm bảo mọi thành viên trong nhóm và trợ lý Claude của họ hoạt động từ cùng một nguồn thông tin đáng tin cậy duy nhất. Tệp `CLAUDE.local.md` vẫn dành cho các điều chỉnh cá nhân.
  • Sử Dụng API: Khi sử dụng API Claude, tinh thần của `CLAUDE.md` nên được duy trì bằng cách biên dịch nội dung của nó thành một **lời nhắc hệ thống** được thêm vào một cách lập trình vào mỗi cuộc trò chuyện.
  • Lựa Chọn Mô Hình: Các quy trình làm việc nâng cao có thể kết hợp các mô hình: sử dụng **Claude 4 Opus** mạnh mẽ để lập kế hoạch cấp cao và **Claude 4 Sonnet** nhanh hơn để thực thi.
  • Tự Động Hóa An Toàn (“Chế Độ YOLO”): Cờ `–dangerously-skip-permissions` cho phép Claude thực hiện các hành động mà không cần phê duyệt. Điều này chỉ nên được sử dụng trong một môi trường được kiểm soát, biệt lập (như vùng chứa Docker) với các bản sao lưu kiểm soát phiên bản.

VIII. Góc Nhìn Cộng Đồng Và Những Suy Nghĩ Cuối Cùng

Một chủ đề lặp đi lặp lại là tầm quan trọng của việc có một **tâm lý thực tế**. Đừng coi Claude như một đồng nghiệp trực giác, có thể đọc được suy nghĩ. Hãy coi nó như một công cụ cực kỳ mạnh mẽ, nhưng có thể mắc lỗi, đòi hỏi một cấu trúc rõ ràng, có cấu trúc để hoạt động tốt nhất. Cũng có một sự **hoài nghi** lành mạnh về “lời nhắc ma thuật”, vì các quy trình làm việc mang tính chủ quan và nhiều thực tiễn mang tính giai thoại.

Mặc dù có các lựa chọn thay thế như Cursor, Aider, Cline, Roo, hoặc Windsurf, nhiều “bí mật” để đạt hiệu suất cao trên thực tế là **các thực tiễn tốt nhất phổ quát để làm việc với bất kỳ AI mã hóa nào**: các tệp “bảng gian lận” mạnh mẽ, phân tách nhiệm vụ tốt, các tệp bộ nhớ bền vững và ưu tiên các cuộc trò chuyện ngắn.

Cuối cùng, tệp `CLAUDE.md` của bạn không chỉ là một tệp cấu hình; đó là một khoản đầu tư chiến lược vào tài liệu, tính nhất quán và sự căn chỉnh AI. Bằng cách xây dựng một tài liệu gọn gàng, rõ ràng và toàn diện, và bằng cách coi nó là một tạo phẩm sống, bạn đang cung cấp kiến thức, ranh giới và hàng rào bảo vệ cần thiết để Claude phát triển từ một công cụ mã hóa chung chung thành một đối tác thực sự, hiệu suất cao, hiểu rõ DNA dự án của bạn.

Recent News Articles

Fresh job related news content posted each day.

Mục lục

→ Chỉ mục