Clarify and Prompt

Chuyển đổi yêu cầu thô thành bản giao việc hoàn chỉnh cho AI agent qua 5 khung tư duy có cấu trúc, tối đa 2 vòng phỏng vấn tinh gọn kèm phương án chọn nhanh.

Clarify and Prompt
Tóm tắt bằng:ChatGPTPerplexityGrokClaude

Clarify and Prompt: Biến Ý Tưởng Thô Thành Bản Giao Việc Chuẩn Cho Agent

Khi giao việc cho coding agent, thói quen đưa ra câu lệnh ngắn rồi mong agent tự hiểu hết mọi chi tiết thường dẫn đến kết quả tệ: agent tự bịa ra giả định ngầm, sửa lan sang các file không liên quan, hoặc sinh hàng trăm dòng code thừa rồi kẹt cứng. Ngược lại, nếu agent hỏi cả chục câu mở, bạn sẽ mất kiên nhẫn khi phải gõ giải trình dài dòng.

Tôi viết clarify-and-prompt (MIT, v1.1.0), nằm trong repo the-skills, để xử lý điểm nghẽn này. Skill làm rõ bài toán trước khi bắt đầu code: quét qua các khung tư duy có cấu trúc, giới hạn phỏng vấn từ 3 đến 5 câu kèm sẵn phương án chọn nhanh, rồi xuất ra một bản giao việc độc lập hoàn toàn.

Prompt đầu ra là chỉ lệnh đầu tiên và duy nhất cho agent nhận việc. Agent nhận prompt không cần đọc lại lịch sử chat, không bị phụ thuộc vào các đại từ mơ hồ, và thấy ngay các ràng buộc kỹ thuật từ đầu.


1. Bộ 5 Khung Tư Duy Và Bảng Điều Hướng

Khi nhận yêu cầu, skill không hỏi ngay. Nó đọc lướt mã nguồn hiện có (package.json, cấu hình môi trường, các file liên quan) để tránh hỏi lại những thứ đã có sẵn trong repo. Sau đó, skill chọn khung tư duy dựa trên điểm yếu trong câu lệnh của người dùng:

Dấu hiệu trong yêu cầu Khung tư duy áp dụng Mục tiêu giải quyết
Nhảy thẳng vào giải pháp khi chưa rõ bài toán gốc ("Viết cronjob copy dữ liệu") First Principles & 5 Whys Tìm nguyên nhân cốt lõi và bỏ giả định thừa
Tính năng có giá trị hoặc điều kiện kích hoạt mơ hồ ("Thêm nút xuất file") Jobs-to-be-Done (JTBD) Chốt công thức: Khi [ngữ cảnh] -> Tôi muốn [hành động] -> Để [kết quả]
Ngữ cảnh phức tạp, nhiều tầng lớp kỹ thuật đan xen SCQA + MECE Dựng khung Tình huống, Biến cố, Câu hỏi và chia nhỏ nhánh không trùng lặp
Dùng tính từ cảm tính ("làm cho nhanh, sạch, bảo mật, nhẹ") Lượng hóa Socratic Dịch tính từ thành con số đo được, SLA phản hồi hoặc ngưỡng tài nguyên
Nguy cơ agent ảo giác hoặc làm vỡ code cũ Nghịch đảo rủi ro Pre-mortem Đặt câu hỏi "Điều gì khiến kết quả này thất bại?" để chốt Non-Goals

Mỗi phiên phỏng vấn kết hợp các khung trên theo 4 vị trí:

  1. Vị trí 1: Mục tiêu gốc và sự kiện kích hoạt (First Principles / JTBD / SCQA).
  2. Vị trí 2: Phạm vi kỹ thuật và kiến trúc cốt lõi (nhánh MECE A).
  3. Vị trí 3: Xử lý trường hợp biên và lượng hóa SLA (Socratic / nhánh MECE B).
  4. Vị trí 4: Rào chắn an toàn và ranh giới ngoài phạm vi (Pre-mortem Inversion).

Mỗi câu hỏi bắt buộc đi kèm gợi ý (Khuyến nghị: Lựa chọn A - lý do). Người dùng chỉ cần gõ 1A, 2A, 3B là hoàn tất lượt trao đổi trong vài giây.


