Cách viết spec tốt cho AI agent

 (addyosmani.com)
110 điểm bởi GN⁺ 2026-01-19 | 2 bình luận | Chia sẻ qua WhatsApp
  • Nếu ném cho AI coding agent một bản spec đồ sộ cùng lúc, nó sẽ không hoạt động hiệu quả; điểm cốt lõi nằm ở việc viết smart spec
  • Khuyến nghị cách làm: trước tiên đưa ra tầm nhìn ở mức cao, để AI mở rộng thành kế hoạch chi tiết, sau đó dùng Plan Mode ở trạng thái chỉ đọc để rà soát kế hoạch rồi mới chuyển sang giai đoạn viết mã
  • Kết quả phân tích hơn 2.500 tệp cấu hình agent trên GitHub cho thấy spec hiệu quả nên bao gồm 6 lĩnh vực cốt lõi: Commands, Testing, Project Structure, Code Style, Git Workflow, Boundaries
  • Với công việc quy mô lớn, nên chia thành các tác vụ nhỏ được mô-đun hóa thay vì một prompt khổng lồ duy nhất, và chỉ cung cấp đúng ngữ cảnh cần thiết cho từng tác vụ để tránh suy giảm chất lượng
  • Cốt lõi của quy trình phát triển dựa trên spec là nhúng vào spec ranh giới 3 cấp (Always/Ask first/Never), tự kiểm chứng, kiểm tra mức độ phù hợp, rồi liên tục kiểm thử, lặp lại và tiến hóa

TL;DR

  • Hãy viết một bản đặc tả rõ ràng có chứa mức độ chi tiết phù hợp (cấu trúc, phong cách, kiểm thử, ranh giới, v.v.)
  • Với công việc lớn, khuyến nghị phân rã thành các đơn vị nhỏ thay vì dùng một prompt nguyên khối
  • Kế hoạch nên được lập trước ở chế độ chỉ đọc, sau đó thực thi và liên tục cải thiện

Nguyên tắc cốt lõi: viết smart spec

  • Cách làm chỉ đơn giản ném một bản spec khổng lồ vào AI agent sẽ thất bại, vì sẽ vấp phải giới hạn cửa sổ ngữ cảnh và ngân sách chú ý (attention budget) của mô hình
  • “Smart spec” là tài liệu vừa hướng dẫn agent một cách rõ ràng, vừa nằm trong kích thước ngữ cảnh thực tế, đồng thời tiến hóa cùng dự án
  • Bài viết hệ thống hóa thành một framework các nguyên tắc rút ra từ trải nghiệm dùng các coding agent như Claude Code và Gemini CLI

Nguyên tắc 1: đưa ra bức tranh lớn trước, rồi để AI phác thảo chi tiết

  • Thay vì cố thiết kế mọi thứ quá mức ngay từ đầu, hãy bắt đầu bằng cách xác định thật rõ tuyên bố mục tiêu và một vài yêu cầu cốt lõi
  • Cách làm này xem spec ban đầu như một “product brief”, rồi để agent dựa trên đó mở rộng thành spec chi tiết
  • Các agent dựa trên LLM thường điền chi tiết rất tốt khi chỉ dẫn cấp cao đủ rõ ràng, nhưng nếu nhiệm vụ mơ hồ thì rất dễ đi chệch hướng
  • Vì vậy, điều quan trọng là phải đóng đinh một sứ mệnh rõ ràng ngay từ đầu để agent không bị lạc hướng

  • Tận dụng Plan Mode

    • Plan Mode của Claude Code là chế độ khóa agent ở trạng thái chỉ đọc, chỉ cho phép phân tích codebase và lập kế hoạch chi tiết
    • Sau khi vào Plan Mode bằng Shift+Tab và mô tả “bạn muốn tạo ra điều gì”, agent sẽ rà soát mã hiện có và viết bản nháp spec
    • Lúc này có thể yêu cầu nó cùng kiểm tra cả kiến trúc, best practice, rủi ro bảo mật và chiến lược kiểm thử của kế hoạch
    • Hãy giữ Plan Mode cho đến khi kế hoạch được tinh chỉnh không còn chỗ cho hiểu nhầm, rồi mới thoát Plan Mode và bước sang giai đoạn thực thi

  • Dùng spec làm ngữ cảnh

    • Spec đã chốt nên được lưu vào một tệp như SPEC.md, và khi làm việc chỉ chọn các phần cần thiết để đưa lại cho agent
    • Vì tệp spec vẫn tồn tại giữa các phiên, nó giúp neo AI vào cùng một điểm chuẩn ngay cả khi khởi động lại dự án
    • Điều này hữu ích để giảm tình trạng quên xảy ra khi lịch sử hội thoại quá dài hoặc khi khởi động lại agent
    • Giống như cách nhóm dùng PRD (tài liệu yêu cầu sản phẩm) làm chuẩn tham chiếu chung, nó trở thành “tài liệu chuẩn duy nhất” mà cả con người lẫn AI đều cùng tham chiếu

  • Duy trì tính định hướng mục tiêu

    • Spec ở mức cao nên tập trung vào what/why thay vì ghi hết cách triển khai ngay từ đầu; phần how cụ thể nên để lại phía sau
    • Có thể cấu trúc như user story và tiêu chí chấp nhận: “Người dùng là ai? / Họ cần gì? / Thành công trông như thế nào?”
    • GitHub Spec Kit cũng nhấn mạnh luồng làm việc “đưa ra mô tả cấp cao về việc tạo cái gì và vì sao, rồi để coding agent tạo đặc tả chi tiết xoay quanh trải nghiệm người dùng và tiêu chí thành công”

