Tác giả htmx: Markdown đang trở thành mã nguồn và nên được đưa vào thư mục /src

Giới thiệu

Để bổ sung thu nhập với tư cách là giáo sư tại Đại học Bang Montana, tôi có làm thêm công việc tư vấn. Tôi thích công việc tư vấn cũng như việc viết mã và hỗ trợ xây dựng các hệ thống, không chỉ vì bản thân công việc đó mà còn vì nó giúp tôi duy trì kỹ năng và cho phép tôi giảng dạy cho sinh viên về những ý tưởng mới nhất trong phát triển phần mềm.

Rõ ràng, sự kiện lớn nhất xảy ra trong lĩnh vực phát triển phần mềm vài năm gần đây chính là lập trình bằng tác nhân (agentic coding): sử dụng các mô hình ngôn ngữ lớn (LLM) để tạo mã thay vì viết mã thủ công. Tôi đã viết một vài bài luận về chủ đề này:

Trong bài luận này, tôi muốn thảo luận về một ý tưởng đang dần trở nên rõ ràng hơn đối với tôi khi làm việc tại các công ty đang ưu tiên lập trình bằng tác nhân:

Markdown hiện nay đã trở thành mã nguồn, chứ không còn là tài liệu hướng dẫn nữa.

Tất nhiên, đây không phải là một ý tưởng mới lạ hay đặc biệt thông minh.

Trong bài viết "Markdown is the new source code", Hartley Brody đã viết:

Có cảm giác như logic ứng dụng của phần mềm đang được định nghĩa và chỉnh sửa dưới dạng Markdown, còn mã thực tế do tác nhân tạo ra dường như chỉ trở thành một chi tiết triển khai cấp thấp.

Như các bài luận trên đã cho thấy, tôi có cái nhìn khá mâu thuẫn về mã do AI tạo ra. Tuy nhiên, công việc tư vấn cho thấy các tổ chức đang đi theo hướng này, thường là với tốc độ chóng mặt.

Điều tôi muốn thực hiện trong phần còn lại của bài luận này là suy ngẫm về những hệ quả khi Markdown ngày càng trở thành nguồn sự thật (source of truth) cho các hệ thống phần mềm.

Mã nguồn bị thiếu

Có một luồng tư duy, được tóm tắt trong trích dẫn trên, cho rằng các LLM giống như trình biên dịch, lấy các đặc tả cấp cao và chuyển chúng thành các triển khai cấp thấp. Theo quan điểm này, chúng ta không cần xem mã mà LLM tạo ra, cũng giống như cách chúng ta không xem mã máy do trình biên dịch tạo ra vậy.

Như tôi đã đề cập trong bài "Code is Cheap(er)", tôi không hoàn toàn đồng ý với phép so sánh này vì một vài lý do, nhưng lý do liên quan đến bài luận này là: quy trình làm việc với trình biên dịch vẫn giữ lại mã nguồn gốc, trong khi quy trình làm việc với LLM thì thường không.

Ngày nay, mã do LLM tạo ra thường được tạo thông qua một chuỗi các câu lệnh (prompt) được đưa vào tác nhân khi lập trình viên xây dựng một tính năng. Trên thực tế, điều này có nghĩa là mã được tạo ra là thứ gần nhất với "nguồn sự thật" cho tính năng đó. Có thể có tài liệu cho tính năng được lưu trữ ở nơi khác (ví dụ: Linear, các luồng Slack, wiki, v.v.) nhưng xét về cơ sở mã (codebase), mã được tạo ra chính là nguồn sự thật.

Ý kiến của tôi là trong các môi trường lập trình bằng tác nhân chuyên nghiệp, chúng ta cần chấp nhận rằng mã do LLM tạo ra từ các phiên nhắc lệnh tạm thời là chưa lý tưởng, và cần bắt đầu chuyển sang việc lưu trữ và kiểm soát các tệp Markdown cùng với mã được tạo ra trong thư mục nguồn.

Markdown với tư cách là mã nguồn

