CCA-F Readiness Dossier

Liên hệ task 1.2 · 1.6 · 3.4

Đáp ứng điều kiện bắt buộc trước; trong các cách đáp ứng được, chọn cách ít phức tạp và ít đánh đổi không cần thiết hơn.

Vì sao: mỗi agent, lượt gọi và lớp điều phối đều thêm chi phí, độ trễ và một chỗ có thể mất thông tin. Tăng độ phức tạp chỉ có ích khi nó giải quyết một nhu cầu cụ thể.

Phân biệt: một lần gọi phù hợp khi đầu vào đã đủ và đầu ra rõ. Workflow/prompt chain phù hợp khi các bước đã biết trước. Agent phù hợp khi bước tiếp theo phụ thuộc kết quả vừa tìm thấy. Multi-agent có ích khi cần chia chuyên môn, cô lập context hoặc chạy các phần độc lập song song.

Ranh giới: một workflow cố định vẫn có thể dùng model để suy luận ở từng bước. Model-driven không có nghĩa bỏ mọi thứ tự bắt buộc. Một agent có thể tự chọn hướng điều tra, nhưng vẫn phải qua bước xác minh trước hành động tài chính.

“Đơn giản nhất” không có nghĩa “ít dòng code nhất”. Prompt ngắn không thay được chốt chặn khi yêu cầu là không bao giờ vượt chính sách. Cũng không mặc định chọn multi-agent chỉ vì đề nhắc đến agent.

Liên hệ task 1.1

Model đề xuất bước tiếp theo; runtime thực thi tool, trả kết quả và điều khiển vòng lặp bằng tín hiệu có cấu trúc.

Cơ chế: gửi messages và tools → nhận response → nếu có stop_reason: tool_use, thực thi các tool được yêu cầu → giữ assistant response trong history và gửi các tool_result tương ứng ở lượt tiếp theo → model dùng kết quả đó để quyết định tiếp. Trong Messages API, tool result được gửi dưới role user, gắn đúng tool_use_id.

Điểm dừng: end_turn kết thúc lượt của model; ứng dụng vẫn phải phân biệt đã hoàn thành yêu cầu với đang chờ thông tin người dùng. Không dùng câu văn “done”, sự xuất hiện của text, hay một số vòng cố định làm dấu hiệu hoàn thành. Giới hạn vòng/thời gian là chốt an toàn phụ. max_tokens là hạn mức độ dài của một response, không phải tín hiệu công việc đã xong: chạm trần thì response bị cắt giữa chừng, cần xử lý riêng chứ đừng đọc như end_turn.

Thông tin và tiến triển: xóa tool history tùy tiện khiến agent quên việc đã làm. Ngược lại, thêm cùng một kết quả nhiều lần không tự tạo tiến triển. Khi có lỗi, cần trả trạng thái đủ rõ để model đổi hướng hoặc dừng có lý do.

Cache không mặc nhiên làm agent lặp. Dữ liệu ổn định có thể được dùng lại; dữ liệu đang chờ thay đổi cần chính sách làm mới phù hợp. Chỉ thấy lặp chưa đủ kết luận thiếu tool_use_id, dữ liệu đã cũ hay model phát hiện được cache. Đây là giới hạn suy luận, không phải một quy luật mới cần học thuộc.

Liên hệ task 1.2 · 1.3 · 1.6

Các subagent làm đúng phần được giao vẫn có thể tạo ra một báo cáo sai phạm vi. Độ phủ và tích hợp là trách nhiệm của coordinator.

Cơ chế: coordinator đọc mục tiêu, chia thành các phần đủ rộng để có ý nghĩa, chọn agent phù hợp, nhận kết quả rồi kiểm tra còn thiếu gì. Nếu tổng hợp chưa đủ, giao lại truy vấn có mục tiêu vào phần thiếu thay vì chạy lại toàn bộ pipeline.

Context: subagent không tự nhận lịch sử hội thoại của coordinator hoặc findings của agent trước. Prompt giao việc phải chứa mục tiêu, dữ liệu cần dùng, ràng buộc và tiêu chí chất lượng. Findings nên tách claim khỏi metadata: nguồn, đoạn trích, ngày và vị trí.

