Sửa code theo tài liệu nào khi bản cũ vẫn có vẻ đúng?

Thử hình dung một biểu mẫu đặt lịch cần thêm thông báo về việc hủy lịch. Trước khi sửa biểu mẫu, ai đó phải tìm chính sách hủy lịch, nên họ tra trong kho tài liệu nội bộ (wiki) của nhóm và nhận về hai tài liệu có vẻ phù hợp: một ghi chú lập kế hoạch và một hướng dẫn hỗ trợ. Cả hai đều nhắc đến chuyện hủy lịch và đều viết rất chắc chắn, mà rắc rối nằm ở đó, vì ghi chú cũ có thể thuyết phục chẳng kém hướng dẫn đang áp dụng. Nếu người sửa chọn nhầm tài liệu, kết quả có thể là một biểu mẫu được sửa rất chỉn chu nhưng lại làm theo một quyết định cũ.

Chuyện tương tự cũng có thể xảy ra khi người đi tìm là một agent lập trình, tức một trợ lý AI có thể đọc và sửa code. Một câu khớp từ khóa trong kết quả tìm kiếm giúp agent thu hẹp phạm vi, nhưng không cho nó biết cả tài liệu đó có thực sự là hướng dẫn áp dụng cho biểu mẫu này hay không. Điều mình muốn là cả quá trình để lại dấu vết rõ ràng từ câu hỏi ban đầu đến tài liệu mà bản sửa dựa vào, nghĩa là agent dùng kết quả tìm kiếm để chọn tài liệu, đọc nội dung hiện tại của tài liệu ấy, rồi giữ liên kết của nó đi cùng công việc.

Đây là một trong những vấn đề khiến mình tạo ra Outline CLI, công cụ dành cho những nhóm lưu tài liệu nội bộ trên Outline, một ứng dụng quản lý kho kiến thức, để người dùng hoặc agent có thể tìm, đọc và sửa các tài liệu đó bằng cách gõ lệnh trong cửa sổ dòng lệnh (terminal). Dùng công cụ này cho việc chọn tài liệu giống một lần lên thư viện tra cứu cẩn thận: xem qua phiếu mục lục trước, chỉ mượn đúng cuốn cần đọc, rồi ghi lại đoạn trích lấy từ đâu. Cụ thể, lệnh tìm kiếm trả về một danh sách ngắn gồm bản tóm tắt hoặc ID tài liệu, lệnh đọc lấy nội dung tài liệu mà agent đã chọn, còn lệnh sửa có thể cho xem trước rồi áp dụng một bản sửa nhỏ, với điều kiện agent đã nói rõ ý định ghi và tài liệu vẫn đang ở đúng phiên bản mà bản sửa dựa vào. Các phần dưới đây theo từng bước agent tìm và dùng chính sách hủy lịch để sửa biểu mẫu đặt lịch.

Khi tìm kiếm trả về vài tài liệu

Tìm "hủy lịch" có thể ra vài tài liệu khác nhau. Outline CLI trả về một nhóm nhỏ bản tóm tắt hoặc ID tài liệu, nên agent chọn trong danh sách đó rồi mới yêu cầu nội dung của tài liệu trông có vẻ liên quan. Nhờ vậy kết quả tìm kiếm chỉ cần làm một việc vừa sức là giúp quyết định mở tài liệu nào tiếp theo, và cuộc trao đổi với agent cũng không bị lấp đầy bởi toàn bộ nội dung tài liệu trước khi ai biết chúng có cần thiết hay không.

Một đoạn trích hữu ích là đoạn dẫn người đọc về tài liệu gốc. Khi câu chữ hiện tại của chính sách là điều quan trọng, agent phải mở tài liệu ra và tự đọc đúng câu chữ ấy.

Khi agent đã sẵn sàng sửa biểu mẫu

