thuongtin/Ucai-Guide.md

## Ucai-Guide.md

      
    Raw
  

              Ucai-Guide.md
            
          
  tags
  
  
  type/guide
  ai/concept/vibe-coding
  ai/concept/agent
  ai/concept/skills
  dev/workflow
  dev/framework/ucai
  dev/tool/claude-code
  dev/best-practices
  dev/open-source
  project/vibe-coding
  
  
Ucai – Hướng dẫn từ cơ bản đến thành thạo

Giới thiệu tổng quan

Ucai (viết tắt của Use Claude Code As Is) là một Claude Code plugin giải quyết cùng những vấn đề mà các framework cộng đồng (GSD, BMAD, Ralph, Agent OS) đã giải quyết – nhưng bằng cách sử dụng kiến trúc gốc (native architecture) của Claude Code thay vì "chiến đấu" chống lại nó. Mọi thành phần của Ucai đều map 1:1 với một hệ thống native của Claude Code: Commands, Agents, Hooks, và Skills.
Thông tin dự án:

Repository: github.com/Joncik91/ucai
Tác giả: Jounes De Schrijver (@Joncik91)
Ngôn ngữ: JavaScript (Node.js CommonJS, không dependency bên ngoài)
Plugin format: Markdown (YAML frontmatter) + JSON configs
Phiên bản hiện tại: 0.2.0
Stars: ~20 (dự án mới, rất tích cực phát triển)
Yêu cầu: Claude Code v1.0.33+
Cross-platform: Windows / Linux / macOS


      graph TB
    CENTER["🔌 Ucai Plugin"]

    subgraph commands ["⚡ Commands"]
        C1["/init · /plan · /build"]
        C2["/iterate · /review · /cancel-iterate"]
    end

    subgraph agents ["🤖 Agents"]
        A1["explorer · project-scanner"]
        A2["architect · reviewer · verifier"]
    end

    subgraph hooks ["🔗 Hooks"]
        H1["SessionStart: context injection"]
        H2["PreToolUse: config protection"]
        H3["Stop: iteration control"]
    end

    subgraph skills ["📚 Skills"]
        S1["ucai-patterns · senior-backend"]
        S2["senior-frontend · senior-architect"]
        S3["code-reviewer · senior-qa · senior-devops"]
    end

    CENTER --- commands
    CENTER --- agents
    CENTER --- hooks
    CENTER --- skills

    style CENTER fill:#6c5ce7,color:#fff,stroke:#a29bfe,stroke-width:3px
    style commands fill:#1e272e,color:#dfe6e9,stroke:#0984e3,stroke-width:2px
    style agents fill:#1e272e,color:#dfe6e9,stroke:#00b894,stroke-width:2px
    style hooks fill:#1e272e,color:#dfe6e9,stroke:#e17055,stroke-width:2px
    style skills fill:#1e272e,color:#dfe6e9,stroke:#fdcb6e,stroke-width:2px
    style C1 fill:#0984e3,color:#fff,stroke:#74b9ff
    style C2 fill:#0984e3,color:#fff,stroke:#74b9ff
    style A1 fill:#00b894,color:#fff,stroke:#55efc4
    style A2 fill:#00b894,color:#fff,stroke:#55efc4
    style H1 fill:#e17055,color:#fff,stroke:#fab1a0
    style H2 fill:#e17055,color:#fff,stroke:#fab1a0
    style H3 fill:#e17055,color:#fff,stroke:#fab1a0
    style S1 fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style S2 fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style S3 fill:#fdcb6e,color:#2d3436,stroke:#f9ca24

    
      Loading

  
Tại sao cần Ucai?

Các framework cộng đồng (GSD, BMAD, Ralph, Agent OS) được xây dựng từ ngoài nhìn vào – chúng giải quyết các vấn đề thực tế (context rot, thiếu cấu trúc, không có guardrails, không thể iterate tự động) nhưng bằng cách bọc công cụ trong bash scripts, mega-prompts, và persona engineering.
Ucai được xây dựng từ bên trong nhìn ra. Team phát triển đã đọc source code của Claude Code, nghiên cứu cách Anthropic build plugin của chính họ, và map mọi component 1:1 với hệ thống native.


Vấn đề
Framework Approach
Ucai (Native) Approach


Context rot
Bash wrappers spawn fresh sessions
Task tool đã cho fresh context per agent


Không có cấu trúc
Persona prompts + ceremonies
Commands với phased workflows + parallel agents


Không có guardrails
CLAUDE.md rules (hope-based)
PreToolUse hooks (deterministic)


Không thể iterate
External bash loops
Stop hooks (native, built-in)


Không có planning
Manual PRD docs hoặc bỏ qua
/plan với discovery agents + structured file output


Không có onboarding
Template CLAUDE.md dumps
Agent-powered codebase analysis


Triết lý cốt lõi


      graph LR
    P1["🔧 Use Native Systems"] --> P2["📁 Files Are Context"]
    P2 --> P3["🌐 Context Is Public Good"]
    P3 --> P4["🎯 Agents Are Not Personas"]
    P4 --> P5["✋ Explicit Approval Gates"]
    P5 --> P6["⚡ Parallel By Default"]

    style P1 fill:#6c5ce7,color:#fff,stroke:#a29bfe,stroke-width:2px
    style P2 fill:#0984e3,color:#fff,stroke:#74b9ff,stroke-width:2px
    style P3 fill:#00b894,color:#fff,stroke:#55efc4,stroke-width:2px
    style P4 fill:#e17055,color:#fff,stroke:#fab1a0,stroke-width:2px
    style P5 fill:#fdcb6e,color:#2d3436,stroke:#f9ca24,stroke-width:2px
    style P6 fill:#00cec9,color:#fff,stroke:#81ecec,stroke-width:2px

    
      Loading

  
Use native systems — Commands, agents, hooks, skills. Không wrapper.
Files are context — Commands ghi files. Commands khác đọc files. Context persist qua file system, không cần external memory.
Context is a public good — Chỉ thêm những gì Claude chưa biết. Progressive disclosure.
Agents are not personas — Có model assignments, tool declarations, focused missions. Không phải "giả vờ là PM".
Explicit approval gates — Không bao giờ tiến hành mà không có quyết định của user.
Parallel by default — Spawn nhiều focused agents đồng thời. Consolidate.
CLAUDE.md is for project facts — Không phải framework configuration.

Ucai so với các phương pháp khác


Tiêu chí
Vibe Coding
BMAD Method
Ralph
bmalph
Ucai


Tiếp cận
Prompt → Code
Persona agents → Workflows
Bash loop → Auto-code
BMAD + Ralph
Native plugin architecture


Planning
Không
Rất chi tiết
Cơ bản (prd.json)
BMAD-level
/plan + discovery agents


