Cẩm nang SDLC AI-native

Code không còn là nút thắt

Các tổ chức đã bắt đầu dùng AI để viết code với tốc độ mà một năm trước không ai nghĩ tới, nhưng những quy trình bao quanh code thì chưa đổi kịp.

Nhiều đội kỹ thuật vẫn giữ nguyên bấy nhiêu cổng duyệt, vòng review, lượt bàn giao và chính sách như cũ, làm nghẽn lại chính phần năng suất mà họ vừa có được nhờ các công cụ lập trình dạng agent như Claude Code.

Vòng đời phát triển phần mềm (SDLC)SDLC, software development lifecycle, là toàn bộ chặng đường đưa phần mềm từ ý tưởng ra tới môi trường chạy thật là quy trình đưa phần mềm từ ý tưởng tới sản phẩm chạy thật. Phần lớn tổ chức đều chạy một biến thể của cùng sáu giai đoạn: lập kế hoạch, thiết kế, xây dựng, kiểm thử, triển khai và bảo trì. Theo lối truyền thống, mỗi giai đoạn là một chặng riêng do một vai trò khác nhau nắm. Product manager viết yêu cầu, kiến trúc sư kỹ thuật biến yêu cầu thành thiết kế, kỹ sư dựng theo thiết kế, đội QA ở các doanh nghiệp thuộc ngành bị quản lý chặt kiểm tra lại, đội phát hành đưa ra thị trường, và đội vận hành trông chừng thứ đang chạy. Công việc đi từ chặng này sang chặng kia qua tài liệu, ticket và các lượt phê duyệt.

SDLC truyền thống nặng về quy trình, mục đích là bảo đảm có người chịu trách nhiệm và có kiểm soát ở từng bước. Nhưng nó được thiết kế cho một thời mà chặng tốn thời gian và tốn tiền nhất là viết và cài đặt code, còn giờ thì không còn như vậy nữa. PRDPRD, product requirements document, là tài liệu mô tả yêu cầu sản phẩm, các nghi thức ước lượng, các vòng review bảo mật sản phẩm, tất cả sinh ra để ép mọi người thống nhất với nhau trong suốt quãng phát triển có thể kéo dài hàng tuần, hàng tháng, thậm chí hàng quý.

SDLC truyền thống còn có những chốt kiểm soát mặc định rằng mỗi bước đều do con người làm. Những tổ chức tạo ra nhiều giá trị nhất đã dựng lại quy trình của họ quanh những gì AI dạng agent làm được hôm nay, đồng thời vẫn giữ con người trong vòng. Trong cẩm nang này, chúng tôi đi qua một số cách làm tốt nhất mà đội Applied AI của chúng tôi đúc rút được khi đưa Claude vào từng giai đoạn của SDLC trong nội bộ, để tăng tốc phát triển và làm quy trình chạy nhanh hơn, lấy cảm hứng từ chính việc làm cùng khách hàng.

Khi code không còn là nút thắt và chặng xây dựng chạy nhanh hơn mức SDLC truyền thống cho phép, ba điều sau trở thành sự thật:

• Nút thắt dịch sang những bước nằm bên trái và bên phải chặng xây dựng. Chủ yếu là lập kế hoạch, review và kiểm thử, và triển khai, những chặng vẫn chạy ở tốc độ con người.
• Các chốt kiểm soát không còn khớp với thực tế và trở nên bất khả thi. Soi từng dòng bằng tay là hợp lý khi dòng đó do người viết, nhưng không theo kịp một khi agent viết phần lớn diffdiff là phần code đã thay đổi.
• Chi phí quản trị tăng lên, vì các ngoại lệ vẫn phải đi qua những cuộc họp và hội đồng chỉ họp hàng tuần hoặc hàng tháng.

Lấy một nút thắt về bảo mật làm ví dụ. Đội bảo mật được bố trí nhân sự theo sức làm của con người, nên khi agent nhân sản lượng code lên nhiều lần, hoặc hàng chờ review phình ra, hoặc code được đẩy đi mà chưa review đủ. Một tổ chức thuộc ngành bị quản lý chặt không chấp nhận được cả hai kết cục đó, nên các chốt kiểm bảo mật và chính sách của họ buộc phải chạy kịp tốc độ của agent.

Muốn thật sự thu được phần năng suất đó và muốn dùng AI dạng agent một cách an toàn, SDLC truyền thống phải được chuyển đổi ở đúng mức độ mà chặng cài đặt đã trải qua.

SDLC AI-native là gì?

SDLC AI-nativeAI-native nghĩa là lấy AI làm nền tảng ngay từ gốc, chứ không phải gắn AI vào một quy trình cũ là một quy trình được hình dung lại, kết hợp các mục tiêu kiểm soát cũ với cách thực thi mới. Thay vì chạy thẳng một mạch, quy trình trở thành một vòng lặp, và AI được cài vào từng điểm trên vòng đó. SDLC AI-native khuyến khích việc bàn giao tự động và tự kích hoạt nước đi kế tiếp, nhằm xử lý đúng chỗ thủ công và lấn cấn nhất của SDLC truyền thống là khâu chuyển giao giữa các chặng.

Bạn cũng sẽ nghe người ta gọi bước dịch chuyển này là SDLC agentic, SDLC AI, hoặc đơn giản là phát triển phần mềm dạng agent. Tên gọi khác nhau, nhưng đều nói về cùng một thứ.

Sáu giai đoạn của SDLC dịch chuyển ra sao

Bảng dưới đây nêu hai đầu của một quang phổ, một bên là SDLC truyền thống, một bên là SDLC AI-native có Claude hỗ trợ. Phần lớn tổ chức nằm đâu đó ở giữa hai cột.

Sợi chỉ xuyên suốt cột bên phải chính là artifact được commitartifact là file mà mỗi giai đoạn tạo ra rồi giao lại cho giai đoạn sau. Mỗi giai đoạn kết thúc bằng việc ghi một artifact vào hệ thống quản lý phiên bản (gồm intent.md, spec.md, plan.md, phần diff cùng test của nó, cái PRPR, pull request, là đề nghị gộp một nhánh code vào nhánh chính kèm các phát hiện khi review, và bản ghi sự cố), rồi giai đoạn kế tiếp mở đầu bằng việc đọc nó. Ở các giai đoạn đầu, file .md là dạng artifact chủ đạo, vì cả product owner lẫn agent đều đọc được và hành động được trên cùng một file. Từ giai đoạn Xây dựng trở đi, artifact là code và các bản ghi quanh nó. Chuỗi commit cũng chính là dấu vết kiểm toán: ai yêu cầu điều gì, agent tạo ra thứ gì, và ai đã duyệt.

Con người vẫn chịu trách nhiệm cho mọi quyết định cần tới phán đoán. Trong thế giới SDLC dạng agent, sự chú ý của con người dịch chuyển theo chính những artifact cần được review.

Các nước đi

Các nước đi là phần lõi của cẩm nang này, được xếp vào sáu giai đoạn không chạy tuần tự (Lập kế hoạch, Thiết kế, Xây dựng, Kiểm thử, Triển khai, Bảo trì), và gộp lại thì phủ trọn vòng đời.

Mỗi nước đi gồm:

• Cái gì thay đổi;
• Bắt đầu thế nào;
• Các bước cụ thể để thực hiện;
• Những điều cần cân nhắc về mặt quản trị; và
• Cách đo xem nó có hiệu quả không.

Các bước được chia thành từng khối rời, nên mỗi tổ chức có thể chọn ưu tiên chuyển đổi những giai đoạn khác nhau vào những thời điểm khác nhau tùy nhu cầu riêng. Mỗi nước đi đều ghi rõ nó phụ thuộc vào cái gì ở mục "Cần có trước", và sơ đồ phụ thuộc bên dưới minh họa thêm điều đó.

Một giai đoạn kết thúc bằng việc commit một artifact, và chính commit đó khởi động giai đoạn kế tiếp. Một intent.md được chấp nhận sẽ kích hoạt lượt làm yêu cầu và thiết kế, một spec.md được duyệt sẽ kích hoạt plan mode, một PR được gộp sẽ kích hoạt pipelinepipeline là đường ống các bước tự động chạy nối tiếp nhau, và một dải kiểm soát bị vượt ngưỡng ở môi trường chạy thật sẽ viết ra intent.md tiếp theo, cứ thế vòng lặp chạy tiếp.

Ban đầu, bạn tự tay ra lệnh cho từng bước. Đích đến là một vòng lặp trong đó mỗi artifact được chấp nhận sẽ tự bật cổng kế tiếp. Sự chú ý của con người dồn lại ở các cổng, để review những gì agent đã đánh dấu, thay vì phải bắt đầu lại từ đầu ở mỗi giai đoạn.

