Best practices khi dùng one-toolkit

1. Cách thiết kế phase hợp lý

Principle: Right-size your phases

Quá chi tiết ❌:

## Requirements Phase
- User story 1: As a user, I want to click login button
- User story 2: As a user, I want to see login form
- User story 3: As a user, I want to enter email
- User story 4: As a user, I want to enter password
- User story 5: As a user, I want to click submit
...

→ Quá verbose, mất thời gian

Quá vague ❌:

## Requirements Phase
- User needs authentication

→ Thiếu detail, AI không hiểu rõ

Vừa đủ ✅:

## Requirements Phase

### User Stories
- As a user, I want to login with email/password so that I can access my account
- As a user, I want to register a new account so that I can use the system
- As a user, I want to reset password if I forget so that I can regain access
- As a user, I want to stay logged in so that I don't have to login every time

### Success Criteria
- Login completes in < 2 seconds
- Password must be hashed (bcrypt)
- JWT tokens with 15min expiry
- Support "remember me" feature

→ Đủ detail, không quá dài

Best practice: 5-10 user stories per feature

Quá ít (< 5):

• Thiếu coverage
• Miss edge cases

Quá nhiều (> 15):

• Overwhelming
• Khó maintain

Sweet spot: 5-10 user stories, cover:

• Happy path (3-5 stories)
• Edge cases (2-3 stories)
• Error scenarios (1-2 stories)

---

2. Không over-engineer workflow

Principle: Start simple, add complexity when needed

Over-engineered ❌:

Requirements Phase
  ↓
Requirements Review Phase
  ↓
Requirements Approval Phase
  ↓
Pre-Design Phase
  ↓
Design Phase
  ↓
Design Review Phase
  ↓
Design Approval Phase
  ↓
...

→ Quá nhiều phases, chậm

Under-engineered ❌:

Requirements → Code → Done

→ Thiếu phases quan trọng

Just right ✅:

Requirements → Design → Planning → Implementation → Testing

→ 5 phases chuẩn, đủ dùng

Khi nào thêm phases?

Thêm "Security Review" phase nếu:

• Fintech/Healthcare app
• Handle sensitive data
• Compliance requirements

Thêm "Performance Testing" phase nếu:

• High traffic app (> 10K users)
• Real-time requirements
• SLA commitments

Thêm "Documentation" phase nếu:

• Public API
• Open source project
• External users

Không thêm nếu:

• Internal tool
• Small team
• Simple CRUD app

---

3. Khi nào nên break phase

Principle: Break phase khi scope quá lớn

Scenario: Feature "E-commerce Platform"

Không break ❌:

docs/agent/requirements/feature-ecommerce-platform.md
- 50 user stories
- 200 lines
- Overwhelming

Break thành sub-features ✅:

docs/agent/requirements/feature-product-catalog.md
docs/agent/requirements/feature-shopping-cart.md
docs/agent/requirements/feature-checkout.md
docs/agent/requirements/feature-payment.md
docs/agent/requirements/feature-order-management.md

Rule of thumb: Break nếu

Metric	Threshold
User stories	> 15
File size	> 300 lines
Implementation time	> 2 weeks
Number of APIs	> 10 endpoints
Database tables	> 5 tables

Cách break hợp lý

By domain (recommended):

feature-user-management.md
feature-product-management.md
feature-order-management.md

By layer (not recommended):

feature-frontend.md
feature-backend.md
feature-database.md

→ Khó track end-to-end flow

By priority (for MVP):

feature-core-mvp.md
feature-nice-to-have.md
feature-future.md

---

4. Sai lầm thường gặp

Sai lầm #1: Skip requirements phase

Tư duy sai:

"Requirements rõ rồi, nhảy thẳng vào design"

Hậu quả:

• Miss edge cases
• Không có success criteria
• Khó verify khi done

Best practice:

Luôn viết requirements, dù ngắn
Ít nhất: problem statement + 3-5 user stories + success criteria

Sai lầm #2: Design quá chi tiết

Tư duy sai:

## Design Phase

### Function: createUser()
```typescript
async function createUser(
  email: string,
  password: string,
  name: string,
  age?: number,
  address?: string,
  phone?: string
): Promise<User> {
  // Step 1: Validate email
  if (!isValidEmail(email)) {
    throw new ValidationError('Invalid email');
  }
  
  // Step 2: Hash password
  const hash = await bcrypt.hash(password, 10);
  
  // Step 3: Create user
  const user = await db.users.create({
    email,
    passwordHash: hash,
    name,
    age,
    address,
    phone
  });
  
  // Step 4: Send welcome email
  await emailService.sendWelcome(user.email);
  
  return user;
}

**Vấn đề**: Đây là implementation, không phải design

**Best practice**:
```markdown
## Design Phase