Execution
Thủ công
Thủ công
Autonomous loop
Ralph loop
/build 8-phase + /iterate


Context management
Không
In-session
Git + progress.txt
Docs + Git
File-based chain + hooks


Guardrails
Không
CLAUDE.md rules
Không
Hạn chế
PreToolUse hooks (deterministic)


Skill system
Không
Không
Không
Không
7 curated skills + project-level


Cài đặt
Không cần
npx install
Clone repo
npm install
/plugin marketplace add


Phù hợp với
Prototype nhanh
Dự án lớn cần planning
Dự án đã có PRD
End-to-end pipeline
Mọi dự án Claude Code


      graph LR
    A["🎲 Vibe Coding"] -->|"Prompt mơ hồ"| B["Kết quả không ổn định"]
    C["📋 BMAD only"] -->|"Planning tốt"| D["Execution thủ công"]
    E["⚡ Ralph only"] -->|"Loop mạnh"| F["Planning yếu"]
    G["🔗 bmalph"] -->|"BMAD + Ralph"| H["Cồng kềnh, nhiều dependency"]
    I["🔌 Ucai"] -->|"Native architecture"| J["Gọn nhẹ, đúng bản chất"]

    style A fill:#e17055,color:#fff,stroke:#fab1a0,stroke-width:2px
    style B fill:#e17055,color:#fff,stroke:#fab1a0,stroke-width:2px
    style C fill:#0984e3,color:#fff,stroke:#74b9ff,stroke-width:2px
    style D fill:#fdcb6e,color:#2d3436,stroke:#f9ca24,stroke-width:2px
    style E fill:#00b894,color:#fff,stroke:#55efc4,stroke-width:2px
    style F fill:#fdcb6e,color:#2d3436,stroke:#f9ca24,stroke-width:2px
    style G fill:#636e72,color:#fff,stroke:#b2bec3,stroke-width:2px
    style H fill:#636e72,color:#fff,stroke:#b2bec3,stroke-width:2px
    style I fill:#6c5ce7,color:#fff,stroke:#a29bfe,stroke-width:2px
    style J fill:#6c5ce7,color:#fff,stroke:#a29bfe,stroke-width:2px

    
      Loading

  
Cài đặt và thiết lập

Yêu cầu chuẩn bị


Claude Code v1.0.33+ – Kiểm tra bằng claude --version
Node.js – Runtime cho hooks/scripts (đã đi kèm hầu hết hệ thống)
Git (khuyến nghị) – Cho version control và code review

Cài đặt từ Marketplace (khuyến nghị)

Mở một phiên Claude Code interactive và chạy:
/plugin marketplace add Joncik91/ucai
/plugin install ucai@ucai-marketplace
Plugin được cài đặt globally – có sẵn ở mọi project, mọi session.
Cài đặt cho Development / Testing

Nếu muốn chỉnh sửa plugin hoặc thử nghiệm:
git clone https://github.com/Joncik91/ucai.git
claude --plugin-dir ./ucai
Xác nhận cài đặt thành công

Sau khi cài, tất cả commands đều có namespace ucai::
/ucai:init
/ucai:plan
/ucai:build
/ucai:iterate
/ucai:review
/ucai:cancel-iterate

Chạy /help trong Claude Code để thấy chúng trong danh sách.
Khi session bắt đầu, SessionStart hook sẽ hiển thị:
Ucai plugin is active. Use /init to analyze this project...
Git branch: main
Available skills: [plugin] ucai-patterns (...), [plugin] senior-backend (...), ...


Kiến trúc tổng quan

Cấu trúc thư mục

ucai/
├── plugin.json                   # Plugin manifest
├── marketplace.json              # Marketplace listing
├── CLAUDE.md                     # Project guidelines
├── commands/                     # Slash commands (Markdown + YAML frontmatter)
│   ├── init.md                   # /init — Project onboarding
│   ├── plan.md                   # /plan — Project spec & feature PRDs
│   ├── build.md                  # /build — Feature development (8 phases)
│   ├── iterate.md                # /iterate — Autonomous iteration
│   ├── review.md                 # /review — Multi-agent code review
│   └── cancel-iterate.md        # /cancel-iterate — Stop iterate loop
├── agents/                       # Subagents (Markdown + YAML frontmatter)
│   ├── project-scanner.md        # Phân tích codebase (tech stack, conventions)
│   ├── explorer.md               # Khám phá deep (execution paths, architecture)
│   ├── architect.md              # Thiết kế kiến trúc
│   ├── reviewer.md               # Code review (bugs, security, quality)
│   └── verifier.md               # Kiểm tra acceptance criteria
├── hooks/                        # Lifecycle handlers
│   ├── hooks.json                # Hook configuration
│   └── handlers/
│       ├── sessionstart-handler.js  # Context injection khi bắt đầu session
│       ├── pretooluse-guard.js      # Bảo vệ config files
│       └── stop-handler.js          # Điều khiển iteration loop
├── scripts/
│   └── setup-iterate.js          # Thiết lập iterate loop
└── skills/                       # Progressive disclosure (auto-loaded)
    ├── ucai-patterns/            # Claude Code best practices
    ├── senior-backend/           # API design, databases, auth
    ├── senior-frontend/          # React, Next.js, Tailwind
    ├── senior-architect/         # System design, ADRs
    ├── code-reviewer/            # Code review automation
    ├── senior-qa/                # Testing patterns
    └── senior-devops/            # CI/CD, deployment

Mô hình kiến trúc: Commands điều phối, Agents thực thi


      graph TB
    USER["👤 User"] -->|"Chạy slash command"| CMD["⚡ Command<br/>(orchestrator)"]
    CMD -->|"Spawn via Task tool"| AG1["🤖 Agent 1<br/>(read-only)"]
    CMD -->|"Spawn via Task tool"| AG2["🤖 Agent 2<br/>(read-only)"]
    CMD -->|"Spawn via Task tool"| AG3["🤖 Agent 3<br/>(read-only)"]
    AG1 -->|"Trả kết quả"| CMD
    AG2 -->|"Trả kết quả"| CMD
    AG3 -->|"Trả kết quả"| CMD
    CMD -->|"Tổng hợp + trình bày"| USER
    USER -->|"Phê duyệt"| CMD
    CMD -->|"Write/Edit files"| FILES["📁 Project Files"]

    HOOK1["🔗 SessionStart Hook"] -.->|"Inject context"| CMD
    HOOK2["🔗 PreToolUse Hook"] -.->|"Guard config files"| CMD
    HOOK3["🔗 Stop Hook"] -.->|"Control iteration"| CMD

    SKILLS["📚 Skills"] -.->|"Load on demand"| CMD

    style USER fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style CMD fill:#0984e3,color:#fff,stroke:#74b9ff,stroke-width:2px
    style AG1 fill:#00b894,color:#fff,stroke:#55efc4
    style AG2 fill:#00b894,color:#fff,stroke:#55efc4
    style AG3 fill:#00b894,color:#fff,stroke:#55efc4
    style FILES fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style HOOK1 fill:#e17055,color:#fff,stroke:#fab1a0
    style HOOK2 fill:#e17055,color:#fff,stroke:#fab1a0
    style HOOK3 fill:#e17055,color:#fff,stroke:#fab1a0
    style SKILLS fill:#fdcb6e,color:#2d3436,stroke:#f9ca24

    
      Loading

  
