vidreview/CLAUDE.md

Môi trường

Môi trường	URL / Port	Mục đích	Quy tắc
local	localhost	Phát triển, debug nhanh	Không commit trực tiếp vào test
dev	dev-vid.k9tech.space	Integration test trước khi lên test	✅ Dùng để verify trước khi merge
test	(hiện tại)	Production-like validation	🔒 Read-mostly, không test trực tiếp

Dev Team Workflow

Luồng phát triển

Checkout từ main
    ↓
Tạo branch: feature/<ticket>-<mô-tả>
    ↓
Phát triển + chạy lint + typecheck + unit tests trên local
    ↓
Deploy lên dev để integration test
    ↓
Tạo PR / merge vào main
    ↓
Deploy lên test khi đã ổn định trên dev

Git conventions

Branch naming: feature/<ticket>-<mô-tả-ngắn>

Commit message prefix:

• feat: tính năng mới
• fix: sửa bug
• refactor: tái cấu trúc
• test: thêm/sửa test
• docs: cập nhật docs
• chore: config, dependency

Trước khi merge/PR

git fetch origin && git rebase origin/main
npm run lint && npm run typecheck && npm test

Database migration — KHÔNG bao giờ chạy trực tiếp trên test

1. Tạo migration file mới
2. Apply lên dev trước
3. Verify trên dev → chỉ khi ổn định mới apply lên test
4. Backup DB trước khi thay đổi lớn
5. Migration phải idempotent

Các lệnh thường dùng

# Deploy lên dev
./scripts/deploy.sh dev <branch-name>

# Xem worker logs trên dev
docker logs -f vidreview-worker-dev

# Check health dev
curl https://dev-vid.k9tech.space/api/health

# Reset stuck jobs trên dev
docker restart vidreview-worker-dev

Quy tắc quan trọng

✅ NÊN	❌ KHÔNG
Test trên dev trước	Test trực tiếp trên test
Dùng .env.local cho local	Hardcode credentials
Viết migration idempotent	Migration fail giữa chừng
Backup DB trước thay đổi lớn	Sửa schema trên test không qua migration
Có test cho logic mới	Deploy lên test sau giờ làm việc

Incident response

1. Báo team ngay
2. Không tự ý restart services trên test
3. Điều tra trên dev trước
4. Fix → merge → deploy dev → verify → deploy test

5. Post-mortem sau khi resolved

   MCP Tools: code-review-graph

IMPORTANT: This project has a knowledge graph. ALWAYS use the code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore the codebase. The graph is faster, cheaper (fewer tokens), and gives you structural context (callers, dependents, test coverage) that file scanning cannot.

When to use graph tools FIRST

• Exploring code: semantic_search_nodes or query_graph instead of Grep
• Understanding impact: get_impact_radius instead of manually tracing imports
• Code review: detect_changes + get_review_context instead of reading entire files
• Finding relationships: query_graph with callers_of/callees_of/imports_of/tests_for
• Architecture questions: get_architecture_overview + list_communities

Fall back to Grep/Glob/Read only when the graph doesn't cover what you need.

Key Tools

Tool	Use when
detect_changes	Reviewing code changes — gives risk-scored analysis
get_review_context	Need source snippets for review — token-efficient
get_impact_radius	Understanding blast radius of a change
get_affected_flows	Finding which execution paths are impacted
query_graph	Tracing callers, callees, imports, tests, dependencies
semantic_search_nodes	Finding functions/classes by name or keyword
get_architecture_overview	Understanding high-level codebase structure
refactor_tool	Planning renames, finding dead code

Workflow

1. The graph auto-updates on file changes (via hooks).
2. Use detect_changes for code review.
3. Use get_affected_flows to understand impact.
4. Use query_graph pattern="tests_for" to check coverage.