Danh mục Nghiên cứu
Tổng hợp toàn bộ nghiên cứu đã thực hiện trong phiên Khám phá Liên tục trước khi viết dòng code đầu tiên. Mỗi Spike là một phiên nghiên cứu có giả thuyết, phát hiện, và kết luận rõ ràng.
PRDs — Bản Thiết kế
PRD-01: Tổng quan & Kiến trúc 5 Lớp
Định nghĩa kiến trúc hệ thống đầy đủ với 5+1 lớp: Lưu trữ (FrankenSQLite + Zvec), Công cụ Cốt lõi (gmind CLI, beads_rust, FastCode), Thực thi (AI Agents), Xác minh (CI/CD Gates), API Gateway (Go REST), và Trình bày (Web UI).
- ›AI agent KHÔNG THỂ tự đóng task — phải qua Lớp Xác minh trước
- ›Web UI giao tiếp qua Go REST API (nhúng FrankenSQLite) — không truy cập DB trực tiếp
- ›FastCode thay thế Zvec cho Trí tuệ Mã nguồn — Zvec chỉ phục vụ tài liệu/chat
- ›Trực quan RTM: Mục PRD ↔ Kế hoạch ↔ Task ↔ Commit có truy vết đầy đủ
Tác động: Bản thiết kế nền tảng cho mọi PRD và công việc triển khai khác
PRD-02: Lớp Lưu trữ & Theo dõi Phổ quát
Lưu trữ kết hợp: FrankenSQLite (trạng thái có cấu trúc, MVCC ghi đồng thời) + Zvec (tìm kiếm ngữ nghĩa cho tài liệu/chat). Theo dõi Phổ quát qua Beads-ID là khoá chính xuyên suốt mọi lớp. ID cấp phần cho truy vết PRD ↔ Kế hoạch ↔ Task.
- ›FrankenSQLite dùng cột SQL first-class (indexed, type-safe) — KHÔNG dùng JSON blob
- ›JSONL là SSOT đồng bộ qua git — FrankenSQLite là cache cục bộ (tái tạo được)
- ›Beads ID cấp phần: br-prdNN-sM cho mục PRD, br-plan-NN cho kế hoạch
- ›Chiến lược Dọn rác Lười: polling bảng events + garbage collection Zvec
- ›Dữ liệu GitHub lưu trong Zvec dạng tài liệu ngữ nghĩa — chỉ lưu PR/CI mới nhất trong FrankenSQLite
Tác động: Định hướng thiết kế schema beads_rust và luồng truy vấn gmind context
PRD-03: gmind CLI & Quy trình Agent
gmind là Cổng API Ngữ cảnh duy nhất. Định nghĩa 8+ lệnh CLI: search, search-codebase, context, trace, coverage, impact, gaps, github. Áp dụng Nguyên tắc Bốn Mắt (Code Agent ≠ Reviewer Agent) và khoá tệp Lease Timeout.
- ›gmind search-codebase là điểm vào duy nhất cho Trí tuệ Mã nguồn (FastCode ẩn bên trong)
- ›Quy trình Agent: Phân loại → TimCode → NạpNgữCảnh → KhoáTệp → Code → XácMinh → Đóng
- ›Tag truy vết bắt buộc: --tag='implements:' và --tag='satisfies:' trên mọi task
- ›Beads-ID: Git Trailer trong mọi commit — không còn cú pháp #br-123
Tác động: Định nghĩa chính xác quy tắc skill agent và bề mặt API CLI
Phiên Nghiên cứu — Hoàn tất
FrankenSQLite vs DoltDB
Đánh giá beads_rust+FrankenSQLite so với DoltDB cho quản lý task. FrankenSQLite thắng ở: MVCC trong tiến trình (không qua giao thức MySQL), đồng bộ JSONL qua git (1 VCS thay vì 2), binary 5-8MB vs 30+MB, và cột SQL first-class thay JSON blob.
- ›✅ beads_rust thay thế DoltDB — lợi ích vượt trội hơn mất mát
- ›Cell-level merge không cần thiết — agent làm việc trên task riêng biệt (khác hàng)
- ›Cần migration 5 cột PM: qa_status, qa_verified_by, test_logs_ref, coverage, escalation_level
- +1 kết luận nữa
Tích hợp FastCode CLI
FastCode đã có pipeline hoàn chỉnh: Tree-sitter AST → Graph Builder → BM25/Vector Index → LLM Iterative Retrieval → Answer Generator. Zvec không còn cần cho trí tuệ mã nguồn — chỉ phục vụ tài liệu/chat.
- ›gmind search-codebase là điểm vào duy nhất — FastCode là chi tiết nội bộ
- ›Zvec được đơn giản hoá: chỉ Tài liệu + Lịch sử Chat (không còn AST node hay đồ thị code)
- ›2 lệnh search tách biệt: gmind search (docs/Zvec) vs gmind search-codebase (code/FastCode)
- +1 kết luận nữa
Động cơ Knowledge Graph Beads
Beads ID là Nút Đồ thị Phổ quát — không chỉ là ID task. Mọi thực thể (PRD, Kế hoạch, Task, Commit, Chat, Ghi chú cuộc họp, Tệp code, PR, CI Run) liên kết qua Beads ID. gmind xây đồ thị tại thời điểm truy vấn từ 5+ nguồn dữ liệu, không lưu trùng lặp.
- ›gmind = Động cơ Truy vấn Đồ thị — duyệt song song FrankenSQLite, Git, Zvec, GitHub, YAML
- ›12+ loại cạnh tự phát hiện: satisfies, implements, committed-for, discussed-in, approved-by, code-touches, v.v.
- ›Zvec mở rộng thành Bộ Lập chỉ mục Dữ liệu Phi cấu trúc Phổ quát — index git commits, PRs, CI logs, ghi chú cuộc họp
- +1 kết luận nữa
Tích hợp Hệ sinh thái GitHub
Nghiên cứu sâu 3 phiên: GitHub Autolinks, Quy ước Commit (Git Trailers), tích hợp CI/CD, giới hạn API, chiến lược đồng bộ. Quyết định cuối: ưu tiên cục bộ dùng git + gh CLI — không dùng thư viện Go API, không webhooks.
- ›git + gh CLI thay thế thư viện Go API — không phụ thuộc bên ngoài
- ›Đồng bộ 3 tầng: Git cục bộ (90% trường hợp) → Theo sự kiện (CI đẩy) → Polling theo lịch (15-30 phút)
- ›Dữ liệu GitHub là ngữ cảnh ngữ nghĩa → thuộc về Zvec, không phải bảng SQL
- +2 kết luận nữa
Monorepo Đa ngôn ngữ & Hệ thống Thiết kế
Gmind là Monorepo Đa ngôn ngữ (Go, Rust, TypeScript). Sử dụng Language-Native Workspaces (go.work, Cargo.toml, pnpm) + Turborepo làm Bộ điều phối Gốc. Design System chia sẻ qua packages/design-system/.
- ›Turborepo + pnpm là bộ điều phối gốc — không dùng Bazel (quá nặng cho agent)
- ›Thư mục Go/Rust có package.json tối thiểu để Turborepo ủy quyền script
- ›PRDs phân vùng tên dưới /docs/PRDs/{subsystem}/ — SSOT tại gốc
- +1 kết luận nữa
Beads ID trong Tài liệu (Cấp phần)
Mở rộng Beads ID từ cấp task lên cấp phần tài liệu. Mục PRD, phần tử Kế hoạch được gán ID duy nhất qua YAML front matter. Cho phép RTM 3 lớp: Mục PRD ↔ Phần tử Kế hoạch ↔ Task.
- ›YAML front matter với beads-id mỗi phần: định dạng br-prdNN-sM
- ›Hai loại liên kết mới: satisfies (Kế hoạch→PRD) và implements (Task→Kế hoạch)
- ›Giai đoạn 1: dùng tag tạm (--tag='implements:br-plan-01')
- +1 kết luận nữa
Nghiên cứu Trong hàng đợi
Hiệu năng Graph Assembler
Đo hiệu năng xây đồ thị tại thời điểm truy vấn với 1000+ Beads ID. Xác định có cần tầng cache cho Graph Assembler không.
Pipeline Lập chỉ mục Zvec
Chi tiết cách lập chỉ mục git commits, mô tả PR, CI logs vào Zvec — kích thước chunk, schema metadata, tự phát hiện Beads ID trong mỗi chunk.