Hệ thống mất spec: dựng spec hiện trạng từ mã nguồn bằng AI
Tóm tắt: Với hệ thống đang chạy mà không còn spec, AI như Claude Code có thể đọc mã nguồn và soạn bản nháp spec hiện trạng (現行仕様書). Bản nháp chỉ cho biết hệ thống đang làm gì, không cho biết vì sao, nên người dùng nghiệp vụ phải xác nhận từng mục trước khi dùng làm cơ sở cho hệ thống mới.
Mục lục
- Có dựng được spec hiện trạng từ mã nguồn bằng AI không?
- Spec từ mã nguồn cho biết gì và không cho biết gì?
- Quy trình dựng spec hiện trạng gồm những bước nào?
- Đối chiếu từng mục với người nghiệp vụ như thế nào?
- VAON đặt việc này ở đâu trong giai đoạn chốt đặc tả?
- Khi nào không nên làm theo cách này?
- Câu hỏi thường gặp
1. Có dựng được spec hiện trạng từ mã nguồn bằng AI không?
Dựng được bản nháp, nhưng bản nháp chưa phải spec. Claude Code, theo tài liệu công khai của Anthropic, là công cụ lập trình có thể đọc cả codebase, nên nó đọc nhanh những thứ người đọc tay thấy mệt: hàng trăm màn hình, bảng dữ liệu, các nhánh điều kiện lồng nhau.
Nhưng một hệ thống chạy 10 năm là 10 năm quyết định của nhiều người, đã sửa đi sửa lại. Mã ghi lại kết quả của các quyết định đó, không ghi lại lý do. Vì vậy VAON coi đầu ra của AI là danh sách giả thuyết về hành vi của hệ thống, và công việc thật nằm ở bước kiểm từng giả thuyết với người đang dùng hệ thống.
Chúng tôi đã làm theo cách này trên dự án thật. Chúng tôi chưa có số đo (nhanh hơn bao nhiêu, đúng bao nhiêu phần trăm), nên bài này không nêu con số nào và không nêu tên khách.
2. Spec từ mã nguồn cho biết gì và không cho biết gì?
Spec dựng từ mã nguồn cho biết hệ thống đang làm gì ở mức hành vi, và hầu như không cho biết lý do, độ còn hiệu lực hay những gì nằm ngoài mã. Bảng dưới là những giới hạn cần biết trước khi bắt đầu.
| Câu hỏi | Spec từ mã nguồn trả lời được? | Cách xử lý |
|---|---|---|
| Hệ thống đang làm gì (màn hình, API, batch, tính toán)? | Phần lớn được | Đối chiếu với màn hình chạy thật |
| Vì sao quy tắc này tồn tại? | Không | Hỏi người nghiệp vụ, người làm lâu năm |
| Quy tắc này còn dùng hay đã chết? | Không chắc: mã còn nằm đó không có nghĩa là còn chạy | Xem log và dữ liệu thực, hỏi người dùng |
| Logic nằm ngoài mã (dữ liệu master, cấu hình môi trường thật, thao tác tay)? | Không | Phỏng vấn vận hành, xem môi trường thật |
| Hệ thống bên thứ ba xử lý thế nào? | Chỉ thấy phần gọi, không thấy bên trong | Tài liệu của bên đó, hỏi người phụ trách |
| Hành vi này là spec hay là bug lâu năm? | Không phân biệt được | Người dùng nghiệp vụ quyết định giữ hay sửa |
Dòng cuối là chỗ nguy hiểm nhất. Một lỗi tồn tại nhiều năm, nếu AI ghi nó thành "spec", sẽ được chép nguyên sang hệ thống mới. Có khi chính nhân viên đã quen đường vòng quanh lỗi đó và coi nó là bình thường.
3. Quy trình dựng spec hiện trạng gồm những bước nào?
Quy trình dựng spec hiện trạng của VAON gồm bảy bước, trong đó AI chỉ tham gia từ bước 2 đến bước 4 và con người giữ các bước còn lại.
- Thống nhất quyền và phạm vi. Hỏi khách có cho phép đưa mã nguồn vào công cụ AI không, và phần nào. Ký NDA, thống nhất dữ liệu nào được dùng và ai được xem. Chưa được phép thì không đưa mã vào AI; việc đọc mã khi đó do người làm, chậm hơn nhưng vẫn làm được.
- Kiểm kê hệ thống. Lập danh sách điểm vào: màn hình, API, tác vụ batch, bảng dữ liệu, liên kết ngoài. Đây là khung xương của spec, và là danh sách để biết sau này còn thiếu gì.
- Soạn nháp theo từng đơn vị nhỏ. Cho AI đọc từng chức năng một, không cho đọc cả hệ thống một lượt. Mỗi dòng nháp phải ghi nguồn (tệp và hàm), để người kiểm tra mở ra đối chiếu được.
- Gắn nhãn. Mỗi mục là: có vẻ đang chạy, nghi là đã chết, hoặc chưa rõ. Mục nào AI diễn giải ý định ("có lẽ để tránh trùng đơn") thì tách riêng, vì đó là suy đoán chứ không phải hành vi.
- Lập danh sách câu hỏi cho người nghiệp vụ. Tách "hệ thống làm gì" (đã có từ mã) khỏi "vì sao, còn cần không, có đúng không" (chỉ người trả lời được).
- Họp đối chiếu từng mục. Xem mục 4 bên dưới. Đây là bước tốn thời gian nhất và không thể bỏ.
- Chốt và ký. Spec hiện trạng đã xác nhận, kèm danh sách quyết định giữ, sửa hay bỏ cho từng mục, trở thành đầu vào cho spec của hệ thống mới.
Song song với bước 3 đến 6, chúng tôi quan sát hệ thống đang chạy thật: log, dữ liệu thực, cấu hình môi trường thật. Đó là lớp đo lường mà mã nguồn không đưa ra.
4. Đối chiếu từng mục với người nghiệp vụ như thế nào?
Đối chiếu từng mục nghĩa là mỗi hành vi trong bản nháp được một người nghiệp vụ nhìn vào và cho một trong bốn kết luận. Không có kết luận thì mục đó chưa thành spec.
| Kết luận | Nghĩa là | Việc tiếp theo |
|---|---|---|
| Đúng, giữ | Hành vi đúng và cần | Vào spec mới |
| Sai, sửa | Mã làm khác thực tế nghiệp vụ | Ghi hành vi đúng vào spec mới |
| Đã chết, bỏ | Không còn ai dùng | Loại khỏi phạm vi, giảm việc phải làm |
| Là bug, quyết định | Mã làm khác ý định ban đầu | Người nghiệp vụ quyết định sửa hay giữ |
Mỗi dòng trong tài liệu nên có sáu cột: mã mục, hành vi theo mã, nguồn trong mã, câu hỏi cho người nghiệp vụ, kết luận, người xác nhận kèm ngày. Cột cuối quan trọng: sau này khi có tranh cãi, bạn biết ai đã nói gì và khi nào.
Họp theo nhóm chức năng, không theo thứ tự tệp. Người nghiệp vụ nhớ quy trình, không nhớ tên hàm. Và để người dùng thật đến, không chỉ người quản lý: người quản lý hay không biết đường vòng mà nhân viên đang đi.
5. VAON đặt việc này ở đâu trong giai đoạn chốt đặc tả?
Dựng spec hiện trạng là phần chính của lối vào A trong giai đoạn chốt đặc tả (仕様確定フェーズ) của VAON, dành cho khách đã có hệ thống. Lối vào A gồm đọc mã, phỏng vấn người vận hành và đo lường, do BrSE (Bridge System Engineer) và Tech Lead dẫn.
Giai đoạn này kéo dài 1 đến 2 tuần, dự án lớn 2 đến 4 tuần. Giá cố định, báo trước, không phát sinh. Đầu ra gồm tài liệu yêu cầu, wireframe từng màn hình, thiết kế CSDL, kiến trúc hệ thống và báo giá cố định cho giai đoạn xây dựng. Khách được dừng sau giai đoạn này.
Về cách làm việc, chúng tôi dùng Claude Code và GitHub Copilot hằng ngày, và người luôn kiểm tra trước khi phát hành. Kết quả cuối vẫn là tài liệu do người ký, không phải đầu ra thô của máy.
Nếu bạn muốn hiểu giai đoạn yêu cầu nói chung tốn bao lâu và bao nhiêu, đọc định nghĩa yêu cầu mất bao lâu, tốn bao nhiêu. Với hệ thống đã vận hành lâu và người hiểu nó đã rời đi, xem thêm bài về việc tiếp quản hệ thống. Về cách kiểm soát chất lượng khi có AI tham gia, xem 12 mục cần kiểm trước khi thuê ngoài phát triển có AI. Còn bài toán thay một hệ thống cũ mà không dừng dịch vụ nằm ở hiện đại hoá CMS legacy không downtime.
6. Khi nào không nên làm theo cách này?
Cách này không phù hợp khi bạn không có người nghiệp vụ nào đủ thời gian xác nhận. Không có bước 6 thì chỉ còn một bản nháp trơn tru mà không ai biết đúng sai, và đó là tình huống tệ hơn không có spec.
Nó cũng không làm được khi không có mã nguồn (chỉ có sản phẩm đóng gói), khi khách chưa cho phép đưa mã vào công cụ AI mà vẫn cần tiến độ như khi có AI, hoặc khi phần lớn hành vi của hệ thống nằm ở thao tác tay và quy tắc ngầm mà mã không phản ánh. Với trường hợp cuối, phỏng vấn vận hành là chính, mã chỉ là phụ.
Và spec hiện trạng không phải là kiểm thử. Nó mô tả hệ thống đang làm gì, chưa chứng minh hệ thống mới làm đúng như vậy. Phần kiểm chứng đó cần có kịch bản kiểm thử riêng.
7. Câu hỏi thường gặp
Hệ thống không có spec và người viết đã nghỉ, VAON có nhận không? Có thể nhận. Trước hết chúng tôi hỏi xem có mã nguồn và có người dùng nghiệp vụ tham gia xác nhận không. Hai điều đó quyết định việc có làm được hay không. Buổi đầu 60 phút có CEO tham dự, không cần tài liệu.
AI có đọc được mã viết bằng ngôn ngữ cũ không? Phụ thuộc vào ngôn ngữ và quy mô, và chúng tôi không hứa trước khi xem mã. Cách làm là thử với một chức năng nhỏ, đối chiếu với người dùng, rồi mới quyết định mở rộng. Kết quả của lần thử đó cho biết độ tin cậy thực.
Spec dựng bằng AI có đúng không? Chưa thể nói là đúng cho đến khi người nghiệp vụ xác nhận. Bản nháp có thể sai ở chỗ diễn giải ý định, ở quy tắc đã chết, hoặc ở bug bị ghi thành spec. Vì vậy mỗi mục có nguồn trong mã và có kết luận của người xác nhận.
Phải đưa mã nguồn cho VAON không? Mã nguồn có thể đặt trên kho của khách, và chúng tôi chỉ đưa mã hay dữ liệu vào công cụ AI khi khách cho phép. Chưa được phép thì người đọc mã, nên mất nhiều thời gian hơn.
Làm xong spec hiện trạng thì bước tiếp theo là gì? Là giai đoạn chốt đặc tả: tài liệu yêu cầu, wireframe, thiết kế CSDL, kiến trúc và báo giá cố định cho giai đoạn xây dựng. Khách được dừng sau giai đoạn đó nếu muốn.
Có hệ thống chạy mà không ai còn giữ spec? Kể cho chúng tôi tình hình, kể cả khi bạn chưa có mã trong tay. Đặt lịch trao đổi 60 phút miễn phí
Tác giả: Đoàn Minh Hoàng, Co-Founder & CTO, VAON.
Tài liệu tham khảo
- Anthropic, Claude Code overview: https://code.claude.com/docs/en/overview (đã mở 17/10/2026)