grill-with-docs

Tổng quan về kỹ năng grill-with-docs

grill-with-docs là một kỹ năng lập kế hoạch và tài liệu dành cho các nhóm muốn “stress-test” một thiết kế dựa trên ngôn ngữ và các quyết định đã có sẵn trong repo. Kỹ năng này phù hợp nhất cho Technical Writing, engineering theo tư duy sản phẩm, và công việc kiến trúc có hỗ trợ AI, nơi thuật ngữ phải bám sát CONTEXT.md và các ADR thay vì trôi dạt sang kiểu diễn đạt mơ hồ chỉ “prompt-only”.

Nhiệm vụ chính rất đơn giản: phỏng vấn người dùng từng câu một, đề xuất câu trả lời, và dùng codebase hoặc tài liệu khi một câu hỏi có thể được giải quyết từ nguồn. Nhờ vậy, kỹ năng grill-with-docs hữu ích hơn nhiều so với một prompt brainstorm chung chung khi rủi ro thực sự nằm ở lệch thuật ngữ, giả định không được ghi lại, hoặc các quyết định đã cũ.

Điều gì làm grill-with-docs khác biệt

Kỹ năng này được xây quanh mức độ hiểu miền nghiệp vụ, không chỉ xoay quanh hội thoại. Nó nhắc bạn kiểm tra các file ngữ cảnh hiện có, đọc qua ADR, và cập nhật tài liệu khi quyết định dần sáng tỏ, vì thế nó đặc biệt hợp với grill-with-docs for Technical Writing và các workflow nhiều tài liệu khác.

Trường hợp phù hợp nhất

Hãy dùng grill-with-docs khi bạn cần:

• kiểm tra một kế hoạch so với mô hình miền nghiệp vụ sẵn có,
• chọn thuật ngữ chính xác cho dự án,
• ghi lại quyết định ngay khi chúng được đưa ra,
• hoặc giữ bản nháp bám sát tài liệu đã có trước khi bắt đầu triển khai.

Khi nào không phù hợp

Nếu bạn chỉ muốn một bản tóm tắt nhanh, một spec đã được trau chuốt, hoặc brainstorming tự do mà không cần bám repo, kỹ năng này sẽ có cảm giác chậm hơn một prompt thông thường. Giá trị của nó đến từ việc đặt câu hỏi có kỷ luật và kiểm tra dựa trên tài liệu.

Cách sử dụng kỹ năng grill-with-docs

Cài đặt grill-with-docs

Cài kỹ năng grill-with-docs vào thư mục skills bằng skill manager tiêu chuẩn của repo, rồi mở các file của skill trong ngữ cảnh project mục tiêu. Mẫu cài đặt cơ bản là:

npx skills add mattpocock/skills --skill grill-with-docs

Hãy xem đó là điểm khởi đầu của grill-with-docs install, sau đó xác nhận kỹ năng đã khả dụng trong đúng môi trường agent mà bạn thực sự dùng.

Bắt đầu bằng đầu vào đúng

Kỹ năng này hoạt động tốt nhất khi tin nhắn đầu tiên của bạn chứa:

• mục tiêu bạn đang lập kế hoạch,
• tên hệ thống hoặc tính năng,
• bất kỳ thuật ngữ quan trọng nào đã biết,
• và ranh giới quyết định bạn muốn làm rõ.

Một prompt yếu sẽ là: “Giúp tôi thiết kế tính năng này.”
Một prompt mạnh hơn sẽ là: “Dùng grill-with-docs để grill bản kế hoạch tính năng này theo domain billing hiện tại. Tôi cần thuật ngữ đúng cho ‘subscription period’, data shape, và mọi quyết định đáng đưa vào ADR trước khi tôi viết tài liệu.”

Đọc các file này trước

Với grill-with-docs usage, hãy bắt đầu từ:

• SKILL.md để hiểu hành vi phỏng vấn và workflow,
• CONTEXT.md hoặc CONTEXT-MAP.md cho mô hình miền nghiệp vụ đang hoạt động,
• docs/adr/ cho các quyết định trước đó,
• ADR-FORMAT.md và CONTEXT-FORMAT.md nếu bạn cần tạo hoặc cập nhật file.

Những file này cho bạn biết điều gì có thể suy ra từ repo và điều gì cần được ghi rõ bằng văn bản.

Workflow giúp đầu ra tốt hơn

