CASAN/docs/plans/CASAN_APPLY_IDE_OPERATOR_PLAYBOOK.md

CASAN APPLY — Playbook vận hành trong VS Code (thực chiến)

Mục đích: trả lời rất cụ thể: ngồi trước VS Code thì thao tác gì, chọn model nào, gõ tin nhắn gì để khởi động một luồng, và có phải gửi 1 phát là xong không — hay phải tối ưu qua nhiều phiên. Lấy dự án BĐS match người mua ↔ BĐS làm ví dụ xuyên suốt. Đọc kèm: CASAN_APPLY_REALESTATE_MATCHING.md (runbook luồng gate).

---

0. SỰ THẬT CỐT LÕI — KHÔNG phải "1 tin nhắn là xong"

Gửi một prompt khổng lồ "làm cho tôi hệ thống match BĐS hoàn chỉnh" = cách chắc chắn thất bại. Vì:

• Context window có hạn, prompt càng dài chất lượng càng degrade.
• Không verify từng bước → sai chồng sai, cuối cùng không ai kiểm được.
• Không có bằng chứng, không rollback, không giải trình — trái toàn bộ tư tưởng CASAN.

→ Đúng cách: prompt → LOOP. Chia thành nhiều phiên (session), mỗi phiên một mục tiêu nhỏ, nhiều lượt (turn), verify rồi commit. Prompt tốt cho một câu trả lời; loop tốt cho một hệ thống.

---

1. PHÂN BIỆT SỐNG CÒN: 2 loại "model"

Đừng nhầm hai thứ hoàn toàn khác nhau:

	Model trong IDE (giúp bạn XÂY hệ thống)	Model trong sản phẩm (runtime CHẤM match)
Ai dùng	Bạn (dev/harness engineer)	Ứng dụng BĐS khi chạy thật
Việc	Viết code, plan, test, review	Xếp hạng người mua ↔ BĐS
Dữ liệu	Code, plan (không PII thật)	PII tài chính người mua
Chọn ở đâu	Model picker của VS Code	model-router.sh + loop-policy
Ràng buộc	Chọn theo độ mạnh/nhanh	PII → model LOCAL, cloud cần approval

Phần dưới nói về model trong IDE (để bạn build). Model runtime đã bàn ở runbook kia.

---

2. CHỌN MODEL TRONG IDE theo từng việc

Trong VS Code, đổi model theo loại việc (không dùng một model cho mọi thứ):

Việc	Loại model nên chọn	Vì sao
Brainstorm, thiết kế kiến trúc, viết plan/spec	Model suy luận mạnh (lớp Opus/GPT-5)	Cần lập luận sâu, đánh đổi kiến trúc
Sinh code cơ học, sửa lặp, đổi tên	Model nhanh/rẻ	Việc rõ ràng, ưu tiên tốc độ
Review bảo mật / soi lỗi tinh vi	Model suy luận mạnh	Bắt lỗi khó
Hỏi nhanh/giải thích	Model nhanh	Rẻ

Thao tác VS Code: mở Chat (Ctrl+Alt+I) → dropdown chọn model → chọn theo bảng. Đổi model giữa các phiên tuỳ việc.

---

3. CHUẨN BỊ WORKSPACE (làm 1 lần, trước khi khởi động)

1. Mở đúng workspace chứa: plan/spec (casan-next-plans/…), harness scripts (.specify/…), code app.
2. Terminal WSL sẵn sàng (harness verify chạy trong WSL — xem memory dự án).
3. Git sạch (git status clean) — để mỗi bước commit nhỏ, rollback được.
4. Plan/Spec = bộ nhớ bền giữa các phiên. Trước khi code, phải có: success-criteria.yaml, hard-constraints.yaml, fairness-rules.yaml (dù mới ở dạng nháp).
5. Dữ liệu giả cho dev — không dán PII thật vào chat.

---

4. CẤU TRÚC MỘT PHIÊN (session) — vòng lặp chuẩn

Một phiên KHÔNG phải một tin nhắn. Nó là vòng lặp:

flowchart LR
    K["① Kickoff<br/>nạp ngữ cảnh + goal<br/>+ success-criteria"] --> B["② Bàn trước<br/>(brainstorm, CHƯA code)"]
    B --> T["③ Giao task nhỏ"]
    T --> V["④ Verify<br/>chạy test/gate"]
    V -- fail --> T
    V -- pass --> C["⑤ Commit nhỏ"]
    C --> N{"còn task?"}
    N -- có --> T
    N -- hết --> E["⑥ Kết phiên<br/>update plan + /clear"]

• 1 phiên = 1 mục tiêu nhỏ (vd "dựng hard-filter + test"), không ôm cả hệ thống.
• Verify-before-accept: không nhận code chưa chạy test/gate.
• Kết phiên: commit, cập nhật plan, /clear để context sạch cho phiên sau (giữ vệ sinh ngữ cảnh — H1).

---

5. BẢN ĐỒ NHIỀU PHIÊN cho dự án BĐS (tối ưu qua nhiều lần, không 1 phát)

