仕様書 là gì? Cách đọc specification trong dự án Nhật
Giải thích 仕様書 trong dự án Nhật và cách developer Việt Nam nên đọc specification: mục tiêu, input, output, rule, exception và câu hỏi xác nhận.
Nội dung được JLPTVN biên tập cho người học tiếng Nhật tại Việt Nam. Với lịch thi, đăng ký và địa điểm thi, hãy kiểm tra thêm nguồn chính thức được dẫn trong bài trước khi quyết định.
Introduction
仕様書 là một từ bạn sẽ gặp liên tục khi làm với công ty Nhật. Nhiều người dịch là specification hoặc tài liệu spec. Nhưng khi vào dự án thật, 仕様書 có thể là tài liệu chức năng, tài liệu màn hình, API spec, batch spec, test spec hoặc một phần trong ticket. Vì vậy, điều quan trọng không chỉ là biết nghĩa, mà là biết cách đọc.
Bài này giúp developer Việt Nam hiểu 仕様書 là gì, vì sao công ty Nhật coi trọng spec, và khi đọc spec nên nhìn vào những điểm nào. Nếu bạn đang học N5/N4, hãy tập nhớ các từ: 仕様, 項目, 条件, 表示, 入力, 出力, エラー, 権限, 例外, 備考.
Sau bài này, bạn nên luyện thêm mẫu câu spec và đọc bài khi không hiểu specification nên hỏi lại thế nào, vì đọc spec tốt luôn đi kèm kỹ năng hỏi lại.
Main concept
仕様書 là tài liệu mô tả cách một chức năng, màn hình, API hoặc hệ thống phải hoạt động. Nếu 要件定義 trả lời "cần gì", thì 仕様書 trả lời rõ hơn "nó hoạt động như thế nào". Một spec tốt cần giúp developer, tester và reviewer cùng hiểu một hành vi.
Khi đọc 仕様書, bạn nên tìm năm nhóm thông tin. Thứ nhất là mục tiêu: chức năng này để làm gì. Thứ hai là input: user hoặc hệ thống nhập dữ liệu nào. Thứ ba là output: màn hình, API response, file hoặc DB thay đổi ra sao. Thứ tư là condition: nếu A thì làm gì, nếu B thì làm gì. Thứ năm là exception: lỗi, dữ liệu thiếu, quyền không đủ, timeout, duplicate.
Trong dự án Nhật, spec còn rất quan trọng vì nó là căn cứ để review và test. Tester có thể viết test case từ 仕様書. Reviewer có thể kiểm tra code có đúng spec không. Khi có bug, team sẽ hỏi: spec đã ghi chưa, code sai spec hay spec thiếu?
Developer đọc spec không nên chỉ tìm phần mình code. Hãy đọc cả rule liên quan, message lỗi, quyền user, ảnh hưởng đến màn hình khác và dữ liệu cũ. Nhiều bug trong dự án Nhật không phải vì thuật toán khó, mà vì bỏ sót một dòng spec nhỏ.
Common misunderstanding
1. "Spec đã có thì chắc chắn rõ"
Không phải. 仕様書 vẫn có thể thiếu case, wording mơ hồ hoặc update chưa kịp. Developer cần phát hiện và hỏi.
2. "Chỉ cần đọc phần happy path"
Happy path là đường đi bình thường. Nhưng dự án thật có lỗi input, quyền khác nhau, dữ liệu null, mạng chậm, user thao tác lặp. Hãy đọc cả exception.
3. "Nếu spec mâu thuẫn với ticket thì cứ làm theo ticket"
Không nên tự quyết. Hãy hỏi lại. Có thể ticket mới hơn spec, hoặc ticket chỉ là tóm tắt. Cần xác nhận nguồn đúng.
4. "Không hiểu spec là do tiếng Nhật kém"
Không hẳn. Có khi spec viết mơ hồ thật. Điều quan trọng là biết hỏi đúng chỗ, không im lặng.
Real project example
Spec ghi: "検索条件を入力して検索ボタンを押すと、一覧を表示する". Developer implement search theo keyword. Nhưng khi test, khách hàng nói nếu không nhập điều kiện, hệ thống phải hiển thị error chứ không được search toàn bộ.
Tester: "検索条件が未入力の場合、エラーが表示されません。"
Developer: "仕様書には未入力の場合の動作が記載されていませんでした。"
PM: "未入力の場合は『検索条件を入力してください。』を表示してください。仕様書に追記します。"
Developer: "承知しました。エラー表示を追加し、仕様書更新後に再確認します。"
Điểm học được: khi spec không ghi case no input, developer nên hỏi trước, nhất là với chức năng search, delete, export, payment hoặc permission.
Useful Japanese phrases
| 日本語 | かな | Nghĩa tiếng Việt | Dùng khi nào | 丁寧度 |
|---|---|---|---|---|
| 仕様書を確認しました。 | しようしょをかくにんしました | Tôi đã kiểm tra spec. | Sau khi đọc tài liệu | Lịch sự |
| この仕様で実装します。 | このしようでじっそうします | Tôi sẽ implement theo spec này. | Khi đã rõ | Lịch sự |
| 仕様書に記載がありません。 | しようしょにきさいがありません | Spec chưa ghi nội dung này. | Khi thiếu case | Lịch sự |
| この場合の動作を確認したいです。 | このばあいのどうさをかくにんしたいです | Tôi muốn xác nhận behavior trong case này. | Khi có edge case | Lịch sự |
| 入力チェックの条件を確認します。 | にゅうりょくちぇっくのじょうけんをかくにんします | Tôi sẽ xác nhận điều kiện validation. | Khi làm form | Lịch sự |
| エラーメッセージの文言を確認したいです。 | えらーめっせーじのもんごんをかくにんしたいです | Tôi muốn xác nhận wording của message lỗi. | Khi text chưa rõ | Lịch sự |
| 権限による違いはありますか。 | けんげんによるちがいはありますか | Có khác nhau theo quyền user không ạ? | Khi liên quan permission | Rất lịch sự |
| APIのレスポンス形式を確認します。 | えーぴーあいのれすぽんすけいしきをかくにんします | Tôi sẽ xác nhận format response API. | Khi làm API | Lịch sự |
| 仕様変更として扱いますか。 | しようへんこうとしてあつかいますか | Có xử lý như spec change không ạ? | Khi có thay đổi mới | Rất lịch sự |
| 認識が合っているか確認させてください。 | にんしきがあっているかかくにんさせてください | Cho tôi xác nhận cách hiểu có đúng không. | Khi tóm tắt lại spec | Rất lịch sự |
Vocabulary
| 日本語 | かな | Nghĩa | 使用例 |
|---|---|---|---|
| 仕様書 | しようしょ | specification document | 仕様書を読みます。 |
| 仕様 | しよう | spec | 仕様を確認します。 |
| 項目 | こうもく | field, item | 項目を追加します。 |
| 表示 | ひょうじ | hiển thị | 一覧を表示します。 |
| 入力 | にゅうりょく | input | 入力してください。 |
| 出力 | しゅつりょく | output | CSVを出力します。 |
| 条件 | じょうけん | điều kiện | 条件を確認します。 |
| 動作 | どうさ | behavior | 動作を確認します。 |
| 例外 | れいがい | exception | 例外を処理します。 |
| 権限 | けんげん | permission | 権限を確認します。 |
| 文言 | もんごん | wording | 文言を修正します。 |
| 仕様変更 | しようへんこう | spec change | 仕様変更があります。 |
Practical checklist
Khi đọc 仕様書, hãy đánh dấu những phần có khả năng gây bug: input trống, dữ liệu null, quyền user, trạng thái cancelled, duplicate, timeout, file encoding, timezone và message lỗi. Đây là các điểm nhỏ nhưng rất hay làm task bị trả lại.
Một cách đọc hiệu quả là chuyển spec thành câu hỏi test. Ví dụ spec ghi "検索条件を入力して検索する". Bạn hãy hỏi: nếu không nhập điều kiện thì sao, nếu nhập ký tự đặc biệt thì sao, nếu kết quả quá nhiều thì sao, user không có quyền thì sao. Nếu spec chưa trả lời, hãy hỏi lại trước khi code.
Bạn cũng nên so sánh 仕様書 với ticket và thiết kế liên quan. Nếu ticket nói sửa A nhưng spec cũ nói B, đừng tự chọn. Hãy hỏi: "チケットと仕様書の内容が異なるため、確認させてください." Câu này giúp tránh tranh luận sau này.
Mini quiz
Câu 1
仕様書 chủ yếu mô tả điều gì?
- A. Cách chức năng hoặc hệ thống phải hoạt động
- B. Chỉ lịch nghỉ
- C. Chỉ tên công ty
- D. Chỉ cách cài editor
Đáp án: A. 仕様書 là căn cứ để implement, review và test hành vi hệ thống.
Câu 2
Khi spec chưa ghi case cụ thể, nên làm gì?
- A. Tự đoán rồi làm
- B. Im lặng
- C. Hỏi lại và nêu rõ case
- D. Xóa chức năng
Đáp án: C. Hỏi lại giúp tránh 認識違い và sửa lại sau này.
Câu 3
文言 nghĩa là gì trong dự án IT?
- A. Wording, câu chữ hiển thị
- B. Server
- C. Database
- D. Deadline
Đáp án: A. 文言 thường dùng khi nói về message lỗi, label, button text.
Next action
Để đọc spec tốt hơn, hãy làm chẩn đoán, sau đó học đều qua vòng 15 phút. Luyện mẫu câu spec, mẫu câu ticket, và làm bài luyện IT. Nếu còn yếu nền tảng, học từ vựng, ngữ pháp N5, ngữ pháp N4. Bạn cũng có thể dùng checklist 14 ngày.
Đọc tiếp: 要件定義 là gì, 基本設計 và 詳細設計, và cách hỏi lại khi không hiểu specification.
FAQ
仕様書 có phải lúc nào cũng là một file riêng không?
Không. Có thể là file Excel, Confluence, Google Docs, ticket, API document hoặc phần mô tả trong issue.
Nếu 仕様書 viết bằng tiếng Nhật khó quá thì làm sao?
Hãy chia nhỏ: tìm mục tiêu, input, output, condition, error. Sau đó hỏi lại từng điểm cụ thể thay vì nói chung là không hiểu.
Developer có nên sửa 仕様書 không?
Tùy quyền trong dự án. Nếu được phép, hãy sửa và báo review. Nếu không, hãy comment hoặc báo PM/BrSE cập nhật.
仕様変更 khác gì bug?
Bug là hệ thống không chạy đúng spec hiện tại. 仕様変更 là yêu cầu thay đổi spec. Hai việc này ảnh hưởng lịch và phạm vi khác nhau.
Học tiếp sau bài này
Chuyển từ bài viết sang lộ trình học 15 phút
Nếu bạn chưa rõ nên học N5, N4 hay tiếng Nhật IT trước, hãy làm bài kiểm tra ngắn. Nếu đã sẵn sàng, làm một bài luyện N5 ngắn rồi lưu lỗi sai vào vòng ôn tập.