ĐIỀU 20 — LUẬT THIẾT KẾ TRƯỚC TRIỂN KHAI

(Design Before Execution Law) — v1.2 FINAL BAN HÀNH

Version: v1.2 FINAL Ngày BAN HÀNH: 2026-05-04 Tác giả: GPT-5.5 Thinking / Incomex Hội đồng AI, theo chỉ đạo User Tư cách: Luật quy trình phát triển kỹ thuật của Incomex Mục tiêu: Chuẩn hóa văn hóa “có bản vẽ trước khi thi công”: mục tiêu → luật → thiết kế kỹ thuật → spike nếu cần → triển khai → đánh giá. Hiến pháp: Đã được đưa vào Điều 1 NT15 — Thiết kế Trước Triển khai.

§0. TÓM TẮT BAN HÀNH

Điều 20 quy định quy trình bắt buộc cho các thay đổi kỹ thuật có rủi ro trong Incomex.

NGUYÊN TẮC SỐ 1 — KHÔNG SÁNG TÁC HỆ THỐNG:

Trước khi thiết kế bất cứ tài liệu, schema, API, workflow, agent, vector hay runtime nào, bắt buộc phải kiểm tra hệ thống đang có gì, đọc các luật liên quan, xác nhận tình trạng hiện tại bằng evidence thật, rồi mới thiết kế.

Mọi bản thiết kế bắt buộc phải làm theo một luật đã có. Nếu thiếu luật hoặc luật chưa đủ rõ thì DỪNG LẠI VIẾT / SỬA LUẬT TRƯỚC. Không tự tiện sáng tác cấu trúc mới trong hệ thống.

Sáng tác = phá hoại.

BẮT BUỘC TRƯỚC KHI THIẾT KẾ — CONTEXT GRAPH GATE (Đ43):

Với mọi thiết kế không nhỏ, trước khi viết design phải đọc context graph mới nhất của Đ43, tối thiểu: PROJECT_MAP.md, LAWS_INDEX.md, DOT_REGISTRY.md, DB_MAP.md, RED_ZONES.md; sau đó mới resolve luật quản lý, DOT/tool bắt buộc, runtime evidence và unknowns.

Nếu chưa đi qua Context Graph Gate thì chưa được thiết kế; nếu graph/luật/tool còn thiếu hoặc không rõ thì dừng để bổ sung luật/tool/discovery trước, không tự chế.

Nguyên tắc lõi tiếp theo:

Với thay đổi quan trọng, thiết kế kỹ thuật đã review là SSOT trước code/DDL/runtime. Code không được đi trước bản vẽ.

Luật này không thay thế luật chuyên môn. Luật chuyên môn quyết định nội dung đúng; Điều 20 quyết định cách triển khai đúng.

Ví dụ:

Đ44 quyết schema information_unit; Điều 20 quyết cách thiết kế, review, backup, smoke test và đánh giá trước khi triển khai schema đó.
Đ38 quyết TAC pipeline; Điều 20 quyết cách thiết kế/triển khai từng bước để không tạo drift.
Đ43 quyết bản đồ hệ thống; Điều 20 yêu cầu current state/evidence phải được đọc trước khi execute.

Nôm na: luật chuyên môn là bản quy hoạch; Điều 20 là quy chế công trường.

§1. MỤC TIÊU

Điều 20 có 8 mục tiêu:

Mã	Mục tiêu
MT1	Ngăn code/DDL/runtime đi trước hiểu biết thật.
MT2	Ép thay đổi rủi ro phải có mục tiêu, non-goal, thiết kế, rollback, test.
MT3	Giảm hallucination của AI/Agent bằng context anchor rõ ràng.
MT4	Tạo checkpoint review độc lập trước khi execute.
MT5	Cho phép spike/POC để kiểm chứng giả định khó trước khi thiết kế bị đóng cứng.
MT6	Buộc thiết kế tính error handling, observability, rollback, không chỉ happy path.
MT7	Không quan liêu hóa việc nhỏ; áp dụng theo mức rủi ro.
MT8	Giữ roadmap liền mạch: thiết kế để triển khai nhanh hơn, không phải tạo giấy tờ vô ích.

Triết lý nền:

Code là tài sản nhưng cũng là nợ kỹ thuật. Thiết kế là khoản đầu tư. Sửa lỗi logic trên bản thiết kế mất vài phút; sửa sau khi code/DDL đã vào hệ thống có thể mất nhiều ngày và tạo regression.

§2. PHẠM VI ÁP DỤNG

Điều 20 áp dụng cho:

