Trả lời ngắn: AI System Design Document là tài liệu giúp team thống nhất problem, boundary, architecture, contract, decision, evidence, risk và cách vận hành trước khi build. Một document tốt nói rõ system không làm gì, giả định nào chưa kiểm và gate nào cho phép release; nó không chỉ liệt kê model, API và box trong diagram.

Đọc xong, bạn sẽ hiểu:

  • Design document khác component catalog hoặc diagram đẹp ở đâu.
  • Cách viết goal, non-goal, boundary và contract cho AI workflow.
  • Cách ghi alternative, assumption, evidence, safety và rollback.
  • Cách dùng một template miễn phí để tạo bản draft có thể review.

Lưu ý giáo dục: Case support copilot, ID và metric là dữ liệu giả. Không đưa production credential, customer transcript, private prompt hoặc secret vào bài tập. Design document thật cần review theo risk, privacy, security và quy định của tổ chức.

1. Design doc phải trả lời câu hỏi nào?

Một design document mô tả problem, design, decision, risk và evidence cần review. Nó không phải bản cam kết mọi chi tiết đã đúng. Với support copilot DES-25, câu hỏi đầu tiên là: team đang muốn hỗ trợ việc gì, cho ai, và kết quả nào được xem là tốt?

Mục Ví dụ giả Không nên viết
Problem Route request đến queue phù hợp “Dùng AI để cải thiện support”
User Agent support và reviewer “Tất cả mọi người”
Goal Gợi ý queue và evidence policy “Tự động hóa toàn bộ”
Non-goal Không refund, không đổi account Bỏ trống giới hạn
Success Accuracy theo slice + handoff an toàn “Model thông minh”
Owner TEAM-DESIGN-25 “Team sẽ xử lý”

Goal có thể đo; non-goal bảo vệ boundary. Nếu không nói “không refund” thì người đọc có thể tưởng tool action được phép. Boundary là ranh giới system làm gì và không làm gì; nó gồm capability, data, permission, environment và human handoff.

Hình 1 — Một design doc nối problem, boundary, architecture, evidence và decision để reviewer biết cần hỏi gì.

Document cũng cần phần status: DRAFT, IN_REVIEW, APPROVED, HOLD hoặc SUPERSEDED; reviewer, date, open question và version. APPROVED không có nghĩa risk bằng zero. Nó nghĩa decision hiện tại có owner, scope và evidence đủ cho gate hiện tại.

2. Boundary, architecture và contracts

Sau problem, viết context và boundary trước khi chọn component. Case DES-25 nhận request, tìm policy, tạo queue suggestion và có thể route human. Nó không được thực hiện side-effect action. Data flow: intake → redaction → retrieval → model → classifier → reviewer/tool boundary → response → trace.

Component Input/output Contract cần khóa Human boundary
Intake request class → safe envelope schema, redaction, correlation ID reject nếu thiếu consent
Retrieval query → policy snippets source/version, freshness reviewer khi source conflict
Model context → suggestion prompt/model/output schema không tự hành động
Tool boundary suggestion → allowed action permission, approval, audit high-impact bắt buộc approve
Evidence event → trace/eval record retention, owner, access redact raw content

Contract là thỏa thuận input, output, schema và owner giữa components. Contract làm design review cụ thể: field nào required, field nào nullable, lỗi nào block, version nào compatible. Nếu tool trả queue nhưng parser chờ category, document phải ghi migration hoặc block; đừng vẽ mũi tên rồi giả định tự khớp.

Hình 2 — Boundary map làm rõ data/tool contract và cửa human approval trước side effect.

Architecture diagram nên trả lời flow và ownership, không cần nhồi mọi implementation detail. Mỗi box có trách nhiệm, input/output, failure mode và source of truth. Ghi dependency external, data freshness, quota, secret boundary và fallback. Nếu một dependency chưa được kiểm, label là UNKNOWN hoặc NOT_VERIFIED.

3. Decision record và alternatives

