Prompt mục tiêu mở cho Claude Code — Chuẩn ~500x

Version: v0.5 Status: chuẩn thử nghiệm hiện tại đang áp dụng Scope: mẫu soạn prompt macro cho Agent Claude Code/Codex Default scale: ~500x

0. Mục đích

Tài liệu này định nghĩa cách soạn prompt mục tiêu mở cho Agent Claude Code/Codex.

Mục tiêu là giao cho Agent một trạng thái cần đạt, không giao từng thao tác nhỏ. Agent chịu trách nhiệm chọn cách làm trong phạm vi mục tiêu; GPT/User kiểm tra bằng PASS / PARTIAL / BLOCKED và evidence đã định nghĩa trước.

Prompt chuẩn phải có:

live survey before action;
mục tiêu rõ;
SSOT đủ để Agent không đoán;
PASS / PARTIAL / BLOCKED rõ;
forbidden rõ;
gate trước mutation;
DISCOVER-FIRST;
no-hardcode / DOT 100% / five-layer sync;
evidence đủ để kiểm tra;
Agent được tự sửa lỗi kỹ thuật trong scope.

0A. Bắt buộc đọc lại trước khi soạn prompt

Trước khi soạn bất kỳ prompt mục tiêu mở nào cho Agent Claude Code/Codex, người soạn bắt buộc phải đọc lại mục này và tự kiểm tra prompt đang viết.

Nếu prompt vi phạm một trong các điều dưới đây thì chưa được gửi cho Agent.

0A.1 Không hardcode — tuyệt đối

Prompt không được khuyến khích, hợp thức hóa hoặc bỏ qua hardcode dưới bất kỳ hình thức nào.

Cấm hardcode:

host/container/database/path nếu có thể discover;
table/view/function/trigger/route/event/config nếu có registry/catalog/DOT/SSOT;
secret/token/credential;
ID/candidate cụ thể nếu có thể chọn bằng live discovery;
magic constant nếu không phải config default có owner/purpose/lifecycle;
behavior đáng lẽ phải đến từ DOT/config/catalog.

Mọi literal quan trọng phải được Agent phân loại:

literal_classification:
  - DISCOVERED_SSOT
  - CONFIG_DEFAULT
  - REGISTRY_VALUE
  - DOT_REGISTERED_VALUE
  - TEMP_SANDBOX_ONLY
  - TEST_FIXTURE_ONLY
  - NEEDS_DOT_REGISTRATION
  - VIOLATION_TO_FIX

Nếu có VIOLATION_TO_FIX, Agent phải sửa trong scope hoặc báo exact blocker. Không được PASS khi còn hardcode chưa xử lý.

0A.2 DOT 100%

Mọi vật thể production-visible do macro tạo/sửa phải có DOT/check/scan/registry visibility.

Bao gồm table, view, function, trigger, route, worker, config key, event type, healthcheck, runbook và report artifact.

Không có DOT/check/scan visibility thì chưa được coi là production-ready. Không được scale trên vật thể vô hình.

0A.3 Tuân thủ đầy đủ nguyên tắc hiến pháp

Prompt phải buộc Agent tuân thủ các nguyên tắc nền:

PG/runtime source of truth phải được live-check;
DOT 100%;
no-hardcode;
automation-first;
discover-first/reuse-first;
evidence-first;
reversible by default;
fail-visible, không silent fail;
không tạo rác hệ thống;
không để ai phải nhớ quy trình thủ công;
không mutation ngoài gate;
không bypass guard/gateway;
không coi proposal là approved.

0A.4 Không ai phải nhớ quy trình

Prompt phải yêu cầu Agent biến quy trình lặp lại thành command package, SQL function, script, healthcheck, DOT scan, executable runbook, verification query hoặc disable/rollback package.

Không được để an toàn hệ thống phụ thuộc vào câu “sau này nhớ chạy lệnh X”.

0A.5 Điều kiện bắt buộc trước khi gửi prompt

Trước khi gửi prompt, người soạn phải tự xác nhận:

constitutional_prompt_gate:
  no_hardcode_absolute: true
  dot_100_required: true
  constitution_guardrails_included: true
  live_survey_before_action: true
  discover_first_required: true
  automation_first_required: true
  reversible_by_default: true
  evidence_first_required: true
  five_layer_sync_required_if_production_visible: true
  mutation_gates_present_if_needed: true
  forbidden_explicit: true
  pass_partial_blocked_explicit: true

Nếu chưa chắc một mục, phải sửa prompt trước. Không gửi prompt với giả định “Agent sẽ tự hiểu”.

1. Tư tưởng cốt lõi

1.1 Mục tiêu mở là gì?

Mục tiêu mở là prompt giao theo outcome:

Đưa hệ thống từ trạng thái A sang trạng thái B, trong ranh giới an toàn C, và chứng minh bằng evidence D.

Không phải:

Chạy lệnh 1, rồi lệnh 2, rồi tạo file 3.

Agent được quyền tự chọn cách làm nếu:

không vi phạm forbidden;
đạt PASS criteria;
có evidence;
có rollback/disable nếu mutation;
không tạo rác;
không hardcode;
có DOT/visibility.

1.2 Trách nhiệm thuộc về ai?

Nếu prompt khóa quá nhiều thao tác, Agent chỉ chịu trách nhiệm làm đúng checklist. Nếu outcome không đạt, lỗi nằm ở người điều hành.

Nếu prompt là mục tiêu mở đúng chuẩn, Agent chịu trách nhiệm đạt outcome hoặc báo BLOCKED với exact gap.

Prompt phải khóa mục tiêu, PASS/PARTIAL/BLOCKED, forbidden, live precheck, gate trước mutation, evidence và SSOT cần đọc. Prompt không nên khóa từng lệnh nhỏ, từng file cụ thể nếu Agent có cách tốt hơn, thứ tự branch vụn hoặc cách debug local.

Ngoại lệ: production mutation nguy hiểm phải khóa gate, rollback và stop condition.

2. Định nghĩa quy mô ~500x

2.1 1x là gì?

1x là một task nhỏ kiểu cũ: một việc hẹp, thường chỉ gồm đọc một phần nhỏ, sửa một file/lệnh/report, chạy test hẹp và báo cáo. 1x không phải macro end-to-end; nó thường không bao gồm đủ survey + implementation + proof + DOT + rollback + report.

2.2 Current experimental scale

Current experimental scale: ~500x.

Status:

120x: verified PASS.
240x: verified PASS.
480x: authoring/test/proof/report succeeded; production apply was blocked by missing pg_dump/DDL execution tool. This is treated as evidence that ~500x is feasible for Agent execution, while production apply remains gated.
Next target: run ~500x production-closeout macros. If ~500x reaches repeated full PASS including production apply, consider raising the guide later.

2.3 Vì sao ~500x?

Sau khi 120x và 240x PASS thật, macro 480x đã chứng minh Agent có thể author/test/proof/report ở quy mô này. Production apply của 480x bị chặn bởi thiếu pg_dump/DDL execution tool, không phải vì Agent không xử lý nổi scope.

Vì vậy ~500x được chấp nhận là mức thử nghiệm hiện tại và là default mới cho các macro mục tiêu mở lớn. Cách hiểu này không có nghĩa mọi production apply 500x đã PASS; production mutation vẫn phải đi qua đầy đủ gate/tool/backup/rollback/DOT/AgentData verification.

2.4 ~500x là gì?

~500x là một macro end-to-end rất lớn, thường gồm một production closeout lớn cộng với một operator-grade hardening/product slice trong cùng một mission coherent.

~500x tương đương vùng 480x/500x: khoảng hai lát cắt 240x, hoặc bốn lát cắt 120x, nhưng chỉ hợp lệ khi chúng cùng một trục sản phẩm và có thể kiểm chứng bằng cùng một hệ evidence.

Một prompt ~500x vẫn phải bao phủ các lớp liên quan:

live survey;
implementation;
production/sandbox proof;
tests;
DOT/no-hardcode/five-layer visibility;
rollback/disable;
AgentData/KB reports;
repair nếu phát hiện lỗi;
next package.

~500x không phải hàng trăm task rời rạc. Nó là kỳ vọng gom nhiều việc có chung trục mục tiêu vào một mission lớn, miễn là vẫn giữ gate, evidence, DOT và forbidden.

2.5 Scale ladder