Schema, DDL, migration, trigger, constraint, index.
API, service, worker, agent runtime, Claude Code/Codex execution.
Vector/Qdrant/embedding/search pipeline.
Workflow nghiệp vụ, DOT, context-pack, registry/catalog.
Luật triển khai, luật hạ tầng, quy trình ảnh hưởng hệ thống.
Thay đổi production hoặc thay đổi có khả năng mất dữ liệu, drift, orphan, duplicate, phá rollback.
Các task mà AI/Agent phải suy luận nhiều bước hoặc có ranh giới scope dễ trượt.

Điều 20 không bắt full design cho việc nhỏ như sửa chính tả, patch wording, review note, hoặc checklist ngắn không chạm runtime. Những việc Tier 0 chỉ cần mini-plan nếu có rủi ro thấp.

§3. CHUỖI BẮT BUỘC

Mọi thay đổi Tier 2 trở lên phải đi theo chuỗi:

Goal / Non-goal
→ Luật & hiến pháp liên quan
→ Current state / evidence
→ Technical design
→ Review / critique
→ Spike hoặc POC nếu giả định rủi ro
→ Execution plan / prompt
→ Backup / rollback
→ Test / smoke / verify
→ Observability / error handling
→ Post-execution evaluation

Cấm đảo ngược: Không được execute trước rồi mới viết design để hợp thức hóa.

Cấm làm mù: Nếu runtime/schema/logs khác thiết kế, phải dừng và báo cáo; không tự “linh hoạt sửa rộng” khi chưa có approve.

§4. PHÂN TẦNG RỦI RO

Tier	Loại việc	Yêu cầu tối thiểu	Ai duyệt
Tier 0	Việc nhỏ, document patch, wording, review note	Mini-plan hoặc ghi rõ mục tiêu	Agent/GPT tự xử lý nếu không rủi ro
Tier 1	Config/metadata/catalog nhỏ, không DDL, rollback đơn giản	Short design + rollback + verify	GPT/Opus review
Tier 2	DDL, API, code runtime, trigger, worker, DB write có rủi ro	Full technical design + independent review + smoke test	GPT review + User approve khi chạm runtime
Tier 3	Production-critical, vector/search, schema nền, luật/hiến pháp, migration lớn	Full design + spike nếu cần + rollback + independent review + explicit User approval	User quyết định cuối

Nguyên tắc: nếu không chắc Tier nào, nâng lên Tier cao hơn.

§5. OUTPUT CHUẨN CỦA TECHNICAL DESIGN

Một technical design hợp lệ nên có các phần sau. Với Tier thấp có thể rút gọn, nhưng không được bỏ phần liên quan rủi ro thật.

Ưu tiên thời gian: thiết kế phải giúp triển khai nhanh và chắc hơn, không được biến thành thủ tục kéo dài. Với Incomex hiện tại, chi phí lớn nhất là thời gian User + số vòng điều phối GPT↔Opus↔Agent; vì vậy design cần ước lượng độ lớn công việc và số vòng approve cần thiết.

Phần	Nội dung
Goals / Non-goals	Làm gì và cố ý không làm gì — chống scope creep
Current state / evidence	Trạng thái thật từ KB/PG/runtime/report/logs, không đoán
Legal basis	Luật/hiến pháp/guardrail liên quan
System architecture	Thành phần nào tương tác với nhau, boundary ở đâu
Proposed design	Thiết kế đề xuất, luồng chính, stop condition
Data model / schema	Bảng, field, trigger, index, registry nếu có
Cross-cutting concerns	Security, privacy, scalability, data integrity, cost, latency nếu relevant
Estimated execution cost	Ước lượng gọn: thời gian, số vòng User approve, số Agent cần dùng, độ dài context/token ở mức nhỏ/vừa/lớn
Alternatives considered	Ít nhất 1 phương án bị loại với lý do
Risks / conflicts	Rủi ro kỹ thuật, xung đột luật, điểm chưa chắc
Spike / POC	Cần khi giả định lớn chưa được kiểm chứng
Execution plan	Các bước thực thi, checkpoint, hard boundaries
Backup / rollback	Cách quay lại nếu lỗi
Testing strategy	Smoke tests, negative tests, success criteria
Observability	Log, audit row, health check, metric, alert, verify query
Post-evaluation	Báo cáo kết quả, bài học, follow-up

§6. NGUYÊN TẮC THIẾT KẾ

§6.1. Thiết kế là SSOT trước triển khai

Với Tier 2–3, design đã review là nguồn sự thật điều hành execution. Claude Code/Agent không được tự mở rộng scope ngoài design.

§6.2. Evidence-first

Technical design phải bắt đầu từ trạng thái thật: KB, PG schema, report, logs, hoặc runtime investigation. Nếu không chắc, đánh dấu OPEN hoặc làm spike.

§6.3. Review độc lập