Nguyên tắc 2: Cấu trúc spec như một PRD (hoặc SRS) chuyên nghiệp

  • Điều quan trọng là phải xem spec cho AI không phải như một tập hợp ghi chú rời rạc, mà là một tài liệu có cấu trúc với các phần rõ ràng
  • Một dạng tài liệu toàn diện và ngăn nắp như PRD hay tài liệu thiết kế hệ thống đặc biệt phù hợp với AI diễn giải nội dung theo nghĩa đen
  • Theo phân tích hơn 2.500 tệp cấu hình agent trên GitHub, các spec hiệu quả thường cùng có 6 lĩnh vực cốt lõi

    • 1. Commands

      • Đặt các lệnh có thể thực thi ở phần đầu tài liệu
      • Không chỉ ghi tên công cụ, mà phải nêu đầy đủ lệnh kèm cả flag: npm test, pytest -v, npm run build

    • 2. Testing

      • Nêu cụ thể cách chạy kiểm thử, framework sử dụng, vị trí tệp kiểm thử và mức độ coverage mong đợi

    • 3. Project Structure

      • Phân tách rõ ràng vị trí của mã nguồn, kiểm thử và tài liệu
      • Ví dụ: "src/ là mã ứng dụng, tests/ là kiểm thử đơn vị, docs/ dành cho tài liệu"

    • 4. Code Style

      • Một đoạn code snippet thực tế hiệu quả hơn nhiều so với việc mô tả dài dòng về style
      • Đồng thời đưa ra quy tắc đặt tên, tiêu chuẩn định dạng và ví dụ đầu ra mong muốn

    • 5. Git Workflow

      • Nếu nêu rõ quy tắc đặt tên nhánh, định dạng commit message và yêu cầu PR, agent cũng sẽ làm theo luồng đó

    • 6. Boundaries

      • Chỉ rõ những khu vực agent tuyệt đối không được đụng vào
      • Chẳng hạn secret, thư mục vendor, cấu hình production, các thư mục cụ thể
      • Nghiên cứu của GitHub cho thấy “tuyệt đối không commit secret” là ràng buộc hữu ích xuất hiện thường xuyên nhất

  • Mô tả cụ thể về stack

    • Không nên nói chung chung như “dự án React”, mà cần viết cụ thể như “React 18 + TypeScript + Vite + Tailwind CSS”
    • Cần ghi kèm phiên bản và các dependency chính; spec mơ hồ cuối cùng sẽ tạo ra code mơ hồ

  • Sử dụng định dạng nhất quán

  • Tích hợp spec vào toolchain

    • Hãy xem spec không chỉ là tài liệu đơn thuần, mà là “một artifact có thể thực thi” được gắn với quản lý phiên bản và CI/CD
    • GitHub Spec Kit sử dụng quy trình workflow 4 cổng đặt spec ở trung tâm của quy trình kỹ thuật
      • Specify: Cung cấp mô tả cấp cao về việc xây gì và vì sao, sau đó coding agent tạo ra đặc tả chi tiết
      • Plan: Lập kế hoạch kỹ thuật bao gồm stack mong muốn, kiến trúc và các ràng buộc
      • Tasks: Chia spec và kế hoạch thành các đơn vị công việc thực tế, rồi tiếp tục tách nhỏ từng phần đến mức có thể kiểm thử
      • Implement: Coding agent xử lý từng task một hoặc song song

  • Persona chuyên biệt thông qua agents.md

    • Trong các công cụ như GitHub Copilot, có thể định nghĩa persona agent chuyên biệt
    • Có thể tách vai trò như @docs-agent(tài liệu kỹ thuật), @test-agent(QA), @security-agent(code review)
    • Mỗi tệp agents.md đóng vai trò là một spec tập trung, chứa cách hành xử, lệnh và ranh giới của persona đó

  • Thiết kế Agent Experience (AX)

    • Cũng như API được thiết kế theo developer experience (DX), spec cũng cần được thiết kế có tính đến agent experience (AX)
    • Định dạng gọn gàng, dễ parse là rất quan trọng
      • OpenAPI schema của API mà agent sẽ sử dụng
      • Tóm tắt tài liệu cho LLM tiêu thụ (llms.txt)
      • Định nghĩa kiểu dữ liệu tường minh
    • Spec càng tuân theo các chuẩn như MCP(Model Context Protocol), agent càng hiểu và vận hành ổn định hơn

  • Duy trì như một tài liệu sống

    • Spec không phải là tài liệu viết một lần rồi xong, mà phải tiếp tục được cập nhật mỗi khi ra quyết định cùng AI hoặc khi xuất hiện sự thật mới
    • Trong workflow dựa trên spec, spec dẫn dắt việc triển khai, kiểm thử và phân rã task; trước khi spec được xác thực thì không chuyển sang bước tiếp theo
    • Spec này không chỉ dành cho AI mà còn là công cụ cốt lõi để nhà phát triển giám sát toàn bộ luồng và xác nhận đầu ra của AI có thực sự đáp ứng yêu cầu hay không

