ASDLC Review

Mục lục

Vì sao có dự án này · Tính năng · Kiến trúc · Chấm điểm · Ảnh chụp · Cài đặt · Cấu hình · Kết nối GitLab · Harness repo · API · Phát triển · Release · Bảo mật

Vì sao có dự án này

Khi nhiều dev dùng AI "vibecoding" trên nhiều repo, mỗi repo có harness riêng (README, AGENTS.md, CLAUDE.md, subagent, skill, tài liệu tính năng), người review không thể đọc hết từng MR. ASDLC Review tự clone repo, nạp framework chung và harness của repo đó, review theo bộ tiêu chí chi tiết (convention, kiến trúc, đặt tên, “vì sao làm vậy?”), chấm điểm, comment lại cho tác giả để họ cải thiện, và gom số liệu cho leaderboard và báo cáo cuối kỳ.

Tính năng

• Nhiều cách trigger: webhook GitLab, comment /review hoặc @mr-reviewer review, dán link trên giao diện, API chat, poller định kỳ.
• Hiểu harness của repo: đọc README, AGENTS.md, CLAUDE.md, skill, subagent và tài liệu tính năng trong giới hạn ngân sách ngữ cảnh.
• Phân tích tĩnh + AI: secret, debug code, test bị skip, suppress lint, TODO… chạy tất định; AI tìm vấn đề còn lại, kèm bằng chứng và câu hỏi “tại sao”.
• Điểm tất định: LLM không tự cho điểm; công thức + cổng chặn tính điểm 0–100.
• AI đa nhà cung cấp: claude CLI, codex CLI hoặc API tương thích OpenAI.
• Dashboard: tổng quan, danh sách review, chi tiết finding (có phản hồi đồng ý/không), leaderboard Bayesian, thành viên, repo, báo cáo .md/.csv.
• Desktop: vỏ Electron tuỳ chọn; server cũng chạy headless được.

Kiến trúc

Backend là micro-module: 14 module độc lập, không import lẫn nhau, mỗi module sở hữu logic và dữ liệu riêng, chỉ lộ index.ts. Chỉ app/ (composition root) nối chúng qua public API và Port/Adapter. Luật được kiểm bằng máy (pnpm arch).

Luồng review

Cấu trúc thư mục

apps/
  server/            Fastify API + webhook + worker
    src/kernel/        config, logger, errors, event-bus, exec, db, clock, http
    src/modules/<m>/   14 module: domain/ application/ infra/ + index.ts + MODULE.md
    src/app/           composition root: http/, workflows/, adapters/
    prisma/schema/     mỗi module một file .prisma (không quan hệ chéo)
  web/               React 19 + Vite + Tailwind v4 + shadcn/ui, design token, dark mode (features/<x>/ độc lập)
  desktop/           vỏ Electron mỏng
packages/contracts/  DTO + zod dùng chung
frameworks/asdlc/    framework chung: ~50 tiêu chí, mức độ, cổng chặn
docs/  tools/arch/   tài liệu, bộ kiểm luật kiến trúc

Chấm điểm tất định

deduction = severity × confidence × sizeFactor; hạng mục lấy trung bình có trọng số; cổng chặn: lộ secret ≤ 30, lỗi bảo mật critical ≤ 49, có blocker ≤ 59. Chi tiết và công thức leaderboard: docs/SCORING.md.

Ảnh chụp

Danh sách review	Chi tiết finding
Leaderboard thi đua (podium top 3, animation, confetti)	Báo cáo cuối kỳ

Giao diện dùng shadcn/ui + Tailwind với token màu (sáng/tối); ảnh chụp tĩnh, trên app thật podium có animation.

Ảnh chụp dùng dữ liệu demo giả (apps/server/scripts/seed-demo.ts).

Cài đặt

Yêu cầu

Node.js	22+
pnpm	10+
git	có trong PATH
AI	claude hoặc codex CLI đã đăng nhập, hoặc OPENAI_API_KEY
Redis	không bắt buộc: mặc định hàng đợi chạy trong process và lưu vào SQLite (REDIS_URL=sqlite); chỉ đặt redis://… khi chạy nhiều server

Chạy từ mã nguồn

git clone https://github.com/nguyendinhphongdx/asdlc-review.git
cd asdlc-review
cp .env.example .env     # tuỳ chọn: token GitLab nhập được trên UI
pnpm install
pnpm redis               # tuỳ chọn: docker compose up -d redis
pnpm db:push             # tạo SQLite (cũng tự chạy lần đầu)
pnpm build               # build web
pnpm dev                 # server :4319 + web :5173

Production: pnpm build rồi pnpm --filter @mrd/server start (server phục vụ luôn web). Hoặc tải gói ở Releases, giải nén và chạy các bước trên.

Chạy desktop

pnpm desktop

Cấu hình (.env)

Biến	Ý nghĩa
GITLAB_URL, GITLAB_TOKEN, GITLAB_WEBHOOK_SECRET	Dự phòng; thường nhập trên UI (ưu tiên giá trị lưu trong DB). Webhook không có secret thì bị từ chối
MRD_SECRET_KEY	Khoá mã hoá token trong DB (≥ 16 ký tự). Bỏ trống: tự tạo data/secret.key
GITHUB_TOKEN, GITHUB_WEBHOOK_SECRET	Cho GitHub (đang phát triển)
BOT_MENTION	Từ khoá trong comment để trigger review
REVIEW_PROVIDER	claude-cli | codex-cli | gemini-api | openai-compatible
CLAUDE_MODEL, CLAUDE_MAX_BUDGET_USD	Model và trần chi phí mỗi review
OPENAI_BASE_URL, OPENAI_API_KEY, OPENAI_MODEL	Provider tương thích OpenAI
REDIS_URL	sqlite (mặc định), memory hoặc redis://…
DATA_DIR, DATABASE_URL	Nơi lưu repo cache và SQLite
INLINE_MIN_SEVERITY, MAX_INLINE_COMMENTS	Điều khiển comment inline
POLL_INTERVAL_MIN	>0 bật poller (khi không nhận được webhook)

Kết nối GitLab

Làm theo docs/SETUP.md: nhập URL + token ở Cài đặt → Kết nối (token được mã hoá trong DB), bấm Kiểm tra kết nối, thêm repo ở Repository (có nút tạo webhook tự động), rồi dán link MR hoặc comment /review.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