Kiến trúc tư duy của one-toolkit

Command là gì?

Định nghĩa

Command (hay Slash Command) là các lệnh tắt để kích hoạt workflow cụ thể trong AI agent.

Cú pháp

/command-name

Ví dụ:

/new-requirement - Bắt đầu feature mới
/execute-plan - Thực thi kế hoạch
/code-review - Review code
/writing-test - Viết tests

Command hoạt động như thế nào?

Khi bạn gõ /new-requirement trong Cursor hoặc Antigravity:

┌─────────────────────────────────────────┐
│  Developer gõ: /new-requirement         │
└────────────┬────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────┐
│  AI Agent đọc file:                     │
│  .cursor/commands/new-requirement.md    │
└────────────┬────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────┐
│  AI thực hiện theo prompt trong file:   │
│  1. Hỏi feature name                    │
│  2. Tạo docs structure                  │
│  3. Điền requirements                   │
│  4. Chuyển sang design phase            │
│  ...                                    │
└─────────────────────────────────────────┘

Ví dụ nội dung command file

File: .cursor/commands/new-requirement.md

markdown

I want to add a new feature/requirement. Please guide me through:

## Step 1: Capture Requirement
Ask me:
- What is the feature name?
- What problem does it solve?
- Who will use it?

## Step 2: Create Feature Documentation
Create these files:
- docs/agent/requirements/feature-{name}.md
- docs/agent/design/feature-{name}.md
- docs/agent/planning/feature-{name}.md
...

## Step 3: Requirements Phase
Help me fill out requirements doc...

Tại sao cần commands?

Không có commands:

Developer: "Tôi muốn bắt đầu feature mới, hãy hỏi tôi về requirements, 
           sau đó tạo design doc, rồi planning doc, nhớ follow 
           cấu trúc trong docs/agent/, và đừng quên..."

→ Dài dòng, dễ quên bước, không consistent

Có commands:

Developer: /new-requirement

→ Ngắn gọn, consistent, AI biết chính xác phải làm gì

Workflow là gì?

Định nghĩa

Workflow là chuỗi các bước có thứ tự để hoàn thành một mục tiêu.

Workflow trong one-toolkit

one-toolkit định nghĩa workflow chuẩn cho phát triển phần mềm:

Requirements → Design → Planning → Implementation → Testing

Mỗi mũi tên là một transition (chuyển giai đoạn).

Workflow chi tiết

mermaid

graph LR
    A[Start] --> B[Requirements Phase]
    B --> C[Design Phase]
    C --> D[Planning Phase]
    D --> E[Implementation Phase]
    E --> F[Testing Phase]
    F --> G[Code Review]
    G --> H{Pass?}
    H -->|Yes| I[Done]
    H -->|No| E

Workflow thực tế với commands

Developer: /new-requirement
  ↓
[Requirements Phase]
  - AI hỏi về feature
  - Viết user stories
  - Define success criteria
  ↓
Developer: /review-requirements
  ↓
[Design Phase]
  - Thiết kế architecture
  - Define data models
  - Design API
  ↓
Developer: /review-design
  ↓
[Planning Phase]
  - Break down tasks
  - Estimate effort
  - Identify dependencies
  ↓
Developer: /update-planning
  ↓
[Implementation Phase]
  - Execute tasks one by one
  - Update implementation notes
  ↓
Developer: /execute-plan
  ↓
[Testing Phase]
  - Write unit tests
  - Write integration tests
  - Verify coverage
  ↓
Developer: /writing-test
  ↓
[Code Review]
  ↓
Developer: /code-review
  ↓
[Done or Loop back]

Tại sao cần workflow?

Không có workflow:

Developer và AI "nhảy" giữa các giai đoạn tùy tiện
Thiếu bước → thiếu output
Khó track progress

Có workflow:

Rõ ràng đang ở giai đoạn nào
Biết bước tiếp theo là gì
Có deliverable cụ thể cho mỗi bước