Nguyên tắc 3: Chia nhỏ tác vụ thành các prompt và context theo mô-đun

  • Thay vì nhồi mọi thứ vào một prompt khổng lồ, hãy cung cấp context để chỉ tập trung vào một tác vụ tại một thời điểm
  • Nếu dồn toàn bộ yêu cầu, mã nguồn và chỉ dẫn của cả dự án vào một prompt duy nhất, rất dễ làm tăng thêm sự rối rắm
  • Không chỉ có nguy cơ chạm giới hạn token, mà “lời nguyền của chỉ dẫn (curse of instructions)” còn có thể khiến khả năng tập trung của mô hình suy giảm mạnh

  • Lời nguyền của chỉ dẫn

    • Theo kết quả nghiên cứu, càng chồng nhiều chỉ dẫn hoặc dữ liệu vào prompt thì hiệu năng tuân thủ chính xác từng chỉ dẫn càng giảm đi rõ rệt
    • Ngay cả các mô hình mạnh như GPT-4 hay Claude cũng gặp khó khi được yêu cầu đáp ứng đồng thời quá nhiều yêu cầu
    • Ví dụ, nếu đưa ra 10 quy tắc chi tiết dưới dạng bullet, mô hình có xu hướng chỉ làm đúng vài mục đầu và dần bỏ qua các quy tắc phía sau
    • Chiến lược tốt hơn là tập trung lặp lại theo từng bước: chỉ tập trung vào một bài toán con tại một thời điểm, xong rồi mới chuyển sang bài toán tiếp theo

  • Chia spec thành các bước hoặc component

    • Nếu tài liệu spec dài hoặc phạm vi xử lý rộng, hãy cân nhắc chia nó thành nhiều phần
    • Ví dụ: tách “Backend API Spec” và “Frontend UI Spec” thành các mục riêng
    • Khi làm việc backend, không nhất thiết lúc nào cũng phải đưa kèm spec frontend
    • Trong môi trường multi-agent, bạn cũng có thể dùng agent riêng hoặc quy trình con riêng cho từng khu vực
    • Hướng dẫn AI của DigitalOcean cũng cảnh báo rằng “đừng trộn tác vụ xác thực với thay đổi schema cơ sở dữ liệu trong cùng một lúc”

  • TOC/tóm tắt mở rộng cho spec quy mô lớn

    • Một cách làm là để agent viết trước mục lục mở rộng (TOC) tóm tắt toàn bộ spec
    • Nén mỗi phần thành một vài ý chính hoặc từ khóa, đồng thời tham chiếu nơi có nội dung chi tiết
    • Ví dụ: “Security: dùng HTTPS, bảo vệ API key, triển khai kiểm tra đầu vào (xem toàn bộ spec §4.2)”
    • Khi đã có bản tóm tắt phân cấp như vậy, prompt có thể chỉ giữ lại bức tranh tổng thể, còn chi tiết chỉ cung cấp khi cần
    • TOC mở rộng đóng vai trò như một loại chỉ mục, giúp agent nhận ra kiểu như “à, có phần bảo mật ở đây” rồi chủ động yêu cầu phần tương ứng
    • Cách làm tóm tắt phân cấp này giúp LLM giữ được cấu trúc ở cấp độ cao

  • Tận dụng sub-agent hoặc “skill”

    • Có thể sử dụng nhiều agent với vai trò tách biệt, giống như sub-agent (hoặc “skill”) mà Anthropic đề cập
    • Mỗi sub-agent được cấu hình cho một lĩnh vực chuyên môn cụ thể và chỉ nhận phần spec thuộc lĩnh vực đó
    • Ví dụ: sub-agent Database Designer chỉ biết phần mô hình dữ liệu, còn sub-agent API Coder chỉ biết spec endpoint API
    • Cách này giúp mỗi agent có context nhỏ hơn và vai trò rõ hơn, từ đó cải thiện độ chính xác và hỗ trợ xử lý song song
    • Claude Code hỗ trợ định nghĩa sub-agent có system prompt và công cụ riêng

  • Agent song song để tăng throughput

    • Việc chạy nhiều agent cùng lúc đang nổi lên như bước tiến tiếp theo của năng suất lập trình viên
    • Thay vì chờ một agent làm xong, hãy triển khai nhiều agent song song cho các công việc không chồng lấn nhau
    • Simon Willison gọi điều này là “đón nhận các coding agent song song” và nhận xét rằng nó hiệu quả đáng kinh ngạc nhưng cũng khá mệt về mặt tinh thần
    • Cốt lõi là phải chia rõ phạm vi tác vụ để các agent không cản trở công việc của nhau
    • Các framework điều phối như LangGraph hay OpenAI Swarm có thể hỗ trợ việc phối hợp này,
    • Và nếu dùng vector database như Chroma làm bộ nhớ dùng chung, các agent có thể truy cập context chung mà không cần prompt lặp lại

  • Một agent hay nhiều agent: khi nào nên dùng

    Khía cạnh Một agent Agent song song/multi-agent
    Ưu điểm Thiết lập đơn giản, overhead thấp, dễ debug và dễ theo dõi luồng xử lý Throughput cao, có thể xử lý phụ thuộc phức tạp và chuyên môn hóa theo từng domain
    Nhược điểm Quá tải context trong dự án lớn, tốc độ lặp chậm hơn, điểm lỗi đơn lẻ Tăng chi phí điều phối, khả năng xung đột, cần bộ nhớ dùng chung
    Phù hợp khi Module tách biệt, dự án nhỏ đến vừa, giai đoạn tạo prototype ban đầu Codebase lớn, tách riêng coding·testing·review, phát triển tính năng độc lập
    Mẹo Dùng tóm tắt spec, làm mới context theo từng tác vụ, reset session thường xuyên Ban đầu chỉ nên giới hạn ở 2~3 agent, chia sẻ công cụ qua MCP, làm rõ ranh giới

  • Mỗi prompt chỉ tập trung vào một tác vụ/phần

    • Ngay cả khi không có môi trường multi-agent phức tạp, bạn vẫn có thể chủ động áp đặt tính mô-đun bằng cách thủ công
    • Ví dụ: sau khi viết spec, ở giai đoạn “Step 1: triển khai schema cơ sở dữ liệu” thì chỉ cung cấp phần Database của spec
    • Mỗi khi tác vụ chính thay đổi, hãy cấu trúc lại context để giảm sự phân tán do thông tin cũ hoặc không còn liên quan
    • Một số hướng dẫn còn khuyến nghị bắt đầu session mới khi chuyển chức năng lớn để dọn lại context

  • Tận dụng chỉ dẫn inline và code TODO

    • Một cách làm là ghi những việc cần làm bằng comment // TODO trong code rồi để agent xử lý từng mục một
    • Mỗi TODO sẽ đóng vai trò như một mini spec cho một tác vụ nhỏ
    • Nhờ vậy, AI sẽ tập trung vào phạm vi rất hẹp theo kiểu “hãy chỉ triển khai hàm này theo đúng mẩu spec này”