Cách hình dung thực tế:

1x: một task nhỏ kiểu cũ, thường chỉ có đọc hẹp + sửa hẹp + test hẹp + báo cáo.
10x: một lát cắt kỹ thuật lớn, thường gồm author + test + report.
30x: một lát cắt end-to-end gồm implement + production/sandbox proof + DOT + reports + next package.
60x: hai lát cắt end-to-end liên tiếp, ví dụ vừa hoàn tất một nhóm chức năng production-safe, vừa chuẩn bị/kiểm chứng lớp tích hợp kế tiếp.
120x: hai macro 60x coherent trong một mission, tương đương khoảng bốn lát cắt 30x end-to-end.
240x: hai macro 120x coherent, chỉ hợp lệ khi cùng một trục sản phẩm và evidence không bị loãng.
480x/~500x: hai lát 240x hoặc bốn lát 120x trong một production-closeout/operator-hardening mission coherent.

2.6 Khi nào tăng/giảm quy mô?

Giữ ~500x làm mặc định thử nghiệm hiện tại.

Tăng quy mô nếu:

Agent liên tục PASS ở mức ~500x, bao gồm production apply khi có gate/tool đầy đủ;
không vi phạm forbidden;
report đủ evidence;
không phát sinh cleanup debt;
không có hardcode/DOT gap;
không có production safety debt.

Giảm quy mô hoặc tăng gate nếu:

Agent fake PASS;
nhiều PARTIAL do scope quá rộng;
thiếu evidence hoặc PASS không chứng minh được;
phát sinh hardcode/DOT/report debt;
production blast radius lớn;
thiếu SSOT;
thiếu backup/tool/rollback để apply production;
nhiều architecture ruling chưa chốt.

Bigger scale does not weaken safety. Scale increase is valid only if no hardcode/DOT/report/production safety debt appears. Production apply must not proceed without backup, target identity, rollback, DOT, and AgentData verification. If macro returns PARTIAL due to real gate/tool blocker, do not mislabel it PASS.

3. Cấu trúc prompt chuẩn

# MISSION: <MACRO_NAME>

Effort: high.
Target working block: 45–60 phút hoặc hơn nếu macro được định nghĩa rõ.
Primary host: <host chính>.
Remote host: <host phụ nếu có>.

## GOAL_MODE_CHECK
<Trạng thái hiện tại + mục tiêu chuyển trạng thái>

## HOST
<Host bắt buộc + WRONG_EXECUTION_ENVIRONMENT>

## READ TECHNICAL SSOT
<Report/KB/repo path cần đọc>

## CONSTITUTION / DOT GUARDRAILS
<No hardcode, DOT 100%, five-layer, automation-first, reversible, evidence-first>

## OBJECTIVE
<Mục tiêu mở ~500x>

## NARROW PRODUCTION APPROVAL FOR THIS MACRO
<Nếu có production mutation: scope hẹp được phép>

## MANDATORY GATES BEFORE ANY PRODUCTION MUTATION
<Gate bắt buộc trước mutation>

## DISCOVER-FIRST
<Nguyên tắc tự tìm artifact/secret/path/report>

## PASS CRITERIA
<Định nghĩa PASS/PARTIAL/BLOCKED>

## FORBIDDEN
<List cấm rõ>

## FINAL OUTPUT
<Agent phải báo cáo gì + upload ở đâu>

4. Các phần bắt buộc

4.1 GOAL_MODE_CHECK

Phải nói rõ hệ thống đang ở trạng thái nào, macro trước đã làm gì, macro này cần đạt trạng thái nào và đây là open-goal macro, không phải checklist nhỏ.

4.2 HOST

Phải chỉ định rõ host. Không để Agent tự đoán host.

Primary host: MacBook/dev host.
Repo: <repo path>

If repo unavailable or host is wrong, STOP with WRONG_EXECUTION_ENVIRONMENT.

VPS is only remote target for live survey, backup, gated production DB mutation, and verification.

4.3 READ TECHNICAL SSOT

Chỉ đưa tài liệu kỹ thuật/SSOT: latest final report, next macro package, repo paths, roadmap kỹ thuật nếu cần, production package/report nếu liên quan.

