one-toolkit là gì? (Mental Model)

Giải thích one-toolkit bằng tư duy hệ thống

Định nghĩa ngắn gọn

one-toolkit là một CLI tool giúp bạn áp đặt quy trình phát triển phần mềm có cấu trúc (SDLC) lên AI coding agents.

Nói cách khác: one-toolkit biến AI agent từ "code generator" thành "software engineer".

Mental Model: AI Agent như Junior Developer

Hãy tưởng tượng bạn có một junior developer rất giỏi code nhưng:

• Thiếu kinh nghiệm
• Hay quên context
• Không biết quy trình làm việc
• Cần được hướng dẫn cụ thể

Không có one-toolkit:

Bạn: "Làm feature X"
Junior: *viết code ngay*
Bạn: "Sai rồi, phải làm Y trước"
Junior: *viết lại*
Bạn: "Ủa, tại sao không làm theo design?"
Junior: "Design nào ạ?"

Có one-toolkit:

Bạn: "Làm feature X"
Toolkit: "OK, bắt đầu từ Requirements phase"
Junior: *viết requirements doc*
Toolkit: "Xong Requirements, chuyển sang Design phase"
Junior: *thiết kế architecture dựa trên requirements*
Toolkit: "Design xong, giờ làm Planning"
Junior: *break down thành tasks*
Toolkit: "Bắt đầu implement theo plan"
Junior: *code với context đầy đủ*

one-toolkit = Framework + Templates + Rules

┌─────────────────────────────────────────┐
│           one-toolkit                    │
├─────────────────────────────────────────┤
│                                          │
│  📋 Phase Templates                      │
│     ├── requirements.md                  │
│     ├── design.md                        │
│     ├── planning.md                      │
│     ├── implementation.md                │
│     └── testing.md                       │
│                                          │
│  🤖 AI Environment Configs               │
│     ├── AGENTS.md (context rules)        │
│     ├── .cursor/commands/ (slash cmds)   │
│     └── .agent/workflows/ (workflows)    │
│                                          │
│  ⚙️  Configuration                       │
│     └── .one-toolkit.json                │
│                                          │
└─────────────────────────────────────────┘

one-toolkit đóng vai trò gì trong AI coding stack

AI Coding Stack (Từ dưới lên)

┌─────────────────────────────────────────┐
│  Layer 4: Developer (You)               │  ← Quyết định chiến lược
├─────────────────────────────────────────┤
│  Layer 3: one-toolkit                   │  ← Quy trình & cấu trúc
├─────────────────────────────────────────┤
│  Layer 2: AI Agent                      │  ← Code generation
│  (Cursor, Claude, Copilot...)           │
├─────────────────────────────────────────┤
│  Layer 1: LLM                           │  ← AI model
│  (GPT-4, Claude, Gemini...)             │
└─────────────────────────────────────────┘

Vai trò của từng layer:

1. LLM: Hiểu ngôn ngữ tự nhiên, sinh code
2. AI Agent: Tích hợp LLM vào IDE, quản lý context
3. one-toolkit: Áp đặt quy trình, cấu trúc, rules
4. Developer: Đưa ra quyết định, review, approve

Tương tự trong xây dựng

Xây nhà	AI Coding
Kiến trúc sư	Developer
Quy chuẩn xây dựng	one-toolkit
Công nhân	AI Agent
Công cụ	LLM

Bạn không muốn công nhân tự ý xây nhà theo ý họ. Bạn cần quy chuẩn.

So sánh: Không dùng vs Dùng one-toolkit

Scenario: Xây dựng REST API cho blog

Không dùng one-toolkit

Cách làm việc:

Developer: "Tạo REST API cho blog với CRUD posts"
AI: *sinh code ngay*

Kết quả sau 1 tuần:

project/
├── src/
│   ├── controllers/
│   │   └── post.controller.ts (AI sinh)
│   ├── services/
│   │   └── post.service.ts (AI sinh)
│   └── models/
│       └── post.model.ts (AI sinh)
└── README.md (outdated)

Vấn đề:

• ❌ Không có requirements doc → Không biết feature nào cần, nào không cần
• ❌ Không có design doc → Không biết tại sao chọn architecture này
• ❌ Không có test plan → Tests viết sau, coverage thấp
• ❌ Code bị refactor nhiều lần vì thiếu planning
• ❌ 3 tháng sau không ai nhớ tại sao làm như vậy