Nguyên tắc then chốt:

Commands định nghĩa workflow có phases, approval gates. Chỉ commands mới có quyền Write/Edit.
Agents là workers read-only, được spawn song song qua Task tool. Trả kết quả về cho command tổng hợp.
Hooks là lifecycle event handlers – extension point chính.
Skills là knowledge packages, auto-loaded theo context.

Context Chain: Files là memory


      graph LR
    PLAN_P["/plan<br/>(no args)"] -->|"Ghi"| PROJ[".claude/project.md"]
    PLAN_P -->|"Ghi"| REQ[".claude/requirements.md"]
    PLAN_F["/plan feature"] -->|"Ghi"| PRD[".claude/prds/feature.md"]

    PROJ -->|"Đọc"| BUILD["/build"]
    REQ -->|"Đọc"| BUILD
    PRD -->|"Đọc"| BUILD

    PROJ -->|"Đọc"| INIT["/init"]

    BUILD -->|"Cập nhật ✅"| REQ
    BUILD -->|"Cập nhật"| CLAUDE["CLAUDE.md"]

    HOOK["SessionStart Hook"] -->|"Đọc + announce"| PROJ
    HOOK -->|"Đọc + progress"| REQ

    style PLAN_P fill:#0984e3,color:#fff,stroke:#74b9ff
    style PLAN_F fill:#0984e3,color:#fff,stroke:#74b9ff
    style BUILD fill:#00b894,color:#fff,stroke:#55efc4
    style INIT fill:#e17055,color:#fff,stroke:#fab1a0
    style PROJ fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style REQ fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style PRD fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style CLAUDE fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style HOOK fill:#636e72,color:#fff,stroke:#b2bec3

    
      Loading

  
Chuỗi context hoạt động như sau:

/plan (no args) → tạo .claude/project.md + .claude/requirements.md (với build order)
/plan <feature> → tạo .claude/prds/<slug>.md (per-feature, không bao giờ bị overwrite)
Tất cả commands tự động load spec files có sẵn trong .claude/
/build đọc build order → check dependencies → build → mark requirements done
SessionStart hook announce project name, progress (N/M done), và next build step
Mỗi session mới đọc files và biết ngay đã plan gì, build gì, và cần làm gì tiếp

.claude/
├── project.md              # Vision, goals, users, constraints
├── requirements.md         # Feature backlog (checkboxes track progress)
├── ucai-iterate.local.md   # State file cho iterate loop (gitignored)
└── prds/
    ├── auth.md             # Feature PRD (preserved)
    └── payments.md         # Feature PRD (preserved)


Deep Dive: Commands

/ucai:init — Project Onboarding

Mục đích: Phân tích codebase hiện tại và tạo CLAUDE.md chứa project facts – không phải framework config.

  
      graph TD
    START["🚀 /init"] --> DETECT["Phase 1: Detection<br/>Có source code không?"]
    DETECT -->|"Có code"| ANALYZE["Phase 2A: Analysis<br/>Launch 2-3 project-scanner agents"]
    DETECT -->|"Empty project"| SCAFFOLD["Phase 2B: Scaffolding<br/>Hỏi user intent"]
    ANALYZE --> GENERATE["Phase 3: Generate CLAUDE.md<br/>Draft → User review → Write"]
    SCAFFOLD --> GENERATE
    GENERATE --> SETUP["Phase 4: Optional Setup<br/>Suggest hooks, test patterns"]

    style START fill:#6c5ce7,color:#fff,stroke:#a29bfe,stroke-width:2px
    style DETECT fill:#0984e3,color:#fff,stroke:#74b9ff
    style ANALYZE fill:#00b894,color:#fff,stroke:#55efc4
    style SCAFFOLD fill:#e17055,color:#fff,stroke:#fab1a0
    style GENERATE fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style SETUP fill:#636e72,color:#fff,stroke:#b2bec3

    
      Loading

  
Cách dùng:
/ucai:init              # Phân tích project hiện tại
/ucai:init /path/to    # Phân tích project tại đường dẫn khác

Các Phase chi tiết:


Phase
Tên
Mô tả


1
Detection
Dùng Glob kiểm tra source files. Nếu empty → Phase 2B, nếu có code → Phase 2A


2A
Analysis
Launch 2-3 project-scanner agents song song: tech stack, conventions, architecture


2B
Scaffolding
Hỏi user: đang build gì, tech stack, conventions, constraints


3
Generate
Draft CLAUDE.md → trình bày → chờ approval → write file


4
Optional Setup
Gợi ý thêm hooks, test commands nếu cần


CLAUDE.md output tuân theo nguyên tắc:

Chỉ chứa facts specific cho project này
Không có generic programming advice
Không có framework instructions hay persona definitions
Dưới 200 dòng – ngắn gọn là chìa khóa
Mỗi dòng phải giúp Claude viết code tốt hơn cho DỰ ÁN NÀY


/ucai:plan — Project Spec & Feature PRDs