Đọc xong hướng dẫn hủy lịch, agent có thể đã đủ thông tin để sửa biểu mẫu. Nhưng nếu ghi chú lập kế hoạch và hướng dẫn vẫn nói khác nhau, cần có người giải quyết chỗ vênh ấy trước khi nó thành một quy tắc trên giao diện.

Khi yêu cầu đã rõ, liên kết đến tài liệu nguồn có thể đi theo công việc. Người rà soát mở được chính sách mà không phải tìm lại từ đầu, còn người chuẩn bị bàn giao để kiểm thử dùng chính liên kết đó để quyết định hành vi nào cần kiểm tra.

Khi phải sửa luôn tài liệu hướng dẫn

Đôi khi công việc bao gồm cả việc cập nhật hướng dẫn hủy lịch, và việc đó bắt đầu bằng một lần đọc lại bản hiện tại của tài liệu, vì bản sửa phải tính đến nội dung đang có, kể cả những thay đổi xuất hiện trong lúc biểu mẫu đang được làm.

Outline CLI có thể cho xem trước phần khác biệt và chỉ áp dụng bản sửa vào đúng chỗ cần đổi, nên đổi vài chữ thì bản sửa cũng chỉ có vài chữ, và người xem dễ đánh giá điều gì sẽ xảy ra với tài liệu. Yêu cầu sửa biểu mẫu và yêu cầu viết lại chính sách của biểu mẫu là hai phần việc riêng, nên việc sửa hướng dẫn phải nằm trong yêu cầu công việc của người dùng, và khi thực hiện, lệnh còn yêu cầu thể hiện rõ ý định ghi thay đổi.

Khi ai đó đã sửa tài liệu trong lúc mình làm

Mỗi tài liệu có một revision, tức số phiên bản. Trước khi áp dụng bản sửa, CLI kiểm tra xem tài liệu còn ở đúng phiên bản mà bản sửa dựa vào hay không, và nếu không khớp thì agent cần đọc lại tài liệu rồi cân nhắc lại đề xuất của mình.

Bước kiểm tra này có một giới hạn thực tế: nó chạy trước khi gửi thao tác ghi và không khóa tài liệu, nên người khác vẫn có thể sửa trong khoảng thời gian ấy. Mình nói rõ giới hạn này để mọi người hiểu công cụ thực sự bảo vệ được điều gì.

Cách mình giữ agent đi đúng lối

Mình dẫn dắt việc phát triển Outline CLI và đặt ra cách agent đi từ kết quả tìm kiếm đến nội dung hiện tại của tài liệu trước khi chuẩn bị bản sửa. Agent lập trình làm một phần đáng kể việc viết code, còn mình rà lại các thay đổi trong code, thử xem agent có thật sự đi đúng con đường ấy không, và chỉnh lại hướng dẫn khi một bước nào đó chưa rõ. Một trong những hướng dẫn đó là yêu cầu agent trả về liên kết của tài liệu gốc để người khác mở được đúng tài liệu agent đã đọc.

Thứ mình hướng tới là một thay đổi mà ai cũng kiểm tra lại được căn cứ. Bạn lần về được tài liệu, thấy câu chữ đã quyết định bản sửa và biết phần nào cần xem lại nếu sau này chính sách hủy lịch thay đổi.

Đọc, áp dụng bản sửa và xóa

Hướng dẫn sử dụng trình bày cách tìm kiếm gọn, đọc tài liệu đã chọn và chỉnh sửa có chủ đích. Thao tác ghi cần performAction:true. Xóa còn yêu cầu xác nhận rằng tài liệu được chọn đã được đọc gần đây trong đúng hồ sơ kết nối (profile) của không gian làm việc, và xác nhận này có thời hạn. Các bài kiểm thử trong repo kiểm tra việc khớp đúng tài liệu đích khi xóa và yêu cầu đối chiếu với phiên bản tài liệu mà bản sửa dựa vào. Những điều kiện này của lệnh hỗ trợ quy trình, còn căn cứ cho phép thực hiện vẫn là yêu cầu công việc của người dùng.