Markdown có nhiều đặc tính tốt khiến nó tương tự như mã nguồn truyền thống:

Và trên thực tế, nó đã đóng vai trò là mã nguồn ở một mức độ nào đó trong các tệp AGENTS.md, các đặc tả, kế hoạch, TASK.md, v.v. Chỉ là chúng ta chưa chuẩn hóa việc lưu trữ nguồn đó mà thôi.

Trong bài "Markdown is the new source code", Brody cho biết anh lưu các tệp Markdown của mình trong.scratch/research/ và.scratch/plan/ khi làm việc. Tôi đã áp dụng quy ước tạo một thư mục /tmp cho các nhu cầu tạm thời tương tự.

Đề xuất của tôi là chúng ta đưa một số tệp này vào một thư mục mới, nằm cùng với mã nguồn hiện có: /src/md

Các tệp Markdown được lưu trong thư mục đề xuất này sẽ ở cấp độ thấp hơn so với các tài liệu thiết kế truyền thống:

Nó gần với một bản đặc tả kỹ thuật hơn (mặc dù không hoàn toàn là vậy) so với một tài liệu thiết kế được quản lý theo cách truyền thống bởi quản lý dự án hoặc nhà thiết kế.

Tính cục bộ (Locality)

Tôi là người ủng hộ tính cục bộ, và tôi nghĩ rằng việc di chuyển Markdown vào /src mang lại những lợi thế lớn về tính cục bộ:

Còn Linear/Wiki/v.v. thì sao?

Các nguồn sự thật khác về hành vi của hệ thống vẫn có thể tồn tại. Những nguồn này sẽ cung cấp tài liệu cấp cao hơn và/hoặc "định hướng quy trình": tài liệu thiết kế cấp cao, các vấn đề cần quy trình giải quyết, v.v.

Nhưng hành vi cốt lõi, hiện tại và tĩnh của hệ thống sẽ ngày càng được ghi lại trực tiếp trong các tệp Markdown nằm trong thư mục nguồn.

Còn các bài kiểm thử (Tests) thì sao?

Tôi đã thấy nhiều người trên mạng nói rằng các bài kiểm thử chính là bản đặc tả mới (hoặc vốn dĩ đã luôn là như vậy). Tôi nghĩ điều đó có phần đúng.

Tuy nhiên, các bài kiểm thử không phải là cơ chế tốt cho sự tương tác giữa con người và tác nhân:

Tôi nghĩ sự phân công lao động sau đây là hợp lý:

Một lần nữa, ý tưởng cốt lõi ở đây là thay vì tạo mã và kiểm thử từ các câu lệnh, lập trình viên sẽ làm việc trên các tệp Markdown trong thư mục /src, từ đó mã và các bài kiểm thử sẽ được suy ra.

Markdown trong /src/md trông như thế nào

Các tệp Markdown trong /src/md nằm giữa bản đặc tả chính thức cho hệ thống và các tài liệu thiết kế cấp cao.

Giống như mã nguồn, có một "Ngân sách phức tạp" (Complexity Budget) liên quan đến các tệp Markdown này. Nó sẽ đòi hỏi sự quản lý cẩn thận để giữ cho các tài liệu này sạch sẽ, được cấu trúc tốt và ở mức độ trừu tượng phù hợp.

Lập trình viên cần được kỳ vọng sẽ tương tác với cả Markdown và mã được tạo ra, vì vậy việc đồng bộ hóa cả hai (khi thích hợp) sẽ trở thành một kỹ năng quan trọng.

Ví dụ, các lập trình viên thường sẽ thực hiện công việc tinh chỉnh, giới hạn trên mã được tạo ra, và những thay đổi đó có thể cần được đưa ngược lại vào các tệp Markdown.

Tôi tin rằng không nên sử dụng tác nhân để tạo quá nhiều nội dung trong /src/md. Thư mục này chủ yếu nên do con người soạn thảo và quản lý.

Bài gốc còn tiếp — xem tiếp tại bài gốc ↗