2. Quy Trình 4 Giai Đoạn

Quy trình từ ý tưởng thô đến bản giao việc gồm 4 bước:

Quy trình 4 giai đoạn của Clarify and Prompt
Quy trình 4 giai đoạn của Clarify and Prompt
  • Giai đoạn 1: Quét ngữ cảnh & điều hướng. Phân loại tác vụ (Coding, Kiến trúc, Nghiên cứu hay Soạn thảo). Đọc nhanh workspace để nắm stack công nghệ rồi chọn 1 đến 2 khung tư duy phù hợp cùng 2 bước kiểm tra bắt buộc (Socratic và Pre-mortem).
  • Giai đoạn 2: Phỏng vấn tinh gọn. Đặt 3 đến 5 câu hỏi trọng tâm trong 1 lượt duy nhất. Chỉ mở lượt thứ hai nếu còn vướng mắc kỹ thuật quan trọng. Nếu người dùng bỏ qua câu hỏi nào, lựa chọn khuyến nghị sẽ tự động thành giả định mặc định.
  • Giai đoạn 3: Tóm tắt thống nhất. Trình bày tóm tắt SCQA, mục tiêu JTBD, các quyết định kỹ thuật đã chốt và danh sách Non-Goals để người dùng duyệt nhanh.
  • Giai đoạn 4: Sinh prompt độc lập. Chọn mẫu prompt theo domain và xuất khối mã Markdown hoàn chỉnh. Prompt mở đầu trực tiếp bằng Objective, bỏ qua các câu gán vai diễn như "Bạn là kỹ sư cấp cao", không tham chiếu lịch sử trao đổi, sẵn sàng đưa cho agent thực thi.

3. Rào Chắn Thiết Kế & Minh Họa Thực Tế

Hai nguyên tắc thiết kế quan trọng của clarify-and-prompt:

  • Không bàn giao tiếp nối (No handoff): Agent nhận việc chạy trên một phiên độc lập. Viết theo kiểu "tiếp tục thảo luận trước đó" khiến agent mất thời gian tìm kiếm ngữ cảnh không có thật hoặc bỏ qua bước kiểm tra môi trường.
  • Mục tiêu thay vì vai diễn (Objective over persona): Những câu như "You are a world-class engineer" không giúp ích cho LLM khi viết code. Một mục tiêu cụ thể kèm tiêu chí nghiệm thu rõ ràng mang lại kết quả tốt hơn nhiều.

Dưới đây là phiên làm việc thực tế khi làm rõ yêu cầu webhook thông báo trạng thái đơn hàng.

Lượt 1: Yêu cầu ban đầu từ người dùng

User: Tôi muốn thêm tính năng gửi webhook thông báo cho hệ thống đơn hàng hiện tại để báo cho đối tác mỗi khi trạng thái đơn thay đổi. Hãy giúp tôi làm rõ yêu cầu và viết một prompt chi tiết cho coding agent.

Lượt 2: Agent áp dụng khung tư duy và đặt câu hỏi

Agent quét repo, nhận diện stack FastAPI và đưa ra 4 câu hỏi định hướng:

