gitea-admin/CASAN
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update CASAN usage guide

Browse Source
This commit is contained in:
thanhnv
2026-07-23 23:07:38 +07:00
parent ce708fafe5
commit a6c3a5d02f
1 changed files with 118 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+117 -25
View File
@@ -1,15 +1,17 @@
# AI-SDLC Project
# CASAN AI-SDLC
AI-SDLC (AI Software Development Life Cycle) - Applying AI to the software development process.
CASAN là governance harness cho AI Software Development Life Cycle. Harness có
thể được cài một lần ở máy developer rồi adopt vào nhiều dự án hiện hữu mà không
copy toàn bộ CASAN hoặc dựng lại project shell.
> **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).
> [Tạo project shell production đa dự án](docs/guides/CASAN_PROJECT_SHELL_PRODUCTION.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.
> **Bắt đầu nhanh:** xem [CASAN Quick Start](#casan-quick-start). Tài liệu chi
> tiết: [cài đặt hybrid](docs/casan/CASAN_INSTALL_HYBRID.md),
> [dùng CASAN cho dự án thực tế](docs/guides/CASAN_USING_FOR_REAL_PROJECTS_VI.md)
> và [tạo project shell production](docs/guides/CASAN_PROJECT_SHELL_PRODUCTION.md).
## Table of Contents
- [CASAN Quick Start](#casan-quick-start)
- [Project Objectives](#project-objectives)
- [Dùng CASAN cho dự án thực tế](docs/guides/CASAN_USING_FOR_REAL_PROJECTS_VI.md)
- [CASAN Project Shell production](docs/guides/CASAN_PROJECT_SHELL_PRODUCTION.md)
@@ -26,15 +28,104 @@ AI-SDLC (AI Software Development Life Cycle) - Applying AI to the software devel
- [AI-SDLC Usage Guide](#ai-sdlc-usage-guide)
- [Directory Structure](#directory-structure)
- [Directory Details](#directory-details)
- [FPT Deliverable List for NES](#fpt-deliverable-list-for-nes)
- [A. Development Deliverables](#a-development-deliverables)
- [B. Process Records (Required)](#b-process-records-required)
- [C. Process Design Document](#c-process-design-document)
- [D. Specification Files](#d-specification-files)
- [E. Review & Insights](#e-review--insights)
- [Optional Deliverables](#optional-deliverables)
- [License](#license)
- [OKR Web Application — Quick Start](#okr-web-application--quick-start)
## CASAN Quick Start
### 1. Cài CASAN một lần trên máy developer
Yêu cầu chung: Python 3. Trên macOS/Linux cần Bash; trên Windows cần PowerShell
và Git for Windows (Git Bash).
macOS/Linux, chạy từ checkout CASAN:
```bash
sh install.sh --level devkit
# Nếu installer báo launcher chưa nằm trên PATH:
export PATH="${CASAN_HOME:-$HOME/.casan}/bin:$PATH"
casan version
```
Windows PowerShell, chạy từ checkout CASAN:
```powershell
pwsh .\install.ps1
```
Sau lần cài đầu tiên trên Windows, mở PowerShell mới rồi kiểm tra:
```powershell
casan version
```
Mặc định harness được cài tại `~/.casan` trên macOS/Linux và
`%LOCALAPPDATA%\casan` trên Windows.
### 2. Adopt CASAN vào dự án
Chạy tại root của dự án cần bảo vệ:
```bash
cd <project-root>
casan init
```
Trong terminal tương tác, `casan init` hiển thị menu cho phép chọn một hoặc
nhiều integration:
1. Claude Code
2. Codex
3. GitHub Copilot trong VS Code
Có thể cấu hình không tương tác:
```bash
casan init --client claude
casan init --client claude,codex
casan init --client vscode-copilot --vscode-install yes
casan init --client all
```
Mặc định production là `--mode enforce`. Chỉ dùng `--mode observe` cho giai
đoạn pilot telemetry-only.
`casan init` an toàn với dự án đã có project shell, agents, skills hoặc hooks:
- Không sửa source code và không dựng lại vỏ dự án.
- Merge idempotent vào `.claude/settings.json`, `.codex/hooks.json` và
`.vscode/extensions.json`.
- Giữ nguyên cấu hình/hook của dự án; chạy lại không tạo hook CASAN trùng lặp.
- Chỉ ghi bootstrap/config per-project; harness vẫn dùng bản global đã pin hash.
Nếu ứng dụng tự gọi LLM API qua backend riêng, ngoài Claude Code/Codex/Copilot,
luồng đó không tự động đi qua project hooks và cần adapter CASAN riêng.
### 3. Hành vi chat theo client
| Client đã enable | Prompt đi qua CASAN | Onboarding bắt buộc |
|---|---|---|
| Claude Code CLI/extension | Tự động với chat bình thường | Mở project ở trusted workspace |
| Codex CLI/extension | Tự động với chat bình thường | Mở `/hooks`, review và trust đúng hook hash |
| GitHub Copilot Chat | Chỉ khi gửi `@casan <prompt>` | Cài CASAN VSIX; built-in Copilot chat không bị global-intercept |
Không cần chỉ định một “CASAN agent” khi chat bằng Claude Code hoặc Codex.
GitHub Copilot là ngoại lệ: VS Code không cung cấp API cho extension intercept
mọi built-in Copilot prompt, nên CASAN cung cấp route explicit `@casan`.
### 4. Kiểm tra sau khi init
```bash
casan doctor
casan verify-harness
```
Với Codex, `doctor` kiểm tra config/bootstrap/runtime nhưng bước trust vẫn phải
thực hiện trong `/hooks`. Với Copilot, nếu máy chưa có `code` CLI, init trả về
đường dẫn VSIX để cài bằng lệnh **Extensions: Install from VSIX...**.
Khi nâng cấp global CASAN, chạy lại `casan init` trong project để cập nhật
bootstrap và pin hash mới. Xem đầy đủ tùy chọn và troubleshooting tại
[CASAN_INSTALL_HYBRID.md](docs/casan/CASAN_INSTALL_HYBRID.md).
## Project Objectives
@@ -56,7 +147,7 @@ Apply AI to the SDLC process to automate and optimize the creation of software p
- `docs/technical_architecture.md` — Technical stack decisions and constraints
- `apps/okr/domain/input/change-request/` — Change requests (e.g., `change-0406.md`)
## Output for FLow
## Output for Flow
| Output | Location | Description |
|--------|----------|-------------|
@@ -188,11 +279,12 @@ The entire flow is orchestrated by **`casan.pipeline`**, which executes all step
## AI-SDLC Usage Guide
1. **Prepare Input**: Place raw requirements in `apps/okr/domain/input/okr-requirement.md` and tech stack in `docs/technical_architecture.md`
2. **Configuration**: Set up the project constitution first, keep specifications focused on what and why, and only decide technical stack where the input explicitly requires it
3. **(One-time) Generate System SRS**: Run `casan.srs` to generate system-wide SRS → `docs/output/srs-systems/`
4. **Run AI Flow**: Invoke `casan.pipeline` to execute the full 13-step flow automatically, with strict TDD enforced across specification, planning, task generation, and implementation
5. **Output**:
1. **Adopt governance**: Run `casan init`, select the IDE clients, complete any trust/VSIX onboarding, then run `casan doctor`
2. **Prepare Input**: Place raw requirements in `apps/okr/domain/input/okr-requirement.md` and tech stack in `docs/technical_architecture.md`
3. **Configuration**: Set up the project constitution first, keep specifications focused on what and why, and only decide technical stack where the input explicitly requires it
4. **(One-time) Generate System SRS**: Run `casan.srs` to generate system-wide SRS → `docs/output/srs-systems/`
5. **Run AI Flow**: Invoke `casan.pipeline` to execute the full 13-step flow automatically, with strict TDD enforced across specification, planning, task generation, and implementation
6. **Output**:
- `docs/output/ipa-docs/` — IPA design documents (SRS, BD, DD, Test Cases)
- `docs/output/output_logs/` — AI agent execution logs
- `docs/output/srs-systems/` — System-wide SRS (generated once)
@@ -337,8 +429,8 @@ The **OKR Web Application** is a full-stack web app for managing Objectives and
### Quick Start (Docker)
```bash
# Clone the repository and navigate to project root
cd AINative_OKR_Claude_GHCP
# Navigate to the repository root
cd <repo-root>
# Build and start all services (MySQL + Backend + Frontend)
docker compose up --build
@@ -376,7 +468,7 @@ Docker Compose will automatically:
#### Backend
```bash
cd backend
cd apps/okr/backend
# Install dependencies
npm install
@@ -398,7 +490,7 @@ npm run start:dev
#### Frontend
```bash
cd frontend
cd apps/okr/frontend
# Install dependencies
npm install