Ghi lại thành intent.md

File intent.md, thứ khởi động cả quy trình phát triển phần mềm, có thể đi vào từ nhiều đường khác nhau. Một người nảy ra ý tưởng, một ticket được mở, hoặc một sự cố nổi lên qua cảnh báo (xem Giai đoạn 6: Bảo trì).

Khi một người có ý tưởng, họ ngồi nghĩ cùng Claude và cho ra một bản đặc tả sơ khởi dạng markdown. Trong SDLC truyền thống, cũng người đó sau đấy phải thuyết phục được một thành viên đội sản phẩm ngồi viết lại ý tưởng cùng mình, hoặc viết thay mình.

Bản đặc tả sơ khởi mà Claude tạo ra thì người đọc được, có lưu phiên bản, và giai đoạn kế tiếp dùng được ngay. Bản đó được lưu thành một intent.md.

Dù ý định xuất phát từ một sự kiện tự kích hoạt hay từ một agent, các bước vẫn như nhau: product ownerproduct owner là người chịu trách nhiệm về sản phẩm đọc lại và sửa cái intent.md do agent viết trước khi nó được commit.

Bắt đầu thế nào

Việc dựng chỗ này là việc làm một lần của đội nền tảng hoặc đội kỹ thuật. Cần một người có chuyên môn kỹ thuật đứng ra lập chỗ ở cho intent và quyết ai được quyền ghi vào đó, vì người đóng góp sẽ đến từ khắp nơi trong tổ chức.

Một khi kho code đã có, những người đóng góp chưa từng dùng git không cần đụng thẳng vào git. Thay vào đó, một connectorconnector là cầu nối cho phép Claude thao tác trực tiếp với một hệ thống bên ngoài nối tới hệ thống quản lý phiên bản (ví dụ GitHub) cho phép Claude commit các file markdown thay mặt họ, ngay từ claude.ai hoặc Cowork.

Các bước thực hiện

1. Người nghĩ ra ý tưởng mô tả vấn đề cho Claude bằng chính lời của mình. Họ có thể kể hôm nay mình không làm được gì, ai đang chịu ảnh hưởng, thế nào thì tốt hơn, và cái gì nằm ngoài phạm vi. Không cần dùng ngôn ngữ trang trọng.
2. Cứ trao đổi qua lại cho tới khi ý tưởng thành hình rõ ràng. Claude hỏi đúng những câu mà một chuyên viên phân tích sẽ hỏi: phạm vi, người dùng, ràng buộc, và thế nào là thành công.
3. Bảo Claude viết kết quả ra thành intent.md theo mẫu của tổ chức, cái mẫu này có thể mã hóa thành một skill do người có chuyên môn kỹ thuật dựng và một trưởng nhóm ký duyệt. Nội dung có thể gồm vấn đề, kết quả mong muốn, người dùng và hệ thống bị ảnh hưởng, các ràng buộc, và những câu hỏi còn bỏ ngỏ.
4. Người nghĩ ra ý tưởng sửa lại mọi chỗ Claude hiểu sai.
5. Commit intent.md vào chỗ ở chung. Tên tác giả và mốc thời gian nhập vào bản ghi, và product owner tiếp nhận ý tưởng từ đó.

# Intent: khách tự tra tình trạng hồ sơ bồi thường
Tác giả: J. Ortiz (vận hành bồi thường). Trạng thái: bản nháp.

## Vấn đề
Khách gọi lên tổng đài để hỏi hồ sơ bồi thường của mình đang tới đâu.
Nhân viên tốn khoảng một phần ba thời gian gọi chỉ để trả lời
câu hỏi tình trạng.

## Kết quả mong muốn
Khách xem được tình trạng hồ sơ, bước kế tiếp và ngày dự kiến
ngay trên cổng thông tin.

## Người dùng và hệ thống bị ảnh hưởng
Nhân viên xử lý bồi thường, đội làm cổng thông tin, API claims-core.

## Ràng buộc
Không đưa thêm dữ liệu cá nhân nào vào phiên đăng nhập trên cổng.
Chỉ dùng cơ chế xác thực sẵn có.

## Câu hỏi còn bỏ ngỏ
Các đơn vị giám định tổn thất bên ngoài có cần quyền truy cập không?

Về mặt quản trị

Bằng chứng chính là cái intent.md đã commit, trên đó có tên tác giả, mốc thời gian và toàn bộ lịch sử sửa đổi. Tất cả nằm trong lịch sử git của chỗ ở chung. Product owner là người duyệt, và quyết định chấp nhận hay từ chối, thứ đưa intent sang Giai đoạn 2: Thiết kế, được ghi lại dưới dạng một lần gộp hoặc một lượt review đóng lại.

Đo bằng gì

Yêu cầu và thiết kế

Sau khi product owner duyệt, Claude nhận cái intent.md đã được chấp nhận và cho ra một bản đặc tả gồm cả yêu cầu lẫn thiết kế. Quá trình này được dẫn đường bởi các skillskill là gói hướng dẫn đóng sẵn để agent đọc và làm theo của tổ chức về thương hiệu, bảo mật, tuân thủ và trải nghiệm người dùng.

Product owner đọc lại bản đặc tả đó, nhưng không phải người viết nó. Mục tiêu của quá trình này là tạo ra một bản đặc tả mà đội kỹ thuật lập kế hoạch dựa vào được, kèm theo những điểm được đánh dấu cần lưu ý.

Phần giao diện là ví dụ rõ nhất. Ngay khi intent.md được chấp nhận, product owner dựng bản mô phỏng giao diện trong Claude Design (bản beta) từ chính intent.md đó, chỉnh tới chỉnh lui trên bản mô phỏng, rồi xuất sang Claude Code để dựng thật.

Bắt đầu thế nào

Các bước thực hiện

1. Product owner mở một phiên làm việc có sẵn các skill của tổ chức và đính kèm file intent.md.
2. Câu lệnh của product owner trỏ vào intent.md, nêu rõ các ràng buộc, và yêu cầu đánh dấu những điểm cần lưu ý. Ban đầu cứ chạy tay, sau đó đóng gói lại thành một lệnh gạch chéo dùng chung cho cả tổ chức. Từ đó, lấy việc intent.md được chấp nhận trong chỗ ở chung làm sự kiện kích hoạt, cho một tác vụ chạy tự động khởi động ngay khi có lần gộp, chạy lượt xử lý với các skill của tổ chức đã nạp sẵn, rồi commit spec.md dưới dạng một pull request (phần đường ống kỹ thuật nằm ở nước đi CI/CD trong Giai đoạn 5: Triển khai). Từ lúc đó trở đi, lần đầu product owner phải nhúng tay vào chính là lúc review.
3. Cũng chính product owner đó đối chiếu bản đặc tả với ý tưởng ban đầu. Bản đặc tả có giải quyết đúng vấn đề đã nêu không, và những câu hỏi còn bỏ ngỏ trong intent.md đã được trả lời hay được chuyển tiếp sang sau?
4. Xử lý những điểm được đánh dấu trước tiên, vì đó chính là chỗ mà một chuyên viên phân tích sẽ đẩy lên cấp trên. Product owner giải quyết từng điểm với người chủ quản chính sách tương ứng, trước khi đội kỹ thuật nhìn thấy bản đặc tả.
5. Commit spec.md nằm cạnh intent.md. Cặp file này ghi lại thứ được yêu cầu và thứ đã được quyết.
6. Product owner quyết định bản đặc tả và bản intent có được đi tiếp sang chặng xây dựng không, và hỏi ý một trưởng nhóm kỹ thuật với bất cứ thứ gì tổ chức xếp vào diện rủi ro cao hơn. Quyết định này luôn do một đồng nghiệp là người thật đưa ra, và việc chấp nhận bản đặc tả chính là thứ khởi động nước đi plan mode ở Giai đoạn 3: Xây dựng.

Trông nó như thế nào (câu lệnh)

Đọc file intent.md đính kèm và tạo ra một bản đặc tả gồm yêu cầu và thiết kế
để tích hợp nó vào codebase hiện có của chúng tôi. Áp dụng các skill mà bạn
đang có, sao cho kế hoạch tuân thủ bộ nhận diện thương hiệu, các chính sách
bảo mật và các chuẩn về trải nghiệm người dùng của chúng tôi. Ghi lại
bản đặc
tả đầy đủ thành spec.md, sẵn sàng bàn giao cho đội kỹ thuật. Mô tả rõ
ràng mọi
điểm cần lưu ý, nhất là những chỗ bạn không thể thỏa mãn cùng lúc các chính
sách mâu thuẫn nhau.