Phân rã: chia theo subtopic hoặc loại nguồn để tránh tìm trùng. Các phần độc lập có thể chạy song song; bước phụ thuộc phải đợi đầu vào. Review lớn cần lượt phân tích cục bộ và lượt tích hợp giữa các file, vì lỗi luồng dữ liệu có thể nằm ở giao điểm của chúng.

Tool và điều phối: theo thuật ngữ guide, coordinator cần quyền dùng Task để gọi subagent — cụ thể là allowedTools của coordinator phải chứa "Task". Đừng nhầm key này với allowed-tools trong frontmatter của skill: khác cấp, khác cách viết. Mỗi loại subagent được mô tả bằng AgentDefinition gồm description, system prompt và giới hạn tool riêng. Guide gọi kiến trúc này là hub-and-spoke: mọi trao đổi giữa các subagent đều đi qua coordinator, nên luồng thông tin và xử lý lỗi mới nhất quán và quan sát được. Subagent không nói chuyện trực tiếp với nhau. Mỗi agent chỉ cần tools phục vụ vai trò; một tool kiểm chứng hẹp cho nhu cầu thường xuyên có thể tránh nhiều lượt chuyển giao.

Chạy song song: cách làm là coordinator phát nhiều Task call trong cùng một response, không rải mỗi call sang một lượt khác nhau. Nếu chờ từng subagent hoàn thành rồi mới gọi agent tiếp theo thì công việc chạy nối tiếp; không suy ra chỉ từ số lượt gọi rằng runtime không thể chạy nền.

Cô lập context không có nghĩa agent làm việc không cần dữ liệu chung. Song song không có nghĩa các agent được tự sửa cùng một trạng thái mà không phối hợp. Brief cần mục tiêu và chất lượng; không cần trói mọi cuộc điều tra vào một danh sách bước cứng.

Liên hệ task 1.4 · 1.5

Prompt định hướng phán đoán. Điều kiện bắt buộc phải được kiểm tra bằng cơ chế thực thi, ở phạm vi bao phủ đúng các hành động cần bảo vệ.

Soft preference: ưu tiên đề xuất đổi hàng khi hợp lý là hướng dẫn có ngoại lệ; prompt rõ và ví dụ phù hợp giúp model cân nhắc. Hard constraint: chưa xác minh đúng tài khoản thì không được hoàn tiền; hệ thống phải chặn tool nếu điều kiện chưa đạt.

PreToolUse: kiểm tra đầu vào trước khi chạy tool; có thể chặn hành động vi phạm hoặc điều chỉnh input trong giới hạn runtime hỗ trợ. Chặn cần kèm lý do và hướng tiếp tục, chẳng hạn chuyển người có thẩm quyền, thay vì chỉ làm cả phiên chết.

PostToolUse: xử lý kết quả sau khi tool thành công, chẳng hạn chuẩn hóa timestamp hoặc status để model đọc nhất quán. Với MCP result và runtime hỗ trợ thay kết quả, có thể dùng bước này để chuyển đổi payload. Nó không quay ngược một khoản tiền đã chuyển.

Hook và gate: hook là điểm gắn logic; code chạy trong hook có thể chính là gate. Không có thứ bậc “hook chỉ tự động hóa, code mới chặn được”. Bảo đảm phụ thuộc logic kiểm tra, đường gọi được bao phủ và cách xử lý khi kiểm tra thất bại. Luật dùng chung mọi caller có thể cần đặt trong backend/tool chung.

Không suy ra mọi hook chạy tuần tự hoặc mọi runtime kế thừa hook giống nhau. Nếu dữ liệu nhạy cảm tuyệt đối không được vào model hay log, phải kiểm soát cả đường dữ liệu và logging; không chỉ yêu cầu model đừng nhắc lại. Các chi tiết triển khai này cần xem đúng runtime khi xây thật.

Liên hệ task 2.1 · 2.3

Đủ chi tiết về từng tool chưa chắc đã rõ ranh giới giữa hai tool.