Không đưa GPT handoff nếu đó chỉ là ghi chú điều hành nội bộ.

4.4 CONSTITUTION / DOT GUARDRAILS

Luôn nhúng phần này:

1. NO HARDCODE — ABSOLUTE
Every literal route/config/table/event/function/path/host/container/db/value must be discovered from SSOT/config/registry/catalog or classified.

2. DOT 100%
Every new production-visible object must have DOT/check/scan/registry visibility.

3. FIVE-LAYER SYNC
Classify impact on PG, Directus, Nuxt, AgentData/KB, Qdrant/vector.

4. AUTOMATION-FIRST
No safety condition may depend on a human remembering a sequence.

5. REVERSIBLE BY DEFAULT
Every mutation path must have disable/rollback/cleanup/verification.

6. EVIDENCE-FIRST
PASS requires exact counts, healthchecks, tests, report paths, and commit hash.

4.5 OBJECTIVE

Viết outcome lớn, không viết micro-step. Agent may choose exact implementation path. Do not stop after one small success if safe work remains.

5. Gate trước mutation

Chỉ gate cứng khi có production DB write, production DDL/schema mutation, CUT execution, VERIFY execution có tác dụng production, deploy/restart, merge/push/tag, source/schema mutation rủi ro, dry_run=false/downstream delivery, lifecycle mutation hoặc destructive cleanup.

Mẫu gate:

MANDATORY GATES BEFORE ANY PRODUCTION MUTATION

All must PASS:

1. Correct host.
2. Target identity confirmed.
3. Fresh backup with sha/hash verification.
4. Fresh drift check clean.
5. No-hardcode/DOT/five-layer baseline clean.
6. Candidate selected by live discovery, not hardcoded.
7. Operation bounded and reversible.
8. Rollback/disable/cleanup exists before apply.
9. No forbidden side effect can occur.
10. Post-change verification exists.
11. AgentData/KB verification path exists and is readable.

If any gate fails:
- do not perform that production mutation;
- continue all safe repo/sandbox/non-mutating work;
- return exact blocker;
- do not label gate/tool-blocked production apply as PASS.

6. DISCOVER-FIRST

Agent không được yêu cầu User cung cấp artifact/path/secret/backup/approval nếu có thể tự kiểm tra/tạo/tra cứu trong phạm vi quyền hạn đã có.

Trước khi tạo mới bất kỳ artifact/module/backup/config/secret reference nào, Agent phải kiểm tra KB/SSOT, repo, VPS/path chuẩn, production DB/catalog nếu liên quan, GSM/secret store hoặc secret mount nếu là secret/credential, logs/reports trước đó nếu là approval/report artifact.

Nếu đã có, xác minh version/hash/shape/quyền/scope, reuse nếu hợp lệ, không tạo duplicate. Nếu không hợp lệ thì báo rõ vì sao không dùng.

Secret/credential: tìm trong secret store/mount hiện có, không yêu cầu User paste secret, không log secret value, chỉ ghi secret ref/presence proof nếu cần. Nếu thiếu thì STOP_AND_ESCALATE với exact missing secret reference.

7. PASS / PARTIAL / BLOCKED

PASS

PASS cần evidence đủ cho người kiểm tra xác nhận.

Return <MACRO_PASS> if:
- live survey completed;
- gates passed where needed;
- target outcome achieved;
- no-hardcode remains clean;
- DOT scan passes;
- five-layer sync updated;
- rollback/disable ready;
- tests pass;
- commit/report complete;
- no forbidden action happened;
- production apply, if in scope, had backup/tool/rollback/DOT/AgentData verification.

PARTIAL

Dùng khi có tiến triển thật nhưng còn một gap lớn.

Return <MACRO_PARTIAL_WITH_EXACT_GAP> if:
- useful progress was made;
- one major proof/mutation remains blocked by real gate/tool/SSOT gap;
- no unsafe production state remains;
- blocker is reported exactly.

BLOCKED

Chỉ dùng sau khi Agent đã làm hết nhánh an toàn.

Return <BLOCKED_WITH_EXACT_GATE_GAP> only if:
- wrong host;
- unsafe repo;
- target identity uncertain;
- backup unavailable;
- required secret unavailable;
- required execution tool unavailable;
- all meaningful safe work is blocked.