Về mặt quản trị

Thay vì mấy tuần sau mới lòi ra trong một buổi review, chính sách đang có hiệu lực được đọc và áp ngay lúc bản đặc tả đang được viết. Các skill của tổ chức được áp làm ràng buộc lên bản đặc tả. Bản đặc tả, câu lệnh đã tạo ra nó, và phiên bản skill đang có hiệu lực, tất cả đều được ghi lại trong hệ thống quản lý phiên bản. Product owner phê duyệt bản đặc tả, và chuyển những điểm được đánh dấu tới đúng người chủ quản chính sách.

Đo bằng gì

Lấy plan mode của Claude Code làm điểm khởi đầu mặc định

Kỹ sư mở phiên Claude Code ở plan modeplan mode là chế độ Claude đọc được toàn bộ code nhưng chưa được phép sửa gì, đưa cho Claude cái spec.md đã duyệt từ Giai đoạn 2: Thiết kế, rồi để nó phỏng vấn ngược lại mình, chỉnh tới chỉnh lui bản kế hoạch cho tới khi kỹ sư thấy ưng.

Bắt đầu thế nào

Các bước thực hiện

1. Kỹ sư mở phiên làm việc với Claude ở plan mode.
2. Kỹ sư đưa cho Claude intent.md và spec.md, rồi yêu cầu một bản kế hoạch cài đặt có nêu rõ những file nào sẽ thay đổi, thứ tự công việc, và những test nào chứng minh là làm đúng.
3. Vặn lại bản kế hoạch bằng cách hỏi thay đổi này có thể làm hỏng cái gì, bước nào rủi ro nhất, và Claude đã cân nhắc rồi loại bỏ những phương án nào khác.
4. Chỉnh tới chỉnh lui cho tới khi một kỹ sư chưa từng đọc cuộc trò chuyện này vẫn tự cài đặt được thay đổi đó chỉ bằng bản kế hoạch.
5. Commit bản kế hoạch đã duyệt thành plan.md. Bản kế hoạch nhập vào dấu vết kiểm toán, và nước đi review PR (Giai đoạn 5: Triển khai) sẽ đối chiếu phần diff cuối cùng với nó.
6. Chấp nhận bản kế hoạch rồi để Claude cài đặt. Với một bản kế hoạch chắc tay, phần cài đặt thường xong trong một lượt.
7. Khi phần cài đặt đi chệch khỏi kế hoạch, hãy cập nhật plan.md ngay trong cùng commit đó. Có thể cân nhắc dùng một hookhook là đoạn lệnh tự chạy tại một thời điểm nhất định trong phiên làm việc để bắt buộc hai thứ này luôn khớp nhau.

Trông nó như thế nào (plan.md)

# Plan: khách tự tra tình trạng hồ sơ bồi thường (từ intent.md 2026-06-02)

## Những file sẽ thay đổi
portal/src/claims/StatusPanel.tsx (file mới), claims-api/routes/status.py,
claims-api/tests/test_status.py

## Thứ tự công việc
1. Thêm endpoint tình trạng, đặt sau lớp xác thực sẵn có.
2. Dựng panel gọi vào endpoint đó.
3. Nối vào thanh điều hướng của cổng thông tin.

## Rủi ro
API claims-core giới hạn 50 lượt gọi mỗi giây; panel bắt buộc phải có cache.

## Bằng chứng
test_status.py phủ hết bốn trạng thái hồ sơ; ảnh chụp màn hình khớp với
bản mô phỏng đã duyệt.

Về mặt quản trị

Việc review thiết kế diễn ra trước khi có dòng code nào được sinh ra, lúc mà đổi hướng vẫn còn là chuyện sửa một tài liệu. Bản thân plan mode tự ép điều này, vì Claude không sửa được file nào chừng nào kỹ sư chưa chấp nhận kế hoạch. Bản kế hoạch cùng các lần sửa của nó đều được ghi lại, kèm tên người đã chấp nhận. Những thay đổi thường ngày thì kỹ sư duyệt, còn bất cứ thứ gì tổ chức xếp vào diện rủi ro cao hơn thì chuyển lên trưởng nhóm kỹ thuật hoặc kiến trúc sư.

Đo bằng gì

Chạy Claude Code ở auto mode

Claude Code còn chạy được ở auto mode, tức là kỹ sư duyệt bản kế hoạch, và một khi đã ưng sau vài lượt chỉnh, Claude tự áp từng thay đổi mà không hỏi lại ở mỗi lần sửa. Khi các rào chắn từ những nước đi phía sau đã chín (một CLAUDE.md được tinh chỉnh, các skill mã hóa sẵn chính sách, các hook chặn hành động không an toàn, và một bộ test mà Claude chạy được), thì chế độ tự chấp nhận trở thành mặc định cho công việc thường ngày: một spec.md chặt chẽ, phạm vi ảnh hưởng nhỏ, và phần code đã được test phủ sẵn.

Bước dịch chuyển ở đây là đi khỏi cảnh người dùng ngồi nhìn agent sửa từng chỗ rồi duyệt từng hành động, để chuyển sang việc review các artifact sau những phiên tự chạy dài hơn. Chế độ tự chấp nhận còn mở ra khả năng làm song song, cho từng người và cho cả đội, khi dùng kèm worktreeworktree là bản sao thư mục làm việc riêng của cùng một kho code, để chạy nhiều việc song song mà không giẫm chân nhau, và nó là nền tảng để chạy SDLC một cách tự chủ và khép kín vòng lặp như mô tả ở Giai đoạn 6: Bảo trì.

File CLAUDE.md

CLAUDE.md cho Claude đúng phần bối cảnh mà một người mới vào cần biết: quy ước, các lệnh hay dùng, kiến trúc hệ thống, và những lỗi mà cả đội gặp nhiều nhất. Thứ tri thức trước đây nằm trong đầu người và nằm rải trên wiki nay trở thành một file mà agent đọc ở đầu mỗi phiên, do cả đội cùng chăm, và được bồi đắp mỗi lần có ai đó mắc lỗi.

Bắt đầu thế nào

Các bước thực hiện

1. Chạy /init trong kho code. Claude tự sinh ra một CLAUDE.md khởi đầu từ những gì nó tìm thấy.
2. Cắt gọt file vừa sinh xuống còn đúng những gì một người mới cần trong ngày đầu tiên. Giữ lại các lệnh build, test và lintlint là công cụ soát lỗi văn phong và lỗi tiềm ẩn trong code, những quy ước thật sự quan trọng, và những chỗ Claude cứ làm sai hoài.
3. Đưa CLAUDE.md vào git ở thư mục gốc của kho code, để cả đội dùng chung một phiên bản và mọi thay đổi đều được review như review code.
4. Có một quy tắc làm việc rất hữu ích ở đây. Khi Claude mắc cùng một lỗi tới lần thứ hai, phần sửa lỗi đó phải được viết vào CLAUDE.md.
5. Giữ file dưới một trang. Claude đọc trọn file này ở đầu phiên, nên bất cứ thứ gì cũ kỹ lỗi thời đều đang chiếm chỗ trong bộ nhớ ngữ cảnh mà chẳng đem lại lợi ích gì.

Trông nó như thế nào (CLAUDE.md)

# Dịch vụ thanh toán

## Các lệnh
- Build: make build
- Test: make test (unit), make itest (tích hợp, cần docker)
- Lint: make lint (chạy trong CI; sửa xong rồi hãy push)

## Quy ước
- Java 21, Spring Boot 3. Không dùng thêm Lombok nữa.
- Tiền luôn để kiểu BigDecimal, tuyệt đối không dùng double.
- Mỗi endpoint đều phải có một test tích hợp trong src/itest.

## Kiến trúc
- api/ chứa các controller REST, core/ chứa logic nghiệp vụ,
  adapters/ nói chuyện với các hệ thống bên ngoài.
- Các sự kiện Kafka được định nghĩa trong schemas/; tuyệt đối không sửa
  các class được sinh tự động.

## Những chỗ Claude hay làm sai
- Không tự nâng phiên bản thư viện phụ thuộc; đội nền tảng mới là
  chủ chỗ đó.
- Package cũ v1/ đã đóng băng; mọi thay đổi đi vào v2/.

Về mặt quản trị