Một contract tốt: tên khớp hành vi; description nêu khi nào dùng, input được chấp nhận, output có gì, giới hạn và khi nào chuyển sang tool khác. Schema giới hạn input; quyền hạn giới hạn hành động thực sự được phép. Description rõ hỗ trợ lựa chọn, không thay authorization.

Ví dụ giải thích: extract_tables dùng khi mục tiêu chỉ là lấy bảng. extract_document dùng khi cần cả prose, form và bảng. Hai mô tả dù dài vẫn cần nói rõ sự phân biệt này. Lỗi chọn nhầm trước hết cần được kiểm tra ở tên, mô tả và hướng dẫn có thể đang tạo liên tưởng sai.

Khi thay cấu trúc: tách tool quá chung khi nhiều hành vi và input/output bị trộn. Gộp hoặc bỏ tool khi đã xác định chúng dư thừa và không còn nhu cầu riêng. Không tự suy ra tool chuyên biệt rẻ hơn, nhanh hơn hoặc chính xác hơn nếu tình huống chưa cho bằng chứng.

Khi ép tool: forced tool_choice phù hợp khi một bước cụ thể bắt buộc phải xảy ra, như extraction trước enrichment. Nó không phải mặc định cho mọi lỗi chọn tool. Quyền tối thiểu nghĩa là đủ tools cho vai trò, không phải càng ít tool càng tốt bất kể công việc.

Chọn sửa description vì lỗi là ranh giới lựa chọn chưa rõ; không học thành “description luôn thắng”. Nếu description đã rõ mà quyền hoặc input contract sai, phải sửa đúng lớp đang hỏng.

Liên hệ task 4.1 · 4.2

Criteria nói điều gì được tính là đúng. Ví dụ minh họa dấu hiệu khiến một trường hợp nằm ở bên này hoặc bên kia của tiêu chí.

False positive: “be conservative” hoặc “chỉ báo lỗi rất chắc” không định nghĩa lỗi. Hãy xác định loại vấn đề cần báo, loại cần bỏ qua và hậu quả tương ứng với severity. Ví dụ, comment mâu thuẫn hành vi code khác với comment chỉ không kể hết chi tiết.

Few-shot: khi model hiểu yêu cầu nhưng output không nhất quán hoặc gặp ca mơ hồ, dùng một ít ví dụ có chủ đích. Guide nêu 2–4 ví dụ cho tình huống mơ hồ; con số là hướng dẫn, không phải hạn mức kỹ thuật. Ví dụ còn giúp thống nhất format location / issue / severity / suggested fix và cách đọc nhiều cấu trúc tài liệu. Ví dụ cần bao gồm cả trường hợp dễ nhầm và cách xử lý thiếu dữ liệu.

Ví dụ giải thích: “Retry được implement ở đâu?” cần code nên dùng search_code. “Team quy định retry thế nào?” cần tài liệu nên dùng search_docs. Cặp request → tool chỉ cho thấy kết quả; thêm lý do ngắn gọn cho thấy tiêu chí để áp dụng sang câu mới.

Phân biệt ba nhu cầu: chọn sai vấn đề cần báo → criteria; trình bày không đều hoặc khó áp dụng tiêu chí ở ca biên → examples; máy phía sau cần cấu trúc xác định → schema. Chúng bổ sung cho nhau, không phải ba đáp án thay thế trong mọi hoàn cảnh.

Thêm nhiều ví dụ cùng một dạng không chắc bổ sung phần thông tin đang thiếu. Một tie-break mặc định cũng không giải thích được ý định thực sự. Không cần yêu cầu chuỗi suy nghĩ dài; cần dấu hiệu phân biệt và lý do lựa chọn có thể kiểm tra.

Liên hệ task 4.3 · 4.4

Output hợp schema có thể vẫn sai giá trị, sai trường hoặc không được tài liệu gốc hỗ trợ.

Ba lớp: (1) Schema kiểm tra cấu trúc, kiểu, required, enum và những ràng buộc đã định nghĩa. (2) Semantic validation kiểm tra quan hệ và ý nghĩa, như tổng các dòng so với tổng hóa đơn — guide nhắc Pydantic như công cụ quen thuộc cho lớp này và cho vòng validation–retry. (3) Grounding kiểm tra giá trị thực sự xuất phát từ đúng phần của tài liệu.