Không BLOCKED chỉ vì một nhánh bị chặn nếu còn nhánh an toàn khác.

8. Forbidden mẫu

FORBIDDEN

- No action outside approved scope.
- No dry_run=false unless explicitly approved.
- No downstream workflow delivery unless explicitly approved.
- No production CUT execution unless explicitly approved.
- No broad lifecycle mutation.
- No ungoverned IU creation.
- No destructive cleanup.
- No deploy/restart unless explicitly approved.
- No persistent production daemon/service start unless explicitly approved.
- No cron activation unless explicitly approved.
- No execution_enabled flip unless explicitly approved.
- No secret logging.
- No push/merge/tag unless explicitly approved.
- No GPT handoff as task input unless explicitly designated SSOT.
- No metadata-only KB update with empty content.
- No fake PASS.
- Do not stop early if safe work remains.

Forbidden phải cụ thể theo macro.

9. FINAL OUTPUT bắt buộc

Agent phải báo cáo final status, what changed, repo path/branch/HEAD before-after/commit, production backup/gate result nếu mutation happened, live survey result, no-hardcode/DOT/five-layer result, key implementation/proof result, rollback/disable readiness, tests, KB reports uploaded, exact blockers nếu có và exact next macro.

Nếu có production mutation, thêm backup path, backup size/hash, target identity, before/after counts, rollback/disable package và post-change verification.

10. KB update safety

Khi cập nhật tài liệu trong AgentData/KB:

Không thực hiện metadata-only update với content rỗng.
Nếu cần đổi title/tags, gửi kèm full content không rỗng hoặc dùng patch tool an toàn.
Sau bất kỳ KB update nào, verify:
- document exists;
- content_length is non-trivial;
- title/version/default scale correct;
- list_documents works;
- search_knowledge finds the updated guide.

Nếu một bước verify fail, không được báo PASS; báo PARTIAL/BLOCKED với exact gap.

11. Effort

default_effort: high

Dùng high khi macro có nhiều nhánh nhưng scope rõ, Agent đã chứng minh năng lực tốt và không cần suy luận kiến trúc quá mơ hồ.

Dùng xhigh khi cần quyết định kiến trúc sâu, hệ thống mới chưa rõ, production/security blast radius lớn, refactor lớn hoặc nhiều SSOT chưa ổn định.

Dùng medium cho read-only survey, cleanup nhỏ, report-only, patch rất rõ. Không dùng effort thấp cho production mutation.

12. Host

MacBook/dev host

Dùng khi cần sửa repo, viết test, commit, đọc source, tạo package hoặc điều phối nhiều artifact.

VPS

VPS chỉ là remote target cho live survey, backup, production DB gated mutation và verification.

Không bắt đầu trên VPS nếu macro cần repo MacBook.

13. Mẫu prompt ngắn dùng lại

# MISSION: <MACRO_NAME>

Effort: high.
Target working block: 45–60 phút hoặc theo macro scope.
Primary host: MacBook/dev host.
Remote host: VPS only via SSH if explicitly needed.

## GOAL_MODE_CHECK
<Current verified state from latest report.>

Mục tiêu phiên này không phải một bước nhỏ.
Mục tiêu là đưa hệ thống từ <state A> sang <state B>, đồng thời hoàn tất các lớp liên quan: <layer 1>, <layer 2>, <layer 3>, <layer 4>.

Đây là open-goal macro. Agent chịu trách nhiệm đạt trạng thái cuối, không chỉ làm checklist.

## HOST
Start on MacBook/dev host:
<repo path>

If repo unavailable or host is wrong, STOP with WRONG_EXECUTION_ENVIRONMENT.

VPS is only remote target for live survey, backup, gated production DB mutation, and verification.

## READ TECHNICAL SSOT
Read technical SSOT, not GPT handoff:
- <latest final report>
- <latest next macro package>
- <relevant repo paths>

## CONSTITUTION / DOT GUARDRAILS
1. NO HARDCODE — ABSOLUTE.
2. DOT 100%.
3. FIVE-LAYER SYNC.
4. AUTOMATION-FIRST.
5. REVERSIBLE BY DEFAULT.
6. EVIDENCE-FIRST.