Phiên	Mục tiêu	Model	Kết quả
P1	Brainstorm + chốt spec: input schema, hard-constraints, fairness, success-criteria — CHƯA code	mạnh	các file config/*.yaml
P2	hard_filter.py (deterministic) + test	nhanh	filter + test xanh
P3	ranker.py nối model-router (model local cho PII)	mạnh	rank + test
P4	explainer.py → evidence trích thuộc tính thật	nhanh	explain + test
P5	Verify-gate H3 + fairness H5 + test đối kháng	mạnh	gate fail-closed
P6	Loop control (budget/convergence) + audit	mạnh	loop-trace
P7	Widget dashboard (Command Center)	nhanh	UI đọc artifact thật

→ 7 phiên, mỗi phiên bắt đầu context sạch, trỏ vào plan, verify, commit. Đó là "tối ưu qua nhiều phiên".

---

6. TIN NHẮN CỤ THỂ (copy-paste, chỉnh theo ngữ cảnh)

⓵ Kickoff phiên (nạp ngữ cảnh + ràng buộc + success-criteria)

Bối cảnh: dự án BĐS match người mua ↔ BĐS. Đọc casan-next-plans/CASAN_APPLY_REALESTATE_MATCHING.md
và config/hard-constraints.yaml.
Mục tiêu phiên này: dựng hard_filter.py — loại ứng viên vi phạm budget/pháp lý/deal-breaker.
Ràng buộc: luật cứng nằm NGOÀI model (deterministic); fail-closed; không đụng file khác.
Success-criteria: có test cho 5 ca (vượt budget, không sổ, tranh chấp, deal-breaker, hợp lệ) và test xanh.
CHƯA code vội — trình bày cách tiếp cận trước để tôi duyệt.

⓶ Bàn trước khi code (brainstorm — bắt buộc cho việc khó)

Trước khi viết code, liệt kê: input/output của hard_filter, các luật sẽ áp,
edge case, và cách test. Đợi tôi OK rồi mới code.

⓷ Giao task nhỏ (sau khi duyệt hướng)

OK hướng đó. Implement hard_filter.py + test tương ứng. Chỉ file này.
Xong thì chạy test và cho tôi xem kết quả.

⓸ Yêu cầu verify (không tin lời, đòi bằng chứng)

Chạy test trong WSL và dán output. Nếu có ca fail, sửa rồi chạy lại tới khi xanh.

⓹ Sửa hướng (course-correct khi lệch)

Dừng lại. Bạn đang để model quyết budget — sai. Budget là luật cứng deterministic.
Bỏ phần đó, đưa về so sánh số trực tiếp trong hard_filter.

⓺ Chốt & commit

Test xanh rồi. Tóm tắt thay đổi 1 dòng, rồi tôi commit. Cập nhật trạng thái task
trong plan tương ứng.

⓻ Kết phiên / sang phiên mới

Xong mục tiêu phiên. Cập nhật plan (task này Done + verify). Tôi sẽ /clear và mở
phiên mới cho ranker.

---

7. VÌ SAO PHẢI NHIỀU PHIÊN (lý do kỹ thuật, không phải cho vui)

1. Context bền vs context phiên: plan/spec là bộ nhớ bền; chat là bộ nhớ tạm. Context dài → model quên/nhiễu → chất lượng giảm. /clear + trỏ lại plan = luôn "tươi".
2. Verify-before-accept từng bước chặn sai chồng sai — đúng tinh thần verify-gate (H3).
3. Commit nhỏ = rollback được — đúng nguyên tắc accountability/rollback của CASAN.
4. Loop discipline: đặt "budget" cho mỗi phiên (phạm vi hẹp), dừng khi lệch — chính là Loop Engineering áp vào chính cách bạn làm việc.

---

8. DO / DON'T vận hành

✅ Nên	❌ Tránh
1 phiên 1 mục tiêu nhỏ	1 tin nhắn "làm hết hệ thống"
Bàn hướng trước khi code (việc khó)	Để agent code ngay việc mơ hồ
Đòi chạy test + xem output	Tin "đã xong" mà không verify
Commit nhỏ, thường xuyên	Dồn 1 commit khổng lồ
Trỏ vào plan/spec làm ngữ cảnh	Kể lại toàn bộ bối cảnh mỗi lần
/clear khi đổi mục tiêu	Kéo dài 1 phiên vô tận
Chọn model theo việc	Một model cho mọi thứ

---

9. PII & BẢO MẬT khi thao tác IDE (riêng cho BĐS)

• KHÔNG dán PII thật (tài chính/danh tính người mua) vào chat IDE (cloud). Dev dùng dữ liệu giả/ẩn danh.
• Model runtime xử lý PII = local, cấu hình trong app (model-router), khác model bạn dùng trong IDE.
• Nếu buộc phải xử lý dữ liệu nhạy cảm → dùng model local trong IDE hoặc tắt gửi context.

---

10. GHI CHÚ TRUNG THỰC

• Playbook này là cách vận hành — áp dụng được ngay hôm nay với bất kỳ IDE-agent nào (không chờ Plan nào cả).
• Các script gate BĐS (hard_filter, ranker, verify-gate…) là code dự án bạn sẽ viết qua các phiên trên; harness CASAN (context-compress, rai-guard, security-check, model-router…) là thứ đã có để bọc governance.
• "Tối ưu qua nhiều phiên" không phải điểm yếu — đó là cách duy nhất ra hệ thống đáng tin, verify được, giải trình được. One-shot chỉ hợp việc nhỏ/nháp.
• Con số phiên (7) là minh hoạ; thực tế có phiên phải lặp lại nhiều lần (vd P5 gate đối kháng thường tốn nhất).

---

Liên quan: CASAN_APPLY_REALESTATE_MATCHING.md (luồng gate chi tiết) · CASAN_PLAN_17_LOOP_ENGINEERING.md (loop discipline) · CASAN_PLAN_08_CONTEXT_COMPRESSION.md (vệ sinh ngữ cảnh) · CASAN_PLAN_15_RESPONSIBLE_AI_DATA_GOV.md (PII) · FPT_CASAN_Full.md (§4.3 Human-led, §4.4 delegation).