From ef51c90d915c11110108460376e33fc239f4d47a Mon Sep 17 00:00:00 2001 From: thanhnv Date: Fri, 10 Jul 2026 17:20:34 +0900 Subject: [PATCH] docs: explain how to use CASAN for real projects --- README.md | 18 +- docs/guides/CASAN_LOCAL_FULL_STACK.md | 4 + .../CASAN_USING_FOR_REAL_PROJECTS_VI.md | 286 ++++++++++++++++++ .../assets/casan-project-usage-flow.mmd | 11 + .../assets/casan-project-usage-flow.svg | 1 + 5 files changed, 315 insertions(+), 5 deletions(-) create mode 100644 docs/guides/CASAN_USING_FOR_REAL_PROJECTS_VI.md create mode 100644 docs/guides/assets/casan-project-usage-flow.mmd create mode 100644 docs/guides/assets/casan-project-usage-flow.svg diff --git a/README.md b/README.md index 13f1825..05e4727 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,16 @@ -# AI-SDLC Project - -AI-SDLC (AI Software Development Life Cycle) - Applying AI to the software development process. +# AI-SDLC Project + +AI-SDLC (AI Software Development Life Cycle) - Applying AI to the software development process. + +> **Bắt đầu từ đây nếu bạn muốn dùng CASAN:** +> [Dùng CASAN để làm dự án — giải thích thực tế, dễ hiểu](docs/guides/CASAN_USING_FOR_REAL_PROJECTS_VI.md). +> CASAN core không phụ thuộc Codex, VS Code hay Claude Code; các agent được mô tả +> dưới đây là flow demo/legacy có thể đặt phía sau CASAN governance. ## Table of Contents -- [Project Objectives](#project-objectives) +- [Project Objectives](#project-objectives) +- [Dùng CASAN cho dự án thực tế](docs/guides/CASAN_USING_FOR_REAL_PROJECTS_VI.md) - [Requirements](#requirements) - [Input for Flow](#input-for-flow) - [Output for FLow](#output-for-flow) @@ -34,7 +40,9 @@ Apply AI to the SDLC process to automate and optimize the creation of software p ## Requirements - **Flow + Prompt + Template**: **Spec-Kit** -- **AI Tool**: Using **Claude Code** as the main AI assistant +- **AI Tool của flow demo/legacy**: **Claude Code** là assistant chính; CASAN + harness và Control Panel có thể chạy độc lập bằng browser/CLI/CI hoặc dùng model + local/OmniRoute. - **AI-SDLC**: AI-integrated SDLC process **Spec-Kit Modified** (Add IPA Gen + Review Loop + Orchestrator) - **IPA Template**: Following IPA (Information-technology Promotion Agency) template standards diff --git a/docs/guides/CASAN_LOCAL_FULL_STACK.md b/docs/guides/CASAN_LOCAL_FULL_STACK.md index 187915d..59500d0 100644 --- a/docs/guides/CASAN_LOCAL_FULL_STACK.md +++ b/docs/guides/CASAN_LOCAL_FULL_STACK.md @@ -1,5 +1,9 @@ # CASAN local full stack (macOS) +> Nếu bạn chưa rõ CASAN được dùng thế nào trong một dự án thực tế, đọc +> [Dùng CASAN để làm dự án](CASAN_USING_FOR_REAL_PROJECTS_VI.md) trước tài liệu +> cài đặt này. + This guide runs the entire currently implemented CASAN stack on one Mac. It is a local production-like lab, not a production compliance claim. The Linux server is deliberately not used in this phase. diff --git a/docs/guides/CASAN_USING_FOR_REAL_PROJECTS_VI.md b/docs/guides/CASAN_USING_FOR_REAL_PROJECTS_VI.md new file mode 100644 index 0000000..45a9462 --- /dev/null +++ b/docs/guides/CASAN_USING_FOR_REAL_PROJECTS_VI.md @@ -0,0 +1,286 @@ +# Dùng CASAN để làm dự án — giải thích thực tế, dễ hiểu + +Tài liệu này trả lời thẳng ba câu hỏi: + +1. CASAN có phải là một IDE hay một coding agent thay Codex/Claude Code không? +2. Có thể dùng CASAN mà không cần Codex, VS Code hoặc Claude Code không? +3. Với một dự án cụ thể, người dùng phải thao tác như thế nào? + +## 1. Câu trả lời ngắn gọn + +**CASAN không phải IDE. CASAN là lớp điều phối và kiểm soát quá trình dùng AI để +làm phần mềm.** + +- VS Code là nơi con người mở và sửa file. +- Codex/Claude Code là coding agent có thể đọc, sửa và chạy code. +- Model local/OpenAI/OmniRoute là bộ máy sinh nội dung. +- CASAN quyết định model/agent được làm gì, quét input/output, yêu cầu approval, + chạy test, ghi audit, lưu evidence và chặn hành động không an toàn. + +Do đó: + +- **Không cần Codex hoặc Claude Code:** có thể chạy CASAN bằng browser, CLI và CI. +- **Không cần VS Code:** có thể dùng terminal hoặc bất kỳ trình soạn thảo nào. +- **Muốn browser tự xây trọn một dự án:** phiên bản hiện tại **chưa hoàn thành + bước này**. Chat mới sinh và chứng nhận `CODEGEN_DRAFT`; nó chưa được phép tự + ghi tùy ý vào source tree. + +Điểm cuối cùng là chủ ý bảo mật, không phải lỗi giao diện. “Model sinh được code” +khác với “model được quyền thay đổi repository”. CASAN tách hai quyền này. + +## 2. Hình dung CASAN như một dây chuyền có kiểm soát + +![Luồng dùng CASAN cho dự án](assets/casan-project-usage-flow.svg) + +```mermaid +flowchart LR + U["Người dùng mô tả yêu cầu"] --> I["Control Panel hoặc bin/casan"] + I --> R{"CASAN phân loại ý định"} + R --> M["Model local / OmniRoute tùy chọn"] + M --> D["Sinh câu trả lời hoặc bản nháp"] + D --> G{"H4 bảo mật + H5 audit + H3/test/loop gate"} + G -- "Không đạt" --> X["Chặn, sửa hoặc yêu cầu người duyệt"] + G -- "Đạt: chỉ đọc" --> E["Trả kết quả kèm evidence"] + G -- "Đạt: có ghi file" --> A{"Registered action + approval"} + A -- "Đã được cho phép" --> W["Ghi workspace, chạy test, tạo commit"] + A -- "Chưa có action" --> H["Giữ draft, chưa thay đổi dự án"] +``` + +Model chỉ là một công nhân trong dây chuyền. CASAN là cổng kiểm soát, nhật ký, +người điều phối và bộ tiêu chí nghiệm thu. + +## 3. Những gì dùng được ngay hôm nay + +| Nhu cầu | Browser Control Panel | Terminal `bin/casan` | Trạng thái | +|---|---:|---:|---| +| Hỏi về trạng thái, plan, audit, evidence | Có | Có | Hoàn chỉnh | +| Chọn agent, skill và model provider | Có | Có qua tham số/config | Có policy và audit | +| Chạy bộ test đã đăng ký | Có | Có | Hoàn chỉnh | +| Build/verify Evidence Pack | Có | Có | Hoàn chỉnh | +| Sinh code draft qua model | Có | Có | Có, nhưng draft chưa tự apply | +| Tự sửa bất kỳ file nào bằng chat | Không | Chỉ qua command/action được cho phép | Chưa mở tự do | +| Tạo toàn bộ dự án từ chat rồi test/commit | Chưa | Có thể ghép thủ công bằng CLI | Project Builder chưa hoàn thành | +| Chạy CI, CVE scan, SBOM, attestation | Xem evidence | CI thực hiện | Đã có pipeline | + +Ba agent hiện tại: + +| Agent | Dùng khi nào | Quyền | +|---|---|---| +| Evidence Reader | Hỏi đáp, đọc plan/evidence | Chỉ đọc | +| Ops Operator | Chạy test, build pack, verify pack | Chỉ action đã đăng ký | +| Codegen Draft | Yêu cầu sinh code | Tạo draft trong vùng state; không tự ghi source | + +## 4. Cách chạy hệ thống local mà không cần Codex/Claude Code + +Bạn chỉ cần Docker và browser. Terminal được dùng để bật dịch vụ một lần. + +```bash +cd /Users/thanhnguyen/Documents/AI/HarnessHkt/Harness_Hakathon/Output_CASAN5_REFINED +bash packages/casan-harness/scripts/bash/local-full.sh start +bash packages/casan-harness/scripts/bash/local-full.sh status +``` + +Sau đó mở: + +- Control Panel: `https://localhost:18443` +- Trang Chat: `https://localhost:18443/chat` +- AgentOps dashboard: `http://localhost:18080` +- OmniRoute dashboard: `http://localhost:20128` + +Local dùng chứng thư self-signed nên browser có thể yêu cầu xác nhận lần đầu. Mock +OIDC đăng nhập local với quyền `org-admin` để thử nghiệm. + +Nếu UI chưa thấy selector Agent/Skill/Model mới, chạy lại `local-full.sh start` để +rebuild image Control Panel từ source mới nhất. + +## 5. Case 1 — chỉ dùng browser để kiểm tra và vận hành dự án + +Đây là case đã chạy đầy đủ nhất. + +### Hỏi đáp trên evidence + +1. Mở `/chat`. +2. Chọn Agent `Evidence Reader`. +3. Chọn Skill `evidence-summary`. +4. Chọn model: + - `local` để dùng Ornith/Ollama trên máy Mac; + - `omniroute` nếu key và gateway đã được truyền vào container. +5. Hỏi: `Summarize the remaining production gaps and cite the evidence.` + +CASAN sẽ quét câu hỏi, lấy context trong whitelist, gọi model nếu provider sẵn +sàng, quét câu trả lời và chỉ đánh dấu `certified` khi đạt gate. + +### Chạy một action an toàn + +1. Chọn Agent `Ops Operator`. +2. Chọn Skill `registered-actions`. +3. Gõ đúng một trigger đã đăng ký: + - `run tests` + - `build evidence pack` + - `verify evidence pack` + +Chat không biến câu chữ thành shell command tùy ý. Nó ánh xạ vào +`operator-actions.yaml`, chạy `action-gate`, rồi mới thực thi command cố định. + +### Sinh code draft + +1. Chọn Agent `Codegen Draft`. +2. Chọn Skill `sourcegen-draft`. +3. Chọn provider `local` hoặc `omniroute`. +4. Gõ: `Generate code for a small ticket SLA validation function.` + +Kết quả nằm trong vùng runtime dưới +`.specify/logs/chat/codegen-artifacts/` (hoặc tenant state tương ứng). Draft đi +qua artifact scan và loop certification, nhưng **không được tự chép vào source +tree**. + +## 6. Case 2 — áp CASAN vào một repository đã có sẵn + +Ví dụ repository hiện có là `my-ticketing`. + +### Bước 1: cài harness vào repository + +Chạy từ CASAN source hub: + +```bash +packages/casan-devkit/install.sh \ + --target ../my-ticketing \ + --project ticketing \ + --domain "Ticketing" +``` + +Lệnh này thêm: + +```text +my-ticketing/ +├── bin/casan +├── packages/casan-harness/ +├── apps/ticketing/domain/ +└── .gitea/workflows/casan-ci.yml +``` + +Nó không bắt buộc repository phải dùng VS Code, Codex hoặc Claude Code. + +### Bước 2: khai báo domain của dự án + +Điền các file sau: + +- `input/requirement.md`: danh sách `FR-xx`. +- `input/architecture.md`: kiến trúc và constraint. +- `traceability-map.json`: FR nào được thực hiện bởi code/test nào. +- `golden-runs/`: output chuẩn để phát hiện drift. +- `corpus/`: dữ liệu benign và red-team riêng của domain. + +### Bước 3: chạy governance gate + +```bash +cd ../my-ticketing +CASAN_DOMAIN_ROOT=apps/ticketing/domain bin/casan gate +bin/casan reuse +``` + +Kết quả đúng phải có `CI_GATE_SUMMARY ... FAIL=0` và, khi registry có ít nhất hai +dự án active hợp lệ, `HARNESS_REUSE_VALID`. + +### Bước 4: bọc một command bằng CASAN + +Ví dụ chạy test mà vẫn đi qua security, governance, telemetry và output scan: + +```bash +printf 'Run the ticketing test suite\n' > /tmp/casan-ticketing-input.txt +bin/casan run \ + /tmp/casan-ticketing-input.txt \ + /tmp/casan-ticketing-result.txt \ + test_ticketing -- npm test +``` + +CASAN không cần biết command được gõ từ Terminal, Jenkins, Gitea Actions hay một +coding agent. Miễn command đi qua harness, evidence được ghi theo cùng contract. + +## 7. Case 3 — dự án Service Desk thật đã có trong repository này + +Đây là bằng chứng CASAN không chỉ dùng được cho OKR: + +```bash +node --test apps/service-desk/test/ticket.test.mjs + +python3 packages/casan-harness/scripts/bash/traceability-matrix.py \ + --requirements apps/service-desk/domain/input/service-desk-requirement.md \ + --map apps/service-desk/domain/traceability-map.json \ + --out /tmp/service-desk-traceability.json \ + --gate + +bash packages/casan-harness/scripts/bash/verify-harness-reuse.sh +``` + +Service Desk có source/test riêng và Domain Pack riêng. Nó dùng chung đúng một +harness version với OKR. Không có gate nào được copy riêng cho Service Desk. + +## 8. Case 4 — muốn model thực sự “xây dự án cho tôi” + +Mục tiêu mong muốn sẽ là: + +```text +Browser Chat + → mô tả dự án + → chọn Project Builder + model + skill + → sinh nhiều file vào workspace tạm + → H4 scan từng file + → chạy build/test/H3 evaluation + → hiển thị diff + → con người approve + → apply vào repository + → commit + CI + evidence pack +``` + +**Luồng này chưa hoàn chỉnh trong bản hiện tại.** Những phần đã có là model +router, agent/skill binding, RBAC, codegen draft, action gate, approval inbox, +loop gate, tests, audit và evidence. Những phần còn thiếu để browser-only là: + +1. Workspace service quản lý nhiều file/diff. +2. Skill `project-scaffold` và `apply-patch` được đăng ký rõ quyền. +3. Action chạy build/test theo project, không phải command tự do. +4. Approval để apply diff vào source tree. +5. Git commit/revert gắn với provenance. +6. Streaming token/delta và progress của từng bước build/test. + +Cho tới khi sáu phần này hoàn thành, cách dùng đúng là: **Chat tạo draft và +evidence; con người hoặc một registered automation áp draft vào project.** Coding +agent là tùy chọn, không phải dependency của CASAN. + +## 9. Cách dùng khuyến nghị cho môi trường hiện tại + +### Nếu bạn là người quản lý/kiểm soát + +Dùng browser Control Panel. Không cần IDE hay coding agent. Hỏi evidence, xem +security/FinOps, duyệt proposal, chạy registered action và theo dõi audit. + +### Nếu bạn là developer nhưng không muốn dùng coding agent + +Dùng editor bất kỳ + `bin/casan gate` + `bin/casan run`. Bạn tự sửa code, CASAN +kiểm soát quá trình và chứng minh kết quả. + +### Nếu bạn muốn AI hỗ trợ mạnh + +Dùng Chat với local/OmniRoute để sinh draft, sau đó review và apply. Có thể thay +Chat bằng Codex/Claude Code nếu muốn; cả hai vẫn phải chạy command qua CASAN để +giữ governance và evidence. + +### Nếu bạn muốn hoàn toàn browser-only + +Cần hoàn thiện Project Builder ở mục 8. Đây là một sản phẩm phía trên CASAN core, +không phải chỉ thêm một prompt hoặc bật quyền ghi file cho model. + +## 10. Kết luận + +CASAN dùng độc lập được mà không cần Codex, VS Code hay Claude Code cho các chức +năng governance, chat evidence, vận hành, test, CI và evidence pack. Nhưng bản +hiện tại chưa phải một “AI IDE trên browser” có thể tự xây toàn bộ repository. + +Cách hiểu đúng nhất: + +> **Coding tool tạo thay đổi. CASAN quyết định thay đổi đó có được tin, được chạy, +> được áp dụng và được phát hành hay không.** + +Mục tiêu Project Builder sẽ đưa luôn bước tạo thay đổi vào Control Panel, nhưng +vẫn giữ nguyên nguyên tắc: model không có đường ghi file hoặc chạy command tự do. diff --git a/docs/guides/assets/casan-project-usage-flow.mmd b/docs/guides/assets/casan-project-usage-flow.mmd new file mode 100644 index 0000000..0c37312 --- /dev/null +++ b/docs/guides/assets/casan-project-usage-flow.mmd @@ -0,0 +1,11 @@ +flowchart LR + U["Người dùng mô tả yêu cầu"] --> I["Control Panel hoặc bin/casan"] + I --> R{"CASAN phân loại ý định"} + R --> M["Model local / OmniRoute tùy chọn"] + M --> D["Sinh câu trả lời hoặc bản nháp"] + D --> G{"H4 bảo mật + H5 audit + H3/test/loop gate"} + G -- "Không đạt" --> X["Chặn, sửa hoặc yêu cầu người duyệt"] + G -- "Đạt: chỉ đọc" --> E["Trả kết quả kèm evidence"] + G -- "Đạt: có ghi file" --> A{"Registered action + approval"} + A -- "Đã được cho phép" --> W["Ghi workspace, chạy test, tạo commit"] + A -- "Chưa có action" --> H["Giữ draft, chưa thay đổi dự án"] diff --git a/docs/guides/assets/casan-project-usage-flow.svg b/docs/guides/assets/casan-project-usage-flow.svg new file mode 100644 index 0000000..64a969a --- /dev/null +++ b/docs/guides/assets/casan-project-usage-flow.svg @@ -0,0 +1 @@ +

Không đạt

Đạt: chỉ đọc

Đạt: có ghi file

Đã được cho phép

Chưa có action

Người dùng mô tả yêu cầu

Control Panel hoặc bin/casan

CASAN phân loại ý định

Model local / OmniRoute tùy chọn

Sinh câu trả lời hoặc bản nháp

H4 bảo mật + H5 audit + H3/test/loop gate

Chặn, sửa hoặc yêu cầu người duyệt

Trả kết quả kèm evidence

Registered action + approval

Ghi workspace, chạy test, tạo commit

Giữ draft, chưa thay đổi dự án

 \ No newline at end of file