---
description: Đồng bộ CODEBASE.md với codebase thực tế — cập nhật delta, không rewrite toàn bộ
---

# /codebase-sync Workflow

> **Mục đích:** Giữ CODEBASE.md luôn up-to-date với codebase thực tế.
> **Nguyên tắc:** Chỉ append/update delta — không xóa thông tin cũ.
> **Trigger:** Gate 2 (file mới tạo), user gõ /codebase-sync, hoặc AI thấy outdated.

---

## Triggers (Khi nào chạy)

```
AUTO triggers:
  - Gate 2 hoàn thành + needs_codebase_sync = true trong session.json
  - AI biết file không có trong CODEBASE.md (từ orchestrator W6 flag)

MANUAL trigger:
  - User gõ: /codebase-sync
```

---

## Execution Phase: Direct AI Agent Execution

Khi workflow này được gọi (bằng cách gõ `/codebase-sync` hoặc tự động kích hoạt), AI Agent thực hiện trực tiếp các bước sau:

1. **Tìm kiếm các file thay đổi/thêm mới**:
   - Chạy lệnh `git status --porcelain` và `git log -n 30 --oneline` để xác định danh sách các file mới được tạo (`[NEW]`), bị sửa đổi (`[MODIFY]`), hoặc bị xóa (`[DELETE]`).
   - Nếu không có Git, tự động liệt kê hoặc so sánh các thư mục chính.

2. **Khảo sát cấu trúc file thực tế**:
   - Đọc qua phần đầu hoặc cấu trúc export/import của các file mới/sửa đổi để hiểu rõ vai trò và Layer của chúng.

3. **Cập nhật CODEBASE.md**:
   - Đọc `CODEBASE.md` hiện tại.
   - Nhận diện Layer và mục đích (Purpose) của các file thay đổi.
   - Chỉnh sửa trực tiếp file `CODEBASE.md`:
     - Thêm/sửa các bản ghi trong bảng tương ứng của từng thư mục dưới định dạng compact (compact format).
     - Cập nhật thời gian `Last Updated` ở phần đầu file.
     - Append lịch sử thay đổi vào phần `Update Changelog (Delta)` ở cuối file.

> [!IMPORTANT]
> - CODEBASE.md sử dụng định dạng compact dạng bảng. KHÔNG dùng định dạng dài dòng hoặc tự ý viết lại toàn bộ cấu trúc file.
> - Luôn lưu một bản sao lưu `CODEBASE.md.bak` trước khi thực hiện ghi đè hoặc sửa đổi lớn.


---

## Phase 4: Update Session State

```json
// brain/session.json — reset sau khi sync
{
  "codebase_last_synced": "2026-02-24T08:35:00Z",
  "files_touched_this_session": [],
  "needs_codebase_sync": false
}
```

---

## Output Summary

```
✅ CODEBASE.md Synced!

  📊 Added: [K] new entries
  📁 Sections updated: [list]
  🕐 Last Updated: 2026-02-24

💡 Next: AI sẽ dùng CODEBASE.md mới trong session tiếp theo
   → Không cần scan cấu trúc thủ công nữa
```

---

## Error Handling

```yaml
No CODEBASE.md found:
  → AI tạo mới từ đầu bằng cách scan project structure
  → Template dựa theo architecture trong .project-identity

No .git found:
  → Fallback: dùng session.json files_touched_this_session
  → Scan core directories thủ công (App/, Core/, Features/, Presentation/)

CODEBASE.md quá outdated (> 30 ngày):
  → Warn: "CODEBASE.md rất cũ, nên rebuild toàn bộ?"
  → Option A: Rebuild full (scan toàn bộ)
  → Option B: Chỉ update delta 14 ngày gần nhất
```

---

*codebase-sync v1.0 — Delta-based CODEBASE.md Synchronizer*
*Created by Kien AI*