Thiếu dữ liệu: thiết kế field optional hoặc nullable khi nguồn có thể không chứa nó. Optional cho phép thiếu key; nullable cho phép giá trị null — hai khái niệm khác nhau. Một key có thể vừa required vừa nullable: chẳng hạn bắt buộc có invoice_date nhưng cho phép null khi tài liệu không có ngày. Strict không đồng nghĩa mọi key đều phải required; đó là lựa chọn trong schema và phải phù hợp cơ chế được hỗ trợ.

Phân loại mở: other kèm detail dùng khi danh mục có thể chưa đầy đủ; unclear biểu diễn trường hợp chưa thể xác định. Không ép chọn một giá trị cụ thể chỉ để làm đẹp bản ghi.

Retry có phản hồi: gửi tài liệu gốc + kết quả sai + lỗi validation cụ thể. Chỉ thông báo “invalid” không cho model biết cần sửa gì. Nếu nguồn thật sự mâu thuẫn, giữ cả giá trị tính được và giá trị được nêu, đánh dấu xung đột; đừng âm thầm sửa tài liệu cho khớp. Guide đặt tên cho chính cách này: trích calculated_total song song với stated_total để lộ chênh lệch, và thêm cờ conflict_detected khi nguồn tự mâu thuẫn.

Retry có thể sửa cách đọc hoặc format; nó không tạo ra ngày ký vốn không có trong tài liệu. Forced tool selection buộc chọn tool, còn schema enforcement cần cơ chế strict structured output tương ứng. Không coi mọi tool call có schema là tự động được bảo đảm hợp lệ.

Liên hệ task 1.7 · 5.1 · 5.4 · 5.6

Context tốt là đủ bằng chứng đúng, còn hiệu lực và dễ tìm; không phải toàn bộ text từng thu thập được.

Giữ chính xác: mã đơn, số tiền, ngày, trạng thái và cam kết với khách nên nằm trong facts block có cấu trúc, được cập nhật khi dữ kiện đổi. Một summary như “đã thỏa thuận hoàn tiền” làm mất số tiền và điều kiện đã thỏa thuận.

Giảm nhiễu: cắt trường tool output không liên quan, giữ bản chi tiết ở nơi có thể đọc lại. Đặt kết luận quan trọng ở đầu bản tổng hợp, chia phần rõ — vì hiệu ứng lost-in-the-middle: model xử lý phần đầu và phần cuối của input dài đáng tin hơn, và có thể bỏ sót nội dung nằm ở khúc giữa. Dùng subagent để cô lập việc khám phá dài — trong Claude Code đó là Explore subagent, chạy phần discovery nhiều output rồi chỉ trả summary về phiên chính; scratchpad để lưu findings qua ranh giới context; đọc lại scratchpad khi cần chứ không chỉ ghi rồi bỏ.

Resume / fork / fresh: resume khi lịch sử còn hữu ích và báo rõ những file đã đổi. Fork để hai hướng phát triển độc lập từ cùng nền phân tích; lỗi trong nền cũng đi theo cả hai. Khi tool results đã lỗi thời hoặc context đầy thử nghiệm bỏ đi, phiên mới với summary đúng hiện trạng thường đáng tin hơn. Trong Claude Code, /compact nén lịch sử phiên đang chạy để lấy lại chỗ trong context — nó rút gọn, nên vẫn phải giữ facts quan trọng ở nơi không bị tóm tắt, và không làm cho dữ liệu đã cũ trở lại đúng.

Provenance: claim đi cùng nguồn, đoạn trích/vị trí, thời điểm và điều kiện giới hạn. Hai số khác nhau có thể đo hai năm hoặc hai nhóm đối tượng. Giữ khác biệt đó thay vì lấy trung bình hoặc chọn số từ report dài hơn. Phân biệt kết luận đã được nhiều nguồn hỗ trợ với kết luận còn tranh luận.

Khôi phục: state có cấu trúc và manifest cho biết phần nào đã xong, artifact nằm ở đâu, phần nào còn thiếu; coordinator dùng chúng để tiếp tục sau gián đoạn. Đây là lưu trạng thái rõ ràng, không phải shared memory tự động giữa subagent.

