Từ yêu cầu đến code chính là nơi việc áp dụng agent thất bại một cách âm thầm. Agent không viết code dở. Vấn đề là sáu tuần sau, không ai có thể chỉ ra một thay đổi bắt nguồn từ yêu cầu nào, ai đã phê duyệt phạm vi, hay người review đã thấy bằng chứng gì trước khi chấp nhận nó. Code đến rất nhanh. Nhưng bản ghi thì không.
Hướng dẫn này xây dựng bản ghi một cách có chủ đích: một chuỗi từ yêu cầu được viết ra đến pull request đã merge, trong đó mỗi mắt xích là thứ bạn có thể mở ra xem. Spec Kit của GitHub giải quyết khoảng trống tương tự bằng các file trong repository. Hướng dẫn này giải quyết bằng một work system, dùng Sharkly vì nó giữ toàn bộ chuỗi trên một Task, dù mô hình này có thể chuyển sang bất kỳ tracker nào chứa được các liên kết tương tự. Nếu bạn muốn nắm vòng vận hành trước, hãy bắt đầu với hướng dẫn của chúng tôi về quản lý dự án với AI agent.
TL;DR
Một quy trình từ yêu cầu đến code có thể truy vết là quy trình mà ở đó mọi artifact đều trỏ về artifact đã tạo ra nó: yêu cầu, Task, sub-task, các lượt chạy, pull request, nghiệm thu. Trong Sharkly, yêu cầu trở thành một Task, Agent đề xuất cách chia nhỏ trong Plan mode và một người xác nhận, mỗi sub-task chạy trong một worktree riêng biệt kèm execution log, pull request liên kết ngược lại qua Task ID, và một người nghiệm thu kết quả dựa trên tiêu chí nghiệm thu đã viết từ đầu. Agent nghiên cứu, thực thi, kiểm thử và báo cáo. Con người định hướng, trao quyền và nghiệm thu kết quả.
Truy vết phải có nghĩa là gì
Truy vết không phải là một báo cáo bạn tạo ra ở cuối. Đó là một thuộc tính của chuỗi: mỗi mắt xích tồn tại là nhờ mắt xích trước đó, và bạn có thể đi theo chuỗi theo cả hai chiều. Sáu mắt xích là đủ để bao phủ một tính năng.
| Mắt xích | Nằm ở đâu | Cái gì nối nó với mắt xích trước |
|---|---|---|
| Yêu cầu | Mô tả Task, task type Requirement hoặc User Story | Người đã viết ra nó |
| Chia nhỏ | Các sub-task thuộc Task cha | Đề xuất ở Plan mode đã được xác nhận |
| Thực thi | Các lượt chạy của Task và execution log | Việc gán assignee cùng trạng thái sẵn sàng |
| Bằng chứng | Comment của Agent kèm các kiểm tra và kết quả | Lượt chạy đã tạo ra nó |
| Thay đổi | Pull request | Task ID trong branch, tiêu đề hoặc nội dung |
| Nghiệm thu | Thay đổi trạng thái bởi một người cụ thể | Việc review dựa trên tiêu chí nghiệm thu |
Nếu thiếu bất kỳ mắt xích nào, chuỗi chỉ còn mang tính trang trí. Khoảng trống phổ biến nhất nằm ở mắt xích cuối: một pull request đã merge bị coi là đã nghiệm thu, dù không ai đối chiếu thay đổi với yêu cầu.
Bước 1: Viết yêu cầu dưới dạng một Task
Task là đơn vị công việc được theo dõi cơ bản trong Sharkly, và một Space được thiết lập cho phát triển phần mềm sẽ khởi đầu với các task type Requirement, Bug, Task và User Story. Hãy dùng Requirement hoặc User Story cho task cha. Task type quyết định những custom field và trạng thái Workflow nào được áp dụng, nhờ đó một Requirement có thể mang trạng thái review riêng mà không làm nhiễu workflow của Bug.
Phần mô tả gánh phần lớn trọng trách. Hãy viết cho một người chưa từng thấy cuộc trao đổi: vì sao công việc này quan trọng, phạm vi bao gồm và loại trừ những gì, các file liên quan hoặc hành vi quan sát được, những quyết định đã đưa ra, và cách đánh giá khi hoàn thành. Dòng cuối cùng đó chính là tiêu chí nghiệm thu, điểm neo cho mắt xích thứ sáu. Nếu bạn chưa thể viết được, nghĩa là yêu cầu chưa sẵn sàng, và Backlog sinh ra chính vì điều đó: một Task được gán cho Agent sẽ không khởi chạy khi còn nằm ở đó.
Hãy gắn repository ở cấp Space để mọi sub-task đều kế thừa. Một Agent không có repository binding sẽ dùng các Git repository của Space làm mặc định, đúng như bạn mong muốn với một tính năng gồm nhiều Task.
Bước 2: Để Agent định hình cách chia nhỏ, rồi xác nhận
Mở Agent chat của Task và chuyển phiên sang Plan mode. Ở Plan mode, Agent có thể đề xuất hành động để bạn xem xét, và Sharkly chỉ tạo Task cùng các sub-task đã lên kế hoạch sau khi bạn xác nhận đề xuất. Bạn có thể xác nhận mà không khởi chạy, hoặc xác nhận rồi bắt đầu công việc.
Đây là mắt xích mà hầu hết các team bỏ qua, và nó chính là thứ khiến việc chia nhỏ có thể truy vết thay vì tùy hứng. Đề xuất hiện ra trước khi trở thành công việc: bạn có thể xóa sub-task làm phình phạm vi, thêm bước migration mà Agent bỏ sót. Các sub-task nằm cùng Space với task cha, và Sharkly từ chối việc tự làm cha chính mình cũng như các vòng lặp, nên hệ thống phân cấp luôn giữ dạng cây.
Dùng một Agent duy nhất cho yêu cầu mà một vai trò có thể đảm nhiệm. Dùng Crew khi leader cần diễn giải mục tiêu, huy động các thành viên Agent khác như người viết test, và tổng hợp kết quả của họ về một Task. Với một thay đổi chỉ gồm ba file, Crew chỉ thêm các phần phải vận hành mà không tăng thêm khả năng truy vết. Hướng dẫn của chúng tôi về Sharkly Crews trình bày mô hình lấy leader làm trung tâm.
Hãy sao chép mọi nội dung đã quyết trong chat vào phần mô tả Task. Chat trên một Task không phải là comment và không xuất hiện trong Activity, nên một quyết định chỉ nằm ở đó sẽ vô hình với chuỗi.
Bước 3: Thực thi trong môi trường tách biệt, kèm dấu vết
Gán từng sub-task cho một Agent qua điều khiển Assignee, rồi đưa nó ra khỏi Backlog. Sharkly kiểm tra category của trạng thái và mức độ sẵn sàng thực thi, đưa lượt chạy vào hàng đợi và điều phối đến Computer đã chọn, tại đó service cục bộ chuẩn bị một thư mục task tách biệt và khởi động Runtime.
Hai chi tiết giữ cho mắt xích này trung thực. Lượt chạy bao gồm tiêu đề và mô tả của Task, các comment gần đây, cùng Workflow của task type với những trạng thái được phép, nên Agent làm việc dựa trên chính yêu cầu chứ không phải một bản diễn giải lại. Và mỗi lượt chạy gắn với repository đều có worktree riêng ở Temporary mode, nên các sub-task chạy song song không thể ghi đè lên nhau. Bài viết của chúng tôi về chạy agent song song mà không xảy ra merge conflict giải thích vì sao tách biệt chính là yếu tố khiến việc fan-out trở nên an toàn.
Tiến độ, các trace event và kết quả đều quay về Task. Execution log ghi lại lý do lượt chạy được đưa vào hàng đợi, thời điểm bắt đầu và kết thúc, các tool call và Runtime event, nguồn kích hoạt, cùng chi tiết lỗi. Log đó chính là mắt xích thứ tư.
Bước 4: Liên kết pull request bằng ID
Kết nối GitHub organization một lần, sau đó đặt Task ID vào tiêu đề pull request, phần mô tả hoặc tên branch nguồn. Chỉ cần SH-312 hoặc Fixes SH-312 đều tạo được liên kết. Linkback sẽ comment URL của Task lên pull request, mặc định được bật với repository riêng tư.
Giờ đến ranh giới, vì điều này quan trọng với truy vết: những từ như fixes hay closes không mang thêm ý nghĩa nào, và việc merge pull request không làm thay đổi trạng thái của Task. Sharkly liên kết thay đổi với Task; nó không quyết định rằng Task đã xong. Trạng thái vẫn là quyết định của con người, và đó chính là ý nghĩa cốt lõi của mắt xích thứ sáu. Bài hướng dẫn của chúng tôi về gán một Jira ticket cho AI agent và nhận lại PR cho thấy liên kết tương tự từ phía tracker.
Bước 5: Review dựa trên yêu cầu, rồi nghiệm thu
Agent có thể để một Task ở trạng thái chờ người review, và tín hiệu đó sẽ vào Inbox của người phụ trách, mục Primary. Hãy đọc ba thứ theo thứ tự: tiêu chí nghiệm thu từ bước một, comment của Agent liệt kê các kiểm tra đã chạy và những điểm còn chưa chắc chắn, và execution log. Chỉ sau đó mới xem diff.
Nếu có một Task test riêng kiểm chứng thay đổi, hãy ghi lại mối quan hệ đó một cách tường minh. Organization Owner và Admin có thể tạo custom link type, và ví dụ của chính tài liệu, validates / is validated by, chính là cạnh truy vết cho mắt xích này. Relation không tự thay đổi trạng thái, nên việc nghiệm thu vẫn phải là thay đổi trạng thái do con người thực hiện.
Một quy tắc về category sẽ bảo vệ bạn ở đây: chuyển Task sang Completed sẽ đánh dấu nó là trạng thái kết thúc nhưng không hủy một lượt chạy đang hoạt động. Nếu Agent vẫn đang làm, hãy hủy trước, rồi mới quyết định.
Chuỗi đứt ở đâu
Quy trình trên có ba điểm đứt đã biết, và chúng đáng được nói thẳng.
Kết luận bị bỏ lại trong chat. Các phiên Agent Chat độc lập thuộc về người tạo ra chúng. Nếu thiết kế đã được chốt ở đó, Task không hề biết.
Lượt chạy khởi phát ngoài một Task. Hành động Run Agent của một automation workflow không tạo Task; lượt chạy được ghi nhận trên Agent. Điều này ổn với một kiểm tra chạy hằng đêm, nhưng sai với công việc tính năng.
File thay vì một bản ghi. spec.md, plan.md và tasks.md của Spec Kit là một chuỗi vững chắc cho một developer làm việc trong một repository. Hãy dùng chúng khi cả team chỉ có bạn. Hãy dùng một work system chia sẻ khi có người thứ hai cần review, nghiệm thu, hoặc hỏi chuyện gì đã xảy ra mà không phải mở bản checkout của bạn. Sharkly không thay thế Claude Code, Codex hay các công cụ thực thi khác; nó là lớp giữ cho chuỗi luôn hiển thị xung quanh chúng. Tài liệu trình bày chi tiết hơn từng khái niệm tại docs.sharkly.ai.
FAQ
“Từ yêu cầu đến code” có nghĩa là Agent viết yêu cầu phải không? Không. Con người viết yêu cầu và tiêu chí nghiệm thu của nó. Agent có thể nghiên cứu codebase và đề xuất cách chia nhỏ trong Plan mode, nhưng đề xuất chỉ trở thành Task sau khi có người xác nhận.
Tôi có thể giữ yêu cầu trong Jira mà vẫn có được vết truy vết không? Có. Tính năng import và sync Jira giữ nguyên tracker mà tổ chức bạn đang dùng, trong khi Sharkly nắm bản ghi thực thi. Bài viết các lựa chọn thay thế Jira cho team người-agent của chúng tôi đề cập trường hợp chính tracker cũng cần được thay thế.
Nếu pull request được merge trước khi review thì sao? Trạng thái Task không thay đổi, nên chuỗi sẽ cho thấy một Task chưa được nghiệm thu với một thay đổi đã merge. Đó là tín hiệu đúng: vẫn còn một người chưa đưa ra quyết định.
Tính năng truy vết đầu tiên nên nhỏ cỡ nào? Một yêu cầu, hai hoặc ba sub-task, một Agent. Bài hướng dẫn về quản lý dự án với Claude Code của chúng tôi chạy trọn vòng lặp trên một Task duy nhất.