Mục đích: Lập kế hoạch ở hai cấp độ – project-level (toàn bộ dự án) hoặc feature-level (một feature cụ thể).

  
      graph TD
    START["🚀 /plan"] --> ROUTE["Phase 0: Route<br/>Có argument không?"]
    ROUTE -->|"Không argument"| PROJECT["📋 Project-Level Mode"]
    ROUTE -->|"Có argument"| FEATURE["📝 Feature-Level Mode"]

    subgraph proj ["Project-Level (Phases 1P-5P)"]
        P1["1P: Understand"] --> P2["2P: Discovery<br/>2-3 explorer agents"]
        P2 --> P3["3P: Project Definition<br/>Vision, goals, tech stack"]
        P3 --> P4["4P: Requirements Backlog<br/>MoSCoW + Build Order"]
        P4 --> P5["5P: Output<br/>project.md + requirements.md"]
    end

    subgraph feat ["Feature-Level (Phases 1F-5F)"]
        F1["1F: Understand"] --> F2["2F: Discovery<br/>3 explorer agents"]
        F2 --> F3["3F: Requirements<br/>MoSCoW + Acceptance Criteria"]
        F3 --> F4["4F: Architecture<br/>1-2 architect agents"]
        F4 --> F5["5F: Output PRD<br/>prds/feature-slug.md"]
    end

    PROJECT --> proj
    FEATURE --> feat

    style START fill:#6c5ce7,color:#fff,stroke:#a29bfe,stroke-width:2px
    style ROUTE fill:#0984e3,color:#fff,stroke:#74b9ff
    style PROJECT fill:#00b894,color:#fff,stroke:#55efc4
    style FEATURE fill:#e17055,color:#fff,stroke:#fab1a0
    style P1 fill:#00b894,color:#fff,stroke:#55efc4
    style P2 fill:#00b894,color:#fff,stroke:#55efc4
    style P3 fill:#00b894,color:#fff,stroke:#55efc4
    style P4 fill:#00b894,color:#fff,stroke:#55efc4
    style P5 fill:#00b894,color:#fff,stroke:#55efc4
    style F1 fill:#e17055,color:#fff,stroke:#fab1a0
    style F2 fill:#e17055,color:#fff,stroke:#fab1a0
    style F3 fill:#e17055,color:#fff,stroke:#fab1a0
    style F4 fill:#e17055,color:#fff,stroke:#fab1a0
    style F5 fill:#e17055,color:#fff,stroke:#fab1a0

    
      Loading

  
Cách dùng:
/ucai:plan                              # Project-level: tạo project.md + requirements.md
/ucai:plan Add real-time notifications  # Feature-level: tạo prds/real-time-notifications.md
/ucai:plan Migrate from REST to GraphQL # Feature-level PRD

Project-Level Mode tạo ra:
project.md:
---
name: My Awesome App
created: 2026-02-17
status: draft
---
# Project: My Awesome App
## Vision
## Goals
## Target Users
## Constraints
## Tech Stack
## Non-Functional Requirements
requirements.md:
---
project: My Awesome App
created: 2026-02-17
updated: 2026-02-17
---
# Requirements
## Must Have
- [ ] Feature A — description
- [ ] Feature B — description
## Should Have
- [ ] Feature C — description
## Could Have
- [ ] Feature D — description
## Won't Have (This Release)
- Feature E — reason excluded
## Build Order
1. **Vertical slice**: Core pipeline — covers: Feature A, Feature B
2. **Step 2**: Auth system — covers: Feature C — depends on: step 1
## Cross-Cutting Concerns
- Security, performance, testing...
Feature-Level Mode tạo PRD tại .claude/prds/<slug>.md với cấu trúc: Overview → Discovery (codebase patterns + web research) → Requirements (MoSCoW + acceptance criteria) → Architecture (high-level design) → References.

/ucai:build — Feature Development (8 Phases)

Mục đích: Workflow phát triển feature hoàn chỉnh – từ hiểu yêu cầu đến deploy – với approval gates và manual testing bắt buộc.

  
      graph TD
    P1["Phase 1: Understand<br/>Load spec chain + confirm"] --> P2["Phase 2: Explore<br/>2-3 explorer agents"]
    P2 --> P3["Phase 3: Clarify<br/>Resolve ambiguities"]
    P3 --> P4["Phase 4: Design<br/>2-3 architect agents"]
    P4 --> P5["Phase 5: Build<br/>⚠️ CHỜ APPROVAL"]
    P5 --> P6["Phase 6: Verify<br/>verifier + 2 reviewer agents"]
    P6 --> P7["Phase 7: Test<br/>👤 USER MANUAL TEST"]
    P7 --> P8["Phase 8: Done<br/>Mark requirements ✅"]

    style P1 fill:#0984e3,color:#fff,stroke:#74b9ff
    style P2 fill:#0984e3,color:#fff,stroke:#74b9ff
    style P3 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style P4 fill:#00b894,color:#fff,stroke:#55efc4
    style P5 fill:#e17055,color:#fff,stroke:#fab1a0,stroke-width:3px
    style P6 fill:#00b894,color:#fff,stroke:#55efc4
    style P7 fill:#e17055,color:#fff,stroke:#fab1a0,stroke-width:3px
    style P8 fill:#00cec9,color:#fff,stroke:#81ecec

    
      Loading

  
Cách dùng:
/ucai:build Add user authentication with JWT
/ucai:build Refactor the database layer to use connection pooling

Chi tiết từng Phase:


Phase
Tên
Agents
Approval?
Mô tả


1
Understand
—
Confirm specs
Load project.md, requirements.md, PRD. Check build order dependencies


2
Explore
2-3 explorer
—
Map codebase: similar features, architecture, testing patterns


3
Clarify
—
Wait for answers
Liệt kê mọi ambiguity: edge cases, error handling, scope


4
Design
2-3 architect
User chọn approach
3 options: minimal, clean architecture, pragmatic balance


5
Build
—
⚠️ Explicit approval
Implement theo approach được chọn. Follow conventions strictly


6
Verify
verifier + 2 reviewer
Fix now/later/proceed
Kiểm tra acceptance criteria, bugs, conventions, security


7
Test
—
⚠️ User test manually
Tạo concrete test checklist. User phải confirm pass


8
Done
—
Approve requirement updates
Mark requirements ✅, update CLAUDE.md nếu cần


Điểm đặc biệt của Phase 7 (Test):

Bắt buộc – không agent review nào thay thế được human testing
Tạo checklist cụ thể: exact commands, expected results, edge cases
Nếu user báo lỗi → fix → re-run agent review → test lại
Chỉ tiến sang Phase 8 sau khi user confirm pass

Spec chain loading (Phase 1):

Load project.md → summarize vision, constraints, tech stack
Load requirements.md → show backlog status, check build order dependencies
Load matching PRD → summarize discovery, requirements, architecture
Nếu user confirm: PRD's content trở thành baseline cho tất cả phases còn lại


/ucai:iterate — Controlled Autonomous Iteration

Mục đích: Cho Claude chạy tự động nhiều vòng lặp trên một task – mỗi lần try to exit, Stop hook sẽ "nhét" task lại và bắt Claude tiếp tục.

  
      graph TD
    START["🚀 /iterate task"] --> SETUP["setup-iterate.js<br/>Tạo state file"]
    SETUP --> WORK["Claude làm việc<br/>trên task"]
    WORK --> STOP{"Claude muốn<br/>dừng?"}
    STOP -->|"Stop hook<br/>catches"| CHECK{"Max iterations?<br/>Promise met?"}
    CHECK -->|"Chưa"| INJECT["Feed task back<br/>+ iteration count"]
    INJECT --> WORK
    CHECK -->|"Max reached"| CLEANUP["Cleanup state file<br/>✅ Done"]
    CHECK -->|"Promise true"| CLEANUP

    style START fill:#6c5ce7,color:#fff,stroke:#a29bfe,stroke-width:2px
    style SETUP fill:#0984e3,color:#fff,stroke:#74b9ff
    style WORK fill:#00b894,color:#fff,stroke:#55efc4
    style STOP fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style CHECK fill:#e17055,color:#fff,stroke:#fab1a0
    style INJECT fill:#0984e3,color:#fff,stroke:#74b9ff
    style CLEANUP fill:#00b894,color:#fff,stroke:#55efc4,stroke-width:2px

    
      Loading

  