Phase là gì?

Định nghĩa

Phase là một giai đoạn trong workflow, có:

Scope: Làm gì, không làm gì
Input: Cần gì để bắt đầu
Output: Tạo ra artifact gì
Rules: AI được phép/không được phép làm gì

5 Phases trong one-toolkit

1. Requirements Phase

Mục tiêu: Hiểu vấn đề cần giải quyết

Input:

Feature request từ stakeholder
Business context

Output:

File docs/agent/requirements/feature-{name}.md
Chứa:
- Problem statement
- User stories
- Success criteria
- Constraints

AI được phép:

✅ Hỏi câu hỏi làm rõ
✅ Viết user stories
✅ Đề xuất success criteria

AI KHÔNG được phép:

❌ Viết code
❌ Chọn technology stack
❌ Thiết kế database

Template: templates/phases/requirements.md

2. Design Phase

Mục tiêu: Thiết kế giải pháp kỹ thuật

Input:

Requirements document
Existing system architecture

Output:

File docs/agent/design/feature-{name}.md
Chứa:
- Architecture diagram (Mermaid)
- Data models
- API design
- Component breakdown
- Design decisions

AI được phép:

✅ Đề xuất architecture
✅ Thiết kế database schema
✅ Define API endpoints
✅ Vẽ diagrams

AI KHÔNG được phép:

❌ Viết implementation code
❌ Viết tests
❌ Break down thành tasks chi tiết

Template: templates/phases/design.md

3. Planning Phase

Mục tiêu: Chia nhỏ công việc thành tasks

Input:

Design document
Team capacity

Output:

File docs/agent/planning/feature-{name}.md
Chứa:
- Task breakdown (với checkboxes)
- Dependencies
- Effort estimates
- Implementation order
- Risk mitigation

AI được phép:

✅ Break down thành subtasks
✅ Identify dependencies
✅ Suggest implementation order
✅ Estimate effort

AI KHÔNG được phép:

❌ Implement tasks
❌ Viết code
❌ Thay đổi design

Template: templates/phases/planning.md

4. Implementation Phase

Mục tiêu: Viết code theo plan

Input:

Planning document
Design document

Output:

Source code
File docs/agent/implementation/feature-{name}.md
Chứa:
- Implementation notes
- Code patterns used
- Integration points
- Error handling approach

AI được phép:

✅ Viết code theo plan
✅ Implement theo design
✅ Handle errors
✅ Add logging

AI KHÔNG được phép:

❌ Thay đổi design tùy tiện
❌ Skip tasks trong plan
❌ Implement features không có trong requirements

Template: templates/phases/implementation.md

5. Testing Phase

Mục tiêu: Verify implementation

Input:

Implementation code
Requirements document

Output:

Test code
File docs/agent/testing/feature-{name}.md
Chứa:
- Test strategy
- Test cases
- Coverage report
- Manual testing checklist

AI được phép:

✅ Viết unit tests
✅ Viết integration tests
✅ Generate test cases từ requirements
✅ Suggest edge cases

AI KHÔNG được phép:

❌ Skip tests
❌ Viết tests không cover requirements
❌ Fake test results

Template: templates/phases/testing.md

Rule / Constraint hoạt động ra sao?

Rules trong one-toolkit

Rules được định nghĩa ở 2 nơi:

1. Global Rules (AGENTS.md)

File: AGENTS.md (hoặc CLAUDE.md cho Claude Code)

markdown

# One-Toolkit Rules

## Project Context
This project uses One-Toolkit for structured development.
Phase documentation is in `docs/agent/`.

## Code Style & Standards
- Follow project's code style
- Write self-documenting code
- Use TypeScript with strict mode

## Development Workflow
- Review phase docs before implementing
- Keep docs updated
- Reference planning doc for priorities

## AI Interaction Guidelines
- Check relevant phase docs first
- Start with requirements for new features
- Update docs when decisions change

