Day 16 - GitHub workflow với Claude Code

1. Mục tiêu bài học

Sau khoảng 2 tiếng, học viên có thể:

• Tạo feature branch từ main mới nhất và giữ PR nhỏ, đúng phạm vi.
• Dùng Claude Code để đọc git status, git diff, staged diff và PR diff mà không giao quyền quyết định merge cho AI.
• Viết commit message rõ ràng theo Conventional Commits.
• Dùng Claude Code tạo Pull Request description trung thực với diff và test evidence.
• Dùng Claude Code review diff trước commit và trước merge, nhưng vẫn bắt buộc human review.
• Phân biệt manual Claude Code trong terminal, Claude Code GitHub Actions và Claude Code Code Review.
• Thiết kế guardrails cho protected branch hoặc GitHub rulesets: required PR, approving review, status checks, conversation resolution, block force push, block deletion.
• Biết rollback khi branch, commit, PR hoặc merge có vấn đề.

2. Bối cảnh thực tế

Khi taskflow-ai bắt đầu có backend, frontend, database migration, test và CI, làm trực tiếp trên main sẽ tạo nhiều rủi ro:

• Dễ đưa code lỗi vào branch chính.
• Khó biết thay đổi nào thuộc feature nào.
• PR quá lớn làm reviewer bỏ sót bug.
• Commit message mơ hồ làm rollback chậm.
• PR description nói quá so với test evidence.
• AI có thể tóm tắt sai diff nếu context thiếu hoặc diff quá rộng.

Workflow GitHub an toàn dùng branch riêng, Pull Request, automated checks và human review. Claude Code hữu ích ở các bước có tính phân tích và tổng hợp:

• Đọc git status --short và phân loại file.
• Tóm tắt git diff --stat trước khi review sâu.
• Review diff tìm bug, thiếu test, security risk, maintainability risk.
• Đề xuất commit message.
• Viết PR body theo template.
• So sánh PR description với diff để tránh nói quá.

Claude Code không phải người chịu trách nhiệm cuối cùng. Human vẫn phải đọc diff, hiểu requirement, kiểm tra test evidence, đánh giá risk và quyết định merge. Nếu team dùng Claude Code GitHub Actions hoặc Claude Code Code Review, đó vẫn là reviewer phụ trợ; không được thay thế required human approval.

Không nên dùng Claude Code để tự động push, approve hoặc merge khi:

• Diff có thay đổi security, auth, permission, billing hoặc migration.
• Working tree đang có file ngoài phạm vi task.
• Có secret hoặc production credential trong diff.
• CI fail, checks pending hoặc chưa có test evidence.
• PR description chưa khớp với diff thực tế.

3. Kiến thức nền

Branch strategy

Với taskflow-ai, dùng workflow đơn giản:

main
  -> feature/github-workflow-pr-template

Quy tắc:

• main chỉ chứa code đã hoàn thành, đã review và đã pass checks bắt buộc.
• Mỗi feature, fix hoặc tài liệu lớn dùng branch riêng.
• Branch nhỏ và tập trung vào một mục tiêu.
• Không gom docs, refactor, config và feature không liên quan vào cùng PR.
• Không push trực tiếp vào main.
• Không force push lên branch dùng chung. Nếu cần sửa history trên branch cá nhân, ưu tiên --force-with-lease thay vì --force.

Tên branch tốt:

feature/github-workflow-pr-template
feature/task-priority-filter
fix/task-filter-empty-state
docs/pr-template
chore/update-ci-lint

Tên branch kém:

test
update
new-code
final-final

Commit message

Format khuyến nghị:

type(scope): short description

Ví dụ:

docs(github): add pull request template
feat(tasks): add priority filter
fix(api): reject empty task title
ci(test): run lint on pull requests

Commit message tốt giúp reviewer hiểu thay đổi và giúp rollback đúng commit. Không dùng message như update, changes, fix stuff.

Pull Request description

PR description tốt trả lời:

• Thay đổi gì?
• Vì sao cần?
• Đã test gì?
• Rủi ro gì?
• Rollback thế nào?
• Có ảnh hưởng security, performance, cost, context hoặc maintainability không?

Template khuyến nghị cho taskflow-ai:

## Summary

## Changes

## Test Plan

## Risk

## Rollback

## Security

## Performance / Cost / Context

## Maintainability

Không viết “All tests passed” nếu chưa chạy test. Nếu chỉ đổi markdown/template, có thể ghi git diff --check và nói rõ application tests không chạy vì documentation-only hoặc workflow-only.

Claude Code trong GitHub workflow

Có ba cách dùng thường gặp:

Với khóa học này, thực hành chính dùng Claude Code trong terminal vì dễ kiểm soát quyền, dễ quan sát diff và không cần cài GitHub App. Claude Code GitHub Actions và Code Review là phần mở rộng cho team thật, cần kiểm tra docs chính thức trước khi bật vì permission, trigger, pricing và availability có thể thay đổi.

Protected branch và rulesets

Protected branch hoặc GitHub rulesets giúp bảo vệ main:

• Require a pull request before merging.
• Require approving reviews.
• Dismiss stale approvals khi diff thay đổi, nếu team cần review lại sau push mới.
• Require status checks to pass before merging.
• Require branches to be up to date before merging, nếu team muốn giảm rủi ro merge trên base cũ.
• Require conversation resolution before merging.
• Require linear history nếu team chọn squash/rebase.
• Block force pushes.
• Restrict deletions hoặc không bật allow deletion cho branch chính.
• Restrict who can push hoặc bypass nếu repo quan trọng.

Lưu ý quan trọng: yêu cầu “Pull Request before merging” không tự động đồng nghĩa với “có approval”. Nếu cần human review, phải bật required approvals hoặc Code Owners riêng.

Mục tiêu của guardrails không phải làm chậm team, mà là giảm rủi ro merge nhầm, bỏ qua review hoặc mất lịch sử.

4. Step-by-step thực hành

Thực hành trên project taskflow-ai. Giả định repo nằm ở:

taskflow-ai/
  backend/
  frontend/
  .github/
  docs/

Nếu repo của bạn đặt ở thư mục khác, thay taskflow-ai bằng path thực tế. Mỗi block lệnh bên dưới ghi rõ thư mục chạy, output kỳ vọng, rủi ro và rollback.

Bước 1: Kiểm tra trạng thái repo

Thư mục chạy: root taskflow-ai.