ADR là bản ghi decision, alternatives và lý do. Design doc không nên viết “chúng ta dùng agent vì agent hiện đại”. Hãy ghi decision DEC-25-01: chọn bounded workflow cho queue routing; lý do là path predictable, permission dễ giới hạn, replay đơn giản và human approval rõ.

Option Lợi ích Trade-off Evidence cần
Bounded workflow predictable, dễ audit ít linh hoạt fixed eval, failure map
General agent linh hoạt tool path khó bound, khó replay tool guardrail, trace
Human-only risk thấp hơn ở start capacity và latency queue capacity, policy

Assumption là điều tạm coi đúng nhưng cần kiểm: policy source có freshness dưới 24 giờ; reviewer có thể xử lý high-impact trong SLA; output schema đủ để queue system đọc. Mỗi assumption có owner, test hoặc ngày review. Assumption không được viết như fact.

Decision record nên có context, options, constraints, chosen option, rejected option, evidence, risk, owner, date và reversibility. Decision reversible có canary/rollback đơn giản; schema hoặc permission change có thể khó quay lại hơn, cần approval và migration plan.

Hình 3 — Decision tốt nói rõ vì sao chọn, điều gì bị từ chối và evidence nào có thể làm decision đổi.

OpenAI Agents guide mô tả tools, guardrails, state và tracing trong agent workflow; Azure AI architecture patterns cung cấp cách nghĩ về reliability, security, performance và operations. Link nguồn giúp reviewer mở rộng câu hỏi, nhưng không thay thế evidence workload của team. OpenAI Agents guide và Azure AI architecture patterns

4. Evaluation, safety và operations

Evaluation là cách đo quality, safety và operational behavior. Design doc cần nói test set nào, slice nào, baseline nào, failure nào và gate nào. Case có clear request, mixed-language, policy conflict, tool schema error và high-impact handoff. Average score không đủ nếu một slice rủi ro fail.

Area Question Evidence/gate
Quality Suggestion đúng queue và grounded? fixed eval + slice report
Safety Side effect có bị chặn? approval/handoff cases
Privacy Trace có raw PII không? redaction/access review
Reliability Timeout/retry/fallback ra sao? failure replay + SLO
Operations Ai nhận alert và rollback? runbook + owner

Safety case là chuỗi claim, evidence và control cho safety. Claim “high-impact không tự refund” cần policy, tool permission, negative test, human route và audit event. Không viết “an toàn” như một adjective không có evidence.

Operations section ghi deploy environment, observability fields, alert, incident severity, release gate, rollback artifact, on-call owner và retention. Rollback là quay về known-good design/config khi change gây regression; cần biết version nào, dữ liệu nào invalidate và verify sau rollback.

NIST AI RMF Core nhấn mạnh risk management theo vòng đời. Đưa risk vào design sớm giúp team chọn test và approval trước khi component đã khó đổi. NIST AI RMF Core

5. Sai lầm, giới hạn và fallback

  • Component catalog: liệt kê model/API nhưng không có problem, boundary hay decision. Fallback: mở đầu bằng goal/non-goal và owner.
  • Diagram theater: mũi tên đẹp nhưng không input/output/error. Fallback: contract table và failure case.
  • Vague success: “quality tốt”. Fallback: metric, slice, baseline và floor.
  • Hidden assumption: freshness, quota hoặc reviewer capacity chưa kiểm. Fallback: assumption ledger, owner và date.
  • No alternative: design trông như lựa chọn duy nhất. Fallback: ADR có ít nhất hai option và trade-off.
  • Late safety: chỉ hỏi permission khi chuẩn bị release. Fallback: safety case từ boundary/design.
  • False precision: điền số đo chưa có evidence. Fallback: UNKNOWN, NOT_VERIFIED và kế hoạch đo.
  • Scope creep: document biến thành toàn bộ roadmap. Fallback: out-of-scope, decision log và linked follow-up.