### User Service
- createUser(dto: CreateUserDto): Promise<User>
  - Validate input
  - Hash password (bcrypt, 10 rounds)
  - Store in database
  - Send welcome email (async)
  - Return user object (without password)

### Data Model
```typescript
interface User {
  id: string;
  email: string;
  passwordHash: string;
  name: string;
  createdAt: Date;
}

API Endpoint

POST /api/users Request: { email, password, name } Response:

→ High-level design, không phải code

### Sai lầm #3: Planning không có checkboxes

**Tư duy sai**:
```markdown
## Planning

Tasks:
1. Create user model
2. Create user service
3. Create user controller
4. Write tests

Vấn đề: Không track được progress

Best practice:

## Planning

### Tasks
- [ ] Create user model
- [ ] Create user service
- [ ] Create user controller
- [ ] Write unit tests
- [ ] Write integration tests

### Progress
- Completed: 0/5
- In Progress: 0/5
- Blocked: 0/5

→ Dùng checkboxes, dễ track

Sai lầm #4: Không update docs khi thay đổi

Scenario:

Week 1: Design dùng PostgreSQL
Week 2: Đổi sang MongoDB (vì lý do X)
Week 3: Docs vẫn nói PostgreSQL

Hậu quả:

• Docs outdated
• New members confused
• Mất trust vào docs

Best practice:

## Design Decisions

### Database Choice
~~PostgreSQL~~ → **MongoDB** (changed on 2024-01-15)

Rationale for change:
- Need flexible schema for user metadata
- Frequent schema changes expected
- MongoDB better fit for our use case

Original rationale (PostgreSQL):
- ACID transactions
- Complex queries
→ These requirements changed after talking to stakeholders

→ Document changes, giữ history

Sai lầm #5: Copy-paste templates mà không customize

Tư duy sai:

Copy template → Không đổi gì → Done

Ví dụ:

## Problem Statement
**What problem are we solving?**

- Describe the core problem or pain point
- Who is affected by this problem?
- What is the current situation/workaround?

→ Vẫn là template text, chưa fill in

Best practice:

## Problem Statement

Users cannot track their daily expenses, leading to poor budget management.
Currently using spreadsheets which are:
- Time-consuming to update
- Error-prone (manual entry)
- No real-time insights
- Difficult to share with family members

Affected users: 10,000+ active users requesting this feature

→ Filled in với real content

Sai lầm #6: Quá phụ thuộc vào AI

Tư duy sai:

"AI sẽ làm hết, tôi chỉ cần approve"

Thực tế:

• AI có thể miss business logic
• AI không biết context đầy đủ
• AI có thể hallucinate

Best practice:

AI: Draft 80%
You: Review + customize 20%

Đặc biệt review:
- Business logic
- Security requirements
- Edge cases
- Performance considerations

Sai lầm #7: Không dùng commands

Tư duy sai:

"Tôi sẽ tự viết prompt dài"

Developer: "Tôi muốn bắt đầu feature mới, hãy hỏi tôi về 
           requirements, sau đó tạo design doc theo cấu trúc 
           trong docs/agent/, nhớ include mermaid diagram..."

Vấn đề:

• Dài dòng
• Dễ quên steps
• Không consistent

Best practice:

Developer: /new-requirement

→ Ngắn gọn, consistent, AI biết phải làm gì

---

5. Advanced Tips

Tip #1: Versioning cho docs

Khi refactor lớn:

docs/agent/design/
├── feature-auth.md           # Current version
└── archive/
    ├── feature-auth-v1.md    # Original design
    └── feature-auth-v2.md    # First refactor

Lợi ích:

• Giữ history
• Hiểu evolution của feature
• Rollback nếu cần

Tip #2: Link giữa các docs

In requirements doc:

## Related Documents
- Design: [feature-auth design](../design/feature-auth.md)
- Planning: [feature-auth plan](../planning/feature-auth.md)
- Implementation: [feature-auth impl](../implementation/feature-auth.md)

Lợi ích:

• Dễ navigate
• Thấy được big picture

Tip #3: Dùng tags cho filtering

In frontmatter:

---
phase: requirements
feature: authentication
priority: P0
status: completed
team: backend
---

Lợi ích:

• Filter docs by tag
• Generate reports
• Track progress

Tip #4: Template cho common patterns

Create custom templates:

docs/agent/templates/
├── api-endpoint.md
├── database-migration.md
├── integration.md
└── refactor.md