Agent: Để tạo ra một prompt hoàn chỉnh, không mơ hồ cho coding agent, bạn vui lòng xác nhận 4 quyết định kỹ thuật sau (có thể trả lời nhanh dạng 1A, 2A, 3B...):

  1. [JTBD & SLA Socratic] Cơ chế gửi và chính sách thử lại (Retry):
    • A (Khuyến nghị - tránh nghẽn API đơn hàng): Đẩy việc gửi webhook vào hàng đợi ngầm với cơ chế thử lại lũy thừa (tối đa 5 lần) khi gặp lỗi mạng, HTTP 5xx hoặc 429.
    • B: Gửi HTTP đồng bộ ngay trong luồng cập nhật đơn hàng.
  2. [MECE - Bảo mật] Ký xác thực gói tin (Payload Signing):
    • A (Khuyến nghị chuẩn): Ký payload bằng HMAC-SHA256 trong header X-Webhook-Signature kèm X-Webhook-Timestamp để chống tấn công phát lại (replay attack).
    • B: Sử dụng chuỗi Bearer token tĩnh trong header.
  3. [First Principles - Phạm vi] Cấu hình điểm cuối và nhật ký gửi:
    • A (Cho nhiều đối tác): Lưu danh sách URL trong bảng DB webhook_endpoints và ghi nhận lịch sử gửi trong webhook_deliveries.
    • B (Cho 1 đối tác hiện tại): Cấu hình URL và Secret qua biến môi trường (.env), chỉ tạo bảng DB webhook_deliveries để lưu vết đối soát.
  4. [Pre-mortem - Stack & Non-Goals] Công nghệ nền tảng và giới hạn:
    • Stack worker chạy ngầm hiện tại là gì (FastAPI + arq/Redis hay Celery), và có module nào agent tuyệt đối KHÔNG được chạm vào?

Lượt 3: Người dùng phản hồi gọn gàng

User: 1A, 2A, và 3B vì hiện tại chỉ có một đối tác, nhưng cần giữ bảng webhook_deliveries để lưu vết đối soát. Stack hiện tại là FastAPI + SQLAlchemy 2.0 async + PostgreSQL, dùng arq và Redis làm hàng đợi ngầm. Tuyệt đối không chạm vào module thanh toán (services/payment).

Lượt 4: Agent tổng hợp và xuất bản đặc tả chuẩn

Agent tổng hợp thông tin và xuất bản đặc tả nhiệm vụ hoàn chỉnh:

# Objective (JTBD)
Trong codebase FastAPI + Async SQLAlchemy 2.0 + PostgreSQL + arq này, khi trạng thái của một Order thay đổi, hãy gửi webhook bất đồng bộ có chữ ký số qua arq và lưu trạng thái vào PostgreSQL để đối tác nhận được thông báo tin cậy mà không làm tăng độ trễ của API cập nhật đơn hàng.

# Context & Problem Framing (SCQA)
- Tình huống: Ứng dụng chạy trên FastAPI, SQLAlchemy 2.0 Async, PostgreSQL và worker chạy ngầm arq (Redis).
- Biến cố: Hệ thống đối tác cần nhận thông báo trạng thái đơn hàng thời gian thực kèm chữ ký số và khả năng thử lại lũy thừa khi gặp sự cố mạng, đồng thời hệ thống cần lưu vết đối soát cho từng lần thử gửi.
- Phạm vi kiến trúc: Do hiện tại chỉ tích hợp với một đối tác duy nhất, tải WEBHOOK_TARGET_URL và WEBHOOK_SECRET từ cấu hình môi trường (.env qua Pydantic BaseSettings), không tạo bảng quản lý danh sách endpoint.

# Requirements & Quantified Constraints (MECE + Socratic)

## 1. Schema Cơ Sở Dữ Liệu (webhook_deliveries)
Tạo model Async SQLAlchemy và migration Alembic cho bảng webhook_deliveries:
- id: UUID (Khóa chính)
- event_id: UUID (Khóa chống trùng lặp idempotency cho sự kiện)
- order_id: Khóa ngoại liên kết tới bảng orders
- event_type: Chuỗi (ví dụ: order.status_changed)
- payload: JSONB (Toàn bộ dữ liệu JSON đã gửi)
- status: Enum (PENDING, SUCCESS, FAILED)
- attempt_count: Integer (mặc định 0)
- last_response_code: Integer, nullable
- last_error: Text, nullable
- next_retry_at: Timestamp có múi giờ, nullable
- created_at, updated_at: Timestamp có múi giờ

## 2. Chuẩn Bảo Mật Gói Tin (HMAC-SHA256)
- Headers HTTP bắt buộc:
  - Content-Type: application/json
  - X-Webhook-Id: <event_id>
  - X-Webhook-Timestamp: <unix_epoch_seconds>
  - X-Webhook-Signature: sha256=<hex_digest> tạo từ HMAC-SHA256(secret, f"{timestamp}.{raw_json_body}")

