OpenSpec

Khám phá trước tiên ​

/opsx:explore là đối tác tư duy của bạn. Hãy sử dụng nó bất cứ khi nào bạn gặp một vấn đề nhưng chưa có kế hoạch. Nó sẽ điều tra cơ sở mã (codebase) của bạn, cùng bạn cân nhắc các phương án và làm rõ những gì bạn thực sự muốn, tất cả trước khi bất kỳ tài liệu nào hoặc dòng mã nào được tạo ra. Khi bức tranh đã rõ ràng, nó sẽ chuyển tiếp sang /opsx:propose.

Nếu bạn chỉ nhớ được một thói quen từ tài liệu này, hãy nhớ điều này: khi không chắc chắn, hãy khám phá trước khi đề xuất.

Đây là lý do tại sao điều đó lại quan trọng. Các trợ lý lập trình AI rất nhiệt tình. Nếu bạn đặt câu hỏi chung chung, chúng sẽ tự tin xây dựng một cái gì đó, chỉ có thể không phải là thứ bạn cần. Explore chính là giải pháp khắc phục. Đó là một cuộc trò chuyện không rủi ro, nơi bạn và AI cùng nhau tìm ra bước đi đúng đắn, để đến lúc bạn đề xuất, bạn đang đề xuất đúng thứ.

Khi nào nên khám phá ​

Explore là bước đầu tiên phù hợp trong nhiều trường hợp hơn mọi người thường nghĩ. Hãy sử dụng nó khi bất kỳ điều nào sau đây đúng:

  • Bạn biết vấn đề nhưng không biết giải pháp. ("Trang tải chậm." "Xác thực (Auth) lộn xộn." "Chúng ta liên tục nhận được đơn hàng trùng lặp.")
  • Bạn đang lựa chọn giữa các phương pháp tiếp cận và muốn xem xét các đánh đổi dựa trên mã nguồn thực tế của mình.
  • Bạn mới làm quen với cơ sở mã và cần hiểu cách hoạt động của một thứ gì đó trước khi thay đổi nó.
  • Yêu cầu còn mơ hồ và bạn muốn làm rõ chúng trước khi cam kết.
  • Bạn nghi ngờ khối lượng công việc lớn hơn hoặc nhỏ hơn vẻ bề ngoài và muốn định phạm vi một cách trung thực.

Chỉ bỏ qua bước khám phá khi bạn đã biết chính xác những gì mình muốn và cách thực hiện. Trong trường hợp đó, hãy chuyển thẳng đến /opsx:propose.

Những gì nó làm (và không làm) ​

Explore là một cuộc trò chuyện, không phải là một trình tạo nội dung.

Nó làm:

  • Đọc và tìm kiếm cơ sở mã của bạn để trả lời các câu hỏi thực tế.
  • So sánh các phương án và nêu rõ các đánh đổi của từng phương án.
  • Vẽ sơ đồ để thiết kế trở nên dễ hiểu.
  • Giúp bạn thu hẹp một ý tưởng mơ hồ thành một phạm vi cụ thể, có thể xây dựng được.
  • Chuyển tiếp sang /opsx:propose khi bạn sẵn sàng.

Nó không làm:

  • Tạo thư mục thay đổi (change folder).
  • Viết bất kỳ tài liệu nào (không có đề xuất, đặc tả, thiết kế hoặc nhiệm vụ).
  • Viết hoặc sửa đổi mã.

Đó chính là điểm mấu chốt. Việc khám phá không tốn kém cho bạn và cũng không cam kết bạn vào bất cứ điều gì. Bạn có thể khám phá ba ngõ cụt, học hỏi được điều gì đó từ mỗi lần, và chỉ sau đó mới đề xuất con đường khả thi nhất.

Nó đã được cài đặt sẵn ​

Tin tốt: /opsx:explore được tích hợp sẵn trong hồ sơ core mặc định, ngay bên cạnh propose, apply, update, sync và archive. Bạn không cần bật thêm bất kỳ tùy chọn nào. Nếu OpenSpec đã được thiết lập trong dự án của bạn, explore đã sẵn sàng trong cửa sổ chat AI của bạn. (Giống như tất cả các lệnh /opsx:*, bạn gõ nó vào chat của trợ lý, không phải terminal. Xem Cách lệnh hoạt động.)

Một ví dụ đầy đủ ​

Hãy xem cách một mối lo ngại mơ hồ trở thành một thay đổi sắc bén, có thể xây dựng được.

text
Bạn: /opsx:explore

AI:  Bạn muốn khám phá điều gì?

Bạn: Đôi khi quy trình thanh toán của chúng tôi tạo ra các đơn hàng trùng lặp. Tôi không biết tại sao
     và tôi không biết cách sửa lỗi này một cách an toàn.

