READONLY REVIEW LAYER FOR GIT

Đưa tài liệu kỹ thuật ra khỏi rào cản Git.

Để PM và khách hàng đọc, so sánh, comment và xác nhận tài liệu Markdown ngay trên web — không cần Git credential, không cần cài đặt.

Xem sản phẩm Cách hệ thống hoạt động

Git vẫn là nguồn sự thật
Không ghi ngược repository

Giao diện Spec Review System đang hiển thị tài liệu Markdown và comment theo ngữ cảnh

Revision bất biếnNeo đúng commit

Comment đúng ngữ cảnhGiữ xuyên phiên bản

Được xây để hoàn thành, không chỉ để demo

119/119stories hoàn tất

2.373test tự động pass

13epic đã triển khai

19 ngàytừ ý tưởng đến hệ thống

BÀI TOÁN

Markdown đã trở thành ngôn ngữ chung. Trải nghiệm review thì chưa.

AI khiến spec và tài liệu kỹ thuật ngày càng sống cùng code trong Git. Nhưng PM, BA và khách hàng lại không có một con đường đơn giản để đọc và góp ý đúng phiên bản.

Backlog Documents

Update tài liệu có thể làm đứt mạch comment; đổi tên và đồng bộ hàng loạt vẫn phải maintain thủ công.

GitHub / GitLab

Khách không có tài khoản Git, và Pull Request không phải trải nghiệm dành cho người không rành kỹ thuật.

Google Docs

Markdown, Mermaid và bảng biểu dễ vỡ. Upload bản mới đồng nghĩa comment cũ có nguy cơ bị bỏ lại.

Chat / email

Không preview đúng định dạng, không tracking được feedback đang trỏ vào nội dung và phiên bản nào.

GIẢI PHÁP

Một lớp review readonly nằm phía trên Git.

Hệ thống không copy để chỉnh sửa và không ghi ngược repository. PM chọn branch/tag và phạm vi file; Spec Review System đóng băng một Revision theo đúng commit rồi phát hành bản render dễ đọc cho khách.

Readonly by designĐội dev giữ nguyên workflow Git + Markdown + AI.

01 · NGUỒN SỰ THẬT

Git repository

Tài liệu gốc luôn ở nguyên trong Git.

02 · SNAPSHOT

Revision bất biến

Một “bản chụp” neo đúng commit.

03 · TRẢI NGHIỆM

Review trên web

Khách đọc, góp ý và xác nhận.

TRẢI NGHIỆM SẢN PHẨM

Review tài liệu như đọc một trang web — với đầy đủ ngữ cảnh.

Không cần giải thích Git. Không cần hướng dẫn cách preview Markdown. Mỗi vai trò chỉ thấy đúng thứ họ cần.

READING & COMMENT

Đọc tự nhiên. Góp ý ngay tại câu cần hỏi.

Mục lục, ảnh, link nội bộ, bảng và Mermaid đều được render đúng. Reviewer bôi đen một câu hoặc chọn cả khối để mở thread.

Comment neo theo từng Revision
Trả lời theo luồng, đánh dấu đã xử lý
Xác nhận đã đọc theo từng bản

Giao diện đọc Markdown ba cột với danh sách file, nội dung và comment theo ngữ cảnh — Reading surface · Comment theo ngữ cảnh

SEMANTIC DIFF

Chỉ đọc phần thật sự thay đổi.

So sánh theo từng khối nội dung, tách “nội dung đổi” khỏi “chỉ đổi định dạng”. Raw diff luôn sẵn sàng làm căn cứ cuối cùng.

Thu gọn thay đổi whitespace và formatter
Phân biệt thêm, xoá, sửa và di chuyển
So sánh linh hoạt giữa các Revision

Giao diện Semantic Diff so sánh hai bản tài liệu và thu gọn các thay đổi chỉ do định dạng — Semantic Diff · Lọc nhiễu khỏi thay đổi thật

PM CONTROL PLANE

Biết chính xác điều gì sẽ xảy ra trước khi gửi.

PM xem trước file khách sẽ thấy, thay đổi có ý nghĩa và tác động lên comment hiện có — rồi mới phát hành.

Preview đúng phạm vi và người nhận
Kiểm tra comment được giữ, dời hay ẩn
Không phát hành bản xử lý dở dang

Màn hình PM xem trước Revision, phạm vi tài liệu và tác động lên comment trước khi gửi — PM preflight · Kiểm tra trước khi phát hành

6 KHỐI NĂNG LỰC

Không chỉ là một Markdown viewer.

Một hệ thống review hoàn chỉnh từ lúc PM chuẩn bị bản gửi đến khi khách đọc, phản hồi, xác nhận và tra soát lại.

Bề mặt đọc Markdown

TOC, media, link nội bộ và Mermaid với zoom/pan.

Semantic Diff

Content-first, lọc thay đổi rác, có raw fallback.

Comment & thread

Anchor, reply, resolve và định vị lại có kiểm chứng.