CLAUDE.md được lưu phiên bản, nên bộ hướng dẫn mà agent làm theo là thứ review được và kiểm toán được. Quy ước của đội được áp thông qua file này, mọi thay đổi trên nó đều được ghi lại trong lịch sử git, và người chủ quản phần code đó duyệt các thay đổi trong lượt review PR.

Đo bằng gì

Skill là nơi cất tri thức của tổ chức

Skill là cách một tổ chức biến tri thức của mình thành thứ vận hành được. Hướng dẫn được viết ra rõ ràng, có lưu phiên bản, áp dụng trên diện rộng, và cập nhật tập trung mỗi khi chính sách thay đổi. Quy tắc bỏ túi: hãy viết skill cho những tri thức của tổ chức bắt buộc phải được áp dụng nhất quán; đừng viết skill cho những thứ vốn thuộc về CLAUDE.md hoặc thuộc về một câu lệnh.

Bắt đầu thế nào

Các bước thực hiện

1. Chọn một mẩu tri thức mà hôm nay đang được thực thi không đồng đều. Có thể là một chuẩn bảo mật, một quy ước thiết kế API, hay một quy tắc thương hiệu.
2. Viết nó thành một skill, tức một thư mục chứa file SKILL.md, trong đó phần đầu file khai báo khi nào skill được kích hoạt, còn phần thân nói phải làm gì. Một kỹ sư viết nó dựa trên nguồn sự thật của người chủ quản chính sách, có Claude phụ giúp.
3. Đặt skill vào kho code tại .claude/skills/<tên>/ để nó đi kèm với code, hoặc phân phối cho toàn tổ chức qua một plugin.
4. Kiểm tra xem skill có thật sự được kích hoạt không. Bảo Claude làm đúng loại việc đó theo nhiều cách diễn đạt khác nhau và xác nhận lần nào skill cũng được nạp.
5. Khi chính sách đổi, hãy đổi skill và để người chủ quản chính sách ký duyệt thay đổi.
6. Các kỹ sư tự động nhận phiên bản mới ngay trong phiên làm việc kế tiếp.

Trông nó như thế nào (.claude/skills/secure-api-review/SKILL.md)

---
name: secure-api-review
description: Áp dụng chuẩn bảo mật API. Dùng bất cứ khi nào tạo mới hoặc
  sửa một endpoint hướng ra ngoài, review code API, hoặc sinh ra một
  bản đặc tả OpenAPI.
---
# Review bảo mật API

Khi bạn tạo mới hoặc thay đổi một endpoint API:
1. Xác thực: mọi endpoint đều bắt buộc có JWT do gateway cấp;
   không có route ẩn danh nào ngoài /health.
2. Kiểm tra dữ liệu vào: đối chiếu phần thân yêu cầu với schema
   OpenAPI và loại bỏ những trường không khai báo.
3. Ghi vết kiểm toán: mọi endpoint làm thay đổi trạng thái đều phải phát
   ra một sự kiện kiểm toán gồm người thực hiện, hành động, đối tượng
   và mốc thời gian.
4. Phân loại dữ liệu: những trường gắn nhãn pii trong schema tuyệt đối
   không được xuất hiện trong log hay trong thông báo lỗi.

Chạy scripts/check-endpoints.sh và đưa kết quả của nó vào phần
tóm tắt của bạn.

Về mặt quản trị

Skill là một chốt kiểm soát, nhưng là loại mang tính khuyến nghị. Nó khiến Claude nhiều khả năng áp đúng chính sách ngay lúc code đang được viết, chứ không có gì ép một phiên làm việc buộc phải tuân theo. Một chính sách bắt buộc phải đúng trong mọi trường hợp thì cần một thứ mang tính chắc chắn đứng phía sau skill, chẳng hạn một hook chặn thẳng hành động đó, hoặc một lượt review đối chiếu lại chính sách ở khâu PR. Skill làm cho vi phạm trở nên hiếm, còn hook làm cho vi phạm gần như không xảy ra được. Mỗi lần skill được gọi đều được ghi lại trong nhật ký phiên, và người chủ quản chính sách review các thay đổi trên skill y như review code.

Đo bằng gì

Hook là rào chắn ngay lúc xây dựng

Skill là chốt kiểm soát mang tính khuyến nghị, còn hook là lớp chắc chắn nằm phía sau nó. Phần lớn hành động của Claude trong lúc cài đặt là sửa file và chạy lệnh trên terminal, nên chặng xây dựng thường là nơi hook nổ ra nhiều nhất.

Hook ở chặng xây dựng có thể:

• Chặn việc sửa những đường dẫn được bảo vệ, chẳng hạn các class sinh tự động hay một package đã đóng băng;
• Chạy công cụ định dạng và công cụ soát lỗi sau mỗi lần sửa file, để không bao giờ tích tụ độ lệch;
• Giữ cho thông tin đăng nhập không lọt vào phần diff.

Hãy đặt một hook đứng sau bất kỳ skill nào mà chính sách của nó buộc phải đúng không ngoại lệ. Một hook chạy mỗi khi có hành động khớp với nó, nên hook ở chặng xây dựng phải nhanh và chỉ giới hạn trong đúng file vừa thay đổi. Những phép kiểm nặng hơn, ví dụ chạy trọn bộ test, thuộc về khâu commit hoặc khâu PR.

Còn loại hook dừng lại để hỏi ý con người thì thuộc về nhóm cổng duyệt ở Giai đoạn 5: Triển khai, vì một lời nhắc chờ duyệt ngay giữa lúc xây dựng sẽ đặt con người trở lại đúng đường găng của tất cả các phiên đang chạy song song.

Chạy nhiều phiên song song và dùng subagent

Một kỹ sư có thể cầm lái nhiều dòng công việc cùng lúc.

Một phiên song song là thêm một bản Claude Code đầy đủ nữa, làm một việc riêng trong git worktree riêng của nó. Các phiên độc lập không biết gì về nhau, và thứ duy nhất chúng dùng chung là người kỹ sư đang cầm lái.

Còn subagentsubagent là agent con, được giao một việc hẹp rồi báo kết quả về chạy bên trong một phiên duy nhất, đóng vai trợ thủ có phạm vi hẹp, có cửa sổ ngữ cảnh riêng và giới hạn công cụ riêng. Nó hợp với những việc lặp lại ở nhiều tác vụ, ví dụ kiểm tra xem ứng dụng có chạy đúng như mong đợi không.

Chạy nhiều phiên song song làm tăng số việc một kỹ sư ôm được cùng lúc, còn subagent giữ cho mỗi phiên tập trung vào đúng việc của nó. Việc của người kỹ sư là cầm lái và review tất cả những thứ đó.

Bắt đầu thế nào

Các bước thực hiện

1. Kỹ sư chia công việc thành các tác vụ đụng vào những file khác nhau, dùng chính bản kế hoạch từ nước đi plan mode (Giai đoạn 3: Xây dựng) để thấy chỗ nào công việc độc lập với nhau. Những tác vụ dùng chung file thì chạy trong một phiên duy nhất, làm lần lượt.
2. Mỗi tác vụ song song có worktree riêng, ví dụ claude --worktree feature-auth ở một cửa sổ terminal và claude --worktree fix-rate-limit ở cửa sổ khác. Worktree là một bản lấy code riêng nằm trên nhánh riêng của nó, nhờ vậy các phiên không giẫm lên file của nhau.
3. Hai tới ba phiên là điểm khởi đầu hợp lý. Trần thực tế nằm ở chỗ một người review cho tử tế được bao nhiêu dòng việc, nên chỉ thêm phiên chừng nào khâu review còn theo kịp.
4. Biến những việc lặp lại thành subagent, khai báo bằng các file markdown trong .claude/agents/, mỗi file có một cái tên, một mô tả khi nào thì dùng nó, và danh sách công cụ nó được đụng vào. Ví dụ: một agent chuyên rút gọn code để cắt bỏ phần phức tạp thừa sau khi agent chính làm xong; một agent kiểm chứng chạy thử ứng dụng và soát hành vi; một agent tra cứu đi lục codebase rồi báo cáo lại mà không làm ngập ngữ cảnh của phiên chính. Hãy đưa các file khai báo này vào git để cả đội dùng chung.

Trông nó như thế nào (.claude/agents/verifier.md)

---
name: verifier
description: Chạy ứng dụng và kiểm tra thay đổi có hoạt động không, trước
  khi phiên làm việc báo là đã xong
tools: Bash, Read
---
Khởi động ứng dụng bằng make run. Thử đúng phần hành vi vừa thay đổi và
hai luồng lân cận gần nhất. Báo lại bạn đã chạy gì, thấy gì, và bất kỳ hành
vi nào không khớp với plan.md. Không sửa gì cả; chỉ báo cáo.