Nguyên tắc 4: Tích hợp tự kiểm tra, ràng buộc và chuyên môn của con người

  • Hãy coi spec không chỉ là danh sách việc cần làm của agent, mà là hướng dẫn quản lý chất lượng, đồng thời chủ động phản ánh chuyên môn của chính bạn vào đó
  • Một spec tốt sẽ chỉ ra trước những chỗ AI có thể mắc sai lầm và dựng sẵn guardrail tại các điểm đó
  • Đưa vào kiến thức miền, edge case và các “điểm cần lưu ý” khác nhau để AI không hoạt động trong trạng thái chân không thiếu ngữ cảnh
  • Sẽ dễ hiểu hơn nếu xem spec là huấn luyện viên đồng thời là trọng tài của AI: dẫn dắt cách tiếp cận đúng và phanh lại ngay các hành vi sai
  • Theo kết quả phân tích hơn 2.500 file agent của GitHub, những spec hiệu quả nhất không phải là danh sách cấm đơn thuần mà sử dụng hệ thống ranh giới 3 tầng
    • Nói rõ khi nào agent có thể cứ thế tiếp tục, khi nào phải dừng lại để hỏi, và khi nào phải dừng hẳn

    • ✅ Always do (luôn thực hiện)

      • Những việc phải làm mà không cần hỏi
      • Ví dụ: “luôn chạy test trước khi commit”, “luôn tuân thủ naming convention của style guide”, “luôn ghi log lỗi vào dịch vụ giám sát”

    • ⚠️ Ask first (hỏi trước)

      • Những việc cần có sự phê duyệt của con người
      • Ví dụ: “hỏi trước khi sửa schema cơ sở dữ liệu”, “hỏi trước khi thêm dependency mới”, “hỏi trước khi thay đổi cấu hình CI/CD”
      • Có thể về mặt kỹ thuật thì làm được, nhưng ở đây sẽ lọc ra những thay đổi cần con người phán đoán vì phạm vi ảnh hưởng lớn

    • 🚫 Never do (tuyệt đối không làm)

      • Những vùng hard stop rõ ràng
      • Ví dụ: “tuyệt đối không commit secret hay API key”, “tuyệt đối không chỉnh sửa node_modules/ hoặc vendor/”, “không được xóa các test đang fail nếu chưa có phê duyệt rõ ràng”
      • Nghiên cứu cũng xác nhận “tuyệt đối không commit secret” là ràng buộc hữu ích xuất hiện thường xuyên nhất

  • Khuyến khích tự kiểm chứng

    • Khuyến khích agent tự kiểm tra kết quả của mình đối chiếu với spec
    • Nếu công cụ cho phép, hãy đưa vào workflow việc tự chạy unit test hoặc lint sau khi sinh mã
    • Ở cấp độ prompt cũng có thể đưa ra chỉ thị kiểm tra lại
      • Ví dụ: “Sau khi triển khai, hãy so sánh kết quả với spec để xác nhận đã đáp ứng mọi yêu cầu; nếu còn mục nào chưa đáp ứng thì hãy liệt kê ra”
    • Việc buộc LLM đối chiếu đầu ra của chính nó với spec giúp giảm thiếu sót

  • LLM-as-a-Judge cho kiểm tra mang tính chủ quan

    • Với các tiêu chí khó tự động hóa như style code, độ dễ đọc hay việc tuân thủ pattern kiến trúc, hãy dùng cách tiếp cận LLM-as-a-Judge
    • Một agent thứ hai (hoặc prompt riêng) sẽ rà soát đầu ra của agent thứ nhất theo các tiêu chí chất lượng trong spec
    • Ví dụ: “Hãy kiểm tra xem đoạn mã này có tuân thủ style guide của chúng ta không và đánh dấu các chỗ vi phạm”
    • Agent đóng vai trò trọng tài sẽ trả về phản hồi, và có thể dùng phản hồi đó để chỉnh sửa hoặc làm căn cứ sửa đổi

  • Kiểm thử tính phù hợp

    • Willison khuyến nghị xây dựng conformance suite
    • Đây là các bài kiểm thử không phụ thuộc ngôn ngữ (thường dựa trên YAML), đóng vai trò như một hợp đồng mà mọi implementation đều phải vượt qua
    • Nếu bạn đang xây dựng API, conformance suite sẽ định nghĩa đầu vào và đầu ra kỳ vọng, và mã do agent tạo ra phải đáp ứng tất cả
    • Trong mục Success của spec, hãy ghi rõ tiêu chí như “bắt buộc vượt qua mọi case trong conformance/api-tests.yaml”

  • Tận dụng test trong spec

    • Nếu có thể, hãy đưa kế hoạch kiểm thử hoặc test thực tế trực tiếp vào spec và luồng prompt
    • Giống như TDD, dùng test case để làm rõ yêu cầu
      • Ví dụ: trong Success Criteria ghi rõ “input mẫu này bắt buộc phải tạo ra output này”
    • Willison mô tả test suite vững chắc là thứ mang lại cho agent gần như siêu năng lực
    • Vì khi test thất bại, agent có thể lập tức kiểm chứng và lặp lại
    • Trong cấu hình subagent, bạn cũng có thể có một test agent chuyên nhận các tiêu chí trong spec và liên tục xác minh đầu ra mã

  • Phản ánh kiến thức miền

    • Spec nên chứa những insight thực tế mà chỉ lập trình viên có kinh nghiệm hoặc người hiểu ngữ cảnh mới biết
    • Ví dụ, khi tạo agent cho thương mại điện tử, hãy ghi rõ rằng “products” và “categories” có quan hệ nhiều-nhiều
      • Đừng kỳ vọng AI sẽ tự suy ra
    • Nếu một thư viện cụ thể vốn khó dùng, hãy nêu luôn những cái bẫy thường gặp hoặc điểm cần chú ý
    • Đây là cách đưa sự cố vấn của bạn vào trong spec
      • Ví dụ: “Khi dùng thư viện X, phiên bản Y có vấn đề rò rỉ bộ nhớ nên cần áp dụng cách обход Z”

  • Tối giản cho tác vụ đơn giản

    • Spec chặt chẽ là quan trọng, nhưng một phần của chuyên môn là biết khi nào nên giữ mọi thứ đơn giản
    • Với các công việc tương đối đơn giản và tách biệt, spec quá mức đôi khi còn làm tăng sự rối rắm
    • Ví dụ, với tác vụ như “căn giữa một div trên trang”
      • Chỉ cần mức như “giữ giải pháp ngắn gọn, không thêm markup hay style không cần thiết” là đủ
    • Ngược lại, với việc phức tạp như “triển khai luồng OAuth có làm mới token và xử lý lỗi”, bạn cần một spec chi tiết
    • Tiêu chí thực tiễn là điều chỉnh mật độ của spec cho phù hợp với độ phức tạp của tác vụ

  • Giữ con người là bộ lọc chất lượng cuối cùng

    • Spec trao quyền cho agent, nhưng trách nhiệm cuối cùng về chất lượng vẫn thuộc về lập trình viên
    • Ngay cả khi agent đã đáp ứng spec về mặt kỹ thuật, nếu cảm giác hoặc ngữ cảnh không đúng thì hãy tin vào phán đoán của mình
    • Khi cần, việc tinh chỉnh lại spec hoặc trực tiếp sửa kết quả đầu ra cũng là quá trình tự nhiên
    • Willison ví việc làm việc với AI agent là “một dạng quản lý cực kỳ kỳ lạ”, và “giống đến mức khó chịu với việc quản lý một thực tập sinh con người”
    • Cuối cùng, vai trò cung cấp chỉ dẫn rõ ràng (spec), đủ ngữ cảnh và phản hồi có thể hành động được vẫn là phần việc của con người

