Audit Mode & Drift Detection Trong AkiDevRule: Phương Pháp Quét Bất Biến Chuẩn Xác

Chế độ Audit Mode trong bộ quy chuẩn AkiDevRule vận hành dưới một ràng buộc cốt lõi bất biến: Chỉ xuất báo cáo phân tích và phân loại mức độ nghiêm trọng; tuyệt đối không tự ý thay đổi git state hoặc tự động sửa mã nguồn (agent.B5).

Trong quá trình phát triển các hệ thống phần mềm lớn bằng AI Agent, hiện tượng Drift (Sự trôi dạt ngữ nghĩa/kiến trúc) xảy ra liên tục: tài liệu không khớp với code thực tế, giao diện UI lệch khỏi chuẩn thiết kế, hoặc các quy tắc bảo mật bị nới lỏng ngầm. Nếu cho phép AI Agent vừa đi kiểm tra vừa tự ý "sửa giúp", hậu quả thường là các commit rác, vỡ build và mất kiểm soát git working tree.

1. Quy tắc cốt lõi agent.B5: Giới Hạn Phạm Vi Kiểm Toán Chỉ Đọc (Read-Only Audit)

Quy tắc agent.B5 trong ~/.aki/akidevrule/RULE-agent-behavior.md được thiết lập như một bức tường lửa bảo vệ mã nguồn:

!CAUTIONRULE agent.B5 (Read-only Audits): When tasked with auditing, verifying, or assessing a codebase, the agent MUST remain strictly read-only. NEVER invoke write/replace tools or commit changes during an audit pass. Output findings as a structured report only.

Tại sao lại cấm AI Agent tự sửa code trong lúc Audit?

  1. Tránh nhiễu Git History: Tự động sửa hàng loạt lỗi nhỏ (cosmetic) làm lộn xộn git diff, khiến người reviewer thật không thể phân biệt đâu là logic nghiệp vụ chính.
  2. Nguy cơ vỡ Side Effect: Một thay đổi "sửa doc" hoặc "chuẩn hóa format" có thể âm thầm phá vỡ reflection, type declaration hoặc regex parsing ở chỗ khác.
  3. Phân định trách nhiệm (Separation of Concerns): Pha Audit dùng để phát hiện sự thật (Fact-finding), pha Fix dùng để thực thi thay đổi (Execution).

2. Ma trận Phân Vùng Audit Theo Tên Miền (Domain Read-only Specialists)

Để việc kiểm tra đạt độ bao phủ sâu mà không gây tràn ngữ cảnh, AkiDevRule chia nhỏ pha Audit thành 6 miền chuyên biệt:

Specialist DomainPhạm Vi Quét Tự ĐộngTín Hiệu Phát Hiện Drift
Docs Drift (docs-auditor)So sánh comment/JSDoc với function signature thực tếCode đã đổi tham số nhưng JSDoc vẫn giữ kiểu cũ
UI Drift (ui-auditor)Kiểm tra CSS utility, spacing, token màu so với RULE-design-core.mdDùng inline style cứng padding: 13px thay vì Tailwind class
Flow Drift (flow-auditor)Kiểm tra luồng điều hướng, error handling, try/catchNuốt exception ngầm (catch {}) mà không log lỗi
Release Drift (release-auditor)Quét file build, wrangler.toml, package.json, env varsChưa bump version hoặc dùng dependency không đúng allowlist
UX Drift (ux-auditor)Kiểm tra trạng thái Loading, Empty State, Error StateTrang fetch API thiếu màn hình chờ hoặc thiếu nút thử lại
Business Drift (biz-auditor)Kiểm tra USP, thông điệp CTA theo RULE-biz.mdSử dụng từ ngữ quảng cáo mông quạnh, thiếu chứng minh thực tế

3. Quy Trình Triage Của Lead Trên Model Mạnh

Một sai lầm thường gặp là giao việc phân loại mức độ nghiêm trọng của lỗi cho các AI Model giá rẻ. Trong AkiDevRule, hạ tầng vận hành theo mô hình hai tầng linh hoạt:

graph TD
    A[Domain Read-only Specialists] -->|Mechanical Sweeps / Cheap Model| B[Raw Audit Logs]
    B -->|Triage & Impact Assessment| C[Lead Agent / Strong Model pro]
    C --> D1[CRITICAL: Sai Logic / Lỗ Hổng Bảo Mật]
    C --> D2[STALE: Tài Liệu Cũ Cần Cập Nhật]
    C --> D3[INCOMPLETE: Thiếu Trạng Thái Edge Case]
    C --> D4[COSMETIC: Lỗi Định Dạng Giao Diện Nhỏ]
    
    style C fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style D1 fill:#ef4444,stroke:#dc2626,color:#fff

4 Cấp độ Phân Loại Severity (Triage Classification):

  1. WRONG (Sai sót nghiêm trọng): Code chạy sai contract, hở security hoặc crash runtime. Bắt buộc sửa trước khi release.
  2. STALE (Lỗi thời): Tài liệu hoặc comment chưa cập nhật theo code mới. Thấp hơn ưu tiên sửa code.
  3. INCOMPLETE (Chưa hoàn thiện): Thiếu handling cho edge-cases (VD: offline network, 404 response).
  4. COSMETIC (Hình thức): Thừa khoảng trắng, thụt lùi dòng không đều. Mức ưu tiên thấp nhất.

4. Định Dạng Báo Cáo Audit Theo Từng Giai Đoạn

Output của một phiên Audit Mode không được là một đoạn văn bản tự do, mà phải xuất ra file báo cáo theo đúng template chuẩn:

Template Báo Cáo Audit (docs/research/audit-report-YYYY.MM.DD.md):

# Audit Report: [Tên Hệ Thống / Module]
Date: YYYY-MM-DD | Auditor: agent.B5 Read-Only Sweep | Status: TRIAGED

## I. Summary Statistics
- Total Files Scanned: 42
- Critical Findings (WRONG): 2
- Documentation Drifts (STALE): 5
- Edge-Case Gaps (INCOMPLETE): 3

## II. Detailed Triaged Findings

### 1. [WRONG] Missing Webhook Signature Validation
- **Location**: `web/dev.akitao.com/app/server/api/stripe.ts#L45`
- **Rule Violated**: `coding.B3` (External Action Completeness)
- **Empirical Evidence**: Route Handler nhận request body trực tiếp không qua `stripe.webhooks.constructEvent`.
- **Recommended Action**: Wrap body parsing trong Stripe SDK signature check.

### 2. [STALE] Outdated JSDoc Parameters in lessons.ts
- **Location**: `web/dev.akitao.com/app/data/lessons.ts#L12`
- **Rule Violated**: `docs.A1` (Single Source of Truth)
- **Empirical Evidence**: Comment ghi 29 lessons nhưng mảng thực tế có 33 lessons.

5. Hướng Dẫn Tích Hợp Audit Mode Vào CI/CD Pipeline

Để duy trì tính toàn vẹn của mã nguồn liên tục, bạn có thể thiết lập lệnh Audit Mode chạy tự động trong các phiên kiểm thử định kỳ trước khi Merge Code:

# Lệnh chạy Audit Sweep An Toàn (Read-Only) với AkiDevRule
npx akirule audit --domain=docs,ui,flow --strict-read-only

!TIPBest Practice: Kết hợp Audit Mode với git status --porcelain ở cuối script pipeline. Nếu phát hiện bất kỳ file nào bị biến đổi sau lệnh audit, script sẽ ngay lập tức raise exit code 1 và hủy tiến trình deployment.