Design doc cũng có giới hạn: tài liệu có thể stale khi code, policy hoặc provider thay đổi; diagram không quan sát được runtime; review nhóm có thể bỏ qua rare failure; owner có thể đổi. Vì vậy document cần version, last-reviewed date, change trigger và link tới trace/eval/report. Khi design và runtime lệch, mở design change, không âm thầm sửa một bên.

6. Practice Bridge 15 phút

Mở Notes, Google Docs hoặc Google Sheets miễn phí. Tạo các heading Problem, Goal, Non-goal, Boundary, Option, Decision, Evidence, Risk, Owner, Gate, Rollback. Dùng request giả; không gọi model thật.

Mẫu đối chiếu đã điền

Card Nội dung giả Trạng thái
Problem Route support request, không side effect In scope
Decision Bounded workflow + human approval DEC-25-01
Assumption Policy freshness < 24h NOT_VERIFIED, TEAM-DESIGN-25
Evidence Fixed eval + mixed/high-impact slices Planned
Gate Safety handoff 100%, trace redacted Hold until tested

Trong 15 phút, viết một non-goal, một assumption, một evidence link giả và một rollback condition. Stop condition: nếu chưa chỉ ra ai approve, metric nào quyết định và component nào ngoài boundary, giữ status HOLD thay vì gọi document ready.

7. Tổng kết: design doc là hợp đồng quyết định

a. Năm ý chính

  • Design doc bắt đầu từ problem, user, goal, non-goal và owner; không bắt đầu từ tên model.
  • Boundary và contract nói rõ system làm gì, không làm gì và components giao nhận ra sao.
  • ADR ghi alternatives, assumptions, constraints, evidence, risk và reversibility.
  • Evaluation, safety case, observability, release gate và rollback phải xuất hiện trước build xong.
  • UNKNOWN/NOT_VERIFIED có owner và kế hoạch kiểm là trung thực hơn số đo bịa.

b. Câu hỏi tự kiểm tra

  • Non-goal bảo vệ design khỏi rủi ro nào?
  • Contract khác diagram ở điểm nào?
  • Vì sao assumption cần owner và ngày review?
  • Khi nào design document nên giữ HOLD?

c. Gợi ý đáp án

Xem gợi ý câu 1

Non-goal khóa việc system không được làm, chẳng hạn không refund hoặc không tự side effect. Xem lại mục 1 và mục 2.

Xem gợi ý câu 2

Diagram cho thấy flow; contract quy định input/output/schema/owner/error và điều kiện reject để flow có thể phối hợp thật. Xem lại mục 2.

Xem gợi ý câu 3

Owner và review date biến điều chưa chắc thành việc cần kiểm, tránh assumption bị quên rồi trở thành fact. Xem lại mục 3.

Xem gợi ý câu 4

Giữ `HOLD` khi boundary, safety, evidence, owner hoặc rollback chưa đủ rõ để review/release. Xem lại mục 4 và mục 5.

d. Thuật ngữ cần nhớ

Thuật ngữ Giải thích ngắn
Design document Tài liệu mô tả problem, design, decision, risk và evidence.
Boundary Ranh giới system làm gì và không làm gì.
Contract Thỏa thuận input/output/schema/owner giữa components.
ADR Bản ghi quyết định kiến trúc, alternatives và lý do.
Assumption Điều tạm coi đúng nhưng cần kiểm chứng.
Decision Lựa chọn có owner, constraints và evidence.
Evaluation Cách đo quality, safety và operational behavior.
Safety case Chuỗi claim, evidence và control cho safety.
Rollback Quay về known-good design/config khi change gây regression.

e. Nguồn tham khảo

Bài trước là Production AI Operating System #24. Bài tiếp theo là Xây Evaluation Harness #26.

Lưu ý giáo dục: Một design doc chỉ nên mở release khi boundary, evidence, safety owner và rollback đã có trạng thái rõ. Nếu còn assumption quan trọng chưa kiểm, giữ HOLD và ghi kế hoạch kiểm.