205 lines
7.3 KiB
Markdown
205 lines
7.3 KiB
Markdown
# Áp dụng CASAN từ đầu trên Windows
|
|
|
|
Tài liệu này dành cho thành viên đã có một repository dự án nhưng repository đó **chưa có CASAN**. CASAN Core được clone riêng từ Gitea, sau đó DevKit cài runtime và policy vào repository dự án.
|
|
|
|
Giá trị sau được installer thay theo dự án:
|
|
|
|
- Project ID: `__PROJECT_ID__`
|
|
- Project name: `__PROJECT_NAME__`
|
|
|
|
## 1. Phạm vi hỗ trợ
|
|
|
|
Luồng này áp dụng cho agent coding chạy tại project root:
|
|
|
|
- Claude Code;
|
|
- Codex;
|
|
- GitHub Copilot Coding Agent;
|
|
- GitHub Copilot hoặc agent plugin trong VS Code có hỗ trợ repository instructions.
|
|
|
|
CASAN CLI đầy đủ chạy trong WSL2. PowerShell chỉ đóng vai trò gọi wrapper WSL2.
|
|
|
|
## 2. Cài WSL2 và công cụ nền
|
|
|
|
Trong PowerShell Administrator, nếu máy chưa có WSL2:
|
|
|
|
```powershell
|
|
wsl --install -d Ubuntu
|
|
```
|
|
|
|
Khởi động lại Windows nếu được yêu cầu. Sau đó mở PowerShell thường và cài công cụ trong Ubuntu:
|
|
|
|
```powershell
|
|
wsl -d Ubuntu -- bash -lc 'sudo apt-get update && sudo apt-get install -y git python3 rsync'
|
|
wsl -d Ubuntu -- bash -lc 'git --version && python3 --version && rsync --version | head -1'
|
|
```
|
|
|
|
SSH key truy cập Gitea phải được cấu hình trong `~/.ssh` của WSL hoặc thông qua cơ chế quản lý key đã được tổ chức phê duyệt. Không đặt private key trong repository.
|
|
|
|
## 3. Khai báo đường dẫn
|
|
|
|
Thay hai đường dẫn Windows và URL Gitea theo môi trường thực tế:
|
|
|
|
```powershell
|
|
$TargetProjectWin = 'C:\Projects\my-existing-project'
|
|
$CasanSourceWin = 'C:\Projects\.casan-source\casan-core'
|
|
$CasanRepo = 'ssh://git@<gitea-host>:<port>/<owner>/<casan-repo>.git'
|
|
|
|
$TargetProjectWsl = (wsl -d Ubuntu -- wslpath -a $TargetProjectWin).Trim()
|
|
$CasanSourceWsl = (wsl -d Ubuntu -- wslpath -a $CasanSourceWin).Trim()
|
|
```
|
|
|
|
Kiểm tra:
|
|
|
|
```powershell
|
|
wsl -d Ubuntu -- bash -lc "test -d '$TargetProjectWsl' && printf 'TARGET_OK=%s\n' '$TargetProjectWsl'"
|
|
```
|
|
|
|
Nếu dự án là Git repository, commit hoặc lưu riêng thay đổi hiện có trước khi adoption:
|
|
|
|
```powershell
|
|
wsl -d Ubuntu -- bash -lc "cd '$TargetProjectWsl' && git status --short --branch"
|
|
```
|
|
|
|
Không dùng `git reset --hard` hoặc `git clean` để chuẩn bị cài đặt.
|
|
|
|
## 4. Clone CASAN Core từ Gitea
|
|
|
|
Clone lần đầu:
|
|
|
|
```powershell
|
|
New-Item -ItemType Directory -Force -Path (Split-Path $CasanSourceWin -Parent) | Out-Null
|
|
wsl -d Ubuntu -- bash -lc "git clone '$CasanRepo' '$CasanSourceWsl'"
|
|
```
|
|
|
|
Nếu đã clone, chỉ cập nhật bằng fast-forward khi working tree CASAN sạch:
|
|
|
|
```powershell
|
|
wsl -d Ubuntu -- bash -lc "cd '$CasanSourceWsl' && git status --short --branch && git pull --ff-only origin main"
|
|
```
|
|
|
|
## 5. Cài CASAN vào repository dự án
|
|
|
|
```powershell
|
|
wsl -d Ubuntu -- bash -lc "cd '$CasanSourceWsl' && bash packages/casan-devkit/install.sh --target '$TargetProjectWsl' --project '__PROJECT_ID__' --domain '__PROJECT_NAME__'"
|
|
```
|
|
|
|
Installer tạo hoặc cập nhật:
|
|
|
|
- `packages/casan-harness/` — CASAN Core H1-H7;
|
|
- `bin/casan` — CLI;
|
|
- `bin/casan-chat` và `bin/casan-chat.ps1` — prompt entrypoint;
|
|
- `.casan/prompt-policy.json` — project binding;
|
|
- `apps/__PROJECT_ID__/domain/` — domain pack ban đầu;
|
|
- `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md` — agent enforcement block;
|
|
- `.gitea/workflows/casan-prompt-enforcement.yml` — kiểm tra contract trên CI;
|
|
- `docs/casan/` — hướng dẫn đã render cho dự án.
|
|
|
|
Installer giữ nội dung bên ngoài CASAN marker, tài liệu domain hiện hữu, project registry và workflow CI hiện hữu.
|
|
|
|
## 6. Thay domain scaffold bằng context thật
|
|
|
|
Hoàn thiện tối thiểu:
|
|
|
|
```text
|
|
apps/__PROJECT_ID__/domain/input/requirement.md
|
|
apps/__PROJECT_ID__/domain/input/architecture.md
|
|
apps/__PROJECT_ID__/domain/golden-runs/
|
|
apps/__PROJECT_ID__/domain/traceability-map.json
|
|
apps/__PROJECT_ID__/domain/corpus/
|
|
```
|
|
|
|
Không đưa source tree lớn, binary, log, build output, credential hoặc dữ liệu nhạy cảm vào context mặc định. Chỉ khai báo những context root cần thiết và có chủ đích.
|
|
|
|
## 7. Xác minh installation contract
|
|
|
|
```powershell
|
|
wsl -d Ubuntu -- bash -lc "cd '$TargetProjectWsl' && bin/casan prompt verify"
|
|
```
|
|
|
|
Kết quả bắt buộc:
|
|
|
|
```text
|
|
CASAN_PROMPT_ENFORCEMENT_VALID project=__PROJECT_ID__ mode=enforced
|
|
```
|
|
|
|
Nếu lệnh thất bại, dừng sử dụng agent và sửa đúng artifact được báo thiếu hoặc sai.
|
|
|
|
## 8. Chạy gate ban đầu
|
|
|
|
```powershell
|
|
wsl -d Ubuntu -- bash -lc "cd '$TargetProjectWsl' && CASAN_DOMAIN_ROOT='apps/__PROJECT_ID__/domain' bin/casan gate"
|
|
```
|
|
|
|
Gate có thể fail khi domain pack chưa có requirement, golden run hoặc corpus thật. Không sửa report để đổi FAIL thành PASS; bổ sung đúng evidence còn thiếu.
|
|
|
|
## 9. Gửi prompt qua CASAN
|
|
|
|
Từ project root trong PowerShell:
|
|
|
|
```powershell
|
|
Set-Location $TargetProjectWin
|
|
powershell -ExecutionPolicy Bypass -File bin\casan-chat.ps1 "Review the current requirements and identify missing acceptance criteria."
|
|
```
|
|
|
|
Chế độ tương tác:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File bin\casan-chat.ps1
|
|
```
|
|
|
|
Mỗi lượt thành công phải có `certified=true`, `trace_id` và dòng `CASAN_PROMPT_TRACE_CERTIFIED ... gates=7`.
|
|
|
|
## 10. Xác minh một prompt
|
|
|
|
```powershell
|
|
wsl -d Ubuntu -- bash -lc "cd '$TargetProjectWsl' && bin/casan prompt trace '<trace-id>'"
|
|
```
|
|
|
|
Kết quả hợp lệ:
|
|
|
|
```text
|
|
CASAN_PROMPT_TRACE_CERTIFIED project=__PROJECT_ID__ trace_id=<trace-id> gates=7
|
|
```
|
|
|
|
## 11. Dùng với Claude Code, Codex và Copilot
|
|
|
|
Mở agent tại đúng `$TargetProjectWin`. Agent phải đọc instruction tương ứng:
|
|
|
|
- Codex: `AGENTS.md`;
|
|
- Claude Code: `CLAUDE.md`;
|
|
- GitHub Copilot: `.github/copilot-instructions.md`.
|
|
|
|
Nếu plugin không hỗ trợ repository instructions hoặc tính năng đó đang tắt, không được coi prompt là đã enforce. Prompt trực tiếp không có CASAN trace không được gắn nhãn certified.
|
|
|
|
Chi tiết role, codegen và approval nằm trong `docs/casan/CASAN_PROMPT_ENFORCEMENT.md`.
|
|
|
|
## 12. Commit adoption vào repository dự án
|
|
|
|
Sau khi review diff và chạy verify:
|
|
|
|
```powershell
|
|
wsl -d Ubuntu -- bash -lc "cd '$TargetProjectWsl' && git status --short"
|
|
```
|
|
|
|
Commit các artifact CASAN cần được chia sẻ cho team. Không commit `.specify/` runtime log nếu policy repository yêu cầu giữ telemetry ngoài Git.
|
|
|
|
## 13. Nâng cấp CASAN
|
|
|
|
```powershell
|
|
wsl -d Ubuntu -- bash -lc "cd '$CasanSourceWsl' && git pull --ff-only origin main"
|
|
wsl -d Ubuntu -- bash -lc "cd '$CasanSourceWsl' && bash packages/casan-devkit/install.sh --target '$TargetProjectWsl' --project '__PROJECT_ID__' --domain '__PROJECT_NAME__'"
|
|
wsl -d Ubuntu -- bash -lc "cd '$TargetProjectWsl' && bin/casan prompt verify"
|
|
```
|
|
|
|
## Checklist bàn giao
|
|
|
|
- [ ] WSL2 có Git, Python 3 và rsync.
|
|
- [ ] CASAN Core được clone riêng từ Gitea và đang ở `main` mới nhất.
|
|
- [ ] Installer hoàn tất cho project `__PROJECT_ID__`.
|
|
- [ ] Domain pack đã dùng context/evidence thật.
|
|
- [ ] `bin/casan prompt verify` đạt.
|
|
- [ ] Agent coding được mở tại project root và đọc repository instructions.
|
|
- [ ] Prompt mẫu trả `certified=true` và trace H1-H7 xác minh được.
|
|
- [ ] H6 telemetry có `project_id=__PROJECT_ID__`.
|
|
- [ ] Workflow `casan-prompt-enforcement.yml` được commit và chạy trên push/PR.
|