Checklist khi nhận dự án cũ: 11 câu hỏi trước khi sửa code
Checklist khi nhận dự án cũ: 11 câu hỏi về cách chạy, test, Node, biến môi trường, CI và khóa bí mật, kèm script khám dự án và bản nháp bàn giao.
Khi nhận dự án cũ, hãy hỏi mười một câu trước khi sửa code: nó chạy thế nào, có test không, cần Node bản nào, biến môi trường khai báo ở đâu, có CI không, có khóa nằm trong code không, còn bao nhiêu việc nợ. Bạn thường kiểm gì đầu tiên khi mở một dự án lạ?
Mười ba tập sửa một hệ thống, và một danh sách còn thiếu
Trong series Nhận dự án cũ: từ bug report đến pull request, mình đi qua một dự án mà mình nhận lại trong tình trạng trang danh sách đơn của quán Mộc đang sập (quán Mộc là nhân vật minh họa). Mỗi tập sửa một chuyện: đọc stack trace, dò lỗi bằng breakpoint, viết test, mở pull request, review, đặt tên, kiểm tra dữ liệu bằng Zod, xử lý lỗi, tìm chỗ chậm, đọc file CSV lộn xộn, gỡ xung đột Git, gom cấu hình, và viết README cho người đến sau.
Nhìn lại, mỗi chuyện đó đều có thể đã được hỏi từ đầu. Nếu lúc mới nhận dự án mình có một danh sách ngắn, nhiều thứ mình tốn cả một tập mới tìm ra sẽ lộ ngay trong mười phút đầu. Bài này gom danh sách đó lại thành mười một câu hỏi, và viết một script để trả lời chúng cho một thư mục bất kỳ.
Mười một câu hỏi
Script kiem-du-an.ts nhận một thư mục, đọc file (không chạy code của dự án, không sửa gì) và trả lời mười một câu. Mỗi câu có bốn kết quả có thể: đạt, thiếu, cảnh báo, hoặc không áp dụng (ví dụ một dự án không có thư viện ngoài thì câu về lockfile không áp dụng). Mình giải thích từng câu và lý do nó đáng hỏi ngay bên dưới code.
Hàm kiemDuAn nhận một DuAn, tức là danh sách file kèm nội dung và kích thước (cách nhìn này giúp test được mà không cần ổ đĩa), rồi trả về danh sách kết quả:
export type Muc = "dat" | "thieu" | "canh-bao" | "khong-ap-dung";
export type KetQua = { cau: string; muc: Muc; ghiChu: string };
export type DuAn = { files: { duong: string; noiDung: string; byte: number }[] };
const co = (da: DuAn, duong: string) => da.files.some((f) => f.duong === duong);
const doc = (da: DuAn, duong: string) => da.files.find((f) => f.duong === duong)?.noiDung ?? null;
const laMa = (duong: string) => /\.(ts|tsx|js|jsx|mjs|cjs)$/.test(duong);
const laTest = (duong: string) => /\.(test|spec)\.(ts|tsx|js|jsx|mjs)$/.test(duong);
const dungEnv = (da: DuAn) => da.files.some((f) => laMa(f.duong) && !laTest(f.duong) && /process\.env\b/.test(f.noiDung));
const MAU_BI_MAT = /(sk-[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----|(?:api[_-]?key|secret|password)\s*[:=]\s*["'][^"'\s]{12,}["'])/i;
export function kiemDuAn(da: DuAn): KetQua[] {
const goi = doc(da, "package.json");
const pkg = goi ? (JSON.parse(goi) as { scripts?: Record<string, string>; engines?: { node?: string }; dependencies?: object; devDependencies?: object }) : null;
const readme = doc(da, "README.md");
const ketQua: KetQua[] = [];
const them = (cau: string, muc: Muc, ghiChu: string) => ketQua.push({ cau, muc, ghiChu });
// 1. README có khối lệnh để chạy
if (!readme) them("README cho biết cách chạy?", "thieu", "Không có README.md.");
else if (!/```(bash|sh)?\s*\n[\s\S]*?(npm|node|pnpm|yarn)\s/i.test(readme)) them("README cho biết cách chạy?", "thieu", "Có README.md nhưng không có khối lệnh nào để chạy.");
else them("README cho biết cách chạy?", "dat", "Có README.md với khối lệnh.");
// 2. Có script start hoặc dev
const chay = pkg?.scripts?.start ?? pkg?.scripts?.dev;
them("Có một lệnh chạy (npm start hoặc npm run dev)?", chay ? "dat" : "thieu", chay ? `Có: ${chay}` : pkg ? "package.json không có script start hoặc dev." : "Không có package.json.");
// 3. Có script test và ít nhất một file test
const soTest = da.files.filter((f) => laTest(f.duong)).length;
if (pkg?.scripts?.test && soTest > 0) them("Có test chạy được bằng một lệnh?", "dat", `Có script test và ${soTest} file test.`);
else them("Có test chạy được bằng một lệnh?", "thieu", `Script test: ${pkg?.scripts?.test ? "có" : "không"}; file test: ${soTest}.`);
// 4. Ghi rõ phiên bản Node
const node = pkg?.engines?.node ?? doc(da, ".node-version")?.trim() ?? doc(da, ".nvmrc")?.trim();
them("Ghi rõ phiên bản Node?", node ? "dat" : "thieu", node ? `Có: ${node}` : "Không thấy engines.node, .node-version hay .nvmrc.");
// 5. Lockfile (chỉ khi có thư viện ngoài)
const coPhuThuoc = Boolean(pkg && (Object.keys(pkg.dependencies ?? {}).length + Object.keys(pkg.devDependencies ?? {}).length > 0));
if (!coPhuThuoc) them("Có lockfile để cài đúng phiên bản thư viện?", "khong-ap-dung", "Dự án không có thư viện ngoài.");
else them("Có lockfile để cài đúng phiên bản thư viện?", ["package-lock.json", "yarn.lock", "pnpm-lock.yaml"].some((f) => co(da, f)) ? "dat" : "thieu", "Có thư viện ngoài.");
// 6. Biến môi trường được khai báo
if (!dungEnv(da)) them("Biến môi trường được khai báo trong .env.example?", "khong-ap-dung", "Code không đọc biến môi trường.");
else them("Biến môi trường được khai báo trong .env.example?", co(da, ".env.example") ? "dat" : "thieu", co(da, ".env.example") ? "Code dùng biến môi trường và có .env.example." : "Code dùng process.env nhưng không có .env.example.");
// 7. .gitignore chặn .env và node_modules
const gitignore = doc(da, ".gitignore") ?? "";
const thieuIgnore = [!/^\.env\s*$/m.test(gitignore) && (dungEnv(da) || co(da, ".env")) ? ".env" : "", pkg && !/^node_modules\/?\s*$/m.test(gitignore) ? "node_modules" : ""].filter(Boolean);
if (!dungEnv(da) && !pkg && !co(da, ".env")) them(".gitignore chặn .env và node_modules?", "khong-ap-dung", "Không có biến môi trường hay thư viện.");
else them(".gitignore chặn .env và node_modules?", thieuIgnore.length === 0 ? "dat" : "thieu", thieuIgnore.length === 0 ? "Có." : `.gitignore chưa chặn: ${thieuIgnore.join(", ")}.`);
// 8. CI
const coCi = da.files.some((f) => /^\.github\/workflows\/[^/]+\.ya?ml$/.test(f.duong));
them("Có CI chạy kiểm tra mỗi lần đẩy code?", coCi ? "dat" : "thieu", coCi ? "Có workflow trong .github/workflows." : "Không thấy .github/workflows.");
// 9. Khóa hoặc mật khẩu nằm trong file (bỏ qua .env.example, file .env.*, file test)
const loBiMat = da.files.filter((f) => !/^\.env(\.|$)/.test(f.duong.split("/").pop()!) && !/\.example$/.test(f.duong) && !laTest(f.duong) && /\.(ts|tsx|js|mjs|json|md|ya?ml|sh)$/.test(f.duong) && MAU_BI_MAT.test(f.noiDung)).map((f) => f.duong);
them("Có khóa hoặc mật khẩu nằm trong code?", loBiMat.length === 0 ? "dat" : "canh-bao", loBiMat.length === 0 ? "Không thấy mẫu khóa quen thuộc (chỉ là các mẫu mình biết, không đầy đủ)." : `Có thể có khóa trong: ${loBiMat.slice(0, 3).join(", ")}.`);
// 10. TODO và FIXME trong code
const no: string[] = [];
for (const f of da.files.filter((x) => laMa(x.duong) && !laTest(x.duong))) {
f.noiDung.split(/\r?\n/).forEach((d, i) => {
if (/\/\/\s*(TODO|FIXME)\b|\/\*\s*(TODO|FIXME)\b/.test(d)) no.push(`${f.duong}:${i + 1}`);
});
}
them("Có bao nhiêu TODO/FIXME còn nợ?", no.length === 0 ? "dat" : "canh-bao", no.length === 0 ? "Không có." : `${no.length} chỗ, ví dụ ${no.slice(0, 3).join(", ")}.`);
// 11. File lớn bất thường
const lon = da.files.filter((f) => f.byte > 1_000_000).map((f) => f.duong);
them("Có file nào lớn bất thường (trên 1 MB)?", lon.length === 0 ? "dat" : "canh-bao", lon.length === 0 ? "Không." : `Có: ${lon.slice(0, 3).join(", ")}.`);
return ketQua;
}Hàm docThuMuc (không dán ở đây) biến một thư mục thật thành DuAn. Nếu thư mục nằm trong một kho Git, nó chỉ lấy những file mà người clone sẽ có (lệnh git ls-files kèm các file mới chưa bị .gitignore chặn), và nếu không thì duyệt cả thư mục, bỏ qua node_modules, .git, .next. Lý do cho chi tiết này nằm ở phần dưới.
Mười một câu chia làm bốn nhóm. Các câu 1 đến 4 hỏi người mới có chạy được dự án không (README có lệnh, có lệnh chạy, có test, biết dùng Node bản nào); chúng gần như là bài về README của tập trước. Các câu 5 đến 7 hỏi môi trường có tái tạo được không: lockfile để cài đúng phiên bản thư viện, biến môi trường có chỗ khai báo (xem bài biến môi trường), và .gitignore có chặn .env để khóa không bị commit nhầm. Câu 8 hỏi có CI không, vì một dự án không có CI thì mọi lần sửa đều là một lần cầu may. Các câu 9 đến 11 là những thứ để ý: khóa nằm trong code, việc còn nợ ghi bằng TODO và FIXME, và file lớn bất thường (một file dữ liệu vài chục MB bị commit nhầm sẽ làm mọi lần clone chậm đi).
Chạy trên dự án lúc mới nhận
Dự án đơn hàng lúc mình mới nhận nằm trong thư mục 00-ban-dau của repo demo: hai file code, một file dữ liệu mẫu, và một README có hai dòng, trong đó nói trang danh sách đang sập. Mình chạy node kiem-du-an.ts ../00-ban-dau:
../00-ban-dau: đạt 4/10 câu áp dụng
✓ README cho biết cách chạy?
Có README.md với khối lệnh.
✗ Có một lệnh chạy (npm start hoặc npm run dev)?
Không có package.json.
✗ Có test chạy được bằng một lệnh?
Script test: không; file test: 0.
✗ Ghi rõ phiên bản Node?
Không thấy engines.node, .node-version hay .nvmrc.
- Có lockfile để cài đúng phiên bản thư viện?
Dự án không có thư viện ngoài.
✗ Biến môi trường được khai báo trong .env.example?
Code dùng process.env nhưng không có .env.example.
✗ .gitignore chặn .env và node_modules?
.gitignore chưa chặn: .env.
✗ Có CI chạy kiểm tra mỗi lần đẩy code?
Không thấy .github/workflows.
✓ Có khóa hoặc mật khẩu nằm trong code?
Không thấy mẫu khóa quen thuộc (chỉ là các mẫu mình biết, không đầy đủ).
✓ Có bao nhiêu TODO/FIXME còn nợ?
Không có.
✓ Có file nào lớn bất thường (trên 1 MB)?
Không.Dự án lúc đó đạt 4 trên 10 câu áp dụng. Dòng đầu cho thấy README có khối lệnh, nhưng khối lệnh đó chạy node src/server.ts và chỉ để thấy trang bị sập. Các câu thiếu đều là những chuyện mình đã tốn nguyên một tập để làm: test, phiên bản Node, biến môi trường, .gitignore. Chạy lại script cho cùng dự án sau mười ba tập (thư mục 13-readme):
../13-readme: đạt 10/11 câu áp dụng
✓ README cho biết cách chạy?
Có README.md với khối lệnh.
✓ Có một lệnh chạy (npm start hoặc npm run dev)?
Có: node --env-file=.env src/server.ts
✓ Có test chạy được bằng một lệnh?
Có script test và 3 file test.
✓ Ghi rõ phiên bản Node?
Có: >=22.18.0
✓ Có lockfile để cài đúng phiên bản thư viện?
Có thư viện ngoài.
✓ Biến môi trường được khai báo trong .env.example?
Code dùng biến môi trường và có .env.example.
✓ .gitignore chặn .env và node_modules?
Có.
✗ Có CI chạy kiểm tra mỗi lần đẩy code?
Không thấy .github/workflows.
✓ Có khóa hoặc mật khẩu nằm trong code?
Không thấy mẫu khóa quen thuộc (chỉ là các mẫu mình biết, không đầy đủ).
✓ Có bao nhiêu TODO/FIXME còn nợ?
Không có.
✓ Có file nào lớn bất thường (trên 1 MB)?
Không.Từ 4 trên 10 lên 10 trên 11, và chỉ còn thiếu CI. Con số này cho thấy mười ba tập đã đổi gì ở mức mà máy nhìn được, và nó cũng nhắc mình một việc chưa làm: thư mục dự án này chưa có workflow nào.
Hai lần script nói sai
Con số "10 trên 11" ở trên không phải lần chạy đầu. Lần đầu script báo 13-readme đạt 9 trên 10, và câu về biến môi trường được ghi là "không áp dụng" với lý do "code không đọc biến môi trường". Điều đó sai: config.ts của dự án đọc process.env thông qua một tham số mặc định (loadConfig(env = process.env)), không viết dạng process.env.TEN. Regex ban đầu của mình chỉ tìm process.env. kèm tên biến nên bỏ sót. Mình sửa thành tìm process.env đứng riêng, và câu hỏi đó chuyển từ "không áp dụng" sang "đạt". Một script khám dự án mà đọc sai dự án của chính mình thì cũng là một lời nhắc về giá trị của việc thử nó trên nhiều dự án khác nhau.
Lần thứ hai là khi mình chạy nó trên chính repo của blog Tech Notes. Bản đầu của docThuMuc duyệt cả thư mục, nên nó đọc luôn thư mục .tools nằm trong .gitignore (chứa một bản Node và một file zip, mỗi file hơn 1 MB, và cả thư mục không nằm trong git) và báo "có file lớn bất thường". Người clone repo sẽ không bao giờ nhận được những file đó. Mình đổi sang dùng git ls-files khi thư mục nằm trong một kho Git, để script xét đúng những gì người clone nhận được.
Chạy trên một dự án thật khác
Để xem script có đáng tin ngoài những dự án mình tự tạo không, mình chạy nó trên repo blog Tech Notes. Kết quả là 9 trên 11 câu áp dụng, và chỉ có hai chỗ không đạt hoàn toàn:
✗ README cho biết cách chạy?
Không có README.md.
! Có khóa hoặc mật khẩu nằm trong code?
Có thể có khóa trong: .agents/skills/next-best-practices/scripts.md.Chỗ đầu là một phát hiện thật: tại thời điểm mình chạy, thư mục gốc của repo blog không có file README.md. Repo có AGENTS.md mô tả cách làm việc, nhưng người mới mở repo trên GitHub sẽ không thấy gì ở trang chính. Chỗ thứ hai thì là báo nhầm. Mình mở file đó ra xem: dòng bị bắt là apiKey="YOUR_API_KEY", một giá trị giữ chỗ trong tài liệu hướng dẫn, không phải khóa thật. Mẫu tìm khóa của mình khớp bất cứ chuỗi nào dài từ 12 ký tự đứng sau chữ apiKey=, và YOUR_API_KEY có 12 ký tự. Mình giữ nguyên mẫu đó vì phân loại này là cảnh báo chứ không phải lỗi, và một cảnh báo thừa rẻ hơn một khóa bị bỏ sót. Nhưng bạn nên biết rằng bộ kiểm báo nhầm theo cách đó.
Khi mình rời dự án: bản nháp bàn giao
Nhận dự án là một nửa chuyện. Nửa kia là lúc mình chuyển sang việc khác và người sau phải nhận lại. Chuyện này mình nhắc ở tập trước: những gì mình biết về dự án nằm trong đầu mình và rải rác ở các pull request. Script ban-giao.ts làm một phần việc đó. Nó đọc package.json để liệt kê các lệnh, đọc git log để liệt kê việc gần đây, và lấy kết quả của mười một câu ở trên để ghi các chỗ còn thiếu và cần để ý. Mình chạy node ban-giao.ts ../13-readme --lich-su .. (tùy chọn --lich-su cho phép lấy lịch sử Git từ thư mục cha, vì thư mục 13-readme chỉ mới có một commit):
# Bàn giao: don-hang-moc-13
## Chạy dự án
- `npm run setup`: node scripts/setup.ts
- `npm start`: node --env-file=.env src/server.ts
- `npm test`: node --test src/config.test.ts scripts/setup.test.ts kiem-readme.test.ts
## Việc gần đây
- 2026-11-14 (00cadfd): tap 13: README để người mới chạy được dự án
- 2026-11-14 (b1c89a4): tap 12: bien moi truong va cau hinh (ky-nang)
- 2026-11-13 (c8c69e8): tap 11: merge conflict va rebase (ky-nang)
- 2026-11-13 (7ced916): tap 10: regex va nhap file CSV lon xon (ky-nang)
- 2026-11-12 (d8d454d): tap 09: sua so test trong README
- 2026-11-12 (ab6161a): tap 09: tim cho cham, do truoc sua sau (ky-nang)
- 2026-11-12 (7af55b1): tap 08: xu ly loi va ghi log (ky-nang)
- 2026-11-11 (2f972f9): tap 07: don mau thay file json
## Còn thiếu
- Có CI chạy kiểm tra mỗi lần đẩy code? Không thấy .github/workflows.
## Cần để ý
- Không có cảnh báo.
## Phần máy không biết
Vì sao các quyết định lớn được chọn, chỗ nào đang dở, ai hỏi khi cần: phần này người bàn giao phải viết tay.Lần chạy đầu có một lỗi nhỏ mà mình thấy đáng kể: mỗi dòng lệnh được ghi là "npm run setup (hoặc npm setup với start, test)", tức là script hướng dẫn gõ một lệnh không tồn tại (npm setup). Chỉ start và test có dạng ngắn; các script khác phải gõ npm run <tên>. Mình sửa và thêm một test cho đúng điều này.
Mục cuối cùng là mục mình cố ý để máy không làm. Vì sao các quyết định lớn được chọn, phần nào đang dở, ai là người hỏi khi cần: những thứ đó chỉ người trong cuộc biết, và một bản bàn giao mà máy tự điền chúng sẽ là bịa. Vì vậy script ghi thẳng ở cuối rằng phần này phải viết tay, và test kiểm rằng nó không tự thêm tên người nào. Bản nháp chỉ cho bạn một bộ khung đỡ phải gõ lại những gì máy đã biết, và phần còn lại vẫn là việc của bạn.
Giữ danh sách này bằng test
Mười chín test của tập này kiểm các điều bài đã nói. Với kiem-du-an.ts (13 test): một dự án đầy đủ thì mọi câu đạt và đủ 11 câu, thư mục gần như trống thì thiếu README, lệnh chạy, test, Node và CI, README không có khối lệnh vẫn bị coi là thiếu, có script test mà không có file test (hoặc ngược lại) thì thiếu, phiên bản Node lấy được từ .node-version hay .nvmrc, có thư viện mà không có lockfile thì thiếu, code đọc process.env nguyên đối tượng cũng được nhận ra (test cho lỗi ở trên), file test chỉ nhắc process.env thì không tính, .gitignore thiếu gì thì nói rõ thiếu gì, khóa trong code bị cảnh báo kèm tên file còn .env.example và file test thì bỏ qua, đếm đúng TODO và FIXME kèm dòng, file trên 1 MB bị cảnh báo, và một test ghi lại giới hạn đã biết (một khóa dạng GitHub token vẫn lọt qua, vì mẫu của mình không có dạng đó). Với ban-giao.ts (6 test): đủ năm mục theo thứ tự, chỉ start và test có dạng ngắn, câu thiếu và câu cảnh báo vào đúng mục, danh sách commit, mục trống thì nói rõ, và không bịa tên người liên hệ. Bạn chạy bằng npm test (file test nằm trong repo demo, bài này mình không dán).
# tests 19
# pass 19
# fail 0Những điều danh sách này không làm được
Mình nói thẳng các giới hạn. Một, mười một câu là danh sách của mình, rút từ những gì mình gặp trong dự án minh họa này; nó không đầy đủ. Nó không hỏi gì về cơ sở dữ liệu, về log và giám sát, về quyền truy cập, hay về những người đang dùng hệ thống, mà với một dự án thật những thứ đó thường quan trọng hơn. Hai, nó chỉ nhìn file. Một dự án đạt mười một câu vẫn có thể có code rối, test vô dụng hoặc một README nói sai, và một dự án không đạt vài câu vẫn có thể chạy ổn. Ba, mẫu tìm khóa chỉ gồm vài dạng quen thuộc, và như đã thấy nó báo nhầm cả giá trị giữ chỗ; còn khóa dạng lạ thì lọt. Bốn, mình mới thử nó trên ba dự án (hai của mình, một là blog này), nên chưa biết nó sẽ hành xử thế nào trên dự án Python, Java hay một repo nhiều gói. Hãy dùng nó như một danh sách để bạn nhớ hỏi, không phải một điểm số.
Hết mùa đầu, và một dự án lớn hơn đang chờ
Dự án đơn hàng của quán Mộc đi từ một trang bị sập tới một dự án có test, có cấu hình rõ ràng, có README mà người mới chạy được, và có một danh sách để khám bất kỳ dự án nào khác. Nhưng đó vẫn là dự án sửa. Công việc thường gặp hơn của một lập trình viên mới là thêm một tính năng vào một hệ thống đang có người dùng, nơi mỗi thay đổi nhỏ đều có thể chạm vào chỗ mà bạn chưa kịp biết. Làm việc đó mà không phá hệ thống là chuyện của các bài viết sau.
Bạn theo dõi cả hành trình ở Nhận dự án cũ. Bài Zod validation giải thích cách kiểm tra dữ liệu đầu vào ở một trong các tập đầu, và các câu hỏi về cách làm quen một dự án mới nằm trong ngân hàng câu hỏi phỏng vấn. Hướng dẫn của GitHub về việc viết README nằm ở trang About READMEs.