git status --short
git branch --show-current

Lệnh làm gì:

• git status --short hiển thị file modified, added, deleted, untracked.
• git branch --show-current xác nhận branch hiện tại.

Output kỳ vọng nếu working tree sạch:

main

git status --short sạch sẽ không in gì. Nếu có thay đổi:

 M frontend/src/pages/tasks.tsx
?? notes.md

Rủi ro:

• Tạo branch khi working tree bẩn có thể kéo theo thay đổi ngoài phạm vi.
• File untracked như .env, log hoặc notes cá nhân có thể bị stage nhầm.

Prompt cho Claude Code:

Hãy đọc output `git status --short` và branch hiện tại.
Phân loại:
- File nào thuộc task hiện tại
- File nào có vẻ ngoài phạm vi
- Có dấu hiệu secret, `.env`, log hoặc build artifact không
- Tôi có nên tạo branch/commit bây giờ không
- Nếu chưa nên, bước xử lý an toàn là gì

Không chỉnh file, không chạy git command thay tôi.

Rollback:

• Nếu chỉ mới phát hiện working tree bẩn, chưa cần rollback.
• Nếu đã stage nhầm file, dùng git restore --staged <path> sau khi chắc chắn file đó không thuộc commit.

Bước 2: Đồng bộ main

Thư mục chạy: root taskflow-ai.

git checkout main
git pull origin main

Lệnh làm gì:

• git checkout main chuyển về branch chính.
• git pull origin main lấy commit mới nhất từ remote.

Output kỳ vọng:

Already up to date.

Hoặc fast-forward nếu remote có commit mới.

Rủi ro:

• Nếu đang có local change chưa commit, git checkout main có thể bị chặn hoặc mang thay đổi sang main.
• Nếu git pull tạo conflict, không chọn đại ours hoặc theirs.

Rollback:

git merge --abort

Dùng khi git pull tạo merge conflict. Nếu team dùng pull rebase:

git rebase --abort

Bước 3: Tạo feature branch

Thư mục chạy: root taskflow-ai.

git checkout -b feature/github-workflow-pr-template
git branch --show-current

Output kỳ vọng:

feature/github-workflow-pr-template

Rủi ro:

• Branch name quá chung làm khó hiểu PR.
• Branch tạo từ main cũ tạo diff hoặc conflict không cần thiết.

Rollback nếu tạo nhầm và chưa commit:

git checkout main
git branch -D feature/github-workflow-pr-template

Bước 4: Tạo thay đổi nhỏ trong taskflow-ai

Mục tiêu: thêm PR template và ghi chú workflow cho repo.

Thư mục chạy: root taskflow-ai.

mkdir -p .github docs

Output kỳ vọng: lệnh không in gì nếu tạo thư mục thành công.

Rủi ro:

• Lệnh chỉ tạo thư mục, rủi ro thấp.
• Trên Windows PowerShell, có thể dùng New-Item -ItemType Directory -Force .github, docs.

Rollback nếu tạo nhầm và thư mục còn rỗng:

rmdir .github docs

Prompt implement cho Claude Code:

Trong repo taskflow-ai, hãy tạo hoặc cập nhật đúng 2 file:
- .github/pull_request_template.md
- docs/github-workflow.md

Nội dung cần có:
- PR template gồm Summary, Changes, Test Plan, Risk, Rollback, Security, Performance / Cost / Context, Maintainability
- docs/github-workflow.md mô tả branch strategy, commit message, PR review, protected branch guardrails
- Ghi rõ Claude Code review không thay thế human review
- Không thêm workflow tự động, không cài GitHub App, không sửa file khác

Sau khi sửa, dừng lại và tóm tắt file đã thay đổi. Không commit, không push.

Output kỳ vọng sau khi Claude sửa:

 M .github/pull_request_template.md
 M docs/github-workflow.md

Rủi ro:

• Claude có thể sửa thêm file ngoài phạm vi.
• Claude có thể viết PR template nói quá như “All tests passed”.
• Claude có thể thêm workflow .github/workflows/* dù chưa được yêu cầu.

Rollback nếu Claude sửa sai:

git diff --name-only
git restore .github/pull_request_template.md docs/github-workflow.md

Chỉ chạy git restore khi chắc chắn muốn bỏ toàn bộ thay đổi local ở các file đó.

Bước 5: Kiểm tra phạm vi diff

Thư mục chạy: root taskflow-ai.

git diff --stat
git diff --name-only
git diff --check

Lệnh làm gì:

• git diff --stat cho biết file nào đổi và mức độ đổi.
• git diff --name-only xác nhận phạm vi file.
• git diff --check tìm trailing whitespace hoặc whitespace error.

Output kỳ vọng:

.github/pull_request_template.md
docs/github-workflow.md

git diff --check không in gì khi không có lỗi whitespace.

Rủi ro:

• Có file ngoài phạm vi như .env, lockfile hoặc generated file.
• Whitespace error trong markdown có thể làm CI hoặc review khó đọc.

Prompt review scope:

Review output `git diff --stat`, `git diff --name-only`, và `git diff --check`.
Tập trung vào:
1. Có đúng 2 file dự kiến không
2. Có file secret, `.env`, generated file, lockfile hoặc build artifact không
3. Có whitespace error không
4. Có nên tiếp tục review diff sâu không

Không chỉnh file.

Rollback:

• Nếu có file ngoài phạm vi đã bị sửa nhầm, xem diff từng file trước khi restore.
• Nếu file chứa secret, không chỉ restore; rotate secret ngay vì secret có thể đã vào terminal/session/log.

Bước 6: Dùng Claude Code review diff trước commit

Thư mục chạy: root taskflow-ai.

git diff

Prompt:

Review git diff hiện tại ở chế độ read-only.

Tập trung vào:
1. PR template có đủ Summary, Changes, Test Plan, Risk, Rollback, Security, Performance / Cost / Context, Maintainability không
2. docs/github-workflow.md có đúng workflow cho taskflow-ai không
3. Có nhầm lẫn giữa Claude Code review và human review không
4. Có guardrail cho protected branch/rulesets không
5. Có command hoặc hướng dẫn nào nguy hiểm, thiếu rollback, hoặc gây hiểu nhầm không
6. Có security risk như secret, token, production data không

Output theo format:
## Findings
## Suggested fixes
## Questions

Không chỉnh file, không stage, không commit.

Output kỳ vọng:

## Findings

No blocking findings.

## Suggested fixes

- ...

## Questions

- ...

Rủi ro:

• Claude có thể bỏ sót vấn đề nếu diff dài.
• Claude có thể đưa suggestion không phù hợp với team convention.

Rollback:

• Không cần rollback nếu Claude chỉ review read-only.
• Nếu Claude tự sửa dù prompt cấm, chạy lại git diff --name-only và xử lý như Bước 5.

Bước 7: Chạy validation

Thư mục chạy: root taskflow-ai.

Nếu chỉ đổi markdown/template:

git diff --check

Output kỳ vọng: không in gì.

Nếu thay đổi code frontend/backend:

npm run lint
npm test
npm run typecheck

Output kỳ vọng:

... no lint errors
... tests passed
... typecheck passed

Rủi ro:

• Chạy full test suite có thể tốn thời gian.
• Không chạy test nhưng ghi “passed” trong PR là sai sự thật.
• Nếu repo dùng workspace như backend/ và frontend/, cần chạy đúng package manager script thực tế.

Rollback:

• Không rollback vì test fail; đọc lỗi trước.
• Nếu validation fail do thay đổi của bạn, sửa nhỏ nhất và chạy lại.

Prompt debug khi check fail:

Đây là output validation fail.
Hãy giải thích:
- Nguyên nhân gốc có thể là gì
- File nào liên quan
- Fix nhỏ nhất là gì
- Test nào cần chạy lại

Không sửa file cho đến khi tôi xác nhận.

Bước 8: Stage và commit

Thư mục chạy: root taskflow-ai.

git status --short
git add .github/pull_request_template.md docs/github-workflow.md
git diff --cached --stat

Lệnh làm gì:

• git status --short kiểm tra working tree trước khi stage.
• git add ... chỉ stage 2 file đúng phạm vi.
• git diff --cached --stat kiểm tra staged diff.

Output kỳ vọng:

 .github/pull_request_template.md | ...
 docs/github-workflow.md          | ...

Prompt đề xuất commit message:

Dựa trên staged diff, đề xuất 3 commit message theo Conventional Commits.
Ràng buộc:
- Dưới 72 ký tự nếu có thể
- Không dùng từ mơ hồ như update, changes, fix stuff
- Scope phù hợp với taskflow-ai GitHub workflow
- Không commit giúp tôi

Commit:

git commit -m "docs(github): add pull request workflow guide"

Output kỳ vọng:

[feature/github-workflow-pr-template <sha>] docs(github): add pull request workflow guide

Rủi ro:

• Stage nhầm file ngoài phạm vi.
• Commit message nói sai nội dung.

Rollback commit nếu chưa push:

git reset --soft HEAD~1

Lệnh này bỏ commit cuối nhưng giữ thay đổi trong working tree. Không dùng git reset --hard trừ khi bạn chắc chắn muốn xóa thay đổi local.

Bước 9: Push branch

Thư mục chạy: root taskflow-ai.

git push -u origin feature/github-workflow-pr-template

Output kỳ vọng:

branch 'feature/github-workflow-pr-template' set up to track 'origin/feature/github-workflow-pr-template'

Rủi ro:

• Push lên remote sai nếu branch name nhầm.
• Nếu token/credential GitHub cấu hình sai, push fail.

Rollback nếu push nhầm branch:

git push origin --delete feature/github-workflow-pr-template

Chỉ xóa remote branch khi chắc chắn branch chưa được người khác dùng.

Bước 10: Viết PR description bằng Claude Code

Thư mục chạy: root taskflow-ai.

git diff main...HEAD --stat
git log --oneline main..HEAD

Prompt:

Viết Pull Request description cho branch hiện tại dựa trên diff `main...HEAD`.

Template bắt buộc:
## Summary
## Changes
## Test Plan
## Risk
## Rollback
## Security
## Performance / Cost / Context
## Maintainability

Ràng buộc:
- Không nói đã chạy test nếu chưa có bằng chứng
- Nếu chỉ đổi tài liệu/template, ghi rõ documentation-only/workflow-only
- Test Plan phải liệt kê command thực tế đã chạy hoặc ghi Not run kèm lý do
- Rollback phải cụ thể
- Không tự tạo claim về approval, CI pass hoặc human review

PR body tốt:

## Summary

Adds a GitHub workflow guide and pull request template for `taskflow-ai`.

## Changes

- Adds `.github/pull_request_template.md` with required review sections.
- Adds `docs/github-workflow.md` covering branch strategy, commit messages, PR review, and protected branch guardrails.
- Documents that Claude Code review is advisory and does not replace human review.

## Test Plan

- [x] Ran `git diff --check`.
- [ ] Not run: application tests because this is documentation-only/workflow-only.

## Risk

Low. The change does not modify application runtime behavior.

## Rollback

Revert this PR, or remove `.github/pull_request_template.md` and `docs/github-workflow.md` in a follow-up PR.

## Security

No secrets, tokens, credentials, or production data added.

## Performance / Cost / Context

No runtime performance impact. The PR template may slightly increase review effort but improves review evidence.

## Maintainability

Keeps PR expectations explicit for future contributors.

Rủi ro:

• Claude có thể viết PR body quá lạc quan.
• Claude có thể nói test đã pass dù chỉ thấy command gợi ý.

Rollback:

• Sửa PR body trước khi tạo PR hoặc cập nhật PR description sau khi tạo.

Bước 11: Tạo PR bằng GitHub CLI

Điều kiện: đã cài và đăng nhập GitHub CLI.

Thư mục chạy: root taskflow-ai.

gh auth status

Output kỳ vọng:

Logged in to github.com account ...

Tạo PR draft:

gh pr create \
  --base main \
  --head feature/github-workflow-pr-template \
  --title "docs(github): add pull request workflow guide" \
  --body-file pr-body.md \
  --draft

Output kỳ vọng:

https://github.com/owner/taskflow-ai/pull/123

Nếu cần reviewer:

gh pr create \
  --base main \
  --head feature/github-workflow-pr-template \
  --title "docs(github): add pull request workflow guide" \
  --body-file pr-body.md \
  --reviewer username

Rủi ro:

• pr-body.md có thể chứa text nháp chưa review.
• Tạo PR không draft khi chưa sẵn sàng có thể kích hoạt CI hoặc auto review tốn cost.
• Nếu repo có Claude Code GitHub Actions hoặc Code Review bật auto trigger, mỗi PR/push có thể tạo chi phí và comment tự động.

Rollback:

gh pr close --delete-branch

Chỉ dùng khi PR tạo nhầm và branch không còn cần thiết.

Bước 12: Review PR trước merge

Thư mục chạy: root taskflow-ai.

gh pr view
gh pr diff
gh pr checks

Lệnh làm gì:

• gh pr view xem metadata, reviewer, status.
• gh pr diff xem diff thực tế trên PR.
• gh pr checks xem CI/status checks.

Output kỳ vọng:

All checks were successful

Hoặc danh sách check đang pass/fail/pending.

Prompt review trước merge:

Review PR diff hiện tại trước merge ở chế độ read-only.

Tập trung vào:
- Bug hoặc behavior regression
- Thiếu test hoặc validation
- Security risk
- Maintainability risk
- Performance/cost/context impact
- File ngoài phạm vi
- PR description có trung thực với diff không
- Rủi ro rollback
- Protected branch guardrails có bị bypass không

Output bắt buộc:
## Findings
## Questions
## Recommendation

Recommendation phải là một trong ba:
- Ready after human approval
- Needs changes before merge
- Blocked

Không merge, không push, không sửa file.

Chỉ merge khi:

• Human reviewer approve.
• Required checks pass.
• Branch không conflict.
• PR body trung thực với diff và test evidence.
• Không có secret hoặc production data trong diff.
• Protected branch/ruleset không bị bypass.

Rủi ro:

• Claude nói “Ready” nhưng chưa thấy business context hoặc reviewer expectation.
• Checks có thể pass nhưng manual test hoặc security review vẫn thiếu.

Rollback sau merge:

git checkout main
git pull origin main
git checkout -b revert/github-workflow-pr-template
git revert <merge_or_squash_commit_sha>
git push -u origin revert/github-workflow-pr-template
gh pr create --base main --head revert/github-workflow-pr-template --title "revert: GitHub workflow guide" --body "Reverts the GitHub workflow guide change."

Nếu main được bảo vệ, dùng revert PR thay vì push trực tiếp.

5. Prompt mẫu nên dùng

Prompt khám phá codebase và Git state

Hãy khảo sát repo taskflow-ai ở chế độ read-only.
Đọc:
- git status --short
- git branch --show-current
- git diff --stat
- package scripts hoặc README nếu cần biết validation command

Trả lời:
- Repo đang ở branch nào
- Working tree sạch hay bẩn
- File nào thuộc phạm vi task GitHub workflow
- File nào có vẻ ngoài phạm vi hoặc có rủi ro secret/generated artifact
- Command validation phù hợp nhất là gì

Không chỉnh file, không stage, không commit, không push.

Prompt lập plan

Lập plan cho PR nhỏ thêm GitHub workflow guide vào taskflow-ai.

Ràng buộc:
- Chỉ sửa `.github/pull_request_template.md` và `docs/github-workflow.md`
- Không thêm GitHub Actions workflow
- Không cài GitHub App
- Phải có branch strategy, commit message, PR description, Claude Code review advisory, protected branch/rulesets, rollback
- Mỗi bước nêu command, thư mục chạy, output kỳ vọng, rủi ro

Chỉ lập plan, chưa implement.

Prompt implement

Implement plan đã thống nhất.

Chỉ được tạo/sửa:
- .github/pull_request_template.md
- docs/github-workflow.md

Nội dung phải cụ thể cho taskflow-ai, có security, maintainability, performance/cost/context, rollback.
Không stage, không commit, không push.
Sau khi sửa, chạy `git diff --name-only` và báo cáo nếu có file ngoài phạm vi.

Prompt review

Review git diff hiện tại trước commit.
Tìm bug, regression, thiếu test, security issue, maintainability issue, performance/cost/context issue, command nguy hiểm, claim không có bằng chứng.
Chỉ ra file, vấn đề, failure mode, severity và suggested fix.
Không chỉnh file.

Prompt viết test/validation và PR evidence

Dựa trên staged diff, hãy đề xuất validation tối thiểu trước PR.

Yêu cầu:
- Nếu documentation-only, nêu vì sao `git diff --check` là đủ và app tests có thể Not run
- Nếu có code/runtime change, nêu lint/test/typecheck cụ thể theo script trong repo
- Viết Test Plan trung thực cho PR description
- Đề xuất 3 commit message theo Conventional Commits

Không chạy command, không commit.

6. Trade-offs

Claude review nhanh và tốt cho checklist, nhưng human review hiểu business context, release timing và risk appetite. Không dùng Claude để auto-approve hoặc auto-merge.

Protected branch/rulesets chặt giảm rủi ro production nhưng có thể làm prototype chậm hơn. Với repo học cá nhân, tối thiểu nên yêu cầu PR và block force push/delete trên main. Với repo team, thêm required approvals, required checks, conversation resolution và Code Owners cho khu vực nhạy cảm.

7. Best practices

• Luôn chạy git status --short trước branch, commit, push, merge.
• Tạo branch từ main mới nhất.
• Đặt tên branch rõ nghĩa và gắn với một mục tiêu.
• Giữ diff nhỏ, tập trung.
• Review diff bằng mắt trước khi hỏi Claude.
• Dùng Claude Code review read-only trước commit và trước merge.
• Không để Claude tự push, approve hoặc merge nếu human chưa đọc diff.
• Không commit secret, token, .env, log chứa credential hoặc production data.
• PR description phải trung thực với test evidence.
• Với UI change, thêm screenshot hoặc manual test notes nếu phù hợp.
• Với logic change, có test hoặc test plan rõ.
• Nếu conflict, resolve có chủ đích; không chọn đại ours/theirs.
• Sau merge, delete branch đã merge nếu team không cần giữ.
• Không bypass protected branch trừ incident rõ ràng và có audit note.
• Nếu dùng Claude Code GitHub Actions, lưu API key trong GitHub Secrets, giới hạn workflow permissions và review output trước merge.
• Nếu dùng Claude Code settings cho repo, deny đọc file nhạy cảm.

Ví dụ .claude/settings.json cho repo có secret local:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(gh pr merge *)"
    ]
  }
}

Nếu lỡ commit secret:

1. Dừng push/merge.
2. Rotate secret ngay.
3. Xóa secret khỏi repo.
4. Audit log, CI output và nơi secret có thể đã lộ.
5. Thêm .gitignore, secret scanning hoặc pre-commit guard.

Rollback chưa đủ cho secret leakage vì secret có thể đã bị ghi vào remote, CI log hoặc AI session.

8. Performance / cost / context

Claude Code review diff lớn có thể tốn context và bỏ sót chi tiết. Tối ưu bằng cách review theo lớp:

git diff --stat
git diff --name-only main...HEAD
git diff -- path/to/file
git diff --check

Prompt tiết kiệm context:

Trước tiên chỉ đọc `git diff --stat` và `git diff --name-only main...HEAD`.
Cho biết file nào cần review sâu, file nào có thể bỏ qua vì generated hoặc ít rủi ro.
Sau đó chờ tôi chọn file để review chi tiết.

Không paste lockfile, generated file hoặc build artifact dài nếu không cần. Nếu có secret trong diff, xem là blocking issue và rotate secret.

Cost cần chú ý:

• Claude Code trong terminal tốn token theo lượng context, diff và số vòng sửa.
• Claude Code GitHub Actions tốn GitHub Actions minutes và API/subscription usage tùy cấu hình.
• Claude Code Code Review có thể chạy theo trigger PR/push/manual; review mỗi push trên PR lớn sẽ tốn hơn.
• @claude review once phù hợp khi chỉ cần second opinion một lần, còn auto review every push phù hợp với repo có guardrails và budget rõ.

Cách giảm cost/context:

• Chia PR nhỏ.
• Review --stat trước khi review full diff.
• Không yêu cầu Claude đọc toàn repo nếu chỉ cần 2 file.
• Dùng CLAUDE.md ngắn gọn cho quy tắc ổn định, không nhồi tutorial dài.
• Dùng REVIEW.md nếu team có Claude Code Code Review và muốn rule review riêng, nhưng giữ file này ngắn.

Rollback sau merge bằng squash commit:

git revert <squash_commit_sha>

Nếu protected branch không cho push trực tiếp, tạo revert PR.

9. Checklist cuối bài

• Tôi hiểu vì sao không làm trực tiếp trên main.
• Tôi tạo được feature branch từ main mới nhất.
• Tôi dùng git status --short trước commit.
• Tôi xem git diff --stat, git diff --name-only, git diff --check.
• Tôi dùng Claude Code review diff ở chế độ read-only.
• Tôi chạy validation phù hợp và không ghi test evidence giả.
• Tôi viết commit message rõ theo Conventional Commits.
• Tôi push branch lên remote đúng tên.
• Tôi dùng Claude Code viết PR description có Summary, Changes, Test Plan, Risk, Rollback, Security, Performance / Cost / Context, Maintainability.
• Tôi biết dùng gh pr create, gh pr diff, gh pr checks, gh pr view.
• Tôi hiểu Claude review không thay thế human review.
• Tôi biết protected branch/rulesets nên chặn gì.
• Tôi biết rollback branch, commit, PR và merge có vấn đề.
• Tôi biết secret leakage cần rotate secret, không chỉ revert.

10. Bài tập

Bài cơ bản: trong taskflow-ai, tạo feature branch feature/github-workflow-pr-template từ main mới nhất và xác nhận bằng git branch --show-current.

Bài thực tế: thêm .github/pull_request_template.md và docs/github-workflow.md, chạy git diff --check, commit bằng message rõ, viết PR description bằng Claude Code.

Bài nâng cao: dùng gh pr diff và gh pr checks, sau đó yêu cầu Claude review PR read-only trước merge. Nếu team có Claude Code Code Review, so sánh finding của Claude trên PR với review thủ công và ghi điểm AI bỏ sót.

Bài reflection: viết 10-15 dòng giải thích Claude Code giúp gì trong GitHub workflow, điều gì Claude không được tự quyết, protected branch/rulesets cần guardrail nào, và khi nào nên dùng revert PR.

Tài liệu

Tóm tắt kiến thức

GitHub workflow an toàn cho taskflow-ai:

latest main
  -> feature branch
  -> focused change
  -> local validation
  -> Claude Code read-only review
  -> commit
  -> push
  -> Pull Request
  -> checks
  -> Claude Code PR diff review
  -> human review
  -> merge
  -> delete branch or create revert PR if needed

Nguyên tắc cốt lõi:

• main là branch ổn định, được bảo vệ bằng protected branch hoặc rulesets.
• Mỗi thay đổi nằm trong branch riêng, nhỏ và đúng phạm vi.
• Commit message rõ, dễ tìm và dễ rollback.
• PR description phải trung thực với diff và test evidence.
• Claude Code hỗ trợ review, tóm tắt, viết PR body và kiểm tra checklist; không thay thế human review.
• Claude Code GitHub Actions hoặc Claude Code Code Review là automation phụ trợ, cần kiểm soát secrets, permission, trigger và cost.
• Protected branch/rulesets nên yêu cầu PR, approving review, status checks, conversation resolution, block force push và block deletion.

Command cốt lõi, chạy ở root taskflow-ai:

git status --short
git checkout main
git pull origin main
git checkout -b feature/github-workflow-pr-template
git diff --stat
git diff --name-only
git diff --check
git add .github/pull_request_template.md docs/github-workflow.md
git diff --cached --stat
git commit -m "docs(github): add pull request workflow guide"
git push -u origin feature/github-workflow-pr-template
gh pr create --base main --head feature/github-workflow-pr-template --title "..." --body-file pr-body.md --draft
gh pr view
gh pr diff
gh pr checks

Expected output quan trọng:

• git status --short không in gì khi working tree sạch.
• git branch --show-current in đúng branch hiện tại.
• git diff --check không in gì khi không có whitespace error.
• gh pr create trả về URL PR.
• gh pr checks hiển thị trạng thái pass/fail/pending của checks.

Sơ đồ tư duy hoặc luồng xử lý

Start
  -> git status --short
  -> classify existing changes
  -> checkout main
  -> pull origin main
  -> create feature branch
  -> implement focused change
  -> git diff --stat + git diff --name-only + git diff --check
  -> Claude read-only review
  -> run validation
  -> stage exact files
  -> inspect staged diff
  -> commit
  -> push branch
  -> Claude writes PR description
  -> create draft PR
  -> gh pr checks + gh pr diff
  -> Claude read-only PR review
  -> human review
  -> merge only if approved and checks pass
  -> delete branch or revert via PR if needed

Mind map:

GitHub workflow với Claude Code
├── Branch strategy
│   ├── main ổn định
│   ├── feature branch nhỏ
│   ├── branch name rõ nghĩa
│   └── không push trực tiếp vào main
├── Commit
│   ├── Conventional Commits
│   ├── staged diff trước commit
│   └── message dễ rollback
├── Pull Request
│   ├── Summary
│   ├── Changes
│   ├── Test Plan
│   ├── Risk
│   ├── Rollback
│   ├── Security
│   ├── Performance / Cost / Context
│   └── Maintainability
├── Claude Code
│   ├── summarize git status
│   ├── review diff read-only
│   ├── write PR body
│   ├── compare PR body with diff
│   └── không approve hoặc merge thay human
└── Guardrails
    ├── require PR
    ├── required approvals
    ├── required checks
    ├── conversation resolution
    ├── block force push
    └── restrict deletion

Bảng so sánh

Lỗi thường gặp

1. Tạo branch khi working tree bẩn

git status --short có file cũ, rồi branch mới mang theo thay đổi ngoài phạm vi.

2. Branch tạo từ main cũ

Không git pull origin main trước khi tạo branch, dẫn tới conflict muộn hoặc PR diff lạ.

3. Stage quá rộng

Dùng git add . làm stage cả .env, notes cá nhân, generated files hoặc thay đổi của task khác.

4. Commit message mơ hồ

update, fix, changes không giúp review hoặc rollback.

5. PR description nói quá

Ghi “All tests passed” dù chưa chạy test. Cách đúng: ghi command đã chạy hoặc Not run kèm lý do.

6. Claude tự tin nhưng thiếu context

Claude không biết toàn bộ business intent, history hoặc production impact. Human vẫn đọc diff.

7. Merge khi checks pending/fail

gh pr checks còn fail hoặc pending thì chưa merge.

8. Force push sai

Dùng --force làm mất commit người khác. Nếu thật cần trên branch cá nhân, dùng --force-with-lease.

9. Nhầm “required PR” với “required approval”

Yêu cầu PR không tự động bắt buộc có approving review. Cần bật required reviews riêng.

10. Lỡ đưa secret vào diff

Không chỉ revert. Phải rotate secret và audit nơi secret có thể đã lộ.

Cách debug

PR diff có file lạ:

git diff --name-only main...HEAD
git log --oneline main..HEAD

Unstage file không liên quan:

git restore --staged path/to/file

Bỏ thay đổi local ở file không liên quan:

git restore path/to/file

Chỉ dùng git restore path/to/file khi chắc chắn muốn bỏ thay đổi local ở file đó.

PR conflict:

git fetch origin
git diff HEAD...origin/main --stat
git rebase origin/main

Nếu rebase sai:

git rebase --abort

Checks fail:

gh pr checks
gh pr view
npm run lint
npm test
npm run build

Prompt debug:

Checks đang fail. Dựa trên log lỗi này, hãy giải thích nguyên nhân gốc, file liên quan, và đề xuất fix nhỏ nhất. Không sửa file cho đến khi tôi xác nhận.

PR description không khớp diff:

So sánh PR description với `gh pr diff`.
Chỉ ra câu nào không đúng, thiếu bằng chứng, hoặc cần sửa để trung thực hơn.
Không sửa file.

Lỡ commit secret:

1. Dừng push/merge.
2. Rotate secret ngay.
3. Xóa secret khỏi code.
4. Audit terminal output, CI log, PR diff và nơi secret có thể đã lộ.
5. Thêm .gitignore, secret scanning, pre-commit guard hoặc .claude/settings.json deny rules.

Ví dụ deny rule cho Claude Code:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

Rollback commit chưa push:

git reset --soft HEAD~1

Rollback PR đã merge:

git checkout main
git pull origin main
git checkout -b revert/github-workflow-pr-template
git revert <merge_or_squash_commit_sha>
git push -u origin revert/github-workflow-pr-template
gh pr create --base main --head revert/github-workflow-pr-template --title "revert: GitHub workflow guide" --body "Reverts the GitHub workflow guide change."

Link tài liệu nên đọc

• Claude Code Best Practices: https://code.claude.com/docs/en/best-practices
• Claude Code settings và permissions: https://code.claude.com/docs/en/settings
• Claude Code GitHub Actions: https://code.claude.com/docs/en/github-actions
• Claude Code Code Review: https://code.claude.com/docs/en/code-review
• GitHub CLI gh pr: https://cli.github.com/manual/gh_pr
• GitHub Pull Requests: https://docs.github.com/en/pull-requests
• Creating a pull request: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
• Managing protected branches: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches
• GitHub rulesets available rules: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets
• About status checks: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks

Bài tập

Bài 1 — Cơ bản

Mục tiêu: tạo feature branch đúng cách từ main mới nhất trong taskflow-ai.

Thư mục chạy: root taskflow-ai.

git status --short
git branch --show-current
git checkout main
git pull origin main
git checkout -b feature/github-workflow-pr-template
git branch --show-current

Output kỳ vọng:

feature/github-workflow-pr-template

git status --short nên không in gì trước khi tạo branch. Nếu có output như:

 M frontend/src/pages/tasks.tsx
?? notes.md

chưa nên tạo branch ngay. Hỏi Claude:

Hãy đọc output `git status --short` của tôi và phân loại:
- Thay đổi nào thuộc task hiện tại
- Thay đổi nào ngoài phạm vi
- Có file secret, `.env`, log, build artifact hoặc generated file không
- Tôi có nên tạo branch mới bây giờ không
- Nếu chưa nên, đề xuất bước xử lý an toàn

Không chỉnh file, không stage, không commit.

Rủi ro:

• Branch mới có thể mang theo thay đổi ngoài phạm vi nếu working tree bẩn.
• git pull có thể tạo conflict nếu local main lệch remote.

Rollback nếu tạo nhầm branch nhưng chưa commit:

git checkout main
git branch -D feature/github-workflow-pr-template

Rollback nếu git pull tạo conflict:

git merge --abort

Nếu team dùng pull rebase:

git rebase --abort

Bài 2 — Thực tế

Mục tiêu: dùng Claude Code tạo thay đổi nhỏ, kiểm tra diff, viết commit message và Pull Request description dựa trên diff thật.

Yêu cầu:

1. Trong taskflow-ai, tạo hoặc cập nhật đúng 2 file:
   • .github/pull_request_template.md
   • docs/github-workflow.md
2. PR template phải có: Summary, Changes, Test Plan, Risk, Rollback, Security, Performance / Cost / Context, Maintainability.
3. Workflow guide phải có: branch strategy, commit message, PR description, Claude Code read-only review, human review, protected branch/rulesets, rollback.
4. Không thêm GitHub Actions workflow trong bài này.
5. Không commit secret, .env, token hoặc production data.

Thư mục chạy: root taskflow-ai.

mkdir -p .github docs

Trên Windows PowerShell có thể dùng:

New-Item -ItemType Directory -Force .github, docs

Prompt implement:

Trong repo taskflow-ai, hãy tạo hoặc cập nhật đúng 2 file:
- .github/pull_request_template.md
- docs/github-workflow.md

Nội dung cần có:
- PR template gồm Summary, Changes, Test Plan, Risk, Rollback, Security, Performance / Cost / Context, Maintainability
- docs/github-workflow.md mô tả branch strategy, commit message, PR description, Claude Code review advisory, human review, protected branch/rulesets, rollback
- Ghi rõ Claude Code review không thay thế human review
- Không thêm workflow tự động, không cài GitHub App, không sửa file khác

Sau khi sửa, dừng lại và tóm tắt file đã thay đổi. Không stage, không commit, không push.

Kiểm tra diff:

git diff --stat
git diff --name-only
git diff --check

Output kỳ vọng:

.github/pull_request_template.md
docs/github-workflow.md

git diff --check không in gì nếu không có whitespace error.

Prompt review trước commit:

Review git diff hiện tại ở chế độ read-only.

Tập trung vào:
- Nội dung có đúng mục tiêu GitHub workflow cho taskflow-ai không
- PR template có đủ sections không
- Có nhầm Claude Code review thành human approval không
- Có thiếu risk, rollback, security, maintainability, performance/cost/context không
- Có command nào nguy hiểm hoặc thiếu thư mục chạy/output kỳ vọng không
- Có file ngoài phạm vi không

Trả về Findings, Suggested fixes, Questions.
Không chỉnh file, không stage, không commit.

Validation:

git diff --check

Nếu bài của bạn có đổi code runtime ngoài yêu cầu, phải chạy thêm script phù hợp của repo, ví dụ:

npm run lint
npm test
npm run typecheck

Stage đúng file:

git status --short
git add .github/pull_request_template.md docs/github-workflow.md
git diff --cached --stat

Prompt commit message:

Dựa trên staged diff, đề xuất 3 commit message theo Conventional Commits.
Ràng buộc:
- Dưới 72 ký tự nếu có thể
- Không dùng từ mơ hồ như update, changes, fix stuff
- Không commit giúp tôi

Commit:

git commit -m "docs(github): add pull request workflow guide"

Push:

git push -u origin feature/github-workflow-pr-template

Prompt PR body:

Dựa trên diff `main...HEAD`, hãy viết PR description cho GitHub.

Template bắt buộc:
## Summary
## Changes
## Test Plan
## Risk
## Rollback
## Security
## Performance / Cost / Context
## Maintainability

Ràng buộc:
- Ngắn gọn, cụ thể
- Không nói đã chạy test nếu chưa có bằng chứng
- Nếu chỉ đổi tài liệu/template, ghi rõ documentation-only/workflow-only
- Có command validation cụ thể
- Không tự claim CI pass hoặc human review approve

Tạo PR draft bằng GitHub CLI:

gh auth status
gh pr create \
  --base main \
  --head feature/github-workflow-pr-template \
  --title "docs(github): add pull request workflow guide" \
  --body-file pr-body.md \
  --draft

Expected PR body:

## Summary

Adds a GitHub workflow guide and pull request template for `taskflow-ai`.

## Changes

- Adds `.github/pull_request_template.md` with required review sections.
- Adds `docs/github-workflow.md` covering branch strategy, commit messages, PR review, and protected branch guardrails.
- Documents that Claude Code review is advisory and does not replace human review.

## Test Plan

- [x] Ran `git diff --check`.
- [ ] Not run: application tests because this is documentation-only/workflow-only.

## Risk

Low. The change does not modify application runtime behavior.

## Rollback

Revert this PR, or remove `.github/pull_request_template.md` and `docs/github-workflow.md` in a follow-up PR.

## Security

No secrets, tokens, credentials, or production data added.

## Performance / Cost / Context

No runtime performance impact. The PR template may slightly increase review effort but improves review evidence.

## Maintainability

Keeps PR expectations explicit for future contributors.

Rủi ro:

• Claude có thể sửa file ngoài phạm vi.
• git add . có thể stage nhầm file khác; bài này yêu cầu stage exact files.
• PR draft có thể kích hoạt automation nếu repo đã bật GitHub Actions hoặc Claude Code Code Review.

Rollback:

git reset --soft HEAD~1

Dùng nếu đã commit nhưng chưa push và muốn sửa lại commit.

gh pr close --delete-branch

Dùng nếu PR tạo nhầm và branch không còn cần thiết.

Bài 3 — Nâng cao

Mục tiêu: dùng Claude Code review PR diff trước merge nhưng human vẫn là owner cuối.

Nếu đã có PR:

gh pr view
gh pr diff
gh pr checks

Nếu chưa có PR:

git diff main...HEAD --stat
git diff main...HEAD

Prompt:

Review PR diff hiện tại trước merge ở chế độ read-only.

Tập trung vào:
- Bug hoặc behavior regression
- Thiếu test hoặc validation
- Security risk
- Maintainability risk
- Performance/cost/context impact
- File ngoài phạm vi
- PR description có trung thực với diff không
- Rủi ro rollback
- Có dấu hiệu bypass protected branch/rulesets không

Output bắt buộc:
## Findings
- Severity, file, vấn đề, lý do

## Questions
- Câu hỏi cần hỏi author hoặc reviewer

## Recommendation
Chọn một:
- Ready after human approval
- Needs changes before merge
- Blocked

Không merge, không push, không sửa file.

Expected nếu PR ổn:

## Findings

No blocking findings.

## Questions

- Has a human reviewer checked that the PR template matches the team's actual workflow?

## Recommendation

Ready after human approval.

Expected nếu PR có vấn đề:

## Findings

- Medium, `.github/pull_request_template.md`: Test Plan text says all tests passed by default. This can create false evidence when no tests were run. Change it to ask authors to list real commands or mark Not run with a reason.

## Questions

- Should the PR remain draft until the template is corrected?

## Recommendation

Needs changes before merge.

Nếu team có Claude Code Code Review hoặc Claude Code GitHub Actions:

1. Kiểm tra trigger có phải manual, PR open hay every push.
2. Kiểm tra repo có lưu API key bằng GitHub Secrets, không hardcode trong workflow.
3. So sánh finding tự động với review thủ công.
4. Ghi lại ít nhất một điểm AI giúp ích và một điểm human vẫn phải quyết định.

Prompt so sánh:

So sánh review tự động của Claude trên PR với review thủ công của tôi.
Chỉ ra:
- Finding nào hữu ích
- Finding nào là false positive hoặc thiếu context
- Điểm nào AI bỏ sót
- Việc merge có cần human approval và checks pass không

Không sửa file, không merge.

Rollback nếu PR đã merge và cần revert:

git checkout main
git pull origin main
git checkout -b revert/github-workflow-pr-template
git revert <merge_or_squash_commit_sha>
git push -u origin revert/github-workflow-pr-template
gh pr create --base main --head revert/github-workflow-pr-template --title "revert: GitHub workflow guide" --body "Reverts the GitHub workflow guide change."

Rủi ro:

• Revert PR cũng cần review nếu main được bảo vệ.
• Nếu merge đã lộ secret, revert không đủ; phải rotate secret.

Bài 4 — Review & Reflection

Viết reflection 10-15 dòng:

1. Vì sao không nên làm trực tiếp trên main?
2. Claude Code giúp ích ở bước nào trong workflow?
3. Claude Code không nên được phép làm gì nếu chưa có human review?
4. Protected branch hoặc rulesets nên chặn những hành động nào?
5. Nếu Claude nói Ready after human approval, bạn còn cần kiểm tra gì?
6. Nếu PR đã merge sai, khi nào dùng revert PR?
7. Nếu diff có secret, vì sao rollback không đủ?

Prompt tự kiểm tra:

Đọc reflection của tôi và đánh giá:
- Tôi có hiểu đúng vai trò advisory của Claude Code không?
- Có chỗ nào đang giao quá nhiều quyền quyết định cho Claude không?
- Có thiếu protected branch/rulesets, human review, checks, rollback hoặc secret rotation không?
Trả feedback ngắn gọn, không viết lại toàn bộ.

Expected reflection:

Không nên làm trực tiếp trên main vì main nên đại diện cho trạng thái ổn định của project. Feature branch giúp cô lập thay đổi, review dễ hơn và rollback rõ hơn. Claude Code hữu ích khi tóm tắt git status, đề xuất commit message, viết PR description và review diff trước commit hoặc trước merge. Tuy nhiên Claude không nên tự push, approve hoặc merge nếu human chưa đọc diff và checks chưa pass. Protected branch hoặc rulesets nên yêu cầu PR, approving review, required status checks, conversation resolution, chặn force push và chặn delete branch. Nếu Claude nói Ready after human approval, tôi vẫn phải kiểm tra PR diff, CI checks, test plan, reviewer approval, security risk và PR description có đúng với thay đổi thật không. Nếu PR đã merge sai, tôi nên tạo revert PR để giữ audit trail. Nếu diff có secret, revert không đủ vì secret có thể đã lộ trong remote, CI log hoặc session; cần rotate secret ngay.

Tiêu chí hoàn thành

• Tạo được feature branch từ main mới nhất trong taskflow-ai.
• Biết kiểm tra repo bằng git status --short.
• Biết dùng git diff --stat, git diff --name-only, git diff, git diff --check.
• Chỉ stage đúng .github/pull_request_template.md và docs/github-workflow.md.
• Có commit message rõ theo Conventional Commits.
• Có PR description đủ Summary, Changes, Test Plan, Risk, Rollback, Security, Performance / Cost / Context, Maintainability.
• Biết dùng gh auth status, gh pr create, gh pr diff, gh pr checks, gh pr view.
• Có prompt Claude Code review diff read-only.
• Hiểu Claude review không thay thế human review.
• Biết protected branch/rulesets nên có guardrails nào.
• Biết rollback khi branch, commit, PR hoặc merge có vấn đề.
• Biết secret leakage cần rotate secret, không chỉ revert.

Gợi ý nếu bí

Không biết repo đang ở trạng thái nào:

git status --short
git branch --show-current
git log --oneline -5

Không biết diff có gì:

git diff --stat
git diff --name-only
git diff

Không biết command validation:

git diff --check

Nếu có code change:

npm run lint
npm test
npm run typecheck

Không biết commit message:

Dựa trên staged diff, đề xuất 3 commit message theo Conventional Commits. Không commit giúp tôi.

Không biết PR body:

Viết PR description dựa trên diff hiện tại, có Summary, Changes, Test Plan, Risk, Rollback, Security, Performance / Cost / Context, Maintainability. Không nói đã chạy test nếu chưa có bằng chứng.

Checks fail:

gh pr checks

Sau đó:

Đây là output checks fail. Hãy giải thích nguyên nhân có thể, command local nên chạy, và hướng fix nhỏ nhất. Không sửa file.

File ngoài phạm vi:

git diff --name-only
git restore --staged path/to/file

Chỉ dùng lệnh sau nếu chắc chắn muốn bỏ thay đổi local ở file đó:

git restore path/to/file

Đáp án tham khảo hoặc expected result

Branch:

git branch --show-current

Expected:

feature/github-workflow-pr-template

Changed files:

.github/pull_request_template.md
docs/github-workflow.md

Commit message tốt:

docs(github): add pull request workflow guide

PR Test Plan tốt cho documentation/workflow-only:

## Test Plan

- [x] Ran `git diff --check`.
- [ ] Not run: application tests because this is documentation-only/workflow-only.

Protected branch hoặc rulesets expected configuration:

Require a pull request before merging: enabled
Require approvals: enabled
Require status checks to pass: enabled
Require conversation resolution before merging: enabled
Block force pushes: enabled
Restrict deletions / do not allow deletion of main: enabled

Với team nghiêm túc hơn:

Dismiss stale pull request approvals when new commits are pushed: enabled
Require branches to be up to date before merging: enabled
Require linear history: enabled
Require Code Owners review for sensitive paths: enabled
Restrict who can bypass rules: enabled

Claude Code review expected recommendation:

## Recommendation

Ready after human approval.

Không chấp nhận recommendation dạng:

Approved. Merge now.

Lý do: Claude Code không phải human approver cuối và không được tự quyết merge.