Context lớn không bảo đảm chú ý tốt; summary không phải nguồn chân lý; URL đúng không cứu được claim đã mất qualifiers. Giữ cả “nghiên cứu sơ bộ”, thời gian và mẫu khảo sát khi chúng giới hạn kết luận.

Liên hệ task 2.2 · 5.3

Tín hiệu thất bại phải phân biệt được lỗi sửa được, lỗi cần đổi input/quyền và kết quả tìm kiếm hợp lệ nhưng rỗng.

Contract: dùng isError để báo tool thất bại. Bổ sung category, retryability, giải thích và partial results khi có. Các tên như errorCategory, isRetryable là thiết kế metadata của tool; không phải tất cả đều là trường bắt buộc của chuẩn MCP.

Transient: timeout hoặc dịch vụ tạm lỗi có thể đáng thử lại có giới hạn. Validation: input không hợp lệ cần được sửa, không gửi lại y nguyên. Business: chính sách từ chối cần giải thích hoặc chuyển đúng người. Permission: thiếu quyền cần xử lý quyền; chờ thêm không tự cấp quyền.

Phạm vi phục hồi: subagent xử lý cục bộ lỗi tạm thời đơn giản; nếu không khắc phục được, trả lên coordinator loại lỗi, việc đã thử, phần kết quả tốt và hướng thay thế. Coordinator giữ công việc đã thành công và giao lại phần thiếu khi phù hợp.

Báo cáo: nếu chỉ có bằng chứng cho ba trong bốn chủ đề, nêu rõ độ phủ thay vì trình bày như đã hoàn chỉnh. Một tool timeout không phải bằng chứng rằng không có tài liệu phù hợp.

Không retry mù mọi loại lỗi; cũng không dừng cả hệ thống chỉ vì một nguồn thất bại. Với thao tác ghi, timeout còn có thể là kết quả chưa biết; không tự suy rằng thao tác chưa xảy ra. Cơ chế chống ghi lặp là lưu ý triển khai, không thay phần phân loại lỗi của guide.

Liên hệ task 4.1 · 4.4 · 4.6 · 5.5

Kết quả trông hợp lý, confidence cao hoặc accuracy tổng tốt đều chưa đủ chứng minh chất lượng ở trường hợp đang xử lý.

Review độc lập: instance sinh code mang theo lý do đã chọn cách làm, dễ bỏ qua giả định của chính nó. Reviewer độc lập giảm ảnh hưởng đó, nhưng vẫn phải nhận code, yêu cầu, tiêu chí chấp nhận và context cần kiểm chứng. Độc lập với reasoning của generator không có nghĩa thiếu project context.

Review nhiều lượt: local pass cho lỗi trong file; integration pass cho luồng qua nhiều file. Không chỉ tăng context rồi kỳ vọng mọi phần đều được chú ý như nhau. Đồng thuận giữa nhiều model không tự chứng minh một finding đúng, và có thể bỏ sót lỗi chỉ một lượt nhìn thấy.

Đo theo segment: accuracy tổng có thể che lỗi ở một loại chứng từ hoặc một field. Dùng tập có nhãn để đo và hiệu chỉnh confidence theo field; trước khi giảm human review phải xem hiệu năng theo document type và field. Lấy mẫu phân tầng cả nhóm confidence cao để tìm lỗi đang lọt qua.

Confidence: điểm tự báo 0.9 không mặc nhiên nghĩa 90% đúng. Một điểm hữu ích để xếp hạng có thể chưa được hiệu chỉnh thành xác suất. Chuyển attention của reviewer vào trường hợp confidence thấp, mơ hồ hoặc mâu thuẫn; vẫn cần theo dõi nhóm tự động thông qua.

Feedback: lưu loại pattern gây finding và kết quả được chấp nhận/bác bỏ để sửa tiêu chí có mục tiêu. Guide gọi trường này là detected_pattern trong finding có cấu trúc: nhờ nó mới phân tích được dev đang bác bỏ nhóm nào. Tạm tắt một nhóm false positive cao có thể hợp lý trong lúc sửa nhóm đó, thay vì làm mọi nhóm im lặng.