Confirmation

Theo dõi trạng thái “đã đọc N/M người” trên mỗi bản.

PM preflight

Kiểm tra scope, diff và tác động comment trước khi gửi.

Workspace & audit

Quản trị và tra soát mà không đọc nội dung của khách.

QUY TRÌNH

Một vòng review rõ ràng cho mọi vai trò.

Hãy hình dung hệ thống “chụp ảnh” đúng một thời điểm của tủ hồ sơ Git, rồi biến bản chụp đó thành trang web để khách review.

01
ADMIN
Tạo Workspace
Thiết lập không gian và quyền truy cập.
02
PM
Chọn tài liệu
Chọn branch/tag, phạm vi file và reviewer.
03
HỆ THỐNG
Render & so sánh
Đóng băng Revision và xử lý ở phía sau.
04
PM
Xem trước & duyệt
Kiểm tra diff, scope và tác động comment.
05
KHÁCH HÀNG
Đọc · góp ý · xác nhận
Review đúng bản mà không cần biết Git.

DELIVERY PROOF

Một hệ thống hoàn chỉnh.
Được xây trong 19 ngày.

Số liệu lấy trực tiếp từ lịch sử Git và sprint status — không phải con số marketing ước lượng.

223commit

Trong 19 ngày lịch

119/119story

Trên 13 epic hoàn tất

2.373test pass

Trong 220 file test

~130.750dòng TypeScript

4 app + 6 package lõi

QUY ĐỔI NGƯỜI–NGÀY CÔNG

Quy mô tương đương một chương trình nhiều tháng.

So sánh này giúp hình dung quy mô triển khai. Phần bên trái là ước tính tham khảo; phần bên phải là số liệu thực tế của dự án.

ƯỚC TÍNH TRUYỀN THỐNGTham khảo

250–350

Man Day

119 story × khoảng 2–3 người–ngày/story, đã bao gồm thiết kế, kiến trúc, code, test và review.

Đội 4–5 người≈ 10–14 tuần lịch
2,5–3,5 tháng

THỰC TẾ TRIỂN KHAIĐã đo

ngày lịch

Hoàn thành 119/119 story trên 13 epic, với 2.373 test tự động pass và toàn bộ lịch sử commit có thể đối chiếu.

AI-assisted deliveryClaude · Codex · DeepSeek
điều phối bằng BMAD

Lưu ý: 250–350 người–ngày là phép quy đổi dựa trên velocity phổ biến cho story có kiến trúc, bảo mật và test đi kèm; không phải số giờ công được chấm thực tế. Mốc 19 ngày là thời gian thực tế của quá trình triển khai theo dạng vibe code, không thể áp dụng thực tế khi cung cấp dịch vụ cho khách hàng.

BMAD

Giao việc → làm → tự kiểm tra → lặp lại

Mỗi story được đặc tả, hiện thực và bảo vệ bằng test tự động trước khi chuyển sang story tiếp theo — tạo thành lưới an toàn để mở rộng sản phẩm mà không “sửa chỗ này, hỏng chỗ khác”.

FAQ

Những câu hỏi thường gặp.

Mọi quyết định của Spec Review System đều xoay quanh một nguyên tắc: Git là nguồn sự thật, trải nghiệm review phải dành cho con người.

Đây có phải một phiên bản khác của GitHub hay GitLab?

Không. Repository vẫn là nguồn sự thật; sản phẩm chỉ đảm nhiệm snapshot, render, review, comment, diff và audit.

Tại sao không dùng Google Docs hoặc Confluence?

Các công cụ đó phù hợp khi tài liệu được quản lý trong chính workspace của chúng. Spec Review System không tạo bản copy để chỉnh sửa, không thay đổi repository và không làm mất mạch comment khi cập nhật hàng loạt file.

Formatter đổi hàng trăm dòng thì có phải đọc lại hết?

Không. Semantic Diff thu gọn các khối chỉ đổi định dạng và ưu tiên hiển thị những thay đổi có ý nghĩa. Reviewer vẫn có thể mở raw diff khi cần.

Comment cũ có bị mất hoặc trỏ sai khi tài liệu cập nhật?

Comment luôn giữ vị trí ở Revision gốc. Khi có bản mới, hệ thống chỉ định vị lại nếu đủ tin cậy; nếu không, hệ thống báo rõ để PM xử lý thay vì tự đoán.

Dữ liệu và quyền truy cập được bảo vệ thế nào?

Khách chỉ thấy nội dung được gán cho mình. Admin có thể quản trị Workspace và audit nhưng không đọc được nội dung tài liệu hay comment của khách.

SPEC REVIEW SYSTEM

Mỗi bản review.
Đúng phiên bản. Đúng người. Đúng ngữ cảnh.

Để tài liệu tiếp tục sống trong Git — và mọi người vẫn có thể cùng hiểu, cùng góp ý, cùng xác nhận.

Khám phá lại giải pháp