Execution pack Tier 2–3 cần review bởi GPT/Hội đồng độc lập trước runtime. Người viết prompt không tự coi prompt là pass.

Review không được chỉ “đồng ý” hình thức. Với Tier 2–3, reviewer phải nêu ít nhất 1 rủi ro, 1 giả định cần kiểm chứng, hoặc 1 câu hỏi phản biện. Design chỉ PASS khi comment chính đã được address hoặc ghi rõ là accepted risk.

§6.4. Spike khi giả định rủi ro

Nếu design phụ thuộc giả định chưa kiểm chứng — schema thật, trigger guard, vector payload, permission, latency, API behavior — phải có spike/read-only discovery trước write.

Spike không phải triển khai trá hình. Spike có câu hỏi, phạm vi, pass/fail, rollback/report riêng.

§6.5. Observability & fail gracefully

Design phải nói hệ thống biết thành công/thất bại bằng gì, lỗi ghi ở đâu, người vận hành thấy gì, rollback thế nào. Không chỉ viết happy path.

§6.6. Alternatives considered

Thiết kế Tier 2–3 phải ghi phương án bị loại và lý do. Điều này bắt buộc tư duy phản biện, tránh “phương án đầu tiên AI nghĩ ra” trở thành mặc định.

§6.7. Không quan liêu hóa việc nhỏ

Điều 20 không biến mọi việc thành đại dự án. Tier 0–1 được phép gọn. Mục tiêu là giảm rủi ro, không tăng giấy tờ.

§6.8. AI/Agent càng phải có design

AI/Agent dễ drift khi context dài. Design giúp neo mục tiêu, non-goal, law, rollback và stop condition. Prompt execution phải trích đúng design, không tự diễn giải rộng.

§6.9. Parallelism chỉ sau khi có design

Chỉ chia nhiều Agent/sub-agent làm song song khi design đã đủ rõ boundary. Không có design mà parallel = nhiều Agent cùng drift.

§7. EXECUTION PACK / PROMPT CHUẨN

Khi cần gọi Claude Code/Codex/agent runtime, execution prompt phải có tối thiểu:

Objective.
Files/docs phải đọc.
Scope được phép làm.
Prohibitions — những việc cấm làm.
Checkpoints dừng lại hỏi khi mismatch.
Backup/rollback.
Test/smoke.
Observability/verify.
Final report format.
Hard stop sau khi hoàn tất.

Nếu đụng production DB/runtime, prompt phải có câu rõ:

Nếu phát hiện runtime khác design, DỪNG và báo cáo. Không tự sửa rộng.

Nếu task quá nhỏ, không cần execution pack dài; nhưng vẫn phải nêu mục tiêu, boundary và output.

§8. SPIKE / PILOT

Spike là bước kiểm chứng giả định, không phải triển khai trá hình.

Spike hợp lệ khi:

Read-only hoặc phạm vi ghi rất nhỏ, có rollback.
Có câu hỏi kiểm chứng rõ.
Có tiêu chí pass/fail.
Có report sau spike.
Không mở rộng scope sang production rollout.

Ví dụ: trước khi đăng ký TRIGGER-GUARD, Claude Code phải inspect function/body/table registry thật để biết cơ chế đăng ký, rồi mới đề xuất write an toàn.

Pilot hợp lệ khi:

Scope nhỏ.
Success criteria rõ.
Có rollback.
Không tự scale nếu chưa có gate PASS.

§9. BACKUP, ROLLBACK, TEST, OBSERVABILITY

§9.1. Backup / rollback

Tier 2–3 phải có rollback trước execution. Với DB, phải có ít nhất một trong các cơ chế: dump, transaction rollback, reversible migration, hoặc cleanup script đã review.

§9.2. Test / smoke

Mỗi execution phải có success criteria cụ thể. Smoke test phải kiểm cả happy path và negative path nếu có guard/constraint.

Với bước execution quan trọng, áp dụng xác thực kép:

Internal evidence — output trực tiếp từ lệnh/API vừa chạy.
External evidence — lệnh read/count/query độc lập kiểm trạng thái thật sau khi chạy.

Nếu internal và external evidence lệch nhau, phải STOP và không claim DONE.

§9.3. Observability

Design phải nói sau khi triển khai biết thành công/thất bại bằng gì: log, audit row, health check, count, verify query, report, hoặc alert.

§9.4. Error handling

Design phải nói nếu từng bước fail thì:

Dừng hay tiếp tục?
Rollback bằng gì?
Ai được báo?
Data có ở trạng thái safe không?
Có cần postmortem không?

§9.5. Post-evaluation

Sau execution Tier 2–3 phải có report: làm gì, evidence pass/fail, cleanup, boundary có bị vượt không, follow-up còn lại.