## 3. Quy Trình Thực Thi & SLA Thử Lại (arq Worker)
- Khi transaction cập nhật đơn hàng commit thành công vào PostgreSQL:
  1. Thêm một bản ghi webhook_deliveries với status = PENDING.
  2. Đẩy task deliver_order_webhook(delivery_id) vào hàng đợi ngầm arq.
- Trong task worker:
  - Gửi HTTP POST bằng httpx.AsyncClient(timeout=10.0) tới WEBHOOK_TARGET_URL.
  - Khi HTTP 2xx: Cập nhật status = SUCCESS, tăng attempt_count, xóa next_retry_at.
  - Khi lỗi mạng, timeout, HTTP 5xx hoặc 429:
    - Nếu attempt_count < 5: Lên lịch thử lại lũy thừa (15s, 60s, 300s, 900s) và cập nhật next_retry_at.
    - Nếu attempt_count >= 5: Đánh dấu status = FAILED và dừng thử lại.
  - Khi HTTP 4xx (ngoại trừ 429): Đánh dấu status = FAILED ngay lập tức, không thử lại.

# Rào Chắn Pre-mortem & Non-Goals
- Nghiêm cấm tạo bảng hoặc API quản lý nhiều đối tác webhook_endpoints.
- Tuyệt đối không chỉnh sửa hoặc refactor code bên trong thư mục services/payment.
- Không gửi HTTP đồng bộ bên trong request cycle của API đơn hàng.
- Không log lộ WEBHOOK_SECRET ra console hoặc lưu vào database.
- Sử dụng đúng chuỗi byte UTF-8 thực tế gửi qua mạng khi tính chữ ký HMAC để tránh lệch hash do thứ tự key JSON.

# Tiêu Chí Nghiệm Thu (Acceptance Criteria)
- [ ] X-Webhook-Signature khớp chuẩn HMAC-SHA256(secret, "{timestamp}.{raw_body}").
- [ ] Phản hồi 200 OK chuyển trạng thái sang SUCCESS với attempt_count bằng 1.
- [ ] Lỗi 500 hoặc timeout được thử lại tối đa 5 lần trước khi chuyển sang FAILED.
- [ ] Lỗi 400 chuyển ngay sang FAILED mà không kích hoạt thử lại.
- [ ] Toàn bộ test suite pytest mới và cũ đều pass, không phát sinh lỗi hồi quy.

4. Cài Đặt & Sử Dụng

Cách 1: Cài Đặt Vào Thư Mục Skill Cục Bộ

Clone repository và sao chép skill vào thư mục môi trường agent:

# Clone kho lưu trữ the-skills
git clone https://github.com/pxuanbach/the-skills.git

# Sao chép clarify-and-prompt vào thư mục agent skills
cp -r the-skills/skills/clarify-and-prompt ~/.gemini/skills/
# hoặc cho Claude Code:
# cp -r the-skills/skills/clarify-and-prompt ~/.claude/skills/

Cách 2: Kích Hoạt Trực Tiếp Trong Runtime Agent

Khi đã cài đặt skill vào runtime (như Antigravity CLI, Claude Code hay Cursor Agent), bạn chỉ cần kích hoạt bằng lệnh:

/clarify-and-prompt Tôi muốn xây dựng tính năng xác thực hai yếu tố (2FA) bằng mã TOTP cho hệ thống người dùng hiện tại.

Hoặc nhắc trực tiếp trong câu lệnh thông thường:

Hãy áp dụng skill clarify-and-prompt để làm rõ yêu cầu sau và sinh prompt cho coding agent: "Tích hợp Stripe webhook vào ứng dụng Next.js".

Sau khi hoàn tất trao đổi, agent xuất prompt hoàn chỉnh trong một khối code block để copy trực tiếp, hoặc lưu vào file .temp/task-prompt.md.

Tôi đã và đang dùng skill này cho các tác vụ hàng ngày. Thú thật mà nói, tôi nghĩ skill này vẫn còn nhiều điều chưa hoàn thiện. Còn nhiều không gian để cập nhật hơn nên có thể trong tương lai tôi sẽ cập nhật lại nội dung kit này, haha.

|Chia sẻ:

Liên kết