Hãy dùng kỹ năng này theo một vòng lặp:

1. đưa ra một kế hoạch cụ thể hoặc bản nháp sơ bộ,
2. để skill hỏi từng câu một,
3. trả lời bằng chi tiết cụ thể nhất có thể, bám repo,
4. cho phép khám phá codebase khi câu hỏi có thể được giải bằng file,
5. ghi lại thuật ngữ và các quyết định cứng trong context hoặc ghi chú ADR.

Mẹo thực tế quan trọng nhất: tách “cần đặt tên” ra khỏi “cần ra quyết định”. Như vậy phần grill sẽ tập trung hơn và tránh tạo ADR không cần thiết.

Câu hỏi thường gặp về kỹ năng grill-with-docs

grill-with-docs chỉ dành cho đội tài liệu thôi sao?

Không. Nó hữu ích bất cứ khi nào một kế hoạch phải khớp với từ vựng miền nghiệp vụ hiện có, đặc biệt trong product engineering, platform work, hoặc các workflow grill-with-docs for Technical Writing nơi cách diễn đạt và cấu trúc ảnh hưởng trực tiếp đến độ rõ ràng về sau.

Kỹ năng này khác gì một prompt bình thường?

Một prompt bình thường có thể sinh ý tưởng, nhưng grill-with-docs được thiết kế để chất vấn giả định, kiểm tra repository, và siết chặt thuật ngữ theo ngữ cảnh sẵn có. Nhờ vậy, nguy cơ trùng tên, xung đột thuật ngữ, và tài liệu mâu thuẫn với codebase sẽ giảm đi.

Có cần hệ thống tài liệu trưởng thành mới dùng được không?

Không, nhưng nó phát huy tốt nhất khi CONTEXT.md và các ADR đã tồn tại. Nếu chưa có, kỹ năng này vẫn có thể giúp bạn tạo chúng dần dần khi quyết định xuất hiện.

Khi nào nên tránh dùng nó?

Nên tránh khi nhiệm vụ chỉ mang tính khám phá, repository không có ngữ cảnh miền nghiệp vụ đủ ý nghĩa, hoặc bạn cần một câu trả lời nhanh trong một lần thay vì một cuộc phỏng vấn có cấu trúc.

Cách cải thiện kỹ năng grill-with-docs

Cung cấp đầu vào quyết định tốt hơn

Cải thiện chất lượng lớn nhất đến từ việc đưa cho skill một prompt hẹp, có hình dạng của một quyết định. Hãy nêu tên tính năng, phần hệ thống mà nó chạm tới, và đúng điểm mơ hồ bạn muốn làm rõ. Ví dụ: “Trong ngữ cảnh accounting, chúng ta nên gọi đây là invoice, billing record, hay charge, và quyết định đó nên nằm ở đâu?”

Đưa bằng chứng từ repo sớm

Nếu bạn đã biết file liên quan, hãy nhắc ngay từ đầu. Chỉ thẳng CONTEXT.md, một ADR cụ thể, hoặc một thư mục như src/billing/ sẽ giúp skill hỏi ít câu chung chung hơn và đưa ra câu hỏi hữu ích hơn. Điều này đặc biệt quan trọng với grill-with-docs usage vì skill mạnh nhất khi nó có thể đối chiếu kế hoạch của bạn với thuật ngữ và cấu trúc hiện có.

Theo dõi các kiểu lỗi thường gặp

Kiểu lỗi chính là mô tả miền nghiệp vụ quá lỏng, khiến cuộc phỏng vấn bị trôi sang mức trừu tượng. Một lỗi khác là yêu cầu triển khai trước khi mô hình ngôn ngữ đã có đủ thuật ngữ đúng. Nếu đầu ra đầu tiên quá rộng, hãy diễn đạt lại quyết định theo hướng hẹp hơn và yêu cầu skill tiếp tục từ nhánh đã được làm rõ gần nhất.

Lặp lại từ lượt đầu tiên

Sau vòng đầu, hãy chuyển câu trả lời thành một trong ba đầu ra: một mục glossary đã làm sạch, một ADR ngắn, hoặc một bản brief triển khai đã chỉnh lại. Sau đó chạy lại grill-with-docs cho các câu hỏi còn mở. Lượt thứ hai thường là lúc skill mang lại giá trị lớn nhất, vì thuật ngữ và ranh giới lúc này đã rõ hơn.