Một nhà phát triển đã chuyển quy trình làm việc Claude Code đã sử dụng nhiều tháng sang OpenCode và phát hiện ra rằng việc xử lý tệp, tải quy tắc, danh mục công cụ, siêu dữ liệu kỹ năng và bộ nhớ xuyên phiên đều bị lỗi. Những bản sửa lỗi mà anh ấy đã ghi lại hiện đóng vai trò như một danh sách kiểm tra thực tế cho bất kỳ ai đang chuyển từ hệ sinh thái của Claude sang giải pháp thay thế mã nguồn mở.

Tại sao việc di chuyển lại quan trọng

Người dùng Claude Code phụ thuộc vào một bộ tệp được đóng gói chặt chẽ—các quy tắc, định nghĩa kỹ năng và nhật ký bộ nhớ—để giữ cho trợ lý lập trình dựa trên AI hoạt động trơn tru. Khi thiết lập của tác giả ngừng tải các quy tắc, làm xáo trộn các tệp và khiến lượng token sử dụng tăng vọt, trợ lý lập trình hàng ngày của anh ấy đã trở nên không đáng tin cậy. OpenCode hứa hẹn "bảo mật ưu tiên quyền" (permission-first security), khả năng truy cập không phụ thuộc vào mô hình thông qua OpenRouter và mức giá trả theo mức sử dụng, khiến nó trở nên hấp dẫn. Nhưng quá trình chuyển đổi không chỉ đơn giản là sao chép-dán; bạn phải khai báo lại mọi thành phần theo định dạng mà OpenCode mong đợi.

Điều gì dẫn đến sự cố

Claude Code sử dụng một tệp có tên là CLAUDE.md, trong khi OpenCode bỏ qua tệp này và thay vào đó đọc AGENTS.md để lấy thêm siêu dữ liệu. Tác giả đã giả định rằng hai hệ thống này có thể thay thế cho nhau, khiến nhiều thành phần cốt lõi trở nên "vô hình" đối với OpenCode.

Các lỗi cụ thể và cách khắc phục

  • Tệp quy tắc bị bỏ qua
    OpenCode không bao giờ đọc CLAUDE.md; nó chỉ phân tích AGENTS.md. Việc đổi tên tệp là không đủ vì nội dung phải được khai báo lại theo định dạng mới.
    Cách khắc phục: Tạo một tệp AGENTS.md mới, sao chép văn bản quy tắc, bắt đầu một phiên OpenCode mới và hỏi agent “Quy tắc của tôi là gì?”. Nếu nó không thể trích dẫn chúng, nghĩa là các quy tắc chưa được tải.

  • Thiếu danh mục công cụ
    Lệnh di chuyển lẽ ra phải sao chép các kỹ năng và máy chủ MCP (multi-cloud platform) đã thất bại vì OpenCode không thể lập danh mục các công cụ chưa bao giờ được đăng ký.
    Cách khắc phục: Trong khi các công cụ của Claude Code vẫn đang chạy, hãy liệt kê thủ công mọi kỹ năng và lệnh. Quyết định xem cái nào cần xây dựng lại trong OpenCode và cái nào nên bỏ qua.

  • Front-matter bị mất khỏi các kỹ năng
    Các tệp kỹ năng được chuyển sang đã mất hầu hết phần front-matter, bao gồm việc chỉ định mô hình và các chỉ thị xử lý công cụ. OpenCode chỉ tôn trọng một số ít các trường, vì vậy các kỹ năng được nhập vào hoạt động không thể dự đoán được.
    Cách khắc phục: Hãy coi mọi kỹ năng được nhập vào đều bị lỗi. Tạo lại ba kỹ năng được sử dụng nhiều nhất từ đầu, đảm bảo chúng chỉ chứa các trường được hỗ trợ. Xóa bất kỳ tệp kỹ năng nào không sử dụng.

  • Không có bộ nhớ xuyên phiên
    Claude Code lưu giữ một lịch sử liên tục mà tác giả đã dựa vào để lấy ngữ cảnh. OpenCode không duy trì bộ nhớ giữa các phiên, vì vậy trợ lý đã “quên” mọi thứ ngay sau ngày chuyển đổi.
    Cách khắc phục: Thêm một hướng dẫn rõ ràng vào AGENTS.md: “Vào cuối mỗi phiên, hãy thêm một bản tóm tắt ngắn gọn vào session-log.md bao gồm những gì đã làm, những gì còn tồn đọng và các quyết định đã đưa ra.” Khi đó, nhật ký phiên sẽ trở thành nguồn sự thật duy nhất để duy trì tính liên tục.

Những gì bạn đạt được và những gì bạn mất đi

Ưu điểm

  • Bảo mật ưu tiên quyền: OpenCode sẽ hỏi trước khi thực hiện bất kỳ hành động nào, giúp giảm thiểu các thay đổi mã không mong muốn.
  • Tự do về mô hình: Một mã API duy nhất có thể mở khóa hàng chục mô hình thông qua OpenRouter, cho phép bạn thử nghiệm mà không cần thay đổi các tệp cấu hình.
  • Kiểm soát chi phí: Việc thanh toán dựa trên mức sử dụng, tránh được gói đăng ký trả phí cố định vốn có thể trở nên đắt đỏ khi lượng tiêu thụ token tăng vọt.

Nhược điểm

  • Không có bộ nhớ dài hạn tích hợp có nghĩa là bạn phải duy trì một nhật ký thủ công.
  • Siêu dữ liệu kỹ năng hạn chế buộc bạn phải xây dựng lại hầu hết các công cụ tùy chỉnh của mình.

Danh sách kiểm tra di chuyển thực tế

  1. Tạo AGENTS.md trước – khai báo mọi quy tắc bạn cần trước khi nhập bất kỳ tệp nào khác.
  2. Thêm hướng dẫn nhật ký phiên – chèn quy tắc “thêm bản tóm tắt” vào đầu tệp AGENTS.md.
  3. Xây dựng lại ba kỹ năng hàng đầu – chỉ sao chép các trường được hỗ trợ; kiểm tra từng kỹ năng một cách độc lập.
  4. Khai báo lại MCP một cách thủ công – liệt kê từng máy chủ hoặc điểm cuối đám mây mà bạn vẫn cần truy cập.
  5. Xác thực – bắt đầu một phiên OpenCode mới và truy vấn trợ lý về các quy tắc, danh sách kỹ năng và trạng thái bộ nhớ của nó.

Bài học rút ra

Việc di chuyển từ Claude Code sang OpenCode không hẳn là việc di chuyển các tệp, mà là việc tái cấu trúc các khai báo điều khiển trợ lý. Quá trình này buộc bạn phải lược bỏ về các quy tắc cốt lõi, xây dựng lại các kỹ năng thiết yếu và áp dụng nhật ký bộ nhớ thủ công, nhưng nó cũng mở ra cánh cửa cho sự hỗ trợ AI rẻ hơn và không phụ thuộc vào mô hình. Nếu bạn đã sẵn sàng đánh đổi sự tiện lợi để lấy quyền kiểm soát, hãy làm theo danh sách kiểm tra ở trên và coi mọi thành phần được nhập vào như một sự khởi đầu mới.