Viết bản mô tả tác vụ cho agent

Mô tả thay đổi mà người review có thể đánh giá

“Thêm xuất dữ liệu khách hàng” để ngỏ nhiều quyết định. Ai được xuất bản ghi? Bao gồm bản ghi và trường nào? Điều gì xảy ra khi request thất bại? Agent có thể điền khoảng trống bằng lựa chọn có vẻ hợp lý. Những lựa chọn đó vẫn có thể sai với doanh nghiệp.

Bắt đầu từ người dùng và vấn đề. Sau đó mô tả hành vi bắt buộc. Bao gồm bằng chứng cho thấy kết quả có chấp nhận được không.

Bản mô tả nên giảm sự chưa chắc chắn mà không ấn định mọi lựa chọn thiết kế bên trong. Nêu ranh giới dữ liệu bắt buộc. Để phần hiện thực hóa dùng mẫu hiện có trong repository trừ khi có lý do đổi.

Dùng ví dụ cụ thể

Bản mô tả sau dành cho ứng dụng hỗ trợ giả định. Đây là ví dụ học tập, không phải đặc tả production đầy đủ.

Kết quả: Quản lý hỗ trợ có thể tải danh sách khách hàng.
Người thực hiện: Quản lý trong tổ chức hiện tại.
Dữ liệu: Chỉ khách hàng đang hoạt động trong tổ chức đó.
Trường: ID khách hàng, tên công ty và trạng thái tài khoản.
Định dạng: CSV UTF-8 có hàng tiêu đề.
Request bị từ chối: Trả lỗi phân quyền hiện có.
Kết quả trống: Trả CSV hợp lệ chỉ có hàng tiêu đề.
Phạm vi: Dùng route xuất và mẫu kiểm toán hiện có.
Loại trừ: Không thêm vai trò, dependency hoặc triển khai.
Bằng chứng: Test request được phép, bị từ chối, trống và chéo tổ chức.

Bản mô tả xác định hành vi hữu ích và giới hạn. Nó cũng bộc lộ câu hỏi tiếp theo. Hệ thống có nên giới hạn kích thước bản xuất không? Trường có thể chứa công thức bảng tính không? Ai được truy cập bản ghi kiểm toán? Giải quyết câu hỏi có hậu quả đáng kể trước khi viết mã. Không xem ví dụ là checklist chung cho mọi nơi.

Phân biệt yêu cầu với giả định

Yêu cầu nêu hành vi mà thay đổi phải đáp ứng. Giả định là thông tin bạn chưa xác minh. Giữ hai loại riêng biệt.

Ví dụ, “Dùng mẫu kiểm toán hiện có” giả định có mẫu phù hợp. Yêu cầu agent tìm nó. Nếu repository không có, agent cần báo phụ thuộc còn thiếu trước khi tự tạo hệ thống kiểm toán mới.

Ràng buộc cũng có thể xung đột với kết quả. Route hiện có có thể được thiết kế để trả mọi tổ chức. Agent nên chỉ ra xung đột và đề xuất sửa có giới hạn. Nó không nên âm thầm bỏ ranh giới dữ liệu hoặc mở rộng tác vụ thành viết lại kiến trúc.

Đưa bằng chứng vào điều kiện hoàn tất

Yêu cầu tóm tắt bàn giao giải thích hành vi cuối, phạm vi đã thay đổi và kiểm tra đã thực hiện. Yêu cầu lệnh và kết quả chính xác khi quan trọng. Phân biệt kiểm tra đã đạt với kiểm tra không chạy được.

Pull request cần giữ lý do thay đổi. Người bảo trì sau có thể thấy mã mà không có hội thoại ban đầu. Cung cấp đủ ngữ cảnh để giải thích vì sao bản xuất loại trừ một số trường và cách thực thi truy cập.

Hướng dẫn mô tả thay đổi của Google là tài liệu tham chiếu hữu ích cho hồ sơ này. Mô tả cần giải thích thay đổi và mục đích. Giữ hồ sơ khớp phần hiện thực hóa cuối sau các sửa đổi review.

Giữ mức chi tiết phù hợp

Sửa văn bản nhỏ có thể dùng bản mô tả ngắn. Xuất dữ liệu cần chi tiết hơn vì lỗi có thể làm lộ thông tin. Quy trình thanh toán mới cần phân tích và review nhiều hơn nữa.

Không đo chất lượng bản mô tả bằng độ dài. Hỏi liệu người review đủ năng lực có phân biệt được kết quả đúng và sai không. Nếu hai cách hiện thực hóa hợp lý khác nhau về hành vi có hậu quả đáng kể, làm rõ hành vi đó trước.