Ví dụ: api-endpoint.md

## API Endpoint: [METHOD] [PATH]

### Purpose
[What does this endpoint do?]

### Request
```json
{
  "field": "type"
}

Response

{
  "field": "type"
}

Validation Rules

• [ ] Rule 1
• [ ] Rule 2

Error Scenarios

• 400: [scenario]
• 401: [scenario]
• 500: [scenario]

Security

• [ ] Authentication required
• [ ] Authorization check
• [ ] Rate limiting
• [ ] Input sanitization

### Tip #5: Automation với scripts

**Auto-generate summary**:
```bash
# scripts/generate-summary.sh

echo "# Project Summary" > SUMMARY.md
echo "" >> SUMMARY.md

echo "## Features" >> SUMMARY.md
for file in docs/agent/requirements/*.md; do
  feature=$(basename "$file" .md)
  echo "- $feature" >> SUMMARY.md
done

echo "" >> SUMMARY.md
echo "## Progress" >> SUMMARY.md
completed=$(grep -r "\[x\]" docs/agent/planning/ | wc -l)
total=$(grep -r "\[ \]" docs/agent/planning/ | wc -l)
echo "- Completed: $completed/$total tasks" >> SUMMARY.md

Tip #6: Review checklist

Before merging:

## Pre-merge Checklist

### Documentation
- [ ] Requirements doc complete
- [ ] Design doc complete
- [ ] Planning doc updated with status
- [ ] Implementation notes added
- [ ] Test coverage documented

### Code Quality
- [ ] All tests pass
- [ ] Coverage > 90%
- [ ] No linting errors
- [ ] Code reviewed
- [ ] Security checked

### Alignment
- [ ] Implementation matches design
- [ ] All requirements covered
- [ ] All tasks in planning completed

---

6. Team Workflow Best Practices

Practice #1: Daily sync via docs

Instead of daily standup:

Each developer updates:
docs/agent/planning/feature-X.md

- [x] Task A (completed yesterday)
- [~] Task B (in progress, 50% done)
- [ ] Task C (blocked: waiting for API key)
- [ ] Task D (next)

Team lead reviews docs → knows status

Practice #2: Code review with docs

Reviewer checklist:

1. Read design doc
2. Read planning doc
3. Review code against design
4. Check if all tasks completed
5. Verify tests cover requirements

Practice #3: Onboarding checklist

For new team members:

## Week 1: Read Documentation
- [ ] Read all requirements docs
- [ ] Read all design docs
- [ ] Understand architecture

## Week 2: Small Tasks
- [ ] Pick 1-2 small tasks from planning docs
- [ ] Implement with guidance
- [ ] Get code reviewed

## Week 3: Feature Ownership
- [ ] Own 1 small feature end-to-end
- [ ] Write docs + code + tests

---

7. Metrics to Track

Documentation Health

## Documentation Metrics

### Coverage
- Features with requirements doc: 45/50 (90%)
- Features with design doc: 42/50 (84%)
- Features with tests doc: 40/50 (80%)

### Freshness
- Updated in last month: 35/50 (70%)
- Updated in last 3 months: 45/50 (90%)
- Outdated (> 6 months): 5/50 (10%)

### Quality
- Has mermaid diagrams: 38/50 (76%)
- Has code examples: 40/50 (80%)
- Has success criteria: 45/50 (90%)

Development Velocity

## Velocity Metrics

### Before one-toolkit
- Average time per feature: 8 days
- Refactor rate: 15 times/feature
- Bug density: 8 bugs/KLOC

### After one-toolkit
- Average time per feature: 6 days (-25%)
- Refactor rate: 3 times/feature (-80%)
- Bug density: 2 bugs/KLOC (-75%)

### ROI
- Time saved: 2 days/feature
- Quality improved: 75%
- Team satisfaction: +40%

---

Kết luận: Golden Rules

1. Start simple: Dùng 5 phases chuẩn, không over-engineer
2. Right-size: 5-10 user stories, 200-300 lines/doc
3. Break when needed: Feature > 15 stories → break
4. Always update: Docs thay đổi theo code
5. Use commands: Đừng viết prompt dài
6. Review docs: Như review code
7. Track metrics: Measure improvement
8. Customize templates: Fit your needs
9. Link docs: Easy navigation
10. Trust but verify: AI draft 80%, you review 20%

Remember:

"one-toolkit là tool, không phải magic. Bạn vẫn phải suy nghĩ và quyết định."

---

Tiếp theo: Tổng kết và decision guide → Xem phần tiếp theo.