Claude Code nâng cao cho dự án web
Cập nhật tháng 10/2026. Claude Code, Codex và các công cụ AI lập trình cập nhật cách đọc tệp quy tắc khá thường xuyên; hãy đối chiếu với tài liệu chính thức được dẫn trong bài trước khi áp dụng cho dự án lớn.
Bài này dành cho ai: người làm web, agency nhỏ và đội kỹ thuật nội bộ đang dùng Claude Code (có thể kèm Codex, Cursor, Gemini CLI) cho website WordPress hoặc website doanh nghiệp, và mệt vì phiên nào cũng phải dặn lại AI cùng một điều.
Bạn sẽ nắm được gì: phân cấp bộ nhớ, nên ghi gì, cách dùng @import và /init, một nguồn quy tắc cho nhiều công cụ AI, 3 mẫu tệp cho WordPress.
Thời gian đọc: khoảng 13 phút, thực hành thêm 30–45 phút trên một dự án thật.
Bài Claude Code sửa lỗi website WordPress chỉ nhắc lướt CLAUDE.md. Bài này đi sâu vào “bộ nhớ dự án” để mọi phiên mới, dù Claude Code hay Codex, AI đều biết lệnh, quy ước và điều cấm.
1. Bộ nhớ dự án là gì và vì sao cần
Theo tài liệu Claude Code, mỗi phiên bắt đầu với ngữ cảnh trống. Kiến thức được mang qua các phiên bằng ba loại tệp:
CLAUDE.md
Bạn viết, dành riêng cho Claude Code. Chứa lệnh, quy ước, cấu trúc dự án. Nạp ở đầu mọi phiên.
AGENTS.md
Bạn viết, dành cho mọi agent: Codex, Cursor, Gemini CLI, Copilot… Được xem như “README cho agent”.
Auto memory
Claude tự ghi những điều học được từ cách bạn sửa nó. Hữu ích nhưng không thay được quy tắc chung của đội.
Lưu ý quan trọng từ tài liệu chính thức: Claude coi các tệp này là ngữ cảnh, không phải cấu hình bắt buộc. Muốn chặn cứng một hành động (ví dụ cấm chạy lệnh xoá cơ sở dữ liệu), hãy dùng hook hoặc quyền, đừng chỉ viết một dòng “không được”.
2. Phân cấp bộ nhớ: người dùng, dự án, thư mục
CLAUDE.md có thể nằm ở nhiều chỗ, mỗi chỗ một phạm vi. Claude Code nạp theo thứ tự từ rộng đến hẹp:
- Chính sách tổ chức (managed policy): do bộ phận IT đặt trên máy, áp dụng cho mọi người trong công ty, ví dụ quy định bảo mật.
- Người dùng:
~/.claude/CLAUDE.md, sở thích cá nhân dùng cho mọi dự án, ví dụ “trả lời bằng tiếng Việt”. - Dự án:
./CLAUDE.mdhoặc./.claude/CLAUDE.md, đưa vào git để cả đội dùng chung. - Cá nhân trong dự án:
./CLAUDE.local.md, ví dụ đường dẫn staging riêng của bạn; nhớ thêm vào.gitignore.
Các tệp được nối lại chứ không ghi đè nhau; tệp gần thư mục làm việc được đọc sau. CLAUDE.md trong thư mục con (ví dụ wp-content/themes/ten-theme-con/) chỉ nạp khi Claude đụng tới tệp trong đó.
Dự án lớn có thể dùng thư mục .claude/rules/: mỗi tệp một chủ đề, khai báo paths để chỉ nạp khi Claude sửa tệp khớp mẫu, ví dụ *.css.
3. Nên ghi gì, nên bỏ gì
Tài liệu Claude Code khuyên mỗi tệp CLAUDE.md nên dưới 200 dòng, vì tệp dài vừa tốn ngữ cảnh vừa làm Claude tuân thủ kém hơn. Bốn nhóm nội dung đáng giữ nhất:
Lệnh build, test
Lệnh chính xác, chép dán chạy được: npm run build, composer test, lệnh xem trước.
Quy ước đặt tên
Tiền tố class CSS, cách đặt tên hàm PHP, tên nhánh git, mẫu commit message.
Cấu trúc thư mục
Chỗ nào được sửa, chỗ nào sinh tự động, chỗ nào chứa tài liệu tra cứu.
Điều cấm
Không sửa core WordPress, không ghi mật khẩu vào repo, không đẩy thẳng lên production.
Viết cụ thể đến mức kiểm chứng được: “Chạy npm test trước khi commit” tốt hơn “nhớ kiểm thử”.
Nên bỏ ra ngoài: quy trình nhiều bước chỉ dùng thỉnh thoảng (chuyển thành Skill, xem bài Skills trong Claude), nội dung AI tự đọc được từ code, lịch sử thay đổi, và mọi thông tin bí mật. Ghi chú cho người bảo trì đặt trong chú thích HTML sẽ được Claude Code loại bỏ trước khi nạp, không tốn token.
4. Thiết lập từng bước
Chạy /init để có bản nháp
Mở Claude Code ở thư mục gốc dự án, gõ /init. Claude đọc codebase và tạo CLAUDE.md với lệnh build, cách chạy test, quy ước nó tìm thấy. Nếu tệp đã có, /init đề xuất cải tiến thay vì ghi đè.
Cắt gọn và bổ sung điều AI không tự biết
Xoá mô tả hiển nhiên, thêm điều chỉ người trong đội biết: staging ở đâu, plugin nào không được cập nhật.
Chuyển quy tắc chung sang AGENTS.md
Nếu đội dùng nhiều công cụ AI, đổi tên nội dung chung thành AGENTS.md. CLAUDE.md chỉ còn một dòng @AGENTS.md và vài ghi chú riêng cho Claude.
Dùng @import để chia tệp
Viết @docs/naming-conventions.md ở bất kỳ dòng nào để nạp kèm tệp đó. Đường dẫn tương đối tính từ tệp chứa lệnh import; import lồng nhau tối đa 4 cấp.
Kiểm tra tệp nào đã được nạp
Gõ /context và xem mục Memory files, hoặc /memory để xem danh sách và mở tệp ra sửa. Nếu một tệp không có trong danh sách, Claude không nhìn thấy nó.
Cập nhật theo thời gian
Thêm một dòng khi Claude mắc cùng lỗi lần thứ hai hoặc bạn phải dặn lại điều đã dặn. Định kỳ xoá quy tắc lỗi thời.
Lưu ý: @import giúp dễ bảo trì nhưng không giảm token, vì tệp import vẫn nạp đầy đủ.
5. Ba mẫu tệp cho dự án WordPress
Các mẫu dưới đây là ví dụ minh hoạ cho một website doanh nghiệp chạy WordPress với theme con. Sửa phần trong ngoặc vuông cho đúng dự án của bạn.
Mẫu 1: AGENTS.md dùng chung cho mọi công cụ
## Tổng quan
WordPress + theme con [tên theme con]. Chỉ sửa trong wp-content/themes/[theme-con]/ và wp-content/plugins/[plugin-noi-bo]/.
## Lệnh
– Cài phụ thuộc: composer install và npm ci
– Build CSS/JS: npm run build
– Kiểm tra PHP: composer lint
## Quy ước
– Class CSS: tiền tố [ten-]block__element–modifier, không viết tắt
– Hàm PHP: tiền tố [ten_], mọi chuỗi hiển thị bọc trong __() với text domain [ten]
## Điều cấm
– Không sửa wp-admin, wp-includes, plugin bên thứ ba
– Không ghi mật khẩu, khoá API vào bất kỳ tệp nào trong repo
– Không chạy lệnh trên production; mọi thay đổi thử trên staging trước
## Tra cứu khi cần: docs/site-map.md
Mẫu 2: CLAUDE.md chỉ trỏ về AGENTS.md
## Riêng cho Claude Code
– Trước khi sửa nhiều tệp: dùng plan mode và chờ tôi duyệt
– Sau khi sửa giao diện: chạy npm run build rồi báo tôi kiểm tra trên trình duyệt
– Không tự commit; tóm tắt thay đổi để tôi review diff
Mẫu 3: Nhờ Claude rà soát và rút gọn tệp quy tắc
1. Liệt kê quy tắc trùng lặp, mâu thuẫn hoặc trỏ tới tệp, lệnh không còn tồn tại.
2. Đánh dấu nội dung chỉ dùng cho một phần dự án, đề xuất chuyển sang .claude/rules/ có khai báo paths.
3. Đề xuất bản AGENTS.md mới dưới 120 dòng, giữ nguyên mọi điều cấm.
Chỉ trình bày đề xuất dạng diff. Chưa sửa tệp nào cho đến khi tôi đồng ý.
6. Một nguồn quy tắc cho nhiều công cụ AI
AGENTS.md do Agentic AI Foundation (Linux Foundation) quản lý, được Codex, Cursor, Gemini CLI, coding agent của GitHub Copilot, Windsurf và nhiều công cụ khác hỗ trợ. Agent đọc tệp gần nhất trong cây thư mục; lời dặn trong khung chat luôn ưu tiên hơn.
Mỗi công cụ đọc tệp hơi khác nhau:
- Claude Code: từ phiên bản 2.1.277 đọc được AGENTS.md trực tiếp, nhưng mặc định chỉ khi dự án không có CLAUDE.md hay CLAUDE.local.md. Nếu đã có CLAUDE.md, hãy import
@AGENTS.mdtrong đó, hoặc đổi thiết lập Project instructions trong/config. - Codex: đọc
~/.codex/AGENTS.mdlàm quy tắc chung, rồi đi từ gốc dự án xuống thư mục hiện tại, mỗi thư mục lấy tối đa một tệp (ưu tiênAGENTS.override.md). Tổng dung lượng mặc định giới hạn 32 KiB, quá thì tệp sau bị bỏ. Đọc thêm bài OpenAI Codex cho đội nhỏ. - Gemini CLI: mặc định đọc GEMINI.md; muốn dùng AGENTS.md, khai báo tên tệp ngữ cảnh trong
.gemini/settings.json. - Công cụ chưa hỗ trợ: tạo tệp riêng của công cụ đó chỉ chứa một dòng trỏ về AGENTS.md, hoặc dùng symbolic link như trang agents.md gợi ý.
Nguyên tắc: một nguồn sự thật. Chép cùng quy tắc vào nhiều tệp thì sớm muộn sẽ sửa chỗ này quên chỗ kia.
7. Ví dụ minh hoạ: agency 5 người bảo trì 12 website WordPress
Tình huống giả định: một agency ở Cần Thơ bảo trì website cho 12 khách. Hai người dùng Claude Code, một người dùng Cursor, thực tập sinh thử Codex. Mỗi người dặn AI một kiểu nên có lúc AI sửa thẳng plugin bên thứ ba, có lúc đặt tên class lệch chuẩn. Họ thống nhất:
- Kho mẫu chung: một AGENTS.md chuẩn của agency được chép vào mọi repo, kèm mục “Tổng quan” riêng cho từng khách.
- CLAUDE.md: chỉ có
@AGENTS.mdvà vài dòng riêng cho Claude. - Thói quen: AI lặp lại một lỗi thì thêm một dòng vào AGENTS.md trong cùng pull request sửa lỗi đó.
Mục tiêu là AI làm nhất quán giữa các công cụ và thành viên. Mới làm quen tư duy agentic? Xem hướng dẫn toàn diện về Claude Code.
8. Lỗi thường gặp và cách khắc phục
Claude Code bỏ qua AGENTS.md
Thường do dự án đã có CLAUDE.md hoặc CLAUDE.local.md, nên Claude chỉ đọc chúng. Thêm dòng @AGENTS.md vào CLAUDE.md rồi kiểm tra lại bằng /memory. Cẩn thận: chỉ cần tạo CLAUDE.local.md cho riêng mình cũng đủ làm Claude ngừng đọc AGENTS.md.
Import không chạy với đường dẫn có dấu cách
Đặt dấu gạch chéo ngược trước mỗi dấu cách, ví dụ @Design\ Docs/api.md. Đường dẫn bọc trong dấu nháy sẽ không được import.
Tệp quy tắc phình to, AI vẫn làm sai
Tệp dài khó tuân thủ, quy tắc mâu thuẫn khiến Claude chọn đại. Chạy mẫu 3, chuyển phần đặc thù sang rule hoặc Skill.
9. Bài tập thực hành
- Chọn một repo website đang bảo trì, chạy
/init, rồi cắt bản nháp xuống dưới 80 dòng, chỉ giữ 4 nhóm: lệnh, quy ước, cấu trúc, điều cấm. - Đổi nội dung đó thành AGENTS.md, để CLAUDE.md chỉ còn
@AGENTS.md. Mở phiên mới, gõ/contextxác nhận cả hai tệp đã nạp, rồi hỏi Claude “quy tắc đặt tên class của dự án là gì?”.
10. Thuật ngữ cần biết
- CLAUDE.md: tệp Markdown chứa hướng dẫn lâu dài mà Claude Code đọc ở đầu mỗi phiên, theo phạm vi tổ chức, người dùng hoặc dự án. Nguồn: How Claude remembers your project.
- AGENTS.md: định dạng Markdown mở chứa hướng dẫn dự án cho các coding agent, được nhiều công cụ cùng hỗ trợ. Nguồn: agents.md.
- Auto memory: ghi chú Claude Code tự lưu từ những lần bạn sửa và nhắc nó, nạp lại ở các phiên sau. Nguồn: Claude Code docs.
11. Tìm hiểu thêm
- How Claude remembers your project: tài liệu đầy đủ về CLAUDE.md, import, rules và AGENTS.md trong Claude Code.
- Best practices for Claude Code: cách tổ chức công việc hiệu quả với Claude Code.
- Hướng dẫn AGENTS.md của Codex: thứ tự tìm tệp, giới hạn dung lượng, tên tệp dự phòng.
- Kho GitHub agentsmd/agents.md và tài liệu tệp ngữ cảnh của Gemini CLI.
12. Câu hỏi thường gặp
Đội chỉ dùng Claude Code, có cần AGENTS.md không?
Không bắt buộc. Nhưng viết sẵn AGENTS.md và import từ CLAUDE.md gần như không tốn công, lại giúp đổi công cụ sau này mà không viết lại quy tắc.
Viết CLAUDE.md bằng tiếng Việt được không?
Được. Điều quan trọng là câu ngắn, cụ thể, kiểm chứng được. Tên lệnh, tên tệp và tên class giữ nguyên như trong code để AI đối chiếu chính xác.
Đọc tiếp
- Bài trước (Công cụ AI): Qwen chạy cục bộ: tóm tắt hợp đồng, hỏi đáp tài liệu nội bộ mà dữ liệu không rời máy công ty
- Nên đọc cùng: Claude Code sửa lỗi website WordPress: quy trình an toàn từ log lỗi đến review diff
- Bài sau trong chuyên mục Công cụ AI: Muse Code của Meta: cài đặt, đặt quyền an toàn và giao việc song song cho subagent
PDL Digital đào tạo và triển khai AI cho đội kỹ thuật doanh nghiệp, từ thiết lập Claude Code, viết bộ quy tắc dự án dùng chung cho nhiều công cụ đến quy trình review an toàn cho website. Xem trang đào tạo để chọn khoá phù hợp.
