Kiểm tra tài liệu dự án do AI viết bằng seiso

seiso làm gì

seiso là một quy ước và công cụ lint Markdown dành cho tài liệu dự án do AI viết và con người cùng các tác nhân lập trình đọc. Công cụ giúp các kho mã duy trì tài liệu nhất quán, dễ bảo trì và dễ sử dụng hơn làm ngữ cảnh cho những thay đổi sau này.

Công cụ kiểm tra tài liệu theo một quy ước chung thay vì yêu cầu mỗi dự án tự xây dựng các quy tắc tài liệu riêng. Mỗi tài liệu khai báo một loại, chẳng hạn như howto, reference hoặc adr, và chỉ chứa nội dung phù hợp với loại đó.

seiso cũng khuyến khích mỗi sự kiện chỉ có một nơi làm nguồn chính thức. Các trang khác nên liên kết đến nguồn đó thay vì lặp lại cùng thông tin. Điều này làm giảm mâu thuẫn, đặc biệt khi tài liệu do AI tạo sao chép danh sách trường, phiên bản, trạng thái hoặc số lượng vào nhiều tệp.

Nguyên tắc tài liệu cốt lõi

• Mỗi tài liệu khai báo một loại và tuân theo mục đích của loại đó. Tài liệu hướng dẫn giải thích các bước, còn phần lý giải thiết kế thuộc về ADR.
• Mỗi sự kiện có một nơi lưu trữ chính thức. Các tài liệu khác liên kết đến trang chính thức thay vì diễn đạt lại.
• Các trang tồn tại lâu dài tránh những giá trị thay đổi nhanh hơn chính trang đó, bao gồm phiên bản, trạng thái triển khai và số lượng.
• Một con trỏ xác định tệp hoặc ký hiệu khi một câu đề cập đến chi tiết triển khai cụ thể.
• Tài liệu đã hoàn thiện không nên đề cập đến người yêu cầu hoặc kể lại cách tài liệu được tạo ra.
• Những quyết định cần phán đoán mà công cụ không thể đưa ra nên được ghi lại cùng lý do. Một ngoại lệ không có lời giải thích cũng là một vi phạm.

seiso tập trung vào các quy tắc tài liệu này. Công cụ không cố xác định văn xuôi có vẻ do máy viết hay không, và để việc định dạng cùng chính tả cho các công cụ khác xử lý.

Cài đặt seiso

Chọn một trong các phương thức cài đặt được hỗ trợ. Các gói Rust, Python và npm cung cấp cùng một công cụ dòng lệnh.

cargo install seiso

uv tool install seiso
# Hoặc dùng pipx:
pipx install seiso

npm install -g @scarletkc/seiso

Các gói PyPI và npm bao gồm tệp nhị phân dựng sẵn cho macOS trên Apple silicon và Intel, Linux x64 và arm64 dùng glibc, cùng Windows x64. Trên các nền tảng khác, bao gồm các bản phân phối Linux dựa trên musl như Alpine, hãy cài đặt bằng Cargo. Gói PyPI cũng có thể dựng từ mã nguồn trên các nền tảng đó, với điều kiện có sẵn bộ công cụ Rust.

Nếu bạn làm việc từ bản sao mã nguồn, hãy chạy lệnh thông qua Cargo:

cargo run -- <command>

Khởi tạo kho mã

Chạy seiso từ thư mục gốc của kho mã. Trước tiên, yêu cầu công cụ tạo cấu hình ban đầu:

seiso init

Lệnh này ghi một tệp seiso.toml vào thư mục gốc của kho mã. Cấu hình được tạo bao gồm các đề xuất loại trừ và ánh xạ loại tài liệu. Hãy xem lại các đề xuất đó trước khi dựa vào kết quả, vì ánh xạ ban đầu chỉ là điểm khởi đầu cho kho mã của bạn, không thể thay thế các quyết định của dự án.

Chạy lần kiểm tra đầu tiên

Sau khi xem lại cấu hình được tạo, hãy kiểm tra kho mã:

seiso check

Theo mặc định, seiso check chỉ chạy các quy tắc ổn định. Những quy tắc này đã đáp ứng tiêu chí nâng cấp của seiso và được thiết kế để cung cấp nền tảng đáng tin cậy cho một dự án.

Thông báo chẩn đoán xác định nơi xảy ra vấn đề và giải thích cách khắc phục. Vì vậy, nhiều phát hiện có thể được sửa trực tiếp từ đầu ra của lệnh. Khi một phát hiện cần phán đoán của con người, chẳng hạn quyết định trang nào trong hai trang sẽ là nơi lưu trữ chính thức của một sự kiện, thông báo chẩn đoán sẽ nêu rõ quyết định cần đưa ra.