Cách dùng:
/ucai:iterate Build a REST API --max-iterations 15 --completion-promise 'All endpoints working and tested'
/ucai:iterate Fix the auth bug --max-iterations 5
/ucai:iterate Refactor the auth module

Cơ chế hoạt động:

setup-iterate.js tạo state file .claude/ucai-iterate.local.md với frontmatter:
---
iteration: 1
max_iterations: 15
completion_promise: "All endpoints working and tested"
---
Build a REST API

Claude bắt đầu làm việc trên task
Khi Claude muốn dừng, Stop hook (stop-handler.js) kiểm tra:

Đã đạt max iterations? → Dừng
Completion promise đã true? (check <promise>...</promise> tag trong output) → Dừng
Còn chưa? → { "decision": "block", "reason": "<task>" } → Feed task lại


Mỗi iteration Claude thấy work trước đó qua files, git history, TodoWrite

Completion Promise:

Claude chỉ được output <promise>All endpoints working and tested</promise> khi statement thật sự đúng
Stop hook kiểm tra transcript, tìm <promise> tag trong last assistant message
Nếu match → dừng loop. Nếu không → tiếp tục iterate

Hủy iterate loop:
/ucai:cancel-iterate


/ucai:review — Multi-Agent Code Review

Mục đích: Code review song song bởi 3 agents độc lập, với confidence-based filtering để chỉ báo cáo issues quan trọng.

  
      graph TD
    START["🚀 /review"] --> SCOPE["Phase 1: Scope<br/>Xác định review gì"]
    SCOPE --> AGENTS["Phase 2: Parallel Review<br/>3 reviewer agents"]

    AGENTS --> R1["Agent 1: CLAUDE.md<br/>compliance"]
    AGENTS --> R2["Agent 2: Bugs &<br/>logic errors"]
    AGENTS --> R3["Agent 3: Security &<br/>performance"]

    R1 --> VALIDATE["Phase 3: Validation<br/>Filter confidence < 80"]
    R2 --> VALIDATE
    R3 --> VALIDATE

    VALIDATE --> REPORT["Phase 4: Report<br/>Critical / Important"]

    style START fill:#6c5ce7,color:#fff,stroke:#a29bfe,stroke-width:2px
    style SCOPE fill:#0984e3,color:#fff,stroke:#74b9ff
    style AGENTS fill:#00b894,color:#fff,stroke:#55efc4
    style R1 fill:#e17055,color:#fff,stroke:#fab1a0
    style R2 fill:#e17055,color:#fff,stroke:#fab1a0
    style R3 fill:#e17055,color:#fff,stroke:#fab1a0
    style VALIDATE fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style REPORT fill:#00cec9,color:#fff,stroke:#81ecec

    
      Loading

  
Cách dùng:
/ucai:review              # Review unstaged changes (git diff)
/ucai:review src/auth/    # Review specific directory

Confidence scoring:

0-50: Có thể là false positive → bỏ qua
50-79: Real nhưng minor → bỏ qua
80-100: Report → với file:line, description, fix suggestion
Không flag: pre-existing issues, style nitpicks, hypothetical issues


Deep Dive: Agents

Ucai có 5 agents, tất cả đều dùng model sonnet, read-only (không có Write/Edit), và được color-coded.


Agent
Color
Tools
Mission


project-scanner
🟡 Yellow
Glob, Grep, Read, Bash, WebFetch, WebSearch
Phân tích project: tech stack, conventions, patterns


explorer
🔵 Cyan
Glob, Grep, Read, Bash, WebFetch, TodoWrite, WebSearch
Khám phá deep: execution paths, architecture, dependencies


architect
🟢 Green
Glob, Grep, Read, Bash, WebFetch, TodoWrite, WebSearch
Thiết kế architecture blueprint: components, data flow, build sequence


reviewer
🔴 Red
Glob, Grep, Read, Bash, WebFetch, TodoWrite, WebSearch
Code review: bugs, security, conventions. Confidence-based filtering


verifier
🔵 Blue
Glob, Grep, Read, Bash, WebFetch, TodoWrite, WebSearch
Kiểm tra acceptance criteria


Nguyên tắc agent design:

Không phải personas – không "giả vờ là Senior Developer". Có model assignment, tool declaration, và focused mission.
Read-only – agents không được phép Write/Edit. Implementation chỉ xảy ra trong commands, sau khi user approve.
Parallel by default – luôn spawn 2-3 agents đồng thời, mỗi agent một focus khác nhau.
Consolidation ở command – command tổng hợp kết quả, không phải agent khác.

Ví dụ: Explorer Agent trong action

Khi /build Add authentication chạy Phase 2 (Explore), command spawn 3 explorer agents:
Agent 1: "Find features similar to authentication and trace their implementation"
Agent 2: "Map the architecture and abstractions for auth/security area"
Agent 3: "Identify testing approaches and extension points relevant to authentication"

Mỗi agent trả về 5-10 key files. Command đọc tất cả files được identify, rồi present summary.

Deep Dive: Hooks

Hooks là gì?

Hooks là lifecycle event handlers – code chạy tại các thời điểm cụ thể trong lifecycle của Claude Code session. Ucai dùng 3 loại hooks:


Hook
Event
Handler
Mục đích


SessionStart
Khi session bắt đầu
sessionstart-handler.js
Inject context: git branch, iterate status, skills, spec progress


PreToolUse
Trước khi Write/Edit
pretooluse-guard.js
Chặn sửa đổi config files (plugin.json, marketplace.json, hooks.json)


Stop
Khi Claude muốn dừng
stop-handler.js
Điều khiển iterate loop: block exit + feed task back


SessionStart Hook – Chi tiết

sessionstart-handler.js inject context khi mỗi session bắt đầu:

  
      graph LR
    START["Session Start"] --> GIT["Đọc git branch"]
    START --> ITER["Check iterate state"]
    START --> CLAUDE_MD["Check CLAUDE.md"]
    START --> SPEC["Đọc project.md +<br/>requirements.md"]
    START --> SKILLS["Scan skills:<br/>plugin + project + user"]

    GIT --> OUTPUT["Gửi context string<br/>→ Claude"]
    ITER --> OUTPUT
    CLAUDE_MD --> OUTPUT
    SPEC --> OUTPUT
    SKILLS --> OUTPUT

    style START fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style OUTPUT fill:#00b894,color:#fff,stroke:#55efc4,stroke-width:2px

    
      Loading

  