Nếu Tier 2–3 fail, phải rollback, hoặc phát hiện runtime khác design, bắt buộc viết mini postmortem trước khi retry. Mini postmortem chỉ cần ngắn: sự cố, root cause, impact, fix, prevention.

§10. QUAN HỆ VỚI LUẬT KHÁC

Luật	Quan hệ với Điều 20
Điều 1 / Hiến pháp	Điều 20 đã được đưa vào NT15. Nếu xung đột, Điều 1/Hiến pháp thắng.
Đ4 / Birth	Đ4 quyết điều kiện khai sinh entity; Điều 20 quyết quy trình thiết kế/triển khai birth path.
Đ7 / Assembly First	Điều 20 yêu cầu design nêu rõ assembly/dependency trước execution.
Đ8 / Dependency	Design phải nêu dependency và stop condition.
Đ10–13 / Operations & Catalog	Design phải tính vận hành, registry/catalog, observability.
Đ14 / No Duplicate	Design phải kiểm duplicate trước khi tạo object mới.
Đ38 / TAC	Đ38 quyết văn bản quy phạm; Điều 20 quyết quy trình triển khai pipeline.
Đ43 / System Context	Điều 20 dùng context/evidence để tránh hành động mù.
Đ44 / Information Unit	Đ44 quyết schema IU; Điều 20 quyết cách design, review, execute từng pack IU.

Điều 20 không lấn chuyên môn các luật khác. Điều 20 chỉ là luật quy trình triển khai.

§11. ÁP DỤNG NGAY CHO IU-0 PACK 2

Tại thời điểm v1.1:

IU-0 Pack 1 đã PASS.
Pack 2 Readiness đã PASS.
Điều 20 đã được đưa vào Điều 1 NT15.
Pack 2 execution chưa mở.
Bước tiếp theo đề xuất là Option A — Governance cleanup only.

Theo Điều 20, Option A phải đi theo Tier 1/Tier 2 nhẹ:

Opus soạn execution design/prompt gọn.
Claude Code chỉ được inspect/read-only trước khi write.
Nếu TRIGGER-GUARD cơ chế không rõ, dừng.
Không DDL, không outbox, không Qdrant, không production units.
GPT/User duyệt trước runtime write.

Điều 20 không tự mở Pack 2 execution.

§12. ANTI-PATTERNS

Mã	Anti-pattern	Cấm vì
AP20-1	Code trước, design sau	Hợp thức hóa ngược, dễ drift
AP20-2	Design không có non-goal	Agent dễ mở rộng scope
AP20-3	Không có rollback	Production risk
AP20-4	Không có smoke test	Không biết đã đúng hay chưa
AP20-5	Dựa report thay vì đọc evidence khi có thể	Vi phạm Zero Trust
AP20-6	Full design cho việc nhỏ	Quan liêu, làm chậm vô ích
AP20-7	Spike biến thành triển khai thật	Bypass approval
AP20-8	Execution prompt không có prohibitions	Agent tự diễn giải quá rộng
AP20-9	Thiết kế chỉ có happy path	Không fail gracefully
AP20-10	Không ghi alternatives	Thiếu phản biện, dễ chọn phương án đầu tiên

§13. ENFORCEMENT

Điều 20 enforce theo 3 mức:

Mức	Áp dụng	Hành động
WARN	Tier 0–1 thiếu mini-plan	Nhắc bổ sung trong report/review
BLOCK	Tier 2 thiếu design/review/rollback/smoke	Không approve execution
CRITICAL	Tier 3 hoặc production change execute trước design/approval	Dừng, postmortem, rollback nếu cần

GPT/Hội đồng AI có quyền chặn execution nếu vi phạm Điều 20.

§14. CHANGELOG

Version	Ngày	Thay đổi
v1.0 FINAL	2026-05-04	Ban hành bản đầu. Chuẩn hóa Design Before Execution, phân tầng Tier 0–3, output technical design, execution prompt, spike, rollback/test/observability, quan hệ với IU-0 Pack 2.
v1.1 FINAL	2026-05-04	Bổ sung tinh thần Design Docs/Google-grade: Goals & Non-goals, architecture, data model, cross-cutting concerns, alternatives, observability, testing, spike/POC, error handling, review & iterate; liên kết Điều 1 NT15.
v1.2 FINAL	2026-05-04	Chắt lọc bổ sung thực dụng: ưu tiên thời gian, estimated execution cost gọn, review phải có phản biện thật cho Tier 2–3, xác thực kép internal/external evidence, mini postmortem khi rollback/fail.

Điều 20 v1.2 FINAL BAN HÀNH | Luật quy trình phát triển kỹ thuật | Dùng ngay cho IU-0 Pack 2 Option A và các triển khai tiếp theo