Thời gian:

• Code: 2 ngày
• Debug & refactor: 3 ngày
• Viết tests sau: 1 ngày
• Total: 6 ngày (và code quality thấp)

Dùng one-toolkit

Cách làm việc:

# Bước 1: Init toolkit
one-toolkit init --all

# Bước 2: Bắt đầu feature
/new-requirement

Quy trình:

Day 1: Requirements & Design

Developer: /new-requirement
AI: "Feature name?"
Developer: "blog-api"
AI: *tạo structure docs/agent/requirements/feature-blog-api.md*
AI: "What problem does it solve?"
Developer: "Users need to create, read, update, delete blog posts"
AI: *điền requirements doc với user stories, success criteria*
AI: "Let's move to design phase"
AI: *thiết kế database schema, API endpoints, architecture*

Day 2: Planning

Developer: /update-planning
AI: *break down thành tasks*:
  - [ ] Setup database models
  - [ ] Implement POST /posts
  - [ ] Implement GET /posts
  - [ ] Implement PUT /posts/:id
  - [ ] Implement DELETE /posts/:id
  - [ ] Add validation
  - [ ] Add authentication
  - [ ] Write tests

Day 3-4: Implementation

Developer: /execute-plan
AI: "Starting task: Setup database models"
AI: *implement với context từ design doc*
AI: "Task done. Next: Implement POST /posts"
...

Day 5: Testing

Developer: /writing-test
AI: *sinh tests dựa trên requirements & test plan*
AI: "Coverage: 95%"

Kết quả sau 1 tuần:

project/
├── docs/
│   └── agent/
│       ├── requirements/
│       │   └── feature-blog-api.md ✅
│       ├── design/
│       │   └── feature-blog-api.md ✅
│       ├── planning/
│       │   └── feature-blog-api.md ✅
│       ├── implementation/
│       │   └── feature-blog-api.md ✅
│       └── testing/
│           └── feature-blog-api.md ✅
├── src/
│   ├── controllers/
│   │   └── post.controller.ts
│   ├── services/
│   │   └── post.service.ts
│   ├── models/
│   │   └── post.model.ts
│   └── __tests__/
│       └── post.test.ts (95% coverage)
└── .one-toolkit.json

Lợi ích:

• ✅ Có đầy đủ documentation
• ✅ Design decisions được ghi lại
• ✅ Tests được viết song song với code
• ✅ Code ít bị refactor vì có planning tốt
• ✅ 3 tháng sau vẫn hiểu tại sao làm như vậy
• ✅ Onboard developer mới dễ dàng

Thời gian:

• Requirements: 0.5 ngày
• Design: 0.5 ngày
• Planning: 0.5 ngày
• Implementation: 2 ngày
• Testing: 1 ngày
• Total: 4.5 ngày (và code quality cao)

So sánh tổng quan

Tiêu chí	Không dùng toolkit	Dùng one-toolkit
Thời gian dev	6 ngày	4.5 ngày
Code quality	Trung bình	Cao
Documentation	Không có	Đầy đủ
Test coverage	40-60%	90%+
Maintainability	Khó	Dễ
Onboarding	Khó	Dễ
Refactor count	Nhiều	Ít
Technical debt	Cao	Thấp

Khi nào one-toolkit phát huy tác dụng?

✅ Phù hợp khi:

1. Project có tính dài hạn (> 3 tháng)
2. Team > 1 người (cần documentation để collaborate)
3. Code cần maintain (không phải prototype bỏ đi)
4. Yêu cầu chất lượng cao (production-ready)
5. Làm việc với AI agent thường xuyên

❌ Không cần khi:

1. Quick prototype (làm xong bỏ)
2. Script đơn giản (< 100 lines)
3. Deadline cực gấp (ship trước, refactor sau)
4. Solo project rất nhỏ (todo app cá nhân)

Kết luận

one-toolkit không phải là magic tool. Nó là một framework giúp bạn:

• Làm việc có kỷ luật với AI
• Tạo ra code có chất lượng
• Dễ dàng maintain và scale

Core philosophy:

"Slow down to speed up. Think before code."

Thay vì nhảy thẳng vào code, one-toolkit ép bạn (và AI) suy nghĩ trước. Kết quả là code tốt hơn, ít bug hơn, dễ maintain hơn.

---

Tiếp theo: Hiểu sâu hơn về kiến trúc của one-toolkit → Xem phần tiếp theo.