Output mẫu:
Ucai plugin is active | Git branch: feature/auth | Project: MyApp | 3/12 requirements done |
Next: step 2 — Auth system | PRDs: auth, payments |
Available skills: [plugin] ucai-patterns (...), [plugin] senior-backend (...), [project] my-api-conventions (...)

PreToolUse Hook – Chi tiết

pretooluse-guard.js chặn Write/Edit calls targeting plugin config files:
// Protected files
const PROTECTED_FILES = ["plugin.json", "marketplace.json", "hooks/hooks.json"]

// Khi tool_input.file_path match → exit code 2 → BLOCK
// Khi không match → exit code 0 → ALLOW

Exit code 0 = Allow operation
Exit code 2 = Block operation (stderr message hiển thị cho Claude)
Đây là deterministic guardrail – không phải "hy vọng Claude sẽ tuân theo CLAUDE.md rules"

Stop Hook – Chi tiết

stop-handler.js là core của /iterate:
// Kiểm tra 3 điều kiện:
// 1. Max iterations reached? → cleanup + exit(0)
// 2. Completion promise met? (check <promise> tag in transcript) → cleanup + exit(0)
// 3. Chưa xong? → { decision: "block", reason: task } → Continue loop

Deep Dive: Skills

Skills System

Ucai ship 7 curated skills mà Claude Code tự động load dựa trên context:


Skill
Activates When


ucai-patterns
Hỏi về Claude Code best practices, hooks, agents, context management


senior-backend
Building APIs, databases, authentication


senior-frontend
React, Next.js, Tailwind, component design


senior-architect
System design, architecture decisions, ADRs


code-reviewer
Reviewing code quality, PRs, anti-patterns


senior-qa
Testing strategies, coverage, E2E testing


senior-devops
CI/CD pipelines, deployment, infrastructure


Cơ chế hoạt động:

SessionStart hook scan skills/*/SKILL.md (plugin) + .claude/skills/*/SKILL.md (project)
Announce skills dạng: [plugin] name (description) hoặc [project] name (description)
Commands có phần Skill Loading — MANDATORY: phải load ít nhất 1 skill trước khi bắt đầu
Claude quyết định load skill nào dựa trên context

Tạo Project-Level Custom Skills

Bạn có thể tạo skills riêng cho project:
your-project/
└── .claude/
    └── skills/
        └── my-api-conventions/
            ├── SKILL.md          # Bắt buộc: YAML frontmatter + body
            └── references/       # Tùy chọn: detail loaded on demand

Ví dụ SKILL.md:
---
name: my-api-conventions
description: Use when building or modifying API endpoints in this project
---

# API Conventions

- All endpoints return JSON with `{ data, error, meta }` envelope
- Use zod for request validation
- All routes must have integration tests
- Error codes follow RFC 7807 Problem Details format
Claude Code tự động discover project-level skills cùng với plugin skills – không cần config gì thêm.
Progressive Disclosure trong Skills


      graph TD
    L1["Level 1: YAML Frontmatter<br/>Luôn nằm trong system prompt<br/>→ Claude biết skill tồn tại"] --> L2["Level 2: SKILL.md Body<br/>Load khi skill liên quan<br/>→ Hướng dẫn đầy đủ"]
    L2 --> L3["Level 3: references/<br/>Load khi cần chi tiết<br/>→ API docs, examples"]

    L1 --- A["🎯 Trigger đúng skill"]
    L2 --- B["📋 Workflow + instructions"]
    L3 --- C["📚 Chi tiết + tiết kiệm token"]

    style L1 fill:#0984e3,color:#fff,stroke:#74b9ff
    style L2 fill:#00b894,color:#fff,stroke:#55efc4
    style L3 fill:#fdcb6e,color:#2d3436,stroke:#f9ca24

    
      Loading

  
Workflow thực tế: Greenfield Project

Bước qua toàn bộ flow từ đầu đến cuối cho một dự án mới.
Bước 1: Khởi tạo dự án và lập kế hoạch

# Tạo folder project
mkdir my-app && cd my-app
git init

# Mở Claude Code
claude

# Lập kế hoạch project-level
/ucai:plan
Claude sẽ:

Hỏi bạn đang build gì, cho ai, constraints gì
Launch 2-3 explorer agents nghiên cứu domain + best practices
Draft project definition (vision, goals, tech stack)
Draft requirements backlog với build order
Chờ approval → Ghi .claude/project.md + .claude/requirements.md

Bước 2: Build features theo build order

# Build vertical slice đầu tiên
/ucai:build Core scraping pipeline

# (Tùy chọn) Nếu feature phức tạp, plan trước
/ucai:plan Authentication system
/ucai:build Authentication system
Mỗi /build sẽ:

Auto-load project.md, requirements.md, matching PRD
Check build order dependencies
Chạy qua 8 phases: Understand → Explore → Clarify → Design → Build → Verify → Test → Done
Mark requirements done khi hoàn thành

Bước 3: Generate project guidelines

# Sau khi có code, generate CLAUDE.md
/ucai:init
Bước 4: Iterate cho tasks phức tạp

/ucai:iterate Refactor database layer --max-iterations 10 --completion-promise 'All tests passing and no deprecated patterns'
Bước 5: Review code

# Review tất cả thay đổi
/ucai:review

# Review specific area
/ucai:review src/auth/
Session tiếp theo

Khi mở Claude Code lần sau, SessionStart hook sẽ announce:
Ucai plugin is active | Git branch: main | Project: MyApp | 5/12 requirements done |
Next: step 3 — Payment integration | PRDs: auth, payments, scraping |
Available skills: [plugin] ucai-patterns (...), ...

Bạn biết ngay cần làm gì tiếp: /ucai:build Payment integration

Workflow thực tế: Brownfield Project

Cho dự án đã có code sẵn:
# Bước 1: Onboard project
cd existing-project
claude
/ucai:init

# Bước 2: Lập kế hoạch roadmap
/ucai:plan

# Bước 3: Build features
/ucai:build Add real-time notifications

# Bước 4: Iterate
/ucai:iterate Fix flaky tests --max-iterations 5

Conventions và Best Practices

JavaScript Conventions (trong plugin)


Convention
Ví dụ


Không semicolons (ASI style)
const x = 1


Double quotes
"hello"


camelCase variables/functions
getGitBranch()


SCREAMING_SNAKE_CASE constants
STATE_FILE


