Kỹ thuật "Writing Plans" (hay lập kế hoạch mã hóa vi mô) Claude Code

Kỹ thuật "Writing Plans" (hay lập kế hoạch mã hóa vi mô) là bước chuyển tiếp sống còn giữa tài liệu đặc tả (Technical Spec) và việc gõ code thực tế. Bằng cách chẻ nhỏ một tính năng phức tạp thành các tác vụ siêu ngắn (micro-tasks) chỉ mất 2–5 phút để hoàn thành, bạn loại bỏ hoàn toàn tình trạng quá tải nhận thức (cognitive overload) và sự bối rối khi không biết bắt đầu từ đâu.

Khi kết hợp với các công cụ AI coding như Cursor hay Claude Code, một Writing Plan chuẩn mực sẽ biến AI thành một cỗ máy thực thi hoàn hảo, code đúng file, đúng logic và không phá vỡ kiến trúc hiện tại.

Cấu Trúc Tiêu Chuẩn Của Một Micro-Task

Một tác vụ 2–5 phút không được phép mơ hồ. Nó phải chứa đủ 4 yếu tố để bất kỳ ai (hoặc bất kỳ AI nào) đọc vào cũng có thể thực thi ngay lập tức mà không cần suy luận thêm:

1. Hành động cốt lõi: Làm gì? (Tạo mới, Sửa đổi, Xóa, Refactor).

2. Đường dẫn file (File Path): Định vị chính xác tệp cần thao tác. Tuyệt đối không dùng tên file chung chung.

3. Mã nguồn/Logic (Implementation Details): Khai báo biến, hàm cần viết, hoặc thư viện cần import.

4. Kiểm thử ngay lập tức (Micro-Test): Cách xác minh tác vụ này thành công trước khi chuyển sang tác vụ tiếp theo.

Mẫu Writing Plan Ứng Dụng Thực Tế

Giả sử hệ thống (sử dụng Node.js/Express) cần thêm tính năng: "API cho phép Admin khóa tài khoản người dùng". Thay vì tạo một task lớn là "Làm API khóa user", chúng ta phân rã thành Writing Plan chi tiết như sau:

Giai đoạn 1: Database & Data Layer

[ ] Task 1.1: Cập nhật Database Schema

• File: prisma/schema.prisma (hoặc file migration tương ứng)

• Action: Thêm trường trạng thái vào model User.

• Logic:

  • Thêm status String @default("ACTIVE")

  • Thêm lockedAt DateTime?

  • Thêm lockedReason String?

• Test: Chạy lệnh npx prisma format và npx prisma db push (hoặc npm run migrate) để đảm bảo schema hợp lệ và database được cập nhật.

[ ] Task 1.2: Cập nhật Types/Interfaces

• File: src/types/user.interface.ts

• Action: Đồng bộ interface TypeScript với DB schema.

• Logic: Cập nhật interface IUser thêm các thuộc tính status (kiểu enum 'ACTIVE' | 'LOCKED'), lockedAt, và lockedReason.

• Test: Chạy npx tsc --noEmit để đảm bảo không gãy type check ở các file cũ.

Giai đoạn 2: Business Logic (Service Layer)

[ ] Task 2.1: Viết hàm xử lý khóa tài khoản

• File: src/services/user.service.ts

• Action: Thêm phương thức lockUserAccount.

• Logic:

  • Input: userId (chuỗi UUID), reason (chuỗi).

  • Kiểm tra user có tồn tại không. Nếu không, ném lỗi NotFoundError.

  • Kiểm tra trạng thái hiện tại, nếu đã LOCKED thì ném lỗi BadRequestError.

  • Cập nhật DB: status = 'LOCKED', lockedAt = new Date(), lockedReason = reason.

• Test: Viết một unit test nhanh trong src/services/user.service.spec.ts mock DB để gọi lockUserAccount và assert kết quả trả về. Chạy npm run test:unit.

Giai đoạn 3: Routing & Transport Layer

[ ] Task 3.1: Định nghĩa DTO cho Request Body

• File: src/dtos/user/lock-user.dto.ts

• Action: Tạo mới file DTO để validate dữ liệu đầu vào.

• Logic:

  • Dùng class-validator (hoặc Zod).

  • Trường reason: Bắt buộc, độ dài 5-255 ký tự.

• Test: Không cần test riêng, sẽ test chung ở tầng Controller.

[ ] Task 3.2: Viết Controller xử lý HTTP Request

• File: src/controllers/admin.controller.ts

• Action: Thêm hàm lockUser.

• Logic:

  • Lấy userId từ req.params.

  • Lấy reason từ req.body.

  • Gọi hàm userService.lockUserAccount(userId, reason).

  • Trả về status 200 OK cùng thông báo "User account locked successfully".

• Test: (Chưa cần test ngay, đợi nối Route).

[ ] Task 3.3: Khai báo Route và gắn Middleware

• File: src/routes/admin.routes.ts

• Action: Đăng ký endpoint.

• Logic:

  • Thêm route: PATCH /api/v1/admins/users/:userId/lock

  • Gắn middleware requireAuth và requireRole('ADMIN').

  • Gắn middleware validate body bằng LockUserDto.

  • Trỏ đến adminController.lockUser.

• Test: Khởi động server bằng npm run dev. Đảm bảo không có lỗi crash (Tác vụ 2 phút kiểm tra binding).

Giai đoạn 4: End-to-End Verification

[ ] Task 4.1: Kiểm thử tích hợp qua cURL/Postman

• Action: Gửi request thực tế để xác nhận luồng đi từ Route -> Controller -> Service -> Database.

• Logic:

  • Lấy một userId có sẵn trong DB (ví dụ: 12345).

  • Lấy một Admin Token hợp lệ.

• Test: Chạy lệnh bash sau trên terminal:

  Bash

  curl -X PATCH http://localhost:3000/api/v1/admins/users/12345/lock \
    -H "Authorization: Bearer <ADMIN_TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{"reason": "Phát hiện hành vi spam"}'
  
  

  Xác nhận HTTP Response là 200 OK. Mở database check lại field status của user 12345 đã chuyển thành LOCKED hay chưa.

Cách Vận Hành Cùng AI Workflow

Việc sở hữu một Writing Plan chi tiết như trên thay đổi hoàn toàn cách bạn làm việc với AI:

1. Dùng Cursor Composer / Claude Code CLI: Thay vì nói "Hãy làm cho tôi tính năng khóa user", bạn copy toàn bộ Writing Plan này vào prompt và ra lệnh: "Hãy thực thi chính xác theo thứ tự từng task trong Writing Plan này. Xong task nào, hãy báo cáo lại, hiển thị command test để tôi tự chạy thử, sau đó mới đợi lệnh của tôi để làm task tiếp theo."

2. Khoanh vùng rủi ro (Risk Isolation): Nếu có lỗi xảy ra ở Task 2.1 (Service), bạn biết chính xác mình chỉ cần fix ở logic hàm đó, hệ thống routing chưa hề bị động vào. Việc rollback cực kỳ an toàn.

3. Chống "Ảo giác" (Hallucination): AI rất dễ bịa ra tên file hoặc tự ý cài thêm thư viện rác. Việc bạn cung cấp sẵn đường dẫn file (src/services/user.service.ts) và input/output cụ thể đóng vai trò như một bộ cùm khóa chặt tư duy của AI vào kiến trúc hệ thống bạn mong muốn.