Codebase Prompt Enhancer: Cách Viết Prompt Code Bám Sát Codebase Hơn

Khi làm việc với AI coding agent, tôi gặp một chuyện khá quen thuộc: prompt ban đầu của người dùng nhiều khi không sai, nhưng lại hơi ngắn hoặc hơi chung. Vì vậy agent dễ hiểu lệch ý, đọc sang phần code không liên quan, hoặc đưa ra một hướng xử lý nghe hợp lý nhưng lại không khớp với repository thật.

Tôi tạo codebase-prompt-enhancer từ đúng nhu cầu đó. Ý tưởng của skill này khá đơn giản: đừng vội viết lại prompt ngay, hãy đọc codebase liên quan trước, hiểu bối cảnh thật của repo, rồi mới rewrite prompt theo cách cụ thể hơn và dễ thực thi hơn.

Vì sao tôi làm skill này?

Ban đầu tôi chỉ thấy mình phải làm đi làm lại một việc: mỗi lần người dùng đưa ra một prompt code ngắn, tôi lại phải tự đọc repo, tìm file liên quan, xác định pattern đang dùng, rồi mới biết prompt nên được viết lại như thế nào để một agent khác có thể làm tốt.

Tôi nhận ra đây không chỉ là thói quen cá nhân, mà là một workflow khá hữu ích:

• đọc prompt gốc
• đọc codebase liên quan
• rút ra context thật
• viết lại prompt theo hướng execution-ready

Thay vì lặp lại quy trình đó bằng tay, tôi gom nó thành một skill riêng.

Codebase Prompt Enhancer là gì?

Đây là một skill có nhiệm vụ khá rõ ràng:

1. đọc prompt gốc của người dùng
2. xác định goal, scope, constraints và expected output
3. inspect đúng vùng code liên quan trong repository
4. rút ra file path, function, module, pattern hoặc dependency quan trọng
5. viết lại prompt sao cho prompt mới bám sát codebase hơn

Điểm tôi cố tình giữ là skill này không đổi objective của người dùng. Nếu người dùng muốn sửa blog responsive hơn, thì prompt rewrite vẫn phải xoay quanh việc đó, chứ không tự mở rộng sang refactor cả hệ thống.

Vấn đề mà skill này giải quyết

Theo trải nghiệm của tôi, khi prompt code quá mơ hồ, AI agent thường dễ mắc những lỗi như:

• sửa đúng ý tưởng nhưng sai file
• hiểu scope rộng hơn yêu cầu thật
• đổi luôn pattern hiện có dù chưa cần
• bỏ sót dependency hoặc contract sẵn có trong repo
• trả lời kiểu chung chung, khó dùng tiếp ngay

Nhìn bề ngoài, nhiều người nghĩ đây là lỗi của model. Nhưng khá nhiều trường hợp, vấn đề thực sự chỉ là prompt chưa bám đủ sát codebase.

Ý tưởng cốt lõi của skill

Tôi khá thích một nguyên tắc rất đơn giản:

Prompt tốt hơn không có nghĩa là prompt dài hơn.
Prompt tốt hơn thường là prompt bám sát repository hơn.

Trong SKILL.md, tôi giữ workflow theo hướng khá thực dụng:

• chỉ inspect vùng code liên quan
• ưu tiên path, symbol, module và contract thật trong repo
• không thêm requirement mới nếu codebase không gợi ra điều đó
• nếu phải giả định thì chọn giả định hẹp nhất

Output cuối cùng cũng chỉ giữ 3 phần:

• Intent Summary
• Codebase Context
• Improved Prompt

Mục đích là để prompt viết lại có thể dùng ngay, thay vì biến thành một bài phân tích dài.

Vì sao prompt “mù codebase” dễ làm agent đi sai?

Ví dụ có một prompt kiểu:

Sửa giúp tôi phần blog cho responsive hơn.

Prompt này không sai. Nhưng nếu nhìn từ phía agent, vẫn còn rất nhiều khoảng trống:

• blog nằm ở route nào?
• list page hay detail page?
• đang dùng App Router hay Pages Router?
• data đến từ markdown hay API?
• có pattern nào cần giữ nguyên không?

Khi những phần này không được nói rõ, agent sẽ phải tự đoán. Và càng đoán nhiều thì càng dễ lệch ý.

Prompt sau khi được cải thiện sẽ khác thế nào?

Ví dụ cùng yêu cầu đó, prompt sau khi đi qua codebase-prompt-enhancer có thể trở thành:

Hãy chỉnh phần blog trong `src/app/components/blog/blog-list-page.tsx` và `src/app/components/blog/blog-post-page.tsx` để responsive tốt hơn trên mobile.
Giữ App Router hiện tại, không thay đổi route `/blog` và `/blog/[slug]`.
Ưu tiên giữ layout visual hiện có, chỉ sửa spacing, image sizing, overflow và typography nếu cần.
Sau khi sửa xong, chạy build để kiểm tra.