Shebang trên executable scripts
#!/usr/bin/env node


Không external dependencies
Chỉ Node.js builtins: fs, path, readline


Markdown Conventions (commands/agents/skills)


Commands: frontmatter có description, argument-hint, allowed-tools
Agents: frontmatter có name, description, tools, model, color
Skills: frontmatter có name, description
Phased workflows dùng ## Phase N: Name headers
Approval gates stated explicitly in bold/CAPS

File Naming


Tất cả files: kebab-case
Commands/agents/skills: .md
Scripts/handlers: .js

State Management


File
Persistence
Tracked in Git?


.claude/project.md
Permanent
✅ Yes


.claude/requirements.md
Permanent
✅ Yes


.claude/prds/*.md
Permanent
✅ Yes


.claude/ucai-iterate.local.md
Temporary
❌ No (gitignored)


CLAUDE.md
Permanent
✅ Yes


Cross-Platform Compatibility


Hook paths luôn dùng ${CLAUDE_PLUGIN_ROOT} với quotes cho Windows
YAML frontmatter parse với \r?\n cho CRLF compatibility
File comparison trên Windows dùng case-insensitive matching


So sánh chi tiết: Ucai vs Community Frameworks

Ucai vs BMAD Method


Khía cạnh
BMAD Method
Ucai


Triết lý
21 agent personas, 50+ workflows
5 focused agents, 6 commands


Planning
Agent personas hướng dẫn (PM, Architect, UX...)
Discovery agents + structured output


Execution
Thủ công (dev-story per story)
/build 8-phase + /iterate autonomous


Context
In-session (mất khi đổi session)
File-based chain (persist forever)


Guardrails
CLAUDE.md rules
PreToolUse hooks (deterministic)


Skills
Không
7 curated + project-level custom


Cài đặt
npx bmad-method install
/plugin marketplace add


Complexity
Cao (21 agents, 50+ workflows)
Thấp (5 agents, 6 commands)


Ucai vs Ralph


Khía cạnh
Ralph
Ucai


Iteration
External bash loop, fresh Claude instances
Native Stop hook, same session


Planning
Cần có sẵn prd.json
Built-in /plan


Circuit breaker
Bash-level circuit breaker
Max iterations + completion promise


Memory
progress.txt, AGENTS.md
File system + TodoWrite + git


Dependencies
Bash, tmux
Chỉ Node.js builtins


Ucai vs bmalph


Khía cạnh
bmalph
Ucai


Approach
BMAD + Ralph bundled
Native plugin, built from scratch


Dependencies
Node.js 20+, Bash, Ralph loop
Chỉ Node.js builtins


Installation
npm install -g bmalph
/plugin marketplace add


Complexity
Cao (2 frameworks + glue layer)
Thấp (pure native)


Size
~30+ files across 2 frameworks
~20 files, all native format


Troubleshooting

Ucai commands không hiển thị

Triệu chứng: Chạy /help nhưng không thấy /ucai:* commands.
Nguyên nhân & giải pháp:

Chưa cài plugin: Chạy /plugin marketplace add Joncik91/ucai rồi /plugin install ucai@ucai-marketplace
Claude Code version cũ: Kiểm tra claude --version ≥ 1.0.33
Plugin bị disable: Kiểm tra /plugin list

SessionStart hook không chạy

Triệu chứng: Không thấy "Ucai plugin is active" khi bắt đầu session.
Nguyên nhân & giải pháp:

Node.js không có trong PATH: Kiểm tra which node
Hook timeout: SessionStart hook có timeout 10s. Nếu project quá lớn, scan skills có thể chậm

Iterate loop không dừng

Triệu chứng: Claude cứ tiếp tục iterate dù đã đạt mục tiêu.
Nguyên nhân & giải pháp:

Completion promise format sai: Claude phải output exact <promise>...</promise> tag. Nội dung phải match chính xác
Hủy thủ công: Chạy /ucai:cancel-iterate
Max iterations = 0: Mặc định là unlimited. Luôn set --max-iterations để có safety net

PreToolUse hook block nhầm file

Triệu chứng: Không thể edit file mà bạn muốn edit.
Nguyên nhân: Hook chỉ protect 3 files: plugin.json, marketplace.json, hooks/hooks.json. Nếu bị block file khác → đó là bug, report trên GitHub.
Agent trả kết quả rỗng

Triệu chứng: Explorer/scanner agents không tìm thấy gì.
Nguyên nhân & giải pháp:

Empty project: /init Phase 1 sẽ detect và chuyển sang Phase 2B (Scaffolding). Đừng chạy /build trên empty project
Wrong directory: Kiểm tra pwd – phải đang ở root của project


FAQ

Q: Ucai có thay thế CLAUDE.md không?

A: Không. Ucai generate CLAUDE.md (qua /init) với project facts thực tế. CLAUDE.md vẫn là file guidelines chính, nhưng giờ nó chứa facts được phân tích tự động thay vì template dumps.
Q: Có cần dùng tất cả commands không?

A: Không. Mỗi command hoạt động độc lập:

Chỉ cần onboarding? → /init
Chỉ cần code review? → /review
Chỉ cần iterate? → /iterate
Full workflow? → /plan → /build → /review

Q: Ucai có conflict với BMAD hay plugin khác không?

A: Ucai dùng namespace ucai: cho tất cả commands, nên không conflict. Có thể cài nhiều plugins cùng lúc.
Q: Skills load có tốn token không?

A: Skills dùng progressive disclosure: chỉ YAML frontmatter (~2-3 dòng) nằm trong system prompt. Body chỉ load khi skill được activate. References chỉ load khi thật cần. Rất tiết kiệm token.
Q: Có thể customize agents không?

A: Hiện tại agents nằm trong plugin, không customize trực tiếp được. Nhưng bạn có thể:

Tạo project-level skills để bổ sung knowledge
Tạo project-level CLAUDE.md để thêm conventions
Fork repo và modify agents (dev mode: claude --plugin-dir ./ucai)

Q: Ucai hoạt động trên Windows không?

A: Có. Plugin dùng ${CLAUDE_PLUGIN_ROOT} với quotes, parse frontmatter với \r?\n, và file comparison case-insensitive trên Windows.

Resources & References

Official


Repository: github.com/Joncik91/ucai
CONTRIBUTING.md: Hướng dẫn đóng góp + issue/PR templates
Claude Code Plugin Docs: Tài liệu chính thức về plugin system

Related Frameworks


BMAD Method: github.com/bmad-code-org/BMAD-METHOD
Ralph: github.com/snarktank/ralph
bmalph: github.com/LarsCowe/bmalph

Skills Ecosystem


Engineering skills source: github.com/alirezarezvani/claude-skills (MIT)
Community skills: skillsmp.com (200,000+ skills)

Bài viết liên quan trong Vault


[[Claude-Code-Best-Practice-Guide]] — Best practices cho Claude Code
[[Claude-Skills-Zero-2-Hero]] — Hướng dẫn tạo skills từ cơ bản
[[BMAD-Method-Guide]] — Hướng dẫn BMAD Method
[[Bmalph-Guide]] — Hướng dẫn bmalph (BMAD + Ralph)
Vấn đề	Framework Approach	Ucai (Native) Approach
Context rot	Bash wrappers spawn fresh sessions	Task tool đã cho fresh context per agent
Không có cấu trúc	Persona prompts + ceremonies	Commands với phased workflows + parallel agents
Không có guardrails	CLAUDE.md rules (hope-based)	PreToolUse hooks (deterministic)
Không thể iterate	External bash loops	Stop hooks (native, built-in)
Không có planning	Manual PRD docs hoặc bỏ qua	`/plan` với discovery agents + structured file output
Không có onboarding	Template CLAUDE.md dumps	Agent-powered codebase analysis
Tiêu chí	Vibe Coding	BMAD Method	Ralph	bmalph	Ucai
Tiếp cận	Prompt → Code	Persona agents → Workflows	Bash loop → Auto-code	BMAD + Ralph	Native plugin architecture
Planning	Không	Rất chi tiết	Cơ bản (prd.json)	BMAD-level	`/plan` + discovery agents
Execution	Thủ công	Thủ công	Autonomous loop	Ralph loop	`/build` 8-phase + `/iterate`
Context management	Không	In-session	Git + progress.txt	Docs + Git	File-based chain + hooks
Guardrails	Không	CLAUDE.md rules	Không	Hạn chế	PreToolUse hooks (deterministic)
Skill system	Không	Không	Không	Không	7 curated skills + project-level
Cài đặt	Không cần	npx install	Clone repo	npm install	`/plugin marketplace add`
Phù hợp với	Prototype nhanh	Dự án lớn cần planning	Dự án đã có PRD	End-to-end pipeline	Mọi dự án Claude Code
Phase	Tên	Mô tả
1	Detection	Dùng Glob kiểm tra source files. Nếu empty → Phase 2B, nếu có code → Phase 2A
2A	Analysis	Launch 2-3 `project-scanner` agents song song: tech stack, conventions, architecture
2B	Scaffolding	Hỏi user: đang build gì, tech stack, conventions, constraints
3	Generate	Draft CLAUDE.md → trình bày → chờ approval → write file
4	Optional Setup	Gợi ý thêm hooks, test commands nếu cần
Phase	Tên	Agents	Approval?	Mô tả
1	Understand	—	Confirm specs	Load project.md, requirements.md, PRD. Check build order dependencies
2	Explore	2-3 `explorer`	—	Map codebase: similar features, architecture, testing patterns
3	Clarify	—	Wait for answers	Liệt kê mọi ambiguity: edge cases, error handling, scope
4	Design	2-3 `architect`	User chọn approach	3 options: minimal, clean architecture, pragmatic balance
5	Build	—	⚠️ Explicit approval	Implement theo approach được chọn. Follow conventions strictly
6	Verify	`verifier` + 2 `reviewer`	Fix now/later/proceed	Kiểm tra acceptance criteria, bugs, conventions, security
7	Test	—	⚠️ User test manually	Tạo concrete test checklist. User phải confirm pass
8	Done	—	Approve requirement updates	Mark requirements ✅, update CLAUDE.md nếu cần
Agent	Color	Tools	Mission
`project-scanner`	🟡 Yellow	Glob, Grep, Read, Bash, WebFetch, WebSearch	Phân tích project: tech stack, conventions, patterns
`explorer`	🔵 Cyan	Glob, Grep, Read, Bash, WebFetch, TodoWrite, WebSearch	Khám phá deep: execution paths, architecture, dependencies
`architect`	🟢 Green	Glob, Grep, Read, Bash, WebFetch, TodoWrite, WebSearch	Thiết kế architecture blueprint: components, data flow, build sequence
`reviewer`	🔴 Red	Glob, Grep, Read, Bash, WebFetch, TodoWrite, WebSearch	Code review: bugs, security, conventions. Confidence-based filtering
`verifier`	🔵 Blue	Glob, Grep, Read, Bash, WebFetch, TodoWrite, WebSearch	Kiểm tra acceptance criteria
Hook	Event	Handler	Mục đích
SessionStart	Khi session bắt đầu	`sessionstart-handler.js`	Inject context: git branch, iterate status, skills, spec progress
PreToolUse	Trước khi Write/Edit	`pretooluse-guard.js`	Chặn sửa đổi config files (plugin.json, marketplace.json, hooks.json)
Stop	Khi Claude muốn dừng	`stop-handler.js`	Điều khiển iterate loop: block exit + feed task back
Skill	Activates When
ucai-patterns	Hỏi về Claude Code best practices, hooks, agents, context management
senior-backend	Building APIs, databases, authentication
senior-frontend	React, Next.js, Tailwind, component design
senior-architect	System design, architecture decisions, ADRs
code-reviewer	Reviewing code quality, PRs, anti-patterns
senior-qa	Testing strategies, coverage, E2E testing
senior-devops	CI/CD pipelines, deployment, infrastructure
Convention	Ví dụ
Không semicolons (ASI style)	`const x = 1`
Double quotes	`"hello"`
camelCase variables/functions	`getGitBranch()`
SCREAMING_SNAKE_CASE constants	`STATE_FILE`
Shebang trên executable scripts	`#!/usr/bin/env node`
Không external dependencies	Chỉ Node.js builtins: `fs`, `path`, `readline`
File	Persistence	Tracked in Git?
`.claude/project.md`	Permanent	✅ Yes
`.claude/requirements.md`	Permanent	✅ Yes
`.claude/prds/*.md`	Permanent	✅ Yes
`.claude/ucai-iterate.local.md`	Temporary	❌ No (gitignored)
`CLAUDE.md`	Permanent	✅ Yes
Khía cạnh	BMAD Method	Ucai
Triết lý	21 agent personas, 50+ workflows	5 focused agents, 6 commands
Planning	Agent personas hướng dẫn (PM, Architect, UX...)	Discovery agents + structured output
Execution	Thủ công (dev-story per story)	`/build` 8-phase + `/iterate` autonomous
Context	In-session (mất khi đổi session)	File-based chain (persist forever)
Guardrails	CLAUDE.md rules	PreToolUse hooks (deterministic)
Skills	Không	7 curated + project-level custom
Cài đặt	npx bmad-method install	/plugin marketplace add
Complexity	Cao (21 agents, 50+ workflows)	Thấp (5 agents, 6 commands)