Nguyên tắc 5: Kiểm thử, lặp lại, tiến hóa spec (sử dụng đúng công cụ)

  • Nhận thức việc viết spec và xây dựng agent không phải là công việc làm một lần là xong mà là một vòng lặp lặp lại
    • Luồng làm việc gồm kiểm thử nhanh, thu thập phản hồi, tinh chỉnh spec và tự động hóa việc kiểm tra bằng công cụ
  • Spec ban đầu không phải bản hoàn chỉnh mà là điểm khởi đầu của chu kỳ

  • Kiểm thử liên tục

    • Đừng chờ đến khi hoàn tất toàn bộ phần triển khai; hãy kiểm thử hoặc thực hiện kiểm tra thủ công đơn giản theo từng mốc quan trọng hoặc từng hàm
    • Nếu phát hiện thất bại, đừng tiếp tục như cũ mà hãy sửa spec hoặc prompt trước
    • Kiểm thử tự động đặc biệt hiệu quả, và nếu có test thì có thể để agent tự chạy trực tiếp các lệnh như npm test
    • Dùng nguyên kết quả test thất bại làm đầu vào cho prompt tiếp theo
      • Ví dụ: “Đầu ra không đáp ứng spec ở X, Y, Z nên hãy sửa lại”
    • Vòng lặp agentic nối tiếp code → test → sửa → lặp lại là một cách làm rất mạnh

  • Lặp lại chính spec

    • Nếu lộ ra việc agent hiểu sai hoặc thiếu yêu cầu, đừng che lấp vấn đề mà hãy sửa tài liệu spec trước
    • Đồng bộ lại spec đã sửa với agent một cách rõ ràng
      • Ví dụ: “Tôi đã cập nhật spec như sau. Hãy điều chỉnh kế hoạch hoặc refactor code để phản ánh thay đổi này”
    • Luôn duy trì spec như nguồn chân lý duy nhất
    • Nếu có thể, lưu lịch sử phiên bản bằng commit message hoặc ghi chú để theo dõi điều gì đã thay đổi và vì sao

  • Quản lý ngữ cảnh và tận dụng công cụ bộ nhớ

    • Hệ sinh thái công cụ hỗ trợ quản lý ngữ cảnh và tri thức cho AI agent đang phát triển rất nhanh
    • Nếu tận dụng mô hình RAG (retrieval-augmented generation), agent có thể ngay lập tức lấy đúng thông tin cần thiết từ knowledge base như vector database
    • Nếu spec rất lớn, có thể nhúng từng phần rồi cấu hình để agent chỉ truy xuất những phần liên quan nhất thay vì nhận toàn bộ
    • Các framework dựa trên MCP (Model Context Protocol) tự động cung cấp ngữ cảnh phù hợp với tác vụ hiện tại
    • Các công cụ như Context7(context7.com) tự động gọi ra các snippet liên quan từ tài liệu tùy theo nội dung đang làm

  • Song song hóa một cách thận trọng

    • Một số nhà phát triển tăng tốc bằng cách chạy song song nhiều instance agent trên các tác vụ khác nhau
    • Ví dụ: một agent sinh code, agent khác đồng thời viết test
    • Nếu chọn cách này, các tác vụ phải thực sự độc lập hoặc được tách biệt rõ ràng để tránh xung đột
    • Ví dụ: giới hạn để hai agent không cùng sửa một file tại cùng thời điểm
    • Để giảm gánh nặng quản lý, giai đoạn đầu nên bắt đầu với tối đa 2–3 agent là thực tế hơn

  • Quản lý phiên bản và khóa spec

    • Theo dõi kỹ công việc của agent bằng công cụ quản lý phiên bản như Git
    • Càng dùng AI, tầm quan trọng của thói quen quản lý phiên bản tốt càng lớn
    • Commit chính file spec vào repository để lưu lại lịch sử thay đổi
    • Agent cũng có thể đọc git diff hoặc blame để hiểu bối cảnh thay đổi
      • Trên thực tế, LLM khá giỏi trong việc diễn giải diff
    • Đặt spec trong repo giúp cả lập trình viên lẫn AI cùng theo dõi quá trình tiến hóa của dự án
    • Willison mô tả các model là “cực kỳ thành thạo với Git”

  • Cân nhắc chi phí và tốc độ

    • Các tác vụ dùng model lớn và ngữ cảnh dài có thể chậm và tốn kém
    • Hãy tách chiến lược chọn model
      • Dùng model nhanh và rẻ cho bản nháp ban đầu hoặc tác vụ lặp lại
      • Dùng model mạnh nhất (và đắt nhất) cho đầu ra cuối cùng hoặc suy luận phức tạp
    • Ví dụ: giao GPT-4 hoặc Claude cho việc lập kế hoạch và các bước cốt lõi, còn mở rộng đơn giản hoặc refactor thì giao cho model cục bộ hoặc model API nhỏ
    • Agent chạy test hoặc agent lint thường chỉ cần model tương đối nhỏ là đủ
    • Kích thước ngữ cảnh cũng cần được quản lý

  • Hãy giám sát và ghi log mọi thứ

    • Trong workflow agent phức tạp, log hành vi và đầu ra của agent là thiết yếu
    • Thông qua log có thể kiểm tra agent có đi chệch ý định hay có phát sinh lỗi không
    • Nhiều framework cung cấp trace log hoặc hỗ trợ xuất quá trình suy nghĩ theo từng bước
    • Xem log sẽ cho thấy điểm nào spec hoặc chỉ dẫn bị hiểu sai

  • Học hỏi và cải thiện

    • Hãy coi mỗi dự án là một cơ hội học tập để mài giũa năng lực viết spec
    • Có thể quan sát xem cách diễn đạt nào thường xuyên làm AI bối rối, hoặc cấu trúc spec nào được tuân thủ tốt hơn
    • Chủ động phản ánh những bài học đó vào spec tiếp theo
    • Lĩnh vực AI agent đang tiến hóa nhanh, và các công cụ cùng best practice mới liên tục xuất hiện