Khám phá các quy tắc và cấu trúc tài liệu

Sử dụng các lệnh về quy tắc để tìm hiểu những gì seiso có thể kiểm tra:

seiso rule --all
seiso rule <CODE>

seiso rule --all liệt kê mọi quy tắc và hiển thị trạng thái của chúng. Dùng seiso rule <CODE> để xem một quy tắc riêng lẻ cùng các ví dụ.

Để kiểm tra mô hình tài liệu của seiso mà không chạy các quy tắc, hãy dùng:

seiso parse

Điều này hữu ích khi bạn tìm hiểu cách công cụ diễn giải một tài liệu hoặc điều tra lý do một lần kiểm tra tạo ra kết quả cụ thể.

Sử dụng cẩn thận các quy tắc xem trước

Các quy tắc chưa đáp ứng tiêu chí nâng cấp được cung cấp dưới dạng bản xem trước. Quy tắc xem trước đang trong giai đoạn thử nghiệm và có thể báo cáo dương tính giả, vì vậy chúng không được bật trong lần kiểm tra tiêu chuẩn.

Thử chúng cục bộ bằng tùy chọn --preview:

seiso check --preview

Quy tắc xem trước hữu ích để phát hiện sớm các vấn đề tài liệu tiềm ẩn, nhưng README khuyến nghị không dùng chúng làm điều kiện chặn CI cho đến khi trở nên ổn định. Một quy trình thực tế là dùng các quy tắc ổn định cho những lần kiểm tra bắt buộc và quy tắc xem trước cho việc xem xét cục bộ tùy chọn.

Đưa seiso vào quy trình tài liệu

1. Cài đặt seiso bằng Cargo, uv, pipx hoặc npm.
2. Chạy seiso init từ thư mục gốc của kho mã.
3. Xem lại các đề xuất loại trừ và ánh xạ loại trong seiso.toml.
4. Chạy seiso check và xử lý các phát hiện được báo cáo.
5. Sử dụng seiso rule --all cùng phần giải thích của từng quy tắc khi cần hiểu một thông báo chẩn đoán.
6. Thử nghiệm cục bộ với seiso check --preview, nhưng tránh dùng các phát hiện xem trước làm điều kiện chặn CI.

Đối với các quy trình lớn hơn, tài liệu seiso có hướng dẫn về cấu hình, lựa chọn quy tắc và định dạng đầu ra, cũng như hook Claude Code, pre-commit và tích hợp CI.

Hướng dẫn nâng cao

Duy trì nguồn chính thức cho các sự kiện

Khi seiso báo cáo thông tin bị trùng lặp hoặc đặt sai vị trí, hãy xác định tài liệu nào nên sở hữu thông tin đó. Chuyển phần giải thích chính tắc đến tài liệu ấy và liên kết đến đó từ các trang liên quan. Điều này giúp việc cập nhật an toàn hơn, đồng thời cung cấp cho cả người đọc và tác nhân một nguồn thông tin chuẩn rõ ràng.

Đối chiếu loại tài liệu với mục đích

Sử dụng howto cho các bước thực hiện, reference cho thông tin thực tế có tính ổn định, và adr cho lý do đằng sau một lựa chọn thiết kế. Việc tách biệt các mục đích này giúp một trang không trở thành sự pha trộn giữa hướng dẫn, dữ liệu tham khảo và quá trình ra quyết định trong quá khứ.

Ghi lại các ngoại lệ có lý do chính đáng

Một số quyết định trong kho mã đòi hỏi phán đoán thay vì một quy tắc máy móc. Khi giữ lại một ngoại lệ, hãy ghi rõ lý do. seiso xem một ngoại lệ không có lời giải thích là vấn đề về tài liệu, vì những người đóng góp và tác nhân trong tương lai không thể biết liệu đó có phải là chủ ý hay không.

Tham khảo quy ước khi quy tắc chưa rõ ràng

Quy ước seiso xác định hợp đồng của từng loại tài liệu và bằng chứng mà một chẩn đoán có thể khẳng định. Hãy sử dụng tài liệu này cùng với kết quả của seiso rule <CODE> khi cần hiểu cấu trúc được yêu cầu hoặc quyết định cách khắc phục một phát hiện.

Kết luận

seiso cung cấp cho tài liệu dự án một cấu trúc chung và công cụ xác thực tập trung. Hãy cài đặt công cụ, tạo và rà soát seiso.toml, chạy các kiểm tra ổn định, và sử dụng phần giải thích quy tắc để giúp cả con người lẫn tác nhân lập trình tin cậy tài liệu hơn. Hãy xem các quy tắc xem trước là thử nghiệm cho đến khi được nâng cấp chính thức, đồng thời ghi rõ trong kho mã các quyết định về quyền sở hữu và ngoại lệ.