## Testing & Quality
- Write tests alongside implementation
- Follow testing strategy in docs/agent/testing/
- Ensure 100% coverage target

Tác dụng: AI sẽ đọc file này trước khi làm bất cứ việc gì.

2. Phase-specific Rules

Trong mỗi command file, có rules cụ thể:

File: .cursor/commands/execute-plan.md

markdown

## Step 4: Interactive Task Execution
For each task:
1. Display task context
2. Suggest relevant docs to reference
3. Ask: "Plan for this task?"
4. Implement with design doc context
5. Update status

## Rules:
- MUST reference design doc before coding
- CANNOT skip tasks
- CANNOT change design without approval

Cách AI "bị ràng buộc" bởi rules

Ví dụ thực tế:

Developer: "Implement user authentication"

AI (đọc AGENTS.md):
  - "OK, project dùng one-toolkit"
  - "Cần check docs/agent/ trước"
  
AI: "Let me check the design doc first..."
AI: *đọc docs/agent/design/feature-auth.md*
AI: "According to the design doc, we're using JWT with Redis for token storage"
AI: *implement theo design*

Developer: "Thêm OAuth nữa đi"

AI: "OAuth is not in the requirements or design doc. 
     Should we update the design doc first? 
     Run /review-design to modify the design."

Nếu không có rules:

Developer: "Implement user authentication"

AI: *implement ngay với session-based auth*

Developer: "Ủa, tại sao không dùng JWT?"

AI: "OK" *refactor sang JWT*

Developer: "Thêm OAuth nữa đi"

AI: "OK" *thêm OAuth ngay, không check design*

Enforcement mechanism

Rules được enforce qua:

Context injection: AI đọc AGENTS.md mỗi khi chat mới
Command prompts: Mỗi command có instructions rõ ràng
Phase templates: Templates có structure cố định
Developer discipline: Developer phải follow workflow

Lưu ý: AI vẫn có thể "phá" rules nếu bạn yêu cầu mạnh mẽ. one-toolkit không phải "hard constraint", mà là "soft guidance".

AI agent "bị dẫn dắt" như thế nào qua từng phase

Flow chi tiết

Bước 1: Developer khởi tạo

bash

one-toolkit init --all

Kết quả:

project/
├── .one-toolkit.json          # Config
├── AGENTS.md                  # Global rules
├── .cursor/commands/          # Slash commands
│   ├── new-requirement.md
│   ├── execute-plan.md
│   ├── code-review.md
│   └── ...
└── docs/agent/                # Phase templates
    ├── requirements/README.md
    ├── design/README.md
    ├── planning/README.md
    ├── implementation/README.md
    └── testing/README.md

Bước 2: Developer bắt đầu feature

Developer: /new-requirement

AI đọc file: .cursor/commands/new-requirement.md

AI thực hiện:

AI: "What is the feature name?"
Developer: "user-profile"

AI: "Creating documentation structure..."
AI: *tạo docs/agent/requirements/feature-user-profile.md*
AI: *copy template từ docs/agent/requirements/README.md*

AI: "Let's fill out the requirements. What problem does this solve?"
Developer: "Users need to view and edit their profile info"

AI: *điền vào requirements doc*:
  ## Problem Statement
  Users need to view and edit their profile information
  
  ## User Stories
  - As a user, I want to view my profile so that I can see my info
  - As a user, I want to edit my profile so that I can update my info
  
  ## Success Criteria
  - User can view profile page
  - User can edit name, email, avatar
  - Changes are saved to database
  - Validation errors are shown

AI: "Requirements phase complete. Run /review-requirements to validate."

Bước 3: Review Requirements

Developer: /review-requirements

AI đọc: .cursor/commands/review-requirements.md

AI thực hiện:

AI: *đọc docs/agent/requirements/feature-user-profile.md*

AI: "Reviewing requirements..."