Mục tiêu vẫn là như cũ, nhưng prompt mới:

• cụ thể hơn
• ít chỗ cho agent tự suy diễn sai
• dễ review hơn
• dùng được ngay cho một agent khác

Đó là phần tôi thấy hữu ích nhất.

Workflow thực tế của Codebase Prompt Enhancer

1. Đọc prompt gốc

Bước đầu tiên là tách prompt thành:

• goal
• scope
• constraints
• expected output

Nghe có vẻ cơ bản, nhưng bước này giúp tránh chuyện rewrite prompt theo cảm tính.

2. Chỉ inspect phần code liên quan

Tôi không muốn skill này đi đọc toàn bộ repository nếu không cần. Nó chỉ nên tập trung vào:

• entry points
• route
• component chính
• utility liên quan
• config hoặc test nếu thật sự cần

Nếu đọc quá rộng, prompt rewrite rất dễ bị lan scope.

3. Suy ra context thật từ repo

Sau khi inspect, skill sẽ chọn ra những thứ nên xuất hiện trong prompt:

• exact file paths
• function hoặc class liên quan
• pattern cần giữ
• dependency gần đó
• risk có thể phát sinh

Phần này là nơi prompt trở nên “codebase-aware”.

4. Rewrite prompt theo dạng execution-ready

Prompt cuối cùng không nên chỉ “hay hơn”, mà phải dùng được ngay. Tức là:

• đủ rõ để agent khác bắt đầu làm
• không vòng vo
• không nặng lý thuyết
• vẫn giữ đúng intent ban đầu

Đó cũng là lý do output format của skill được giữ khá ngắn.

Khi nào tôi thấy skill này hữu ích nhất?

Theo tôi, codebase-prompt-enhancer hợp với những tình huống như:

• implement feature mới trong repo thật
• debug bug nhưng prompt gốc còn mơ hồ
• refactor có phạm vi cụ thể
• viết prompt review code
• phân tích codebase trước khi giao việc cho agent khác

Nó đặc biệt hữu ích khi repository đã đủ lớn để model dễ đọc sai hướng.

Khi nào không nhất thiết phải dùng?

Skill này không phải lúc nào cũng cần. Tôi ít dùng nó hơn nếu:

• câu hỏi hoàn toàn lý thuyết
• task rất nhỏ và file liên quan đã quá rõ
• người dùng chỉ cần giải thích khái niệm, không cần prompt rewrite

Nói ngắn gọn, skill này mạnh nhất ở task gắn với codebase thật.

Những nguyên tắc tôi cố tình giữ trong SKILL.md

Khi viết skill này, tôi muốn chặn vài thói quen khá phổ biến của AI:

Không đổi mục tiêu người dùng

Nhiều model có xu hướng “làm tốt hơn” bằng cách đổi luôn bài toán. Tôi không muốn điều đó xảy ra ở đây.

Không tự thêm requirement mới

Nếu codebase không cho thấy điều đó, skill không nên tự thêm chỉ vì nghe hợp lý.

Không mở rộng scope

Repo có thể có nhiều file liên quan, nhưng không phải file nào cũng nên bị kéo vào prompt mới.

Ưu tiên repository facts hơn generic advice

Tôi thấy một prompt có file path, module và constraint cụ thể thường hữu ích hơn nhiều so với kiểu “hãy làm theo best practices”.

Điều tôi thấy đáng giá nhất sau khi dùng skill

Điểm khác biệt lớn nhất không phải là prompt trông chuyên nghiệp hơn. Mà là:

• agent đi đúng hướng hơn
• ít phải sửa vì hiểu nhầm scope
• review dễ hơn
• người và agent phối hợp rõ ràng hơn

Nếu bạn từng mất vài vòng chỉ để sửa lại prompt ban đầu, có lẽ bạn sẽ thấy lợi ích này khá rõ.

Một checklist ngắn để tự kiểm tra prompt code

Trước khi đưa prompt cho AI coding agent, tôi thường tự hỏi:

• prompt đã chỉ ra đúng file hoặc route chưa?
• prompt có giữ nguyên objective ban đầu không?
• prompt có nói rõ constraint quan trọng chưa?
• prompt có vô tình mở rộng scope không?
• prompt đã đủ để một agent khác bắt đầu làm ngay chưa?

Nếu nhiều câu trả lời vẫn là “chưa”, đó là lúc codebase-prompt-enhancer có ích.

Kết luận

Với tôi, codebase-prompt-enhancer không phải là một skill để làm prompt nghe “xịn” hơn. Nó chỉ là một cách khá thực tế để đưa prompt từ trạng thái đúng ý nhưng mơ hồ sang trạng thái đúng ý và bám sát repository hơn.

Trong các workflow AI coding hiện nay, tôi nghĩ đó là một khác biệt đủ đáng để đầu tư.