AI:  Để tôi đào sâu vào luồng thanh toán...
     [đọc dịch vụ xử lý đơn hàng, trình xử lý webhook thanh toán và
      logic gửi yêu cầu từ phía client]

     Đây là những gì tôi tìm thấy. Có hai cách mà sự trùng lặp có thể xảy ra:

     1. Client có thể gửi yêu cầu hai lần (nhấp đúp, thử lại khi mạng chậm).
        Không có cơ chế chống trùng lặp (debounce).
     2. Webhook thanh toán có thể kích hoạt nhiều hơn một lần, và trình xử lý
        tạo đơn hàng mỗi khi điều đó xảy ra. Không có khóa tính toàn vẹn (idempotency key).

     Nguyên nhân #2 là nguy hiểm hơn: nó có thể tính phí và hoàn thành đơn hàng hai lần.

     Ba cách để sửa lỗi này, sắp xếp theo mức độ bền vững giảm dần:
     - Khóa tính toàn vẹn trên endpoint tạo đơn hàng (xử lý được cả hai nguyên nhân)
     - Loại bỏ trùng lặp trên webhook dựa trên payment-intent id (chỉ xử lý được #2)
     - Debounce phía client (chỉ xử lý được #1, che giấu lỗi thực sự)

     Vì mã hiện tại của bạn đã lưu trữ payment-intent id,
     phương pháp khóa tính toàn vẹn là một thay đổi nhỏ nhưng mang lại hiệu quả lớn nhất.
     Bạn có muốn tôi xác định phạm vi cho giải pháp này không?

Bạn: Đúng vậy, hãy dùng khóa tính toàn vẹn.

Bạn: /opsx:propose add-order-idempotency-key

AI:  Đã tạo openspec/changes/add-order-idempotency-key/, với bản đề xuất
     và đặc tả delta dựa trên những gì chúng ta vừa tìm thấy. Sẵn sàng để triển khai.

Hãy chú ý những gì đã xảy ra. Điểm bắt đầu là "có gì đó sai sót và tôi sợ chạm vào nó". Hai mươi giây khám phá đã biến điều đó thành một nguyên nhân gốc rễ được đặt tên, ba phương án được xếp hạng, một khuyến nghị gắn liền với mã hiện có và một thay đổi chính xác. Bản đề xuất tiếp theo sắc bén vì quá trình suy nghĩ đã diễn ra trước đó.

Chuyển tiếp sang propose ​

Explore không lưu trữ vào bất kỳ cấu trúc nào. Khi bạn sẵn sàng, bạn chỉ cần bắt đầu một thay đổi, và AI sẽ mang ngữ cảnh từ cuộc trò chuyện của bạn vào các tài liệu.

text
explore  ──►  propose  ──►  apply  ──►  archive
 (suy nghĩ)    (đồng ý)       (xây dựng)   (ghi lại)

Bạn có thể nói bằng ngôn ngữ thông thường ("hãy biến điều này thành một thay đổi") hoặc chạy trực tiếp /opsx:propose <tên>. Dù bằng cách nào, phần khám phá bạn vừa thực hiện sẽ trở thành nền tảng cho bản đề xuất, chứ không phải là đoạn chat bị loại bỏ.

Nếu bạn sử dụng bộ lệnh mở rộng, explore có thể chuyển tiếp sang /opsx:new thay thế, để tạo từng bước các tài liệu. Xem Quy trình làm việc.

Mẹo cho một buổi khám phá hiệu quả ​

  • Mang theo vấn đề, không phải giải pháp. "Đăng nhập cảm giác chậm" giúp AI có không gian để điều tra. "Thêm bộ nhớ đệm Redis" khiến bạn cam kết trước với một câu trả lời mà bạn chưa kiểm chứng.
  • Yêu cầu nêu rõ các đánh đổi. "Nhược điểm của mỗi phương án là gì?" sẽ mang lại cho bạn một so sánh trung thực hơn.
  • Để nó đọc trước. Những buổi khám phá tốt nhất bắt đầu bằng việc AI thực sự nhìn vào mã của bạn, chứ không phải đoán mò. Chỉ cho nó khu vực liên quan nếu cần.
  • Việc rút lui là bình thường. Nếu việc khám phá cho thấy ý tưởng không đáng giá, đó là một chiến thắng. Bạn đã học được điều đó với chi phí thấp.
  • Khám phá lại giữa chừng. Bị mắc kẹt trong /opsx:apply? Bạn có thể quay lại và khám phá một vấn đề phụ, sau đó quay trở lại.

Các đánh đổi trung thực ​

Những gì bạn đạt được: explore ngăn chặn các hướng đi sai lầm ở thời điểm rẻ nhất có thể, trước khi bất kỳ tài liệu nào tồn tại. Nó đặc biệt mạnh mẽ trong các cơ sở mã lạ, nơi khả năng đọc và tóm tắt hệ thống của AI giúp bạn tiết kiệm cả buổi chiều mày mò.

Chi phí của nó: một chút kiên nhẫn. Explore là một cuộc trò chuyện, vì vậy nó chậm hơn việc bắn ra lệnh /opsx:propose và hy vọng. Đối với công việc mà bạn thực sự đã hiểu rõ, bước bổ sung này là gánh nặng thuần túy, và bạn nên bỏ qua nó.

Quy tắc ngón tay cái: nhiệm vụ càng mơ hồ, explore càng mang lại lợi ích. Nhiệm vụ càng rõ ràng, bạn càng có thể bỏ qua và chuyển thẳng sang đề xuất.

Nơi đi tiếp ​