AI: "✅ Problem statement is clear"
AI: "✅ User stories are well-defined"
AI: "⚠️  Missing: What happens if user uploads large avatar?"
AI: "⚠️  Missing: Password change flow?"

AI: "Should we add these to requirements?"

Bước 4: Design Phase

Developer: "Yes, add them. Now let's design"
AI: *update requirements*

Developer: /review-design

AI tạo: docs/agent/design/feature-user-profile.md

AI thực hiện:

AI: *đọc requirements doc*
AI: "Based on requirements, proposing design..."

AI: *viết vào design doc*:
  ## Architecture
  ```mermaid
  graph TD
    Client --> API[Profile API]
    API --> Service[Profile Service]
    Service --> DB[(Database)]
    Service --> Storage[File Storage]

Data Models

typescript

interface UserProfile {
  id: string;
  name: string;
  email: string;
  avatarUrl?: string;
}

API Endpoints

GET /api/profile
PUT /api/profile
POST /api/profile/avatar

Design Decisions

Use S3 for avatar storage (scalable)
Max avatar size: 5MB
Supported formats: jpg, png, webp

AI: "Design phase complete. Review and approve before planning."


#### Bước 5: Planning Phase

Developer: "Approved. Let's plan" Developer: /update-planning


**AI tạo**: `docs/agent/planning/feature-user-profile.md`

**AI thực hiện**:

AI: đọc design doc AI: "Breaking down into tasks..."

AI: viết vào planning doc:

Task Breakdown

Foundation

[ ] Create UserProfile model
[ ] Setup S3 bucket for avatars
[ ] Create database migration

API Implementation

[ ] Implement GET /api/profile
[ ] Implement PUT /api/profile
[ ] Implement POST /api/profile/avatar
[ ] Add validation middleware

Testing

[ ] Unit tests for ProfileService
[ ] Integration tests for API endpoints
[ ] Test avatar upload flow

Dependencies

S3 bucket must be created first
Database migration before API implementation

Estimates

Foundation: 2 hours
API Implementation: 4 hours
Testing: 2 hours
Total: 8 hours

AI: "Planning complete. Run /execute-plan to start implementation."


#### Bước 6: Implementation Phase

Developer: /execute-plan


**AI đọc**: 
- `.cursor/commands/execute-plan.md`
- `docs/agent/planning/feature-user-profile.md`
- `docs/agent/design/feature-user-profile.md`

**AI thực hiện**:

AI: "Starting task execution..."

AI: "Task 1: Create UserProfile model" AI: đọc design doc để biết schema AI: tạo file src/models/user-profile.model.ts AI: "Task 1 done. Mark as complete?"

Developer: "Yes"

AI: "Task 2: Setup S3 bucket" AI: tạo config cho S3 AI: "Task 2 done."

...

AI: sau mỗi task, update implementation notes AI: ghi lại patterns used, decisions made


#### Bước 7: Testing Phase

Developer: /writing-test


**AI thực hiện**:

AI: đọc requirements để biết test cases AI: đọc implementation code

AI: "Generating tests based on requirements..."

AI: tạo tests:

✅ Test GET /api/profile returns user data
✅ Test PUT /api/profile updates user data
✅ Test avatar upload with valid file
✅ Test avatar upload with invalid file (> 5MB)
✅ Test validation errors

AI: "Running tests..." AI: "Coverage: 95%" AI: "Missing coverage: Error handling in avatar upload"

AI: "Should I add tests for error cases?"


#### Bước 8: Code Review

Developer: /code-review


**AI thực hiện**:

AI: đọc design doc AI: review code

AI: "Reviewing against design doc..."

AI: "✅ API endpoints match design" AI: "✅ Data models match schema" AI: "✅ S3 integration as designed" AI: "⚠️ Found: No rate limiting on avatar upload" AI: "⚠️ Found: Missing error logging"

AI: "Recommendations:" AI: "1. Add rate limiting (5 uploads/minute)" AI: "2. Add error logging with context" AI: "3. Add retry logic for S3 upload failures"


### Tại sao AI "bị dẫn dắt"?

1. **Commands cung cấp instructions rõ ràng**: Mỗi command là một "script" chi tiết
2. **Phase templates cung cấp structure**: AI biết phải điền gì vào đâu
3. **Rules ràng buộc hành vi**: AI không được "nhảy phase"
4. **Context từ docs trước**: Mỗi phase reference output của phase trước

**Kết quả**: AI làm việc có hệ thống, giống một engineer thực thụ.

## Kết luận

**one-toolkit architecture** gồm 3 layers:

1. **Command Layer**: Slash commands để trigger workflows
2. **Workflow Layer**: Chuỗi phases có thứ tự
3. **Phase Layer**: Từng giai đoạn với scope, input, output, rules rõ ràng

**Cách hoạt động**:
- Developer gõ command → AI đọc command file → AI thực hiện theo instructions → AI tạo/update phase docs → Developer review → Chuyển phase tiếp theo

**Lợi ích**:
- AI làm việc có kỷ luật
- Output có cấu trúc
- Dễ track và review
- Giảm hallucination

---

**Tiếp theo**: Áp dụng vào quy trình phát triển thực tế → Xem phần tiếp theo.

Kiến trúc tư duy của one-toolkit ​

Command là gì? ​

Định nghĩa ​

Cú pháp ​

Command hoạt động như thế nào? ​

Ví dụ nội dung command file ​

Tại sao cần commands? ​

Workflow là gì? ​

Định nghĩa ​

Workflow trong one-toolkit ​

Workflow chi tiết ​

Workflow thực tế với commands ​

Tại sao cần workflow? ​

Phase là gì? ​

Định nghĩa ​

5 Phases trong one-toolkit ​

1. Requirements Phase ​

2. Design Phase ​

3. Planning Phase ​

4. Implementation Phase ​

5. Testing Phase ​

Rule / Constraint hoạt động ra sao? ​

Rules trong one-toolkit ​

1. Global Rules (AGENTS.md) ​

2. Phase-specific Rules ​

Cách AI "bị ràng buộc" bởi rules ​

Enforcement mechanism ​

AI agent "bị dẫn dắt" như thế nào qua từng phase ​

Flow chi tiết ​

Bước 1: Developer khởi tạo ​

Bước 2: Developer bắt đầu feature ​

Bước 3: Review Requirements ​

Bước 4: Design Phase ​

Data Models ​

API Endpoints ​

Design Decisions ​

Task Breakdown ​

Foundation ​

API Implementation ​

Testing ​

Dependencies ​

Estimates ​

Kiến trúc tư duy của one-toolkit

Command là gì?

Định nghĩa

Cú pháp

Command hoạt động như thế nào?

Ví dụ nội dung command file

Tại sao cần commands?

Workflow là gì?

Định nghĩa

Workflow trong one-toolkit

Workflow chi tiết

Workflow thực tế với commands

Tại sao cần workflow?

Phase là gì?

Định nghĩa

5 Phases trong one-toolkit

1. Requirements Phase

2. Design Phase

3. Planning Phase

4. Implementation Phase

5. Testing Phase

Rule / Constraint hoạt động ra sao?

Rules trong one-toolkit

1. Global Rules (AGENTS.md)

2. Phase-specific Rules

Cách AI "bị ràng buộc" bởi rules

Enforcement mechanism

AI agent "bị dẫn dắt" như thế nào qua từng phase

Flow chi tiết

Bước 1: Developer khởi tạo

Bước 2: Developer bắt đầu feature

Bước 3: Review Requirements

Bước 4: Design Phase

Data Models

API Endpoints

Design Decisions

Task Breakdown

Foundation

API Implementation

Testing

Dependencies

Estimates