Luật cứng và bài học

Phần lớn nguyên tắc trong nghề đều có vùng xám, nhưng một nhóm nhỏ thì không: vi phạm một lần là gây hại thật không cho cơ hội sửa. Một khóa truy cập kho dữ liệu vô tình bị đẩy lên git công khai có thể bị quét thấy trong vài phút, còn một lần xóa nhầm dữ liệu gốc thu thập bằng tay có thể mất trắng công cả team. Đâu là những lằn ranh cứng mà thành viên mới phải thuộc nằm lòng, và những sai lầm nào đã được trả giá để không lặp lại?

Bài viết này gom các luật cứng về git, bảo mật, và tái lập, cùng một danh sách anti-pattern và bốn bài học cụ thể.

1. Bảng thuật ngữ cục bộ

Thuật ngữ	Tên tiếng Anh	Dịch nghĩa & Giải thích
.env	Environment File	Tệp chứa biến môi trường và khóa.
UV	UV Package Manager	Trình quản lý môi trường, gói Python.
Seed	Random Seed	Hạt giống cố định để kết quả tái lập.

2. Các khái niệm cốt lõi

2.1 Luật cứng về git

• ⚙️ Cơ chế: Ba ràng buộc không được phá khi làm việc trên kho chung.
  • Không tự commit hay push: Người mới chỉ tạo và sửa file; lệnh commit và push do người phụ trách chạy hoặc khi có yêu cầu rõ.
  • Commit theo chuẩn conventional: Mở đầu bằng feat, fix, chore, docs, hay refactor kèm mô tả và định danh người.
  • Repo chung thì branch và pull request: Không commit thẳng nhánh chính, tạo nhánh riêng rồi mở pull request để review.
• 🔍 Cách nhận diện: Lịch sử git sạch, mỗi thay đổi lên nhánh chính đều qua một pull request được duyệt.
• 💡 Ý nghĩa: Giữ nhánh chính luôn chạy được và dễ lần ngược khi có lỗi.
• ⚠️ Bẫy: Tự ý đẩy thẳng lên nhánh chung một thay đổi chưa xong hoặc chưa được soi.

2.2 Luật cứng về bảo mật và dữ liệu

• ⚙️ Cơ chế: Bốn ràng buộc bảo vệ khóa truy cập và dữ liệu gốc.
  • Không viết khóa thẳng vào code: Mật khẩu, khóa truy cập, token đọc qua biến môi trường, không đặt trong code.
  • Có file mẫu không giá trị thật: Kèm một tệp mẫu chỉ ghi tên biến, không ghi giá trị.
  • Chặn khóa khỏi git trước khi tạo: Thêm tệp chứa khóa vào .gitignore trước khi tạo ra.
  • Không xóa dữ liệu gốc khi chưa có bản sao: Dữ liệu thu thập tay là tài sản khó dựng lại.
• 🔍 Cách nhận diện: Rà các file sắp commit không chứa chuỗi khóa hay token thật.
• 💡 Ý nghĩa: Một lần lộ khóa hay mất dữ liệu gốc là hại thật không cứu được.
• ⚠️ Bẫy: Ghi log kèm token hay thông tin cá nhân, hoặc để một khóa thật lọt vào lịch sử git.

2.3 Luật cứng về tái lập

• ⚙️ Cơ chế: Bốn ràng buộc để một kết quả dựng lại được.
  • Python mới quản bằng uv: Commit cả tệp khai báo phụ thuộc lẫn tệp khóa phiên bản.
  • Cố định seed ngẫu nhiên: Đặt seed cho các bước có yếu tố ngẫu nhiên để chạy lại ra đúng số.
  • Kết quả đóng gói chạy lại được: Không nhận một con số từ một lần chỉnh tay chạy một phát.
  • Không rò rỉ dữ liệu: Không để mô hình thấy thông tin tương lai hay học chuẩn hóa trên cả tập kiểm định.
• 🔍 Cách nhận diện: Người khác chạy lại code trên máy khác ra đúng con số đã báo.
• 💡 Ý nghĩa: Kết quả không tái lập được thì không kiểm chứng và không bàn giao được.
• ⚠️ Bẫy: Báo một điểm chạy một lần bằng thao tác tay như một kết luận chắc.

3. Các lối sai thường gặp — anti-pattern

• Đổi nhiều biến trong một thử nghiệm. Không quy được kết quả về nguyên nhân; thay bằng đổi một biến mỗi lần và ghi cấu hình.
• Xóa dữ liệu hay mô hình đã lưu mà không hỏi. Có thể mất thứ khó dựng lại; thay bằng hỏi xác nhận và giữ bản sao trước.
• Không xử lý dòng dữ liệu hỏng khi nạp. Một dòng lỗi làm sập cả lần chạy dài; thay bằng bắt lỗi và bỏ qua có kiểm soát.
• Đổi định dạng dữ liệu giữa chừng mà không báo. Các bước phía sau bị hỏng; thay bằng báo trước cho người dùng phần sau.
• Sao chép một đoạn tính đặc trưng thay vì tách hàm. Sửa một chỗ quên chỗ kia; thay bằng tách một hàm dùng chung.
• Báo một con phần trăm trên tập nhỏ làm bằng chứng chính. Con số dễ đánh lừa; thay bằng bảng phân loại case.

4. Bốn bài học đã trả giá

• Đọc hết các file cùng cụm trước khi sửa một file. Hai file trông giống nhau có thể phụ trách hai luồng khác nhau; liệt kê cả thư mục và đọc tên từng file để hiểu vai trò trước khi sửa.
• Tìm cách làm có sẵn trước khi viết cái mới. Mỗi người xử lý một kiểu vì không xem code người trước; tìm mẫu tương tự đã có trong repo rồi bám theo cho nhất quán.
• Kiểm đường dẫn nạp dữ liệu có trỏ đúng không. Nạp nhầm phiên bản dữ liệu làm sai cả thử nghiệm; mở ra xác nhận đúng tập, đúng cột, đúng khoảng thời gian.
• Đặt tên biến tự giải thích và có lý do khi chọn tầng dữ liệu. Một tên mang hai nghĩa ở hai chỗ gây lệch kết quả; nếu hai đại lượng tính từ hai tầng khác nhau thì phải có lý do thiết kế rõ.

✅ Tự kiểm nhanh

1. Vì sao luật không viết khóa truy cập thẳng vào code thuộc nhóm luật cứng, chứ không phải một lời khuyên?

Đáp án

Vì vi phạm gây hại thật và khó cứu: khóa lên git công khai có thể bị quét thấy trong vài phút và bị lạm dụng, kể cả sau khi xóa thì lịch sử git vẫn còn. Đây là loại lỗi không cho cơ hội sửa.

2. Đồng nghiệp báo một mô hình đạt điểm cao và muốn chốt kết quả. Bạn hỏi lại điều gì trước?

Đáp án

Hỏi kết quả đã đóng gói chạy lại được chưa, đã loại trừ rò rỉ dữ liệu chưa, và điểm đó phân bố thế nào theo từng loại case. Một con số cao chạy một lần chưa loại rò rỉ và chưa soi theo loại case thì chưa đủ để chốt.