Về mặt quản trị

Nhiều phiên hơn nghĩa là nhiều đầu ra hơn, nên các chốt kiểm soát buộc phải đến từ phần cấu hình nằm trong kho code. Hook và thiết lập quyền đặt ở đó sẽ áp cho mọi phiên, và mỗi phiên làm gì đều được ghi lại và quy về đúng người kỹ sư đã chạy nó.

Đo bằng gì

Cho Claude một vòng phản hồi

Luôn cho Claude một cách để tự kiểm việc mình làm, có thể là chạy test, chạy build, hoặc so ảnh chụp màn hình. Một phiên tự soát việc của mình và tự sửa lỗi của mình trước khi kỹ sư nhìn thấy chúng.

Đừng nhầm vòng phản hồi với subagent kiểm chứng (Giai đoạn 3: Xây dựng). Vòng phản hồi chạy xuyên suốt cả tác vụ, lặp bao nhiêu lần tùy khối lượng công việc. Còn subagent kiểm chứng là một cách đóng gói phép kiểm cuối cùng, bằng việc mở một cửa sổ ngữ cảnh mới toanh đúng lúc phiên làm việc tin rằng mình đã xong. Nhờ vậy, phán quyết không bị nhuốm màu bởi chính những giả định đã sinh ra đoạn code đó.

Bắt đầu thế nào

Các bước thực hiện

1. Nếu hôm nay muốn kiểm việc thì phải gõ một loạt lệnh và phải biết chút ít về môi trường, hãy gói tất cả vào một lệnh duy nhất, chẳng hạn make test hay npm test, và lệnh đó phải trả về mã lỗi khác 0 khi thất bại.
2. Trong mục Các lệnh của CLAUDE.md, liệt kê từng lệnh kèm một ví dụ về đầu ra khi mọi thứ bình thường.
3. Nêu ra một mục tiêu và làm cho nó đo đếm được, để Claude tự kiểm mà không phải hỏi bạn, ví dụ: "Toàn bộ test trong test_status.py đều qua", "ảnh chụp màn hình khớp với bản mô phỏng đính kèm", hoặc "endpoint trả về 200 kèm trường mới".
4. Với việc sửa lỗi, hãy viết trước cái test đang hỏng. Bảo Claude tái hiện lỗi đó thành một test, chạy nó, và xác nhận nó hỏng đúng vì lý do bạn nghĩ. Commit cái test đó. Chỉ tới lúc đó mới bảo Claude làm cho test qua mà không được sửa test, với hook chặn file test ở bước cuối cùng đứng ra ép ràng buộc này. Một cái test đã tồn tại từ trước khi sửa, và agent không viết lại được, chính là bằng chứng cho thấy lỗi đã hết.
5. Với việc làm giao diện, hãy khép vòng bằng một phép kiểm bằng mắt. Cho Claude một công cụ trình duyệt hoặc chụp màn hình, đưa nó bản mô phỏng, rồi để nó lặp. Dựng, chụp, so, chỉnh. Hai tới ba vòng là chuyện bình thường, và kết quả phải khá hơn sau mỗi vòng.
6. Đưa việc kiểm chứng vào định nghĩa của chữ "xong". Hướng dẫn nằm trong CLAUDE.md. Chạy test trước khi báo một tác vụ đã hoàn thành, và đưa luôn kết quả ra.
7. Cuối cùng, bản thân vòng phản hồi cũng cần được bảo vệ, vì một agent đang sửa code thì không được phép làm yếu đi chính phép kiểm dành cho đoạn code đó. Một hook chặn việc sửa file test trong lúc đang làm tác vụ sửa lỗi sẽ lo chuyện này. Cách còn lại là soát phần diff lúc review và bác bỏ mọi thay đổi đụng vào test.

Trông nó như thế nào (khối kiểm chứng trong CLAUDE.md)

## Kiểm chứng việc bạn làm

- Build: make build (phải kết thúc bằng dòng "Build succeeded")
- Test: make test (tất cả phải xanh; tuyệt đối không bỏ qua hay xóa
  một test đang hỏng)
- Lint: make lint (không còn cảnh báo nào)

Chạy đủ cả ba trước khi báo bất kỳ tác vụ nào là đã xong, và dán kết quả ra.
Nếu một test hỏng, hãy sửa code, đừng sửa test.

Về mặt quản trị

Đo bằng gì

Eval chạy liên tục trong CI

Evaleval là bài kiểm tra tự động chấm điểm chất lượng đầu ra của agent là thứ tương đương với các cổng QA đặt giữa các giai đoạn, nhưng theo lối AI-native. Thực tế nghĩa là một bộ bài kiểm chạy mỗi khi phần cấu hình của agent thay đổi. Khi thay sang một model mới hoặc viết lại một câu lệnh, bộ eval sẽ cho biết agent có còn làm được việc ở đúng mức chuẩn cũ hay không.

Nên coi bộ eval như một thứ sống. Model càng khá lên thì những ca từng phân loại được tốt sẽ mất tác dụng, và phải thêm ca mới, nảy ra từ việc giám sát liên tục.

Tùy tình huống sử dụng, một số đội có thể muốn chạy các eval này ngoại tuyến theo một nhịp định sẵn thay vì chạy ở mỗi lần thay đổi. Các bước dưới đây dành cho cách chạy liên tục.

Bắt đầu thế nào

Các bước thực hiện

1. Kỹ sư nền tảng gom lại 20 tới 50 tác vụ có thật từ công việc gần đây, kèm theo kết quả mong đợi hoặc kết quả đã được chấp nhận.
2. Viết mỗi tác vụ thành một eval, tức là câu lệnh cộng với các phép kiểm định nghĩa thế nào là đạt (test qua hết, lint sạch, hành vi không đổi, chính sách được tuân thủ).
3. Bộ eval chạy không tương tác trong CI theo lịch, và chạy thêm mỗi khi có thay đổi trên CLAUDE.md, trên skill hoặc trên hook, vì chính phần cấu hình đó lái agent nên nó xứng đáng được kiểm thử hồi quy y như code.
4. Đặt cổng cho các thay đổi cấu hình dựa trên kết quả eval. Một thay đổi trên skill làm tụt tỷ lệ đạt thì phải qua review trước khi được gộp.
5. Mỗi sự cố ở môi trường thật đều được viết thành một eval, do chính đội chịu trách nhiệm sự cố đó viết, rồi nằm lại trong bộ eval như một bài kiểm hồi quy.

Trông nó như thế nào (.github/workflows/agent-evals.yml)

name: Agent evals
on:
  pull_request:
    paths: ['CLAUDE.md', '.claude/**']
  schedule:
    - cron: '0 2 * * *'