## OBJECTIVE
Reach the best safe end-state in one coherent ~500x macro:
1. <Production closeout outcome>
2. <Operator-grade hardening/product slice>
3. Refresh DOT/no-hardcode/five-layer after changes.
4. Add/extend tests.
5. Prepare rollback/disable/cleanup.
6. Commit local repo changes if tests pass.
7. Upload complete KB reports.
8. Produce next package.

Agent may choose exact implementation path. Do not stop after one small success if safe work remains.

## MANDATORY GATES BEFORE ANY PRODUCTION MUTATION
All must PASS before production mutation. If any gate fails, do not perform that production mutation; continue safe work and report PARTIAL/BLOCKED exactly.

## DISCOVER-FIRST
Do not ask User for path/secret/artifact if discoverable. Search KB/SSOT, repo, production catalog, VPS paths, reports/logs before creating anything. Reuse valid existing artifacts. Do not log secrets.

## PASS CRITERIA
Return <MACRO_PASS> if target outcome achieved with evidence, tests, reports, and no forbidden action.
Return <MACRO_PARTIAL_WITH_EXACT_GAP> if useful progress was made but one major gate/tool/proof gap remains.
Return <BLOCKED_WITH_EXACT_GATE_GAP> only if all meaningful safe work is blocked.

## FORBIDDEN
- No action outside approved scope.
- No destructive cleanup.
- No deploy/restart unless explicitly approved.
- No production execution outside gated scope.
- No secret logging.
- No push/merge/tag unless explicitly approved.
- No GPT handoff as task input unless explicitly designated SSOT.
- No metadata-only KB update with empty content.
- No fake PASS.
- Do not stop early if safe work remains.

## FINAL OUTPUT
Report final status, changes, repo HEAD, gates, evidence, tests, KB reports, blockers, and exact next macro.

Upload reports to:
<KB_REPORT_PATH>

STOP and route to GPT/User.

14. Checklist trước khi gửi prompt

prompt_review:
  has_goal_mode_check: true
  has_host: true
  has_live_survey_requirement: true
  has_ssot_list: true
  has_open_goal_objective: true
  has_pass_partial_blocked: true
  has_forbidden: true
  has_discover_first: true
  has_mutation_gates_if_needed: true
  has_no_hardcode_guardrail: true
  has_dot_100_guardrail: true
  has_five_layer_sync: true
  has_final_output_format: true
  avoids_micro_steps: true
  allows_agent_autonomy: true

Nếu thiếu một mục, chưa gửi.

15. Checklist sau khi Agent báo cáo

report_review:
  final_status_matches_allowed_values: true
  live_survey_done: true
  gates_passed_or_blocked_exactly: true
  no_forbidden_action: true
  evidence_present: true
  backup_hash_if_mutated: true
  tests_present: true
  commit_hash_present_if_repo_changed: true
  kb_reports_uploaded: true
  dot_nohardcode_fivelayer_checked: true
  rollback_disable_ready: true
  next_macro_specific: true

Nếu report thiếu evidence, không chấp nhận PASS ngay; yêu cầu repair/report gap trong macro tiếp theo.

16. Quy tắc cập nhật chuẩn ~500x

Sau mỗi 3–5 macro ở mức ~500x, đánh giá:

Agent có hoàn thành coherent macro không?
Production apply có PASS thật khi gate/tool đầy đủ không?
Có vi phạm forbidden không?
Có report thiếu evidence không?
Có cleanup debt không?
Có hardcode/DOT gap không?
Có production incident hoặc near-miss không?

Nếu tất cả tốt và production apply PASS lặp lại, có thể cân nhắc nâng quy mô mặc định. Nếu có lỗi, giảm quy mô hoặc tăng gate.

17. Tóm tắt

Prompt mục tiêu mở chuẩn ~500x phải trả lời đủ 6 câu:

Muốn đạt trạng thái nào?
Agent cần đọc SSOT nào?
Agent được tự quyết trong phạm vi nào?
Cái gì tuyệt đối không được làm?
Thế nào là PASS / PARTIAL / BLOCKED?
Cần evidence gì để User/GPT kiểm tra?

Nếu prompt không trả lời đủ 6 câu này, chưa đạt chuẩn.