Schema check và phép tính có thể kiểm bằng code. Đừng trả tiền cho một lượt model tự nói “tôi chắc” rồi coi đó là validation độc lập. Human approval cũng chỉ có ý nghĩa khi quy trình thật sự kiểm tra được bằng chứng.

Liên hệ task 1.4 · 5.2

Độ khó thao tác, cảm xúc khách và thẩm quyền giải quyết là ba chuyện khác nhau.

Tự xử lý: việc nhiều bước nhưng chính sách rõ, tools đủ và nằm trong thẩm quyền vẫn có thể hoàn thành tự động. Khách bực không tự động biến một việc đơn giản thành trường hợp cần người xử lý.

Escalate: khách yêu cầu người thật; tình huống cần ngoại lệ hoặc chính sách thiếu/không rõ; hệ thống không thể tiến triển có ý nghĩa. Không dùng một confidence score chưa hiệu chỉnh hay sentiment làm đại diện cho các điều kiện này.

Mơ hồ danh tính: nhiều customer match thì xin thêm thông tin phân biệt. Không chọn người có đơn gần nhất, số dư lớn nhất hoặc tên giống nhất. Chỉ “đã xác minh ai đó” chưa đủ để cho phép thao tác trên mọi tài khoản.

Handoff: người nhận cần customer/order ID, vấn đề, nguyên nhân đã tìm được, hành động đã thực hiện, số tiền/trạng thái liên quan và đề xuất tiếp theo. Đừng giả định họ có transcript. Với yêu cầu nhiều vấn đề, phân tách để xử lý và chuyển đúng phần, rồi trả một kết quả nhất quán.

“Luôn escalate để an toàn” không đạt mục tiêu tự động hóa. “Cố giải quyết cho xong trước khi chuyển người” cũng sai khi khách đã yêu cầu người thật hoặc agent không có thẩm quyền.

Liên hệ task 3.4 · 3.5 · 3.6

Chọn cách làm theo mức chưa biết và giá của quyết định sai; không dựa duy nhất vào số file.

Plan mode: dùng để khám phá codebase, hiểu phụ thuộc, cân nhắc nhiều cách và chốt hướng trước khi sửa. Chưa biết nguyên nhân không làm plan mode trở thành sai; có thể lập kế hoạch điều tra trước rồi điều chỉnh theo findings. Giai đoạn discovery nhiều output nên giao cho Explore subagent để khỏi ăn hết context của phiên chính.

Direct execution: phù hợp khi yêu cầu, vị trí sửa và hành vi mong đợi đã rõ, phạm vi nhỏ. Một thay đổi hai file vẫn có thể cần cân nhắc kiến trúc; nhiều file giống nhau không tự tạo nhiều lựa chọn kiến trúc.

Iterative refinement: phản hồi phải chứa input cụ thể, output mong đợi và sai khác hiện tại. Các lỗi tương tác cần được mô tả cùng nhau để không sửa bên này làm hỏng bên kia. Với vấn đề độc lập có thể sửa tuần tự. Interview pattern giúp làm rõ ràng buộc chưa được nói ra trước khi implement.

Tests và context: theo Task 3.5, viết test suite trước, bao gồm hành vi mong đợi, edge cases và yêu cầu hiệu năng, rồi gửi test failures để cải thiện từng lượt. Khi mô tả bằng lời bị hiểu không nhất quán, đưa 2–3 ví dụ input/output cụ thể. Test suite định nghĩa hành vi cần giữ, nhưng test sai vẫn lái vòng lặp sai. Khi lịch sử đầy patch đã bỏ, giữ code hiện tại và kết luận còn giá trị thay vì bắt model tổng hợp mọi phương án cũ.

CI: cần chạy không tương tác, có project conventions và tiêu chí review rõ. Đưa tests/fixtures hiện có để tránh đề xuất trùng. Lượt review sau nhận findings trước đó và chỉ báo lỗi mới hoặc chưa được giải quyết.

Đừng học “plan chỉ dùng sau khi đã biết lời giải”, “cứ 45 file là plan”, hay “sau tám vòng phải viết tay”. Đây không phải các ngưỡng cố định trong guide.