jobs:
  evals:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @anthropic-ai/claude-code
      - name: Chạy bộ eval
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          for eval in evals/*.json; do
            claude -p "$(jq -r '.prompt' $eval)" \
              --allowedTools "Read,Edit,Bash(make test)" \
              --output-format json > result.json
            ./evals/check.sh "$eval" result.json
          done

Về mặt quản trị

Eval cho đội QA một cái cổng chạy kịp tốc độ đầu ra của agent. Ngưỡng tỷ lệ đạt được cài thành một phép kiểm bắt buộc trước khi gộp, mỗi lượt chạy đều được ghi lại để so sánh kết quả theo thời gian, và đội nào chủ quản thay đổi cấu hình thì đội đó duyệt.

Đo bằng gì

Đưa AI vào vòng review PR

Claude vừa review vừa được review. Nó review các PR gửi tới, đối chiếu với chính sách của tổ chức, và xử lý các bình luận review trên chính những PR của nó. Nhờ vậy kỹ sư tập trung được vào hành vi khi review PR, mà rốt cuộc là phán đoán về ý định và về rủi ro.

Bắt đầu thế nào

Các bước thực hiện

1. Dịch vụ Code Review có sẵn là cách khởi đầu nhanh nhất. Quản trị viên bật nó lên và chọn các kho code. Còn hãy chạy phần review trong CI của chính bạn bằng claude-code-action khi bạn cần kiểm soát đường ống, hoặc muốn các lượt gọi API đi qua hợp đồng đám mây của riêng mình (nước đi CI/CD nói về phần đường ống này).
2. Trưởng nhóm kỹ thuật viết chính sách review thành file REVIEW.md ở thư mục gốc kho code, chia theo những lượt review mà tổ chức quan tâm: lỗi và sai sót logic; bảo mật và lỗ hổng; mức tuân thủ so với bản đặc tả (spec.md từ nước đi yêu cầu), so với bản kế hoạch cài đặt (plan.md từ nước đi plan mode) và so với các nguyên tắc thiết kế. REVIEW.md cũng định nghĩa thế nào là Quan trọng, phân biệt với Lỗi vặt, và những gì được bỏ qua.
3. Trưởng nhóm kỹ thuật đặt ra ngưỡng cần con người can thiệp. Bản thân các phát hiện không tự duyệt cũng không tự chặn một PR, và cơ chế bảo vệ nhánhbảo vệ nhánh là quy định của kho code, bắt buộc phải có đủ điều kiện mới được gộp vào nhánh chính vẫn đòi phê duyệt từ người chủ quản phần code đó. Kỹ sư nền tảng nào muốn đặt cổng cho việc gộp dựa trên các phát hiện thì đọc phần đếm theo mức nghiêm trọng mà lượt kiểm tra công bố ra dưới dạng máy đọc được.
4. Khi một người review hoặc chính tác giả gắn thẻ @claude vào một bình luận review, Claude xử lý bình luận đó rồi đẩy bản sửa lên. Luồng thảo luận trên PR ghi lại cả yêu cầu lẫn thay đổi. Vòng sửa này chạy qua claude-code-action. Còn ở dịch vụ có sẵn, việc bình luận @claude review sẽ yêu cầu một lượt review mới. Với những PR do chính Claude mở, có thể đi xa hơn và để Claude trông cái PR đó cho tới lúc được gộp. Nhiều đội gói cả vòng này vào một lệnh gạch chéo riêng, quét hết các bình luận review chưa được xử lý và các phép kiểm đang hỏng trên PR, xử lý chúng rồi đẩy bản sửa lên, cho tới khi PR xanh hết và chỉ còn chờ mỗi phê duyệt của người chủ quản code.
5. Các phát hiện khi review được đưa ngược trở lại CLAUDE.md. Khi một lượt review chỉ ra cùng một lỗi tới lần thứ hai, phần sửa lỗi đó được viết vào CLAUDE.md ngay trong lượt review ấy, và vì việc review có đọc CLAUDE.md nên lỗi đó bị bắt ngay từ PR kế tiếp trở đi. Việc review cũng chỉ ra khi nào một thay đổi đã làm CLAUDE.md trở nên lỗi thời.
6. Mỗi tháng một lần, trưởng nhóm kỹ thuật tinh chỉnh lại cả bộ máy: chấm điểm các phát hiện để người review máy khá lên, và giới hạn bớt lượng lỗi vặt trong REVIEW.md. Các đường dẫn chứa file sinh tự động và mọi thứ CI đã tự kiểm rồi đều bị loại ra.

Trông nó như thế nào (REVIEW.md)

# Hướng dẫn review

## Các lượt review
Chạy ba lượt và gắn nhãn mỗi phát hiện theo lượt của nó:
- Lỗi: sai logic, trường hợp biên bị hỏng, lỗi hồi quy khó thấy
- Bảo mật: nguy cơ tiêm mã, lỗ hổng xác thực, dữ liệu cá nhân lọt vào log
- Tuân thủ: thay đổi có khớp với spec.md, plan.md và các nguyên tắc
  thiết kế của chúng tôi không

## Ở đây Quan trọng nghĩa là gì
Chỉ dành nhãn Quan trọng cho những phát hiện có thể làm hỏng hành vi,
làm lộ dữ liệu hoặc vi phạm một chính sách. Chuyện văn phong và cách
đặt tên chỉ là lỗi vặt.

## Giới hạn lỗi vặt
Mỗi lượt review báo tối đa năm lỗi vặt; phần còn lại chỉ tóm tắt bằng
một con số đếm.

## Không cần báo
File sinh tự động nằm dưới src/gen/ và mọi thứ CI đã tự kiểm rồi.

Về mặt quản trị

Nguyên tắc tách bạch trách nhiệm được giữ nguyên, vì cái agent viết ra đoạn code đó không có cách nào tự duyệt nó. Chính sách review trong REVIEW.md được áp cho mọi PR, còn các phát hiện, các bản sửa, các lượt chấm điểm và các lần phê duyệt đều được ghi lại trong lịch sử PR, nên bản thân cái PR chính là bản ghi kiểm toán. Phê duyệt đến từ con người thông qua cơ chế bảo vệ nhánh, dựa trên những phát hiện đó.

Muốn xem các chốt kiểm soát này ghép lại với nhau ra sao ở quy mô thật, đọc thêm bài cách Anthropic bảo mật vòng đời phát triển phần mềm AI-native của mình.

Đo bằng gì

Hook đóng vai cổng duyệt

Ở chặng xây dựng, hook được dùng làm rào chắn, cho phép hoặc chặn hành động mà không cần con người tham gia (Giai đoạn 3: Xây dựng). Nhưng hook còn biết hỏi, tức là tạm dừng hành động lại cho tới khi đúng một người cụ thể duyệt, và đó chính là thứ mà việc gác cổng phát hành cần.

Nước đi này nằm ở Giai đoạn 5: Triển khai vì cổng phát hành là ví dụ rõ nhất, nhưng hook không phải chỉ dành riêng cho việc triển khai: nó chạy ở bất cứ đâu Claude hành động. Ví dụ, hook có thể chặn việc sửa các script chuyển đổi cơ sở dữ liệu và sửa hạ tầng khi chưa có phiếu yêu cầu thay đổi trong Giai đoạn 3: Xây dựng, và chặn agent sửa file test trong lúc đang làm tác vụ sửa lỗi ở Giai đoạn 4: Kiểm thử.

Bắt đầu thế nào

Các bước thực hiện

1. Ban lãnh đạo kỹ thuật, cùng với bộ phận quản lý thay đổi và bộ phận tuân thủ, liệt kê những cổng duyệt của con người bắt buộc phải giữ lại, chẳng hạn phê duyệt quản lý thay đổi, ủy quyền phát hành, và việc sửa các đường dẫn được bảo vệ.
2. Kỹ sư nền tảng diễn đạt mỗi cổng thành một hook, tức một đoạn script chạy trước khi Claude hành động, và nó có thể cho qua, hỏi lại, hoặc chặn.
3. Hook của đội thì đặt trong .claude/settings.json và đưa vào git, còn những hook không thể thương lượng thì đặt trong phần thiết lập do quản trị viên nền tảng hoặc quản trị viên IT quản, nơi từng kỹ sư không tự tắt đi được.
4. Một lệnh chặn phải tự giải thích được. Khi một hook chặn một hành động, lý do chặn và con đường để xin duyệt phải hiện ra ngay trong phần Claude trả lời.

Trông nó như thế nào (.claude/settings.json)

{
    "hooks": {
      "PreToolUse": [
        {
          "matcher": "Bash",
          "hooks": [
            { "type": "command",
              "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/production-gate.sh" }
          ]
        }
      ]
    }
}

Và bản thân cái cổng (.claude/hooks/production-gate.sh)

#!/bin/bash
# Triển khai ra môi trường thật bắt buộc phải có ủy quyền
# phát hành đích danh
cmd=$(jq -r '.tool_input.command' < /dev/stdin)
if [[ "$cmd" == *"deploy"* && "$cmd" == *"production"* ]]; then
   if [ -z "$RELEASE_APPROVAL" ]; then
     echo "Triển khai ra môi trường thật cần có ủy quyền phát hành." >&2
     exit 2 # mã thoát 2 chặn hành động lại; thông báo được gửi tới Claude
   fi
fi
exit 0

Về mặt quản trị

Hook chính là các cổng duyệt. Điều kiện của cổng được thực thi mọi lúc, với mọi người. Các quyết định cho qua và chặn đều được ghi lại kèm mốc thời gian. Cái cổng cũng định nghĩa luôn thế nào thì được tính là đã duyệt, có thể là một phiếu yêu cầu thay đổi đã được chấp thuận, hoặc chữ ký của người quản lý phát hành.

Đo bằng gì (đo chính các hook)

Tích hợp CI/CD và triển khai

Chạy Claude Code ở chế độ không tương tác ngay bên trong đường ống CI/CD, đặt phần thực thi vào vùng cách ly để các agent chạy dài vẫn an toàn, mở phần triển khai ra cho agent thông qua các tích hợp MCP, và tập dượt sẵn các đường lùi trước khi agent thật sự cần tới chúng.

Bắt đầu thế nào

Các bước thực hiện

1. Kỹ sư nền tảng bắt đầu bằng những bước phán đoán chỉ đọc. Dùng claude -p trong một tác vụ của đường ống để phân loại một bản build hỏng, tóm tắt một cái test chập chờn, hoặc soạn nháp nhật ký thay đổi.
2. Thêm các bước có ghi, nhưng đặt sau những cổng sẵn có, cho các việc như sửa lỗi lint, cập nhật tài liệu sinh tự động, hoặc xử lý bình luận review qua các lượt nhắc @claude. Bất cứ thứ gì agent viết ra đều tới dưới dạng một PR đi qua cơ chế bảo vệ nhánh, và agent không có đường nào đẩy thẳng lên nhánh chính.
3. Phần thực thi nằm trong vùng cách ly. Các tác vụ của agent chạy trong container dưới một chính sách mạng, với các token ngắn hạn có giới hạn phạm vi, và về mặc định không giữ thông tin đăng nhập nào của môi trường thật.
4. Mở phần triển khai ra qua MCP. Triển khai, xem trạng thái và lùi lại đều trở thành công cụ, giới hạn phạm vi theo từng môi trường, nhờ vậy quyền triển khai của agent là một danh sách cho phép chứ không phải một script terminal có sẵn thông tin đăng nhập.
5. Chia mức tự chủ theo môi trường. Ở môi trường phát triển, agent triển khai thoải mái. Ở môi trường thật, agent chuẩn bị bản phát hành còn người quản lý phát hành mới là người cho phép, và một hook đứng ra thực thi cổng ra môi trường thật. Môi trường thử nghiệm nằm đâu đó ở giữa.
6. Đường lùi phải là đường được tập dượt nhiều nhất trong cả đường ống, gói gọn trong một lệnh duy nhất mà agent chạy được, và được diễn tập thường xuyên ở môi trường thử nghiệm. Nước đi khép kín vòng lặp (Giai đoạn 6: Bảo trì) sẽ gọi tới đường lùi này mỗi khi một dải kiểm soát bị vượt ngưỡng, nên nó buộc phải được chứng minh là chạy được từ trước.

Trông nó như thế nào (một bước trong đường ống)

- name: Phân loại bản build hỏng
  if: failure()
  run: >
    claude -p "Đọc nhật ký build ở out/build.log. Xác định nguyên nhân
    nhiều khả năng nhất, nói rõ lỗi này trông giống lỗi chập chờn hay lỗi
    thật, và viết một bản tóm tắt ba dòng cho luồng thảo luận của PR."
    >> triage.md

Về mặt quản trị

Nguyên tắc chi phối là: agent được hành động tới sát cổng ra môi trường thật, và không vượt qua được cái cổng đó. Các chốt kiểm soát dưới đây thực thi nguyên tắc này.

• Cơ chế bảo vệ nhánh biến mọi thứ agent viết ra thành một PR, không có đường nào đi thẳng vào nhánh chính.
• Hook gác cổng triển khai ra môi trường thật chặn bản phát hành lại cho tới khi một người quản lý phát hành đích danh cho phép. Mỗi lượt chạy không tương tác đều hành động dưới danh tính riêng của agent, nên nhật ký đường ống tách bạch được thứ agent làm với thứ người kỹ sư đã kích hoạt nó làm.
• Các bậc phân quyền theo từng môi trường quy định agent được làm tới đâu trên đường tới cái cổng.

Đo bằng gì

Bảo trì và khép kín vòng lặp

Cho tới đây, chúng ta đã bàn cách đưa Claude vào từng giai đoạn của quy trình SDLC, và giai đoạn nào cũng cần một con người bấm nút khởi động những bước đầu. Còn giai đoạn này chuyển trọng tâm sang việc để Claude tự chạy nhằm khép kín vòng lặp.

Ví dụ, một agent giám sát chạy liên tục có thể, ngay sau khi một phiếu báo lỗi được mở, tạo ra một intent.md rồi chảy tiếp qua các chặng yêu cầu, kế hoạch, xây dựng, kiểm thử và review. Giai đoạn 6: Bảo trì chạy ở chế độ không giao diện, với một cổng tin cậy độc lập đặt giữa các giai đoạn, có thể là một phép kiểm cố định hoặc một agent review theo lối phản biện, quyết định xem đầu ra của giai đoạn trước được đi tiếp hay phải đẩy lên cho con người.

Khép kín vòng lặp

Một script cố định canh môi trường thật và gọi Claude dậy mỗi khi một dải kiểm soát bị vượt ngưỡng. Việc giám sát một lần vượt ngưỡng là ví dụ dễ hình dung cho mô hình vòng lặp tự chạy, còn phần Claude Tag (bản beta công khai) ở cuối giai đoạn này nói về việc công việc đi vào từ những kênh khác.

Bắt đầu thế nào

Các bước thực hiện

1. Người chủ quản dịch vụ hoặc kỹ sư nền tảng chọn ra một chỉ số có đường nền trượt ổn định, chẳng hạn tỷ lệ test hỏng trong CI, tỷ lệ lỗi 5xx sau khi triển khai, hay thời gian một vòng của PR.
2. Họ viết script phát hiện, thường là tính giá trị trung bình và độ lệch chuẩn trên một cửa sổ trượt, kèm các quy tắc (Western Electric hoặc tương tự) để dải kiểm soát bắt được cả những đợt trôi chậm lẫn những cú vọt đột ngột. Script được lưu phiên bản và có test đơn vị, và phần phát hiện giữ nguyên tính cố định, hoàn toàn không có model nào tham gia.
3. Các bậc phản ứng được khai báo trong file cấu hình có lưu phiên bản (bands.yaml bên dưới). Ở mức 1σσ là độ lệch chuẩn; 1σ, 2σ, 3σ là mức chỉ số lệch khỏi đường nền càng lúc càng xa script chỉ ghi nhật ký, ở mức 2σ nó gọi Claude ở chế độ chỉ đọc để chẩn đoán, còn ở mức 3σ Claude được phép hành động, nhưng chỉ bằng cách mở một PR vào cổng review hoặc kích hoạt một cẩm nang thao tác đã được duyệt trước.
4. Lớp kích hoạt có thể là một quy trình chạy theo lịch trên GitHub hoặc GitLab, một webhookwebhook là cách một hệ thống tự gọi sang hệ thống khác ngay khi có sự kiện xảy ra từ hệ giám sát sẵn có, hoặc một tác vụ Cron chạy trong mạng nội bộ. Claude chạy không giữ trạng thái, hoặc như một bước không tương tác trên máy chạy CI, hoặc như một dịch vụ Agent SDK trong container cách ly, và nước đi CI/CD nói về các phương án triển khai cũng như cách truy cập model. Vì lượt chạy không giữ trạng thái và không tương tác, một vòng lặp có thể bắt đầu rồi kết thúc mà không ai phải khởi động nó.
5. Agent viết phần chẩn đoán của mình thành intent.md theo đúng định dạng ở Giai đoạn 1: Lập kế hoạch, gồm điểm bất thường và bằng chứng của nó, kết quả đề xuất, các hệ thống bị ảnh hưởng và những câu hỏi còn bỏ ngỏ. Từ đó, phát hiện này đi qua đường ống như mọi thứ khác.
6. Người chủ quản dịch vụ hoặc kỹ sư trực ca phân loại hàng chờ, chuyển những phát hiện liên quan tới sản phẩm cho product owner. Sửa ngay, xếp lịch sửa, hoặc bỏ qua. Những lần bỏ qua giúp tinh chỉnh lại các dải kiểm soát và giảm bớt nhiễu.
7. Khi một bản sửa được phát hành, hãy thêm một eval cho sự cố đó (theo nước đi eval chạy liên tục) để về sau loại vấn đề này luôn được canh chừng.

Trông nó như thế nào (ví dụ một file bands.yaml giám sát tỷ lệ test hỏng trong CI)

metric: ci_test_failure_rate
baseline: rolling_30d
rules: western_electric
tiers:
  1sigma: { action: log }
  2sigma: { action: diagnose,
            tools: "Read,Grep,Bash(gh run view *)" }
  3sigma: { action: propose,
            routes: [pull_request, runbook:rollback-deploy] }

Về mặt quản trị

Ranh giới giữa các bậc được thực thi từ file cấu hình có lưu phiên bản, cùng với phần phân quyền và thiết lập do quản trị viên quản đứng ra chặn quyền truy cập môi trường thật. Các lượt gọi, các phát hiện và các quyết định phân loại đều được ghi lại kèm mốc thời gian. Người chủ quản dịch vụ phân loại và duyệt các phát hiện, những thay đổi sinh ra từ đó đi qua đúng cổng review PR bình thường, và các cẩm nang thao tác mà agent được phép kích hoạt đều đã được duyệt từ trước.

Đo bằng gì

Ví dụ

• Khi tỷ lệ test hỏng trong CI vượt ngưỡng 3σ, agent cách ly cái test chập chờn đó hoặc mở một PR hoàn tác, rồi cổng review quyết định.
• Khi tỷ lệ lỗi 5xx sau triển khai vượt ngưỡng 3σ và trong khoảng thời gian đó có một lần triển khai, agent kích hoạt đường ống lùi lại sẵn có.
• Khi thời gian một vòng của PR chạm phải một quy tắc về trôi lệch, agent viết một báo cáo gửi ban lãnh đạo kỹ thuật, cho thấy bộ khung này chạy được với cả chỉ số quy trình chứ không chỉ chỉ số môi trường thật.

Quét codebase định kỳ

Một lượt quét bảo mật là lời khẳng định tại một thời điểm về một codebase, dưới một model cụ thể, và cả hai vế đều cũ đi: code thay đổi mỗi tuần, còn mỗi thế hệ model mới lại tìm ra những lỗ hổng mà thế hệ trước bỏ sót. Câu trả lời theo lối AI-native là chạy quét theo lịch, không có con người nào trên đường gọi, và đẩy thứ tìm được qua đúng những cổng như mọi thay đổi khác trên codebase.

Claude Security là dạng dịch vụ đã dựng sẵn của việc quét theo lịch. Nối một kho GitHub vào, các lượt quét chạy trên Claude Mythos 5 trong hạ tầng của Anthropic, mỗi phát hiện đều được kiểm chứng trước khi báo ra và có kèm mức độ tin cậy. Các bản vá đề xuất được review và áp dụng trong Claude Code trên nền web. Tổ chức nhận được các phát hiện mà không cần có quyền truy cập vào chính model đó.

Bắt đầu thế nào

Các bước thực hiện

1. Trưởng bộ phận bảo mật nối các kho code vào rồi sắp chúng thành từng dự án theo kho, theo dịch vụ, hoặc theo đội, để ngay từ đầu đã rõ ai chịu trách nhiệm cho phát hiện nào.
2. Chạy một lượt quét đầy đủ đầu tiên trên những kho code trọng yếu nhất, kể cả những kho đã từng được quét bằng công cụ khác hoặc bằng model đời trước. Hãy coi lượt quét đầu tiên là mốc nền. Nhiều khả năng nó sẽ lôi ra những phát hiện nằm trong phần code vốn được cho là sạch.
3. Đặt lịch quét cho từng dự án. Mỗi tuần một lần là mặc định hợp lý cho các dịch vụ đang phát triển tích cực; còn với kho code lớn hoặc trộn nhiều thứ thì giới hạn lượt quét vào một thư mục hay một nhánh.
4. Phân loại các phát hiện với mức độ tin cậy nằm sẵn trong tay. Khi bỏ qua thì phải nêu lý do, để lần bỏ qua đó được ghi lại và cùng một phát hiện không quay lại như một cái mới ở lượt quét sau.
5. Với một phát hiện có phạm vi gọn, hãy mở bản vá đề xuất trong Claude Code trên nền web, review nó, rồi đẩy qua cổng review PR như mọi thay đổi khác. Cái agent đã đề xuất bản sửa không có đường nào tự duyệt nó.
6. Với bất cứ thứ gì rộng hơn một bản vá, chẳng hạn một điểm yếu về kiến trúc hay một mẫu lỗi lặp lại xuyên nhiều dịch vụ, hãy viết nó ra thành intent.md theo định dạng ở Giai đoạn 1 rồi khởi động lại từ chặng Lập kế hoạch.
7. Khi một bản sửa được phát hành ra môi trường thật, hãy thêm một eval cho loại lỗ hổng đó vào bộ eval từ nước đi eval chạy liên tục, để từ đó trở đi phần cấu hình lái agent luôn được kiểm với đúng loại lỗ hổng ấy.
8. Xuất các phát hiện ra dạng CSV hoặc Markdown, hoặc dùng webhook, để giữ hệ thống theo dõi và hệ thống kiểm toán sẵn có của tổ chức làm nơi lưu bản ghi chính thức, đúng chỗ mà kiểm toán viên vốn đã quen tìm tới.

Về mặt quản trị

Lượt quét chạy dưới các chốt kiểm soát của quản trị viên tổ chức, nghĩa là những kho code nào được nối vào, ai giữ suất chạy quét, và giới hạn chi tiêu, tất cả đều được đặt tập trung. Mỗi phát hiện đều có kết quả kiểm chứng và mức độ tin cậy, mỗi lần bỏ qua đều có lý do, nhờ vậy lịch sử quét trở thành một bản ghi kiểm toán về những gì đã tìm thấy, đã sửa, và đã chấp nhận một cách có ý thức.

Các bản sửa ra được tới môi trường thật thông qua cổng review PR và cơ chế bảo vệ nhánh, chứ không phải từ chính lượt quét. Claude Security bồi thêm cho phần phân tích tĩnh và quét thư viện phụ thuộc sẵn có. Các phép kiểm cố định vẫn nằm lại trong CI, còn lượt quét do model dẫn dắt thì phủ những lỗ hổng phụ thuộc vào ngữ cảnh, thứ mà các phép kiểm kia vốn không được sinh ra để tìm.

Đo bằng gì

Claude trực ca cùng Claude Tag

Sự cố còn đi vào từ những đường khác, chẳng hạn các ứng dụng nhắn tin nội bộ như Slack hay Teams. Một sự cố có thể trông như một tin nhắn Slack lúc 10 giờ đêm trong kênh sự cố xin sửa gấp, và giờ nó được xử lý ngay lập tức. Claude Tag (bản beta công khai, hiện có trên Slack) đưa Claude vào làm thành viên của những kênh đó dưới danh tính riêng của nó, nên mỗi sự cố mới đều có người ứng cứu đầu tiên, và bản thân phần ứng cứu trở thành một mắt xích của vòng lặp cũng như thành ký ức cho các sự cố sau này.

Cuộc trò chuyện và tri thức của tổ chức nằm lại ngay trong kênh, và bất kỳ ai trong kênh đều dẫn dắt và ra tay được. Bất kỳ thành viên nào cũng thử được giả thuyết, khám phá được phương án mới và điều tra ngay tại chỗ, còn lịch sử kênh thì bồi thêm vào khả năng kiểm toán. Nhờ truy cập được qua MCP, Claude xác minh chỉ số đã về lại mức nền và xác nhận điều đó ngay trong luồng thảo luận, rồi ghi bản rút kinh nghiệm vào một file bài học có lưu phiên bản để những lượt điều tra sau đọc lại được.

Sự cố không phải là loại việc duy nhất Claude Tag nhận. Được gắn thẻ trên một phiếu yêu cầu qua MCP hoặc được hỏi ngay trong kênh, Claude phân loại công việc theo đúng cách đó. Một bản sửa nhỏ và có phạm vi rõ ràng sẽ tới dưới dạng một PR đi qua cổng review, còn bất cứ thứ gì lớn hơn thì được viết ra thành intent.md cho Giai đoạn 1: Lập kế hoạch, và tới lúc đó thì vòng lặp bắt đầu tự nuôi chính nó. Xem thêm: cách Claude Tag trực ca cho CI/CD tại Anthropic.

Lời kết

Model và bộ khung chạy model đã tiến xa hơn, cho phép các tổ chức chuyển đổi không chỉ cách họ tạo ra code, mà cả vòng đời phát triển phần mềm.

Cuộc chuyển đổi này giữ phán đoán của con người ở vị trí trung tâm của quy trình, và có tính tới các đòi hỏi về quản trị cũng như về quy định pháp lý của những doanh nghiệp lớn.

Cẩm nang này gom lại nhiều cách làm tốt nhất có thật mà đội Applied AI của chúng tôi thực hiện hằng ngày cho khách hàng, và chúng tôi hy vọng bạn thấy đây là một tài liệu thiết thực, dùng được ngay.

Vòng lặp cứ chạy tiếp. Phán đoán của con người vẫn đứng bên trên nó.

Tài liệu và lời cảm ơn

Bộ tài liệu dưới đây là những gì một đội nền tảng cần để dựng các chốt kiểm soát đó, xếp gần đúng theo thứ tự bạn sẽ triển khai.

Xin cảm ơn Jim Blackhurst, Will Steuk và Jamal Arif vì những đóng góp cho cẩm nang này, thứ được truyền cảm hứng và xây dựng dựa trên phần lớn công việc trước đó của họ.