Đưa bản đồ dự án cho Claude trước khi viết code: mẹo giúp AI chính xác hơn

Một mẹo đơn giản đang được nhiều lập trình viên chia sẻ: trước khi yêu cầu Claude hay bất kỳ AI trợ lý nào viết code, hãy đưa cho nó "bản đồ" dự án — cây thư mục có chú thích cho biết tài liệu nằm ở đâu, code đặt vào đâu, kế hoạch được theo dõi ở đâu. Nghe có vẻ hiển nhiên, nhưng đây chính là bước khiến câu trả lời của AI từ "đoán mò" chuyển sang "chính xác".

Vì sao AI cần có "bản đồ" trước khi code

AI trợ lý lập trình như Claude Code không nhìn thấy toàn bộ máy tính của bạn. Nó chỉ làm việc với những gì bạn cung cấp: file đang mở, đoạn code bạn dán vào, hoặc thư mục bạn cho phép nó đọc. Trong giới hạn đó, nếu không có điểm bám, AI sẽ xử lý theo thói quen phổ biến của các dự án trên Internet — mà dự án của bạn thì không hề phổ biến.

Hậu quả của việc "thả AI vào dự án mù thông tin" thường gặp ở mọi đội ngũ:

• Đặt file sai chỗ: AI tạo file mới ở thư mục gốc, trong khi dự án của bạn có sẵn thư mục src/services dành riêng cho việc đó.
• Phát sinh trùng lặp: đã có một hàm xử lý ngày tháng rồi, AI vẫn viết thêm một bản nữa vì nó không biết bản cũ tồn tại.
• Vi phạm quy ước đội nhóm: đặt tên biến, cấu trúc thư mục, cách import khác hẳn phần còn lại của codebase.
• Đánh mất yêu cầu: bạn từng ghi chú yêu cầu nghiệp vụ ở file nào đó, nhưng AI không đọc được nên tự chế ra một logic khác.

Bản đồ dự án giải quyết vấn đề này ở gốc: nó cho AI biết tìm chỉ dẫn ở đâu, hiểu cấu trúc ra sao và theo kế hoạch nào — đúng ba việc mà một lập trình viên mới nhận việc cũng cần được hướng dẫn.

Bản đồ dự án là gì

Đơn giản nhất, đó là một cây thư mục (arborescence) kèm chú thích ngắn cho từng thành phần quan trọng. Bạn không cần vẽ đẹp — chỉ cần AI (và con người) nhìn vào là biết mỗi thứ thuộc về đâu. Một ví dụ dạng tối giản:

my-project/
├── CLAUDE.md            # Quy tắc làm việc AI phải tuân theo
├── docs/
│   ├── requirements.md  # Yêu cầu nghiệp vụ, user story
│   └── plan.md          # Kế hoạch các bước đang thực hiện
├── src/
│   ├── api/             # Endpoint, controller
│   ├── services/        # Logic nghiệp vụ
│   └── models/          # Kiểu dữ liệu, schema
├── tests/               # Test đặt cùng cấu trúc với src/
└── .env.example         # Biến môi trường mẫu

Ba thành phần đáng đầu tư nhất trong bản đồ:

1. Vị trí tài liệu yêu cầu và kế hoạch: AI cần đọc lại yêu cầu gốc trước khi sửa code, tránh "trôi" khỏi mục tiêu ban đầu.
2. Cấu trúc thư mục theo vai trò: biết chính xác file mới thuộc thư mục nào, test viết ở đâu.
3. Quy ước riêng của dự án: quy tắc đặt tên, thư viện đã chọn, những thứ "đừng đụng vào".

Cách tạo và duy trì bản đồ

• Sinh cây thư mục tự động: lệnh tree -L 2 (Linux/macOS) hoặc find . -maxdepth 2 cho bạn khung sơ bộ trong vài giây; dán kết quả vào file hướng dẫn của dự án.
• Ghi vào file mà AI đọc đầu tiên: với Claude Code là CLAUDE.md đặt ở gốc dự án; các công cụ khác thường đọc README.md hoặc file cấu hình riêng.
• Chú thích bằng một dòng ngắn: mỗi thư mục một dòng mô tả vai trò — đủ để AI định hướng, không quá dài để ngốn ngữ cảnh.
• Cập nhật theo dự án: thêm mục mới khi nó thực sự cần thiết, đừng cố thiết kế toàn bộ ngay từ đầu. Cách làm việc tăng tiến (start small, extend later) này chính là tinh thần của mẹo gốc đang được chia sẻ.
• Dùng lại cho con người: bản đồ này đồng thời là tài liệu onboarding cho thành viên mới — một mũi tên trúng hai đích.

Checklist trước khi giao việc cho AI

Trước khi gõ yêu cầu lớn, rà nhanh 6 điểm sau:

1. AI đã được đọc cấu trúc thư mục của dự án chưa?
2. Yêu cầu nghiệp vụ gốc nằm ở file nào và AI có biết đường dẫn đó không?
3. Kế hoạch công việc (todo, plan) có nơi lưu cố định không?
4. Đã nêu rõ quy ước đặt tên và cấu trúc mà AI phải tuân theo?
5. Đã chỉ cho AI những file liên quan trực tiếp đến nhiệm vụ?
6. Đã chặn rõ những khu vực không được tự ý sửa chưa?

Nếu cả 6 câu trả lời là "có", xác suất phải dọn "bãi chiến trường" sau mỗi lần AI viết code giảm đi đáng kể.

Góc nhìn cho doanh nghiệp Việt Nam

Với các đội ngũ kỹ thuật nhỏ và vừa tại Việt Nam đang đưa AI vào quy trình phát triển phần mềm, mẹo này có chi phí triển khai gần bằng không nhưng lợi ích cộng dồn rất lớn:

• Chuẩn hoá giữa nhiều lập trình viên: mọi người dùng chung một bản đồ, code AI sinh ra đồng bộ thay vì mỗi người một phong cách.
• Giảm chi phí giám sát: quản lý không phải đọc từng dòng AI viết, chỉ cần kiểm tra theo cấu trúc đã thống nhất.
• Onboarding nhanh: kỹ sư mới (và cả AI mới) nắm dự án trong vài phút thay vì vài ngày.

Đầu tư một giờ đồng hồ để vẽ bản đồ dự án có thể tiết kiệm hàng chục giờ sửa lỗi phát sinh do AI "tự ý" tổ chức code theo cách của nó.

Kết luận

AI không đọc được suy nghĩ của bạn — nó chỉ đọc được ngữ cảnh bạn đưa ra. Một cây thư mục có chú thích, một file yêu cầu rõ vị trí và một kế hoạch được ghi lại chính là khác biệt giữa một trợ lý AI lập trình "may rủi" và một trợ lý thực sự hiểu dự án. Trước lần giao việc tiếp theo cho Claude, hãy dành vài phút vẽ bản đồ: dự án của bạn sẽ cảm ơn bạn vì điều đó.

Nguồn: tổng hợp từ chia sẻ trên Facebook, biên tập bởi Wotech Electronics.

Nếu doanh nghiệp của bạn đang muốn chuẩn hoá quy trình phát hành phần mềm có sự hỗ trợ của AI, đội ngũ Wotech Electronics sẵn sàng đồng hành thiết kế quy trình phù hợp với đội ngũ của bạn.