6 nguyên tắc PR review được áp dụng vào toàn bộ BEUP agent workflow
User chia sẻ cách họ quản lý agent-generated PRs: evidence bắt buộc, decision log, CI gates, multi-angle review. Session này map từng nguyên tắc vào content, product, snippet, và video workflows — và implement 8 thay đổi cụ thể trên 8 files.
StatusLiveWorkflows8 files changedDate2026-06-16StackBEUP WordPress
ReasoningLập luận
6-layer thinking chainChuỗi tư duy 6 tầng
L1
Raw requestYêu cầu gốc
"tôi có thể ứng dụng lời khuyên này trong các workflow skill agent hiện tại như nào"
L2
Reframe — what was really neededDiễn giải lại — nhu cầu thật
User không hỏi về lý thuyết — họ muốn biết GAP nào đang tồn tại trong các workflows hiện có, và cách fill gap đó bằng code/config cụ thể. Câu hỏi thực sự: "Trong 6 nguyên tắc này, BEUP đang thiếu cái nào, và thiếu ở đâu?" Sau đó user chỉ ra scope quá hẹp ('nhưng sao bạn chỉ áp dụng với content') → mở rộng ra snippet, video, product launch.
L3
ConstraintsRàng buộc
• humanizer-lint.py đã có exit 1 (BLOCK) nhưng exit 2 (WARN) là soft warning — agents rewrite để 'technically pass' mà không thực sự fix
• beup-publish chỉ check 'Status: approved' — không có evidence bằng chứng gì đã được kiểm tra
• beup-plan tạo draft nhưng không capture tại sao topic được chọn
• Snippet/CSS changes không có evidence gate nào — rủi ro cao nhất (crashed site 4+ lần)
• Không có multi-angle reviewer nào trong bất kỳ workflow nào
L4
Options weighedCác lựa chọn cân nhắc
Option A — Chỉ document thành checklist thủ công: không enforce gì
Option B — Implement incremental P0→P1→P2 (chosen): mỗi thay đổi atomic và testable
Option C — Một mega-gate script bao hết tất cả: quá rigid, không phù hợp từng workflow
Option D — Tạo skill mới cho từng workflow: YAGNI, thêm complexity không cần thiết
L5
Principle invokedNguyên tắc áp dụng
"Fail fast with named gates" — mỗi gate phải có tên rõ ràng, dừng ngay tại điểm lỗi, không cho agent tiếp tục sau khi gặp sự cố
L6
Pick + recognition signalLựa chọn + dấu hiệu nhận biết
Implement 8 thay đổi theo 3 priorities:
P0: --strict flag + evidence gate trong beup-publish + decision log trong beup-plan + pre-publish-ci.sh
P1: snippet/CSS change protocol + WC product evidence gate + beup-clip strict + product-launch decision log
P2: beup-write Step 4 với 3 subagents song song
Từ chối: Option A (không enforce) và Option C (quá rigid). Recognition signal: khi muốn agent luôn làm X, nhúng X vào flow bắt buộc họ đang đi — không tạo bước optional mới.
PipelineQuy trình
8 thay đổi theo 3 priorities
1
Audit hiện trạng 4 skill files
Đọc beup-publish, beup-plan, beup-write, beup-product-launch, admin-safety-rules.md. Map 6 nguyên tắc PR review → 6 gaps trong BEUP workflows.
2
P0-A: humanizer-lint.py --strict
Thêm --strict flag: exit 2 (WARN) → exit 1 (BLOCK). Backward-compatible — scripts cũ không bị ảnh hưởng. Test với text chứa 'hết sức': exit 1 confirmed.
3
P0-B: beup-publish Evidence Gate (Step 1.5)
Thêm trước mọi REST/API call: chạy humanizer strict, verify keyword trong title/first-para/slug, state persona rationale, check captions distinct, ghi ## Evidence block vào draft file.
4
P0-C: beup-plan Decision Log
Capture WHY topic được chọn ngay khi user select (Step 4). Template draft thêm ## Decision Log section với reason/last-similar/expected/date.
5
P0-D: pre-publish-ci.sh (5 gates)
Script mới: status check → humanizer strict → slug kebab-case regex → taxonomy classification (warn-only) → captions present. Tested với real draft: catch em dashes ở draft thật.
6
P1: admin-safety-rules.md (2 gates)
Snippet/CSS Change Protocol: WHY + BEFORE state capture + single-threaded + AFTER verify + evidence block. WC Product Edit Evidence Gate: old→new + db verify + no auto-publish.
7
P1: beup-clip + beup-product-launch
beup-clip: humanizer upgrade → --strict + Pre-distribute evidence gate trước beup-video-distribute.py. beup-product-launch: Decision Log 5 fields ghi vào manifest tại P0.
8
P2: beup-write Multi-Angle Reviewer
Step 4 mới: spawn 3 Agent subagents song song. Reviewer 1: SEO/AIO lens. Reviewer 2: Reader/Humanizer lens. Reviewer 3: Business/Accuracy lens. ≥2/3 PASS mới qua GEO gate. Fix + re-run nếu FAIL.
DecisionsQuyết định
Layered decision cardsCác quyết định theo tầng
--strict là flag opt-in, không đổi default exit code
L1Humanizer WARN phải block publish — nhưng cách nào an toàn nhất?
L2Cần enforcement chặt hơn cho beup-publish nhưng các scripts khác đang dùng exit 2 = soft warning bình thường. Cần backward-compatibility.
L3• Nhiều scripts hiện tại xử lý exit 2 là non-blocking (logs, pre-commit hooks)
• Đổi default sẽ break tất cả callers ngay lập tức
• Không có test coverage cho humanizer callers
L4• Đổi exit 2 → exit 1 globally: break backward-compat, risky
• --strict flag (opt-in per call): an toàn, rõ ràng
• humanizer-lint-strict.py riêng: duplicate code (DRY violation)
• Wrap trong CI script: đúng nhưng cần flag trước
L5Backward-compatibility: đừng break cái đang chạy — thêm opt-in thay vì thay đổi default
L6Thêm --strict flag. pre-publish-ci.sh dùng --strict. Scripts cũ không bị ảnh hưởng.
Recognition signal: khi cần tighten gate mà backward-compat quan trọng → thêm flag, đừng đổi default.
Evidence gate ở Step 1.5, không phải Step 0
L1Evidence gate trong beup-publish nên đặt ở đâu trong pipeline?
L2Gate cần verify keyword presence (cần KEYWORD variable) và caption dedup (cần 3 captions). Những values này chỉ có sau khi Step 1 đọc file.
L3• KEYWORD, captions, AUTHOR_ID chỉ được extract ở Step 1
• Upload image ở Step 2 là first API call — không thể hoàn tác
• Nếu đặt trước Step 1: thiếu data để verify
L4• Step 0 (trước đọc file): không có data để verify
• Step 1.5 (sau đọc file, trước upload): đủ data, chặn trước API call
• Step 2.5 (sau upload images): quá muộn, đã tốn tiền
• Cuối cùng (Step 7+): vô nghĩa
L5Đặt gate ngay sau khi collect đủ data cần thiết, ngay trước hành động không thể hoàn tác
L6Step 1.5 — sau extract variables, trước upload image.
Recognition signal: khi thiết kế gate, hỏi 'cần data gì để verify?' → đặt gate ngay sau khi có data đó.
Taxonomy gate là warn-only (không blocking)
L1Gate 4 trong pre-publish-ci.sh — taxonomy fail có nên exit 1 không?
L2Taxonomy fail (source='none') nghĩa là post không xuất hiện trong filter chips — quality issue, không phải correctness issue. Post vẫn publish được bình thường.
L3• taxonomy_map.py return 'none' với nhiều lý do hợp lý (topic mới chưa trong mapping)
• Blocking sẽ tạo false positives khi content thực sự OK
• Taxonomy chỉ ảnh hưởng filter UI, không ảnh hưởng post availability
L4• exit 1 nếu source='none': nhiều false positive, frustrating
• Warn-only (yellow, không block): visibility mà không friction
• Skip hoàn toàn: mất visibility
• exit 1 chỉ khi Python exception: đúng — true failure vs quality gap
L5Block on correctness failures, warn on quality gaps — phân biệt 'sai' và 'chưa tốt'
L6Gate 4 warn-only. exit 1 chỉ khi taxonomy_map.py throw exception.
Recognition signal: trước khi set exit 1, hỏi 'failure này sẽ tạo false positive không?' → nếu có, dùng warn.
3 Agent subagents thực sự, không phải self-review loop
L1Multi-angle review cho beup-write: spawn Agent thật hay prompt switching?
L2User mô tả 'summon vài subagents lên để review từng angle khác nhau' và đọc reports riêng từng con. Self-review có anchoring bias — agent biết content của mình, khó thấy lỗi của chính mình.
L3• Agent subagents có context window riêng, độc lập với agent đã viết content
• Self-review với prompt switching vẫn là cùng 1 agent, cùng 1 context
• Subagents chậm hơn và tốn token hơn — nhưng đây là step trước publish, không phải hot path
L4• 3 subagents song song: độc lập, objective, chậm hơn
• Prompt switching trong 1 agent: nhanh hơn nhưng bias
• 1 subagent với system prompt dài: vẫn 1 góc nhìn
• Structured self-checklist: nhanh nhất, ít hiệu quả nhất
L5Độc lập reviewer = không có anchoring bias từ người viết — giống peer review thực sự
L63 Agent subagents song song. Mỗi con có lens rõ ràng: SEO/AIO, Reader/Humanizer, Business/Accuracy.
Recognition signal: khi review quan trọng (trước publish), dùng subagents độc lập. Quick check → self-review đủ.
Snippet protocol vào admin-safety-rules.md, không tạo skill mới
L1Snippet/CSS change protocol — đặt ở đâu trong hệ thống file?
L2Admin workflow không có skill file riêng — được trigger theo context (role=admin). admin-safety-rules.md là file admin role luôn load từ CLAUDE.md.
L3• Không có ~/.claude/skills/beup-admin/ tồn tại
• Tạo skill mới = YAGNI nếu đã có container phù hợp
• admin-safety-rules.md được load khi role=admin — đây là canonical location cho admin rules
L4• Tạo mới ~/.claude/skills/beup-admin/SKILL.md: YAGNI, thêm complexity
• Thêm vào admin-safety-rules.md: đúng ownership
• Thêm vào CLAUDE.md trực tiếp: CLAUDE.md đã dài, nên point đến files riêng
• Tạo snippet-change-protocol.md riêng: fragmented
L5Reuse before build — nếu đã có nơi đặt phù hợp, đừng tạo thêm container mới
L6Thêm 2 sections vào admin-safety-rules.md.
Recognition signal: trước khi tạo file/skill mới, hỏi 'đã có file nào đang own domain này chưa?'
FilesTệp
Artifact mapBản đồ tệp tạo ra
| PathĐường dẫn | WhatLà gì | Who reads itAi dùng |
|---|---|---|
scripts/humanizer-lint.py | Thêm --strict flag: WARN (exit 2) = BLOCK (exit 1) | beup-publish, beup-clip, pre-publish-ci.sh |
scripts/pre-publish-ci.sh (new) | 5-gate CI script: status → humanizer strict → slug kebab → taxonomy (warn) → captions | beup-publish Step 1.5 + standalone CI check |
~/.claude/skills/beup-publish/SKILL.md | Step 1.5 Evidence Gate: humanizer + keyword check + persona rationale + caption dedup + evidence block | Tất cả /beup-publish invocations |
~/.claude/skills/beup-plan/SKILL.md | Decision Log capture ở Step 4 + ## Decision Log section trong draft template | Tất cả /beup-plan invocations |
~/.claude/skills/beup-write/SKILL.md | Step 4 Multi-Angle Content Review: 3 subagents song song, ≥2/3 PASS rule | Tất cả /beup-write invocations |
~/.claude/skills/beup-clip/SKILL.md | Humanizer → --strict + Pre-distribute Evidence Gate trước beup-video-distribute.py | Tất cả /beup-clip invocations |
~/.claude/skills/beup-product-launch/SKILL.md | Decision Log 5 fields ghi vào manifest tại P0 (reason/detail/gap_filled/expected/logged_at) | Tất cả /beup-product-launch invocations |
wordpress/docs/admin-safety-rules.md | Snippet/CSS Change Protocol (WHY + BEFORE/AFTER) + WC Product Edit Evidence Gate | Admin role — load khi role=admin theo CLAUDE.md |
Self-testTự kiểm tra
Kiểm tra hiểu biết
Tại sao --strict được thêm như flag riêng thay vì đổi exit code mặc định từ 2 → 1?
Taxonomy Gate trong pre-publish-ci.sh là warn-only (không exit 1). Lý do chính là gì?
Multi-angle reviewer trong beup-write dùng 3 Agent subagents thực sự (không phải self-review) vì:
Evidence Gate trong beup-publish đặt ở Step 1.5 (sau Step 1 đọc file, trước Step 2 upload images). Giải thích tại sao không đặt ở Step 0 (đầu tiên)?
Mastery checklist — tick what you can explain unpromptedBảng tự đánh giá — tích những gì bạn tự giải thích được