Prompt — Bổ sung Quy tắc Dọn dẹp File Trung gian vào AGENTS.md

Chế độ: Viết mới
Host: Antigravity / Agent có quyền đọc-ghi file
Target: Cùng host (thực thi trực tiếp)
Ngày: 25/09/2026

Prompt hoàn chỉnh — Sẵn copy

## Nhiệm vụ

Bổ sung cơ chế quản lý và dọn dẹp file trung gian vào file AGENTS.md
của dự án CXK, đảm bảo project luôn sạch sẽ, an toàn, dễ bảo trì.

---

## Bối cảnh

Dự án CXK là đề tài NCKH cấp PTTH do học sinh lớp 10 thực hiện.
Trong quá trình làm việc, AI agent thường sinh ra các file trung gian:
- Python script xử lý dữ liệu (validate, convert, scrape)
- File tạm (.tmp, .bak, .log)
- File output thử nghiệm (test_*.md, draft_*.yaml)
- Script shell/batch hỗ trợ
- File cache hoặc __pycache__

Nếu không dọn, các file này gây:
- Rối cấu trúc thư mục (NCS là học sinh, cần project dễ hiểu)
- Rủi ro commit nhầm secrets hoặc đường dẫn cục bộ
- Khó phân biệt file chính thức và file thử nghiệm
- Tốn dung lượng trên Google Shared Drive

---

## Việc cần làm — 4 bước

### Bước 1: Khảo sát file trung gian hiện có

Quét toàn bộ project `CXK/` tìm file nghi ngờ là trung gian:

```powershell
# Tìm file Python không nằm trong backend/ hoặc tools/
Get-ChildItem -Recurse -Filter "*.py" | Where-Object {
    $_.FullName -notmatch "backend" -and
    $_.FullName -notmatch "tools" -and
    $_.FullName -notmatch "scripts" -and
    $_.FullName -notmatch "node_modules" -and
    $_.FullName -notmatch ".venv"
}

# Tìm file tạm
Get-ChildItem -Recurse -Include "*.tmp","*.bak","*.log","__pycache__" -Force

# Tìm file thử nghiệm
Get-ChildItem -Recurse -Filter "test_*" | Where-Object {
    $_.FullName -notmatch "testing"
}

# Tìm file draft
Get-ChildItem -Recurse -Filter "draft_*"

Lập bảng kết quả:
| # | File | Đường dẫn | Loại | Kích thước | Quyết định |
|---|---|---|---|---|---|
| 1 | validate_schema.py | tools/ | Tool chính thức | 2KB | ✅ Giữ |
| 2 | temp_convert.py | docs/ | Script tạm | 1KB | ❌ Xoá |
| ... | ... | ... | ... | ... | ... |

Cột Quyết định có 3 giá trị:
- ✅ Giữ — file chính thức, thuộc codebase
- ❌ Xoá — file trung gian, không còn cần
- ⚠️ Hỏi NCS — không chắc, cần NCS quyết định

Bước 2: Soạn mục mới cho AGENTS.md

Thêm mục "9. Quản lý file trung gian" vào AGENTS.md, đặt sau mục 8
và trước dòng "Cập nhật lần cuối". Nội dung:

## 9. Quản lý file trung gian (BẮT BUỘC)

AI agent thường sinh file trung gian khi xử lý (script Python, file tạm,
output thử nghiệm). Các file này PHẢI được quản lý theo quy tắc sau:

### 9.1 Vị trí lưu trữ

| Loại file | Vị trí cho phép | Ví dụ |
|---|---|---|
| Script Python hỗ trợ | `tools/` hoặc `scripts/` | `tools/validate_schema.py` |
| Script tạm (dùng 1 lần) | KHÔNG lưu — xoá sau khi chạy | — |
| File test/draft | `testing/` hoặc thư mục Sprint | `testing/scratch/` |
| Cache, __pycache__ | KHÔNG commit | Thêm vào .gitignore |
| File output AI (CSV, JSON) | Cùng thư mục deliverable | `knowledge-base/data/` |

### 9.2 Quy tắc dọn dẹp

1. ❌ **Không lưu file trung gian ở thư mục gốc** hoặc ngang cấp source.
   Ví dụ: KHÔNG để `convert.py` trong `docs/`.
2. ❌ **Không commit file trung gian** — thêm pattern vào `.gitignore`:
   ```
   *.tmp
   *.bak
   *.log
   __pycache__/
   *.pyc
   .scratch/
   ```
3. ✅ **Xoá file trung gian ngay sau khi hoàn thành task.**
   Nếu script chỉ dùng 1 lần → xoá. Nếu dùng lại → chuyển vào `tools/`.
4. ✅ **AI agent tự kiểm tra trước khi kết thúc phiên làm việc:**
   - Liệt kê file đã tạo trong phiên
   - Phân loại: giữ / xoá / chuyển vị trí
   - Thực hiện dọn dẹp
   - Báo cáo cho NCS biết đã dọn gì
5. ✅ **File script quan trọng phải có docstring** giải thích mục đích,
   đặt trong `tools/` với tên rõ ràng (snake_case).

### 9.3 Checklist cuối phiên (AI agent BẮT BUỘC chạy)

Trước khi kết thúc mỗi phiên làm việc, AI agent phải:
- [ ] Liệt kê tất cả file đã tạo/sửa trong phiên
- [ ] Xoá file tạm không còn cần
- [ ] Chuyển script hữu ích vào `tools/` hoặc `scripts/`
- [ ] Kiểm tra không có file .py nằm sai vị trí
- [ ] Báo cáo tóm tắt cho NCS

Bước 3: Cập nhật AGENTS.md

1. Chèn nội dung mục 9 vào AGENTS.md (trước dòng > **Cập nhật lần cuối:**).
2. Cập nhật ngày: > **Cập nhật lần cuối:** 25/09/2026
3. Cập nhật phiên bản: > **Phiên bản:** 1.2

Bước 4: Thực hiện dọn dẹp lần đầu

Dựa trên bảng khảo sát ở Bước 1:
1. Xoá tất cả file có quyết định ❌.
2. Chuyển file script hữu ích vào tools/.
3. Liệt kê file ⚠️ cho NCS quyết định.
4. Tạo/cập nhật .gitignore với pattern từ mục 9.2.

Ràng buộc

1. Không xoá file nằm trong cấu trúc 6 tầng (docs/, knowledge-base/,
   safety/, backend/, testing/, community/) trừ khi chắc chắn là file tạm.
2. Không xoá tools/validate_schema.py — đây là file chính thức.
3. Giữ nguyên nội dung mục 1–8 của AGENTS.md. Chỉ thêm mục 9.
4. Thuật ngữ chuẩn AGENTS.md — không tạo thuật ngữ mới.
5. Ngôn ngữ đơn giản — NCS là học sinh PTTH.
6. Báo cáo kết quả — liệt kê file đã xoá, file đã chuyển, file chờ NCS.

Đầu ra

1. File AGENTS.md đã cập nhật (thêm mục 9).
2. .gitignore đã cập nhật.
3. Bảng tổng kết dọn dẹp:
   | Hành động | Số file | Chi tiết |
   |---|---|---|
   | Xoá | X | Danh sách file |
   | Chuyển vào tools/ | X | Danh sách file |
   | Chờ NCS | X | Danh sách file |
   ```

Cách dùng

1. Copy nội dung trong khối ```text ```.
2. Chạy trên agent có quyền đọc-ghi file trong project CXK.
3. Agent sẽ: khảo sát → soạn nội dung → sửa AGENTS.md → dọn dẹp → báo cáo.

Giới hạn

• Prompt không cover file do NCS tự tạo bằng tay (chỉ file AI sinh).
• .gitignore chỉ hiệu quả khi project dùng Git. Hiện CXK trên Google Shared Drive
  nên .gitignore là chuẩn bị sẵn cho tương lai.
• Quy tắc "checklist cuối phiên" phụ thuộc vào agent tuân thủ AGENTS.md.