Tránh những sai lầm thường gặp

  • Kết quả phân tích hơn 2.500 file agent trên GitHub cho thấy nguyên nhân lớn nhất của thất bại là spec và chỉ dẫn quá mơ hồ

  • Prompt mơ hồ

    • Những yêu cầu như “Hãy làm thứ gì đó ngầu”, “Hãy làm cho nó hoạt động tốt hơn” khiến agent thậm chí không có tiêu chí để phán đoán
    • Cần mô tả càng cụ thể càng tốt về đầu vào, đầu ra và các điều kiện ràng buộc
    • Việc gán vai trò chung chung như “Bạn là một coding assistant hữu ích” hầu như không hiệu quả
    • Ngược lại, nếu chỉ định cùng lúc vai trò, phạm vi và ràng buộc như “Bạn là kỹ sư kiểm thử viết test cho React component, hãy làm theo ví dụ này và tuyệt đối không sửa source code” thì kết quả tốt hơn nhiều

  • Quá nhiều ngữ cảnh mà không có tóm tắt

    • Cách đổ nguyên một tài liệu 50 trang vào prompt rồi kỳ vọng model tự hiểu phần lớn sẽ thất bại
    • Cần dùng tóm tắt phân cấp hoặc RAG để chỉ làm lộ ra những nội dung liên quan trực tiếp đến tác vụ hiện tại
    • Tăng độ dài ngữ cảnh không thể bù đắp cho chất lượng ngữ cảnh kém

  • Bỏ qua khâu review của con người

    • Nguyên tắc cá nhân của Willison: “Tôi không commit đoạn code nào mà tôi không thể giải thích cho người khác”
    • Việc agent tạo ra thứ gì đó vượt qua test không có nghĩa code đó ngay lập tức là chính xác, an toàn và dễ bảo trì
    • Đặc biệt với đường đi code quan trọng, con người luôn phải trực tiếp review
    • Phép so sánh “ngôi nhà bằng bài” rất phù hợp ở chỗ code do AI tạo ra có thể trông vững vàng bên ngoài nhưng sụp đổ ở các edge case chưa được kiểm thử

  • Nhầm lẫn giữa vibe coding và production engineering

    • Prototyping nhanh với AI, hay còn gọi là “vibe coding”, phù hợp với giai đoạn khám phá hoặc dự án dùng một lần
    • Nếu triển khai thẳng kết quả đó vào production mà không có spec chặt chẽ, test và review, khả năng cao sẽ phát sinh vấn đề
    • Cần phân biệt rõ “vibe coding” với “AI-assisted engineering”; vế sau đòi hỏi kỷ luật và quy trình như hướng dẫn này mô tả
    • Điều quan trọng là phải tự nhận thức hiện tại mình đang làm việc ở chế độ nào

  • Phớt lờ “bộ ba chí mạng”

    • Ba thuộc tính mà Willison cảnh báo là khiến AI agent trở nên nguy hiểm
      • Tốc độ: tạo kết quả nhanh hơn tốc độ con người có thể review
      • Tính không tất định: cùng một đầu vào nhưng mỗi lần chạy cho ra đầu ra khác nhau
      • Chi phí: khiến người ta bị thúc đẩy dùng đường tắt thay vì xác minh đầy đủ
    • Spec và quy trình review phải được thiết kế với cả ba yếu tố này làm tiền đề
    • Đặc biệt cần kiểm soát có chủ đích để tốc độ không vượt quá năng lực xác minh

  • Bỏ sót 6 lĩnh vực cốt lõi

    • Nếu spec không bao quát Commands, Testing, Project Structure, Code Style, Git Workflow và Boundaries, agent rất dễ bỏ lỡ thông tin quan trọng cần cho công việc
    • Trước khi giao cho agent, an toàn hơn nếu kiểm tra lại một lần bằng checklist 6 lĩnh vực

Kết luận

  • Viết spec hiệu quả cho AI coding agent đòi hỏi kết hợp các nguyên tắc kỹ thuật phần mềm vững chắc với cách tiếp cận hiểu rõ đặc tính của LLM và điều chỉnh phù hợp theo đó
  • Mọi thứ bắt đầu từ việc xác định mục tiêu thật rõ ràng, rồi từ đó phân chia vai trò để AI mở rộng kế hoạch và chi tiết
  • Spec không nên được xem như ghi chú mà phải được đối xử như một tài liệu thiết kế nghiêm túc, bao gồm 6 lĩnh vực cốt lõi và được coi là artifact có thể thực thi gắn với toolchain
  • Thay vì đưa mọi thứ cùng lúc, hãy chia nhỏ theo từng đơn vị công việc để giữ agent tập trung
    (TOC tóm tắt, sub-agent, orchestration song song là những phương tiện thực tế để xử lý spec quy mô lớn)
  • Thông qua ranh giới 3 cấp (Always / Ask first / Never), tự kiểm tra và bài kiểm tra mức độ phù hợp, có thể chặn trước các cạm bẫy mà AI dễ mắc phải
  • Điểm cốt lõi là xem spec và implementation không phải thành phẩm cố định mà là một quá trình lặp, liên tục tinh chỉnh cả spec lẫn code thông qua kiểm thử và phản hồi
  • Nếu làm theo các hướng dẫn này, có thể giảm rõ rệt khả năng AI agent bị lạc hướng trong ngữ cảnh quy mô lớn hoặc trượt sang những nội dung vô nghĩa

Bài viết liên quan

2 bình luận

 
qor0923 2026-01-20

Cảm ơn bạn.
 
googol 2026-01-19

Cá nhân tôi khi phát triển dự án bằng SDD (Specs Driven Development), lúc đầu đúng là cảm nhận được năng suất tăng lên rõ rệt, nhưng vì hiện vẫn chưa thể viết toàn bộ mã dựa trên đặc tả và mỗi khi cần chỉnh sửa trực tiếp thì lại phải cập nhật cả mã lẫn đặc tả, nên tôi đã có trải nghiệm năng suất ngược lại còn bị giảm sút.