TriaDev: Trình biên tập luồng công việc dựa trên tác nhân AI để tự động hóa lập kế hoạch và phát triển dự án

1. Tổng quan dự án: TriaDev, trình biên tập luồng công việc tác nhân AI nhẹ nhàng

Nếu bạn đã từng cảm thấy bất lực khi sử dụng các tác nhân AI (như Claude) để xử lý các dự án phức tạp hơn - ví dụ, yêu cầu nó viết một kế hoạch, nó thực hiện được, nhưng các giai đoạn phát triển, kiểm thử, tạo tài liệu sau đó lại rải rác, khó theo dõi trạng thái - thì TriaDev có thể chính là "chất kết dính" bạn đang tìm kiếm. Nói một cách đơn giản, TriaDev không phải là một "siêu AI" tự mình hoàn thành mọi thứ, mà là một người điều phối luồng công việc. Triết lý cốt lõi của nó là "để kỹ năng chuyên môn làm việc chuyên môn", trong khi bản thân tập trung vào việc liên kết các kỹ năng này thành một luồng công việc ổn định, có thể dự đoán được - "tam giác vàng".

"Tam giác vàng" này đề cập đến một quy trình dự án đa bước có cấu trúc. Hãy tưởng tượng bạn đang xây một ngôi nhà: đầu tiên cần kiến trúc sư vẽ bản thiết kế (lập kế hoạch), sau đó quản lý dự án lên lịch trình và phối hợp nguồn lực (điều phối), cuối cùng các đội thi công mới vào làm (thực hiện). TriaDev đảm nhiệm công việc của người quản lý dự án. Bản thân nó rất nhẹ nhàng, chủ yếu dựa vào một vài "kỹ năng" (Skill) đã hoàn thiện để hoạt động: planning-with-files phụ trách lập kế hoạch và tạo tài liệu, task-workflow phụ trách điều phối và sắp xếp nhiệm vụ, value-first-gate phụ trách đánh giá giá trị, và tdd-sdd-development phụ trách phát triển theo hướng dẫn kiểm thử. Giá trị cốt lõi của TriaDev nằm ở việc nó định nghĩa một bộ quy tắc rõ ràng và một "hợp đồng bàn giao" (triadev-handoff.json) được chia sẻ, đảm bảo các kỹ năng này có thể hợp tác liền mạch, không làm mất trạng thái và dự án không đi chệch hướng.

Nó chủ yếu giải quyết hai loại vấn đề: đường cốt lõi áp dụng cho các dự án không liên quan đến lập trình, như nghiên cứu thị trường, phân tích đối thủ cạnh tranh, soạn thảo tài liệu, chỉ sử dụng khả năng lập kế hoạch và điều phối; trong khi đường mở rộng hướng tới phát triển phần mềm, trên cơ sở đường cốt lõi thêm các khâu đánh giá giá trị và phát triển TDD/SDD. Dù bạn muốn nghiên cứu có hệ thống một chủ đề, hay xây dựng từ đầu một mô-đun mã sản xuất đầy đủ kiểm thử, TriaDev đều có thể cung cấp một khôn khổ tự động hóa rõ ràng, có thể tái tạo.

2. Triết lý thiết kế cốt lõi và phân tích luồng công việc "tam giác vàng"

Thiết kế của TriaDev rất đáng để học hỏi, nó không cố gắng tạo ra một bánh xe đa năng, mà áp dụng cách tiếp cận "biên tập ưu tiên hơn tích hợp". Hãy cùng phân tích sâu luồng công việc "tam giác vàng" của nó vận hành như thế nào, và tại sao thiết kế này lại hiệu quả và vững chắc.

2.1 Hai đường luồng cốt lõi

TriaDev chia tách ý định dự án thành hai đường luồng rõ ràng, và việc phân loại này chính là một quyết định thiết kế quan trọng.

Đường cốt lõi: Lập kế hoạch -> Điều phối. Đường luồng này áp dụng cho tất cả các nhiệm vụ phân tích hoặc sáng tạo không liên quan đến mã. Ví dụ, "nghiên cứu ưu nhược điểm của ba kiến trúc vi dịch vụ và xuất báo cáo so sánh", hoặc "soạn thảo một hướng dẫn người dùng cho sản phẩm mới của chúng tôi". Trên đường luồng này, kỹ năng planning-with-files sẽ tạo ra kế hoạch nhiệm vụ chi tiết (task_plan.md), phát hiện nghiên cứu (findings.md) và ghi tiến độ (progress.md). Sau đó, kỹ năng task-workflow sẽ phân tích kế hoạch này, chia nó thành các lô nhiệm vụ có quan hệ phụ thuộc (DAG, đồ thị có hướng không chu trình), và quyết định thứ tự thực hiện tối ưu. Quá trình này không liên quan đến viết mã, nhưng đảm bảo công việc có cấu trúc và có thể theo dõi.

Đường mở rộng: Lập kế hoạch -> Điều phối -> Đánh giá giá trị -> Thực hiện. Đây là đường ống hoàn chỉnh hướng tới phát triển phần mềm. Sau khi hoàn thành lập kế hoạch và điều phối, công việc sẽ không ngay lập tức vào giai đoạn mã hóa, mà phải trải qua qua khâu đánh giá bởi kỹ năng value-first-gate. Đây là một cổng kiểm tra chất lượng quan trọng. Kỹ năng này sẽ xem xét các nhiệm vụ sắp được thực hiện, đánh giá giá trị kinh doanh, độ phức tạp thực hiện và mức độ ưu tiên, đưa ra phán quyết "đồng ý", "từ chối" hoặc "cần sửa đổi". Chỉ nhận được phán quyết "GO" và không phải là sự đồng ý qua loa, nhiệm vụ mới được chuyển đến kỹ năng tdd-sdd-development để phát triển thực tế theo hướng dẫn kiểm thử hoặc hướng dẫn mẫu. Thiết kế này buộc phải suy nghĩ trước khi mã hóa, tránh lãng phí tài nguyên phát triển.

Lưu ý: Cổng kiểm tra đánh giá giá trị (value-first-gate) là điểm khác biệt giữa đường mở rộng và các kịch bản tự động hóa đơn giản. Nó giới thiệu khâu "phán đoán", mô phỏng vai trò của quản lý dự án hoặc người chịu trách kỹ thuật, đảm bảo AI không chỉ mù quáng thực hiện danh sách nhiệm vụ, mà đang có ý thức tạo ra giá trị.

2.2 Cơ chế quản lý trạng thái cốt lõi: "Hợp đồng bàn giao"

Sự hợp tác giữa nhiều kỹ năng, thách thức lớn nhất là đồng bộ trạng thái. Làm thế nào để kỹ năng B hiểu và sử dụng đầu ra do kỹ năng A tạo ra? Giải pháp của TriaDev là giới thiệu một tệp trạng thái có cấu trúc, tập trung - triadev-handoff.json. Bạn có thể tưởng tượng nó như "bảng nhiệm vụ" hoặc "danh sách bàn giao" được chia sẻ bởi cả nhóm dự án.

Tệp JSON này được chia thành các khu vực riêng biệt, mỗi kỹ năng chỉ được phép đọc và ghi vào khu vực thuộc về mình. Ví dụ, planning-with-files chịu trách nhiệm duy trì khối planning, nơi chứa tổng quan dự án, mục tiêu, v.v.; task-workflow chịu trách nhiệm khối workflow, chứa nhiệm vụ DAG và thông tin lô hiện tại; value-first-gate chịu trách nhiệm khối gate, chứa kết quả đánh giá; và tdd-sdd-development chịu trách nhiệm khối development, chứa trạng thái thực hiện.

Lợi ích của thiết kế này rất rõ ràng:

  1. Gi耦合 và tự trị: Mỗi kỹ năng không cần quan tâm đến việc triển khai nội bộ của các kỹ năng khác, chỉ cần đọc và ghi dữ liệu theo định dạng hợp đồng được thỏa thuận. Kỹ năng có thể được nâng cấp hoặc thay thế độc lập, miễn là giao diện hợp đồng không thay đổi, toàn bộ luồng công việc sẽ không bị ảnh hưởng.
  2. Tính bền vững và khả năng phục hồi trạng thái: Tệp JSON này chính là bản snapshot hoàn chỉnh của dự án. Nếu hội thoại bị gián đoạn, Claude session được đặt lại, hoặc bạn muốn tiếp tục dự án vào ngày hôm sau, TriaDev có thể đọc tệp này, tái tạo chính xác trạng thái dự án, tiếp tục từ nơi bị gián đoạn thay vì bắt đầu lại từ đầu. Đây chính là khả năng "khôi phục phiên làm việc".
  3. Có thể xác thực được bởi máy: TriaDev v3.1 giới thiệu JSON Schema (`triadev-handoff.schema.json), điều này có nghĩa là cấu trúc hợp đồng có thể được xác định chương trình. Sau mỗi lần ghi, có thể dùng Schema kiểm tra định dạng dữ liệu có chính xác không, tránh hiệu quả hỏng hóc hợp đồng do lỗi tay hoặc lỗi kỹ năng, nâng cao độ vững chắc của toàn bộ hệ thống.

2.3 Kiến trúc nhẹ nhàng hoàn toàn do gợi ý (prompt) điều khiển

Từ phiên bản v3.0.0, TriaDev đã thực hiện một thay đổi kiến trúc táo bạo: loại bỏ toàn bộ mã thời gian chạy Python. Các phiên bản ban đầu có thể chứa một tập lệnh orchestrator.py làm bộ điều khiển trung tâm. Phiên bản mới hoàn toàn dựa vào gợi ý (prompt) của Claude Skill (SKILL.md) để điều khiển toàn bộ luồng công việc.

Việc này có ý nghĩa sâu sắc gì?

  1. Tối ưu nhẹ nhàng và chi phí triển khai bằng không: Là một Claude Skill, việc cài đặt nó chỉ là một câu lệnh (claude skill add Charpup/triadev). Người dùng không cần quan tâm đến môi trường Python, xung đột gói phụ thuộc, v.v. Nó tận dụng trực tiếp khả năng suy luận và quản lý ngữ cảnh của chính Claude để thực hiện logic điều phối.
  2. Tối đa hóa tính linh hoạt: Tất cả logic điều phối đều được viết trong gợi ý, điều này có nghĩa là điều chỉnh luồng công việc, sửa lỗi logic, về cơ bản là sửa đổi mô tả văn bản. Việc lặp lại và tùy chỉnh trở nên rất nhanh chóng, không cần biên dịch và triển khai.
  3. Rõ ràng ranh giới năng lực: Nó xác định rõ mình là "người điều phối" chứ không phải "người thực thi". Logic điều phối luồng công việc, phán đoán trạng thái, và lệnh gọi kỹ năng của nó đều được truyền cho Claude thông qua mô tả ngôn ngữ tự nhiên và hướng dẫn có cấu trúc, để Claude hiểu và thực hiện bước tiếp theo nên gọi kỹ năng nào. Điều này ngược lại lại làm cho vai trò của nó trở nên thuần khiết và vững chắc hơn.

Tất nhiên, thiết kế này cũng đặt ra yêu cầu rất cao đối với kỹ thuật gợi ý. SKILL.md phải đủ rõ ràng, vững chắc để xử lý các tình huống biên giới và trạng thái lỗi. Từ việc phiên bản v3.1 thêm vào nhiều trường hợp đánh giá (evals.json) và tài liệu tham chiếu chi tiết, có thể thấy tác giả đang không ngừng gia cố cho cỗ máy gợi ý thuần túy này.

3. Bắt đầu từ đầu: Hướng dẫn cài đặt, cấu hình và khởi động dự án

Sau khi hiểu được triết lý thiết kế, chúng ta hãy bắt đầu thực hành, xem cách sử dụng TriaDev để quản lý một dự án. Tôi sẽ lấy một ví dụ cụ thể xuyên suốt: "phát triển một công cụ đếm từ trong tài liệu Markdown, yêu cầu có thể loại bỏ các khối mã và YAML front matter, và xuất báo cáo ở các định dạng khác nhau." Đây là một dự án đường mở rộng (lập điển hình).

3.1 Chuẩn bị môi trường và cài đặt kỹ năng

TriaDev chạy trên Claude (cụ thể là môi trường Claude hỗ trợ Skills, như Claude Desktop). Đầu tiên, cần cài đặt TriaDev và các kỹ năng phụ thuộc của nó.

Cài đặt kỹ năng cốt lõi của TriaDev: Cách được khuyến nghị nhất là sử dụng công cụ dòng lệnh Claude Code (nếu bạn có quyền truy cập):

claude skill add Charpup/triadev

Câu lệnh này sẽ tự động xử lý việc kéo và đăng ký kỹ năng.

Cài đặt thủ công (phương án dự phòng): Nếu không thể sử dụng câu lệnh trên, bạn có thể sao chép kho lưu trữ thủ công vào thư mục kỹ năng của Claude:

git clone https://github.com/Charpup/triadev.git ~/.claude/skills/triadev

Lưu ý rằng đường dẫn thư mục kỹ năng (~/.claude/skills/) có thể khác tùy vào cấu hình Claude của bạn.

Cài đặt kỹ năng phụ thuộc: TriaDev tự nó không làm công việc, công việc được thực hiện bởi các kỹ năng phụ thuộc. Bạn phải đảm bảo các kỹ năng sau đã được cài đặt:

  • planning-with-files (>=2.10): Phụ trách lập kế hoạch dự án và tạo tài liệu.
  • task-workflow (>=3.0): Phụ trách phân tích và điều phối nhiệm vụ.
  • (Bắt buộc cho đường mở rộng) value-first-gate (>=2.0): Phụ trách đánh giá giá trị.
  • (Bắt buộc cho đường mở rộng) tdd-sdd-development (>=3.0): Phụ trách phát triển theo hướng dẫn kiểm thử.

Cách cài đặt các kỹ năng này tương tự, thường có thể tìm thấy hướng dẫn cài đặt trên kho GitHub của chúng, thường cũng thông qua câu lệnh claude skill add. Hãy chắc chắn kiểm tra phiên bản, các phiên bản không tương thích có thể dẫn đến lỗi luồng công việc.

3.2 Khởi tạo dự án và chạy lần đầu

Sau khi cài đặt xong, bạn không cần phải "khởi động" TriaDev riêng biệt. Việc khởi động của nó được kích hoạt bởi một yêu cầu dự án cụ thể.

  1. Mở một phiên Claude mới. Tốt nhất nên thực hiện trong một thư mục dự án sạch, hoặc cho Claude có quyền tạo và ghi tệp.
  2. Đưa ra yêu cầu dự án của bạn cho Claude. Đây là bước quan trọng nhất, chỉ thị cần rõ ràng. Ví dụ:

"Sử dụng kỹ năng TriaDev, giúp tôi phát triển một công cụ đếm từ trong Markdown. Các chức năng cốt lõi là: đếm số từ văn bản thuần túy, tự động bỏ qua các khối mã (...) và YAML front matter (nội dung giữa ---), hỗ trợ xuất báo cáo ở định dạng văn bản thuần túy và JSON. Vui lòng thực hiện theo đường mở rộng (quy trình phát triển đầy đủ)."

  1. Kích hoạt kỹ năng. Trong hội thoại, Claude nên có thể nhận ra bạn muốn sử dụng TriaDev. Tùy vào giao diện Claude của bạn, bạn có thể cần chọn hoặc kích hoạt thủ công kỹ năng triadev. Một khi được kích hoạt, logic điều phối của TriaDev (tức là gợi ý trong SKILL.md) sẽ bắt đầu chạy.

Trong lần chạy đầu tiên, bạn sẽ quan sát các bước quan trọng sau:

  • Khai báo đường luồng: TriaDev sẽ phân tích yêu cầu của bạn và công bố rõ ràng "Đây là một dự án đường mở rộng", vì liên quan đến lập trình. Điều này giúp bạn ngay lập tức hiểu rõ quy trình tiếp theo.
  • Khởi tạo hợp đồng: TriaDev sẽ tạo tệp triadev-handoff.json trong khu vực làm việc của bạn. Tệp này lúc đầu được sao chép từ mẫu (templates/triadev-handoff.json) với cấu trúc trống.
  • Bắt đầu giai đoạn lập kế hoạch: TriaDev sẽ gọi kỹ năng planning-with-files. Bạn sẽ thấy kỹ năng này bắt đầu làm việc, trò chuyện với bạn để làm rõ yêu cầu, xác định phạm vi, và cuối cùng tạo ra task_plan.md (phân nhiệm vụ chi tiết), findings.md (bất kỳ phát hiện nghiên cứu nào, chẳng hạn như nghiên cứu về các thư viện hiện có) và progress.md (các mục tiến độ ban đầu).

Bài thực hành: Trong hội thoại lập kế hoạch đầu tiên, hãy trả lời càng chi tiết càng tốt các câu hỏi do planning-with-files đặt ra. Mô tả yêu cầu của bạn càng chính xác, kế hoạch nhiệm vụ nó tạo ra càng đáng tin cậy, và quy trình tự động hóa sau đó sẽ trôi chảy hơn. Đ�ng ngại "nói nhiều", hãy giải thích rõ các điều kiện biên, định dạng đầu ra đầu vào, và các yêu cầu phi chức năng (như hiệu suất).

3.3 Hiểu cấu trúc dự án được tạo ra

Sau khi khởi tạo và chạy xong giai đoạn lập kế hoạch, thư mục dự án của bạn sẽ tạo ra một loạt tệp. Hiểu vai trò của chúng rất quan trọng:

  • task_plan.md: Bản thiết kế tổng thể của dự án. Nó sẽ được chia thành nhiều "giai đoạn" và "nhiệm vụ". Ví dụ, có thể chứa "Giai đoạn A: Thiết lập môi trường và khung cơ bản", "Giai đoạn B: Phát triển logic phân tích Markdown", "Giai đoạn C: Phát triển module tạo báo cáo", "Giai đoạn D: Tích hợp và kiểm thử", v.v. Mỗi nhiệm vụ đều có mô tả, tiêu chí chấp nhận và có thể có quan hệ phụ thuộc.
  • findings.md: Ghi chú nghiên cứu. Ghi lại bất kỳ thông tin hữu ích nào mà planning-with-files phát hiện trong quá trình lập kế hoạch, ví dụ như "thư viện markdown của Python có thể phân tích MD, nhưng cần xử lý các khối mã", "thư viện frontmatter có thể trích xuất YAML một cách thuận tiện", v.v. Điều này có giá trị tham khảo cho việc phát triển sau này.
  • progress.md: Nhật ký tiến độ. Ghi lại các hoạt động chính của mỗi kỹ năng theo dòng thời gian, ví dụ như "Giai đoạn lập kế hoạch hoàn thành", "Lịch trình nhiệm vụ đã được tạo", v.v. Đây là bản ghi văn bản về lịch sử dự án.
  • triadev-handoff.json: Tệp trạng thái cốt lõi. Lúc này, khối planning của nó đã được điền, và trường current_phase có thể là planning hoặc scheduling. Không bao giờ chỉnh sửa thủ công tệp này, trừ khi bạn thực sự hiểu rõ các quy tắc hợp đồng. Nó được thiết kế để máy đọc.

Tại thời điểm này, bạn có thể mở task_plan.md để xem, nếu thấy việc phân chia nhiệm vụ không hợp lý, có thể điều chỉnh ngay với AI. Vì cơ chế hợp đồng, chi phí để điều chỉnh ở giai đoạn lập kế hoạch là thấp nhất.

4. Luồng công việc sâu hơn: Điều phối, đánh giá và chu kỳ phát triển

Sau khi hoàn thành lập kế hoạch, TriaDev sẽ tự động tiến đến giai đoạn tiếp theo. Chúng ta tiếp tục với ví dụ công cụ đếm từ, xem quy trình sau này diễn ra như thế nào.

4.1 Điều phối nhiệm vụ và phân tích phụ thuộc

TriaDev sẽ gọi kỹ năng task-workflow. Kỹ năng này đọc task_plan.md, sử dụng thuật toán của nó để chuyển đổi danh sách nhiệm vụ thành một đồ thị có hướng không chu trình (DAG). Đây là bước quan trọng, nó quyết định thứ tự thực hiện nhiệm vụ.

Ví dụ, nó có thể nhận diện:

  • Nhiệm vụ "Thiết cấu trúc dự án (src/, tests/)" và "Khởi tạo pyproject.toml" có thể thực hiện song song (lô 1).
  • Nhiệm vụ "Viết hàm phân tích Markdown" phải sau "Thiết kế cấu trúc dự án", nhưng có thể song song với "Viết hàm đếm từ cốt lõi" (lô 2).
  • Nhiệm vụ "Viết hàm xuất báo cáo JSON" phụ thuộc vào "Hàm đếm từ cốt lõi" (lô 3).
  • Nhiệm vụ "Viểm thử tích hợp" phụ thuộc vào tất cả các module trên (lô 4).

task-workflow sẽ ghi thông tin lô này vào khối workflow của triadev-handoff.json. Logic điều phối của TriaDev sẽ quyết định bước tiếp theo nên làm gì: đối với đường mở rộng, khâu tiếp theo là đánh giá giá trị.

4.2 Cổng kiểm tra đánh giá giá trị: Tránh phát triển vô nghĩa

Đây là khâu độc đáo của đường mở rộng và cũng cực kỳ quan trọng. TriaDev sẽ gọi kỹ năng value-first-gate, và gửi lô nhiệm vụ đầu tiên (ví dụ, "lô 1: Khởi tạo dự án và khung cơ bản") để nó đánh giá.

Quá trình đánh giá mô phỏng một "cuộc họp开工前" hợp lý:

  • Đánh giá giá trị: Lô nhiệm vụ này đóng góp nhiều cho mục tiêu cuối cùng của dự án? Là công việc nền tảng cần thiết, hay chỉ là trang trí không cần thiết?
  • Kiểm tra tính khả thi: Dựa trên ngữ cảnh dự án hiện tại (kế hoạch, tệp đã có), việc hoàn thành các nhiệm vụ này có tồn tại rủi ro kỹ thuật hay vùng mờ không?
  • Xác nhận mức độ ưu tiên: Trên dòng thời gian dự án, hiện tại làm lô nhiệm vụ này có phải là lựa chọn tối ưu không?

value-first-gate sẽ tạo ra kết quả đánh giá (thường trong một tệp tương tự value-review.json), phán quyết có thể là GO, NO-GO hoặc REVISE. Đồng thời, nó sẽ kiểm tra xem mình có ở chế độ "dấu con dấu" - tức là phê duyệt qua loa mà không suy nghĩ kỹ. TriaDev sẽ đọc phán quyết này. Chỉ nhận được phán quyết GO thực sự, luồng công việc mới tiếp tục.

Lưu ý: Nếu nhận được phán quyết REVISE, hãy thực sự coi trọng. Điều này thường có nghĩa là mô tả nhiệm vụ không đủ rõ ràng, hoặc giải pháp thực hiện tồn tại rủi ro. Bạn cần phản hồi đánh giá, hợp tác với AI để sửa đổi mô tả nhiệm vụ trong task_plan.md, sau đó kích hoạt lại đánh giá. Quá trình này tuy có vẻ thêm một bước, nhưng có thể tránh hoàn toàn công việc sửa chữa sau này.

4.3 Chu kỳ phát triển TDD/SDD: Thực hiện tự động hóa chất lượng cao

Nhận được "GO" sau đó, TriaDev vào giai đoạn thực hiện, gọi kỹ năng tdd-sdd-development. Kỹ năng này là cốt lõi của tự động hóa mã hóa, nó tuân thủ nghiêm ngặt quy trình phát triển theo hướng dẫn kiểm thử hoặc hướng dẫn mẫu.

Đối với công cụ đếm từ của chúng ta, việc thực hiện lô đầu tiên (khởi tạo dự án) có thể như sau:

  1. Đọc quy định: tdd-sdd-development sẽ đọc mô tả chi tiết và tiêu chí chấp nhận của nhiệm vụ trong task_plan.md.
  2. Tạo hoặc cập nhật SPEC: Nó có thể tạo hoặc cập nhật tệp SPEC.yaml, định nghĩa cấu trúc hơn về đầu vào, đầu ra và hành vi của module.
  3. Chu kỳ TDD:
  • Đỏ: Dựa vào SPEC, viết một bài kiểm thử thất bại trước. Ví dụ, test_should_ignore_code_blocks.
  • Xanh: Viết lượng mã tối thiểu để bài kiểm thử này qua.
  • Tái cấu trúc: Trong khi vẫn giữ bài kiểm thử qua, tối ưu cấu trúc mã.
  1. Tạo mã và tài liệu thực hiện: Sau khi kết thúc chu kỳ TDD, kỹ năng sẽ tạo ra mã sản phẩm cuối cùng, và có thể kèm theo tài liệu API.

Sau khi hoàn thành một lô, tdd-sdd-development sẽ cập nhật khối development trong triadev-handoff.json, đánh dấu lô đó là hoàn thành. Sau đó, logic điều phối của TriaDev sẽ:

  1. Kiểm tra DAG của task-workflow, xem có lô nhiệm vụ mới nào đã đáp ứng điều kiện phụ thuộc và có thể vào trạng thái "sẵn sàng" không.
  2. Nếu có, gửi lô nhiệm vụ này vào value-first-gate để đánh giá, bắt đầu chu kỳ "đánh giá -> phát triển" tiếp theo.
  3. Nếu không, và tất cả nhiệm vụ đã hoàn thành, dự án sẽ vào giai đoạn kết thúc.

Chu kỳ này sẽ tiếp diễn cho đến khi tất cả các lô nhiệm vụ được định nghĩa trong task-workflow hoàn thành. Toàn bộ quá trình tự động hóa cao độ, nhưng vẫn giữ lại "giám sát" cần thiết của trí tuệ nhân tạo ở khâu đánh giá giá trị, đảm bảo phát triển luôn hướng tới tạo ra giá trị.

5. Tính năng nâng cao và hướng dẫn tránh lỗi thực chiến

Sau khi thành thạo quy trình cơ bản, việc nắm vững một số tính năng nâng cao và cách giải quyết các vấn đề thường gặp của TriaDev sẽ giúp bạn sử dụng nó thành thạo hơn.

5.1 Khôi phục phiên làm việc và hỗ trợ dự án "brownfield"

Đây là một tính năng rất mạnh mẽ của TriaDev. Dự án "brownfield" là những dự án đã tồn tại một phần tệp, không bắt đầu từ đầu. TriaDev có thể xử lý tình huống này một cách trơn tru.

Cách khôi phục một dự án bị gián đoạn? Giả sử hôm nay bạn dùng TriaDev bắt đầu một dự án, ngày mai mở lại phiên Claude mới. Bạn không cần phải mô tả yêu cầu từ đầu. Chỉ cần:

  1. Đảm bảo thư mục làm việc của bạn chứa các tệp dự án trước đó (đặc biệt là triadev-handoff.json).
  2. Trong phiên Claude mới, tải lên hoặc để Claude thấy các tệp này.
  3. Nói với Claude: "Chúng ta tiếp tục dự án TriaDev trước đây." hoặc trực tiếp hỏi: "Dựa trên trạng thái triadev-handoff.json hiện tại, bước tiếp theo của dự án nên là gì?"

Khi kỹ năng TriaDev được kích hoạt, nó sẽ đầu tiên kiểm tra xem có triadev-handoff.json hợp lệ không. Nếu có, nó sẽ đọc các trường như current_phase và các trạng thái khác, khôi phục chính xác đến khâu bị gián đoạn. Ví dụ, nếu hôm qua bị gián đoạn ở khâu "đánh giá giá trị", hôm nay nó sẽ trực tiếp gọi value-first-gate để tiếp tục đánh giá, thay vì lập kế hoạch lại.

Delta Specs (quy định gia tăng): Trong dự án "brownfield", bạn có thể không bắt đầu từ đầu, mà cần cải tiến mã hiện có hoặc thêm chức năng mới. TriaDev (thông qua các kỹ năng phụ thuộc) hỗ trợ khái niệm "Delta Specs". Điều này có nghĩa là khi lập kế hoạch, bạn có thể chỉ rõ đâu là tài sản hiện có, đâu là nhu cầu mới. planning-with-files sẽ tạo ra một kế hoạch nhiệm vụ gia tăng, xem xét cơ sở mã hiện có, thay vì một kế hoạch khởi đầu lại từ đầu.

5.2 Quản lý hợp đồng và xác thực trạng thái

Khi dự án tiến triển, triadev-handoff.json sẽ trở thành tệp quan trọng nhất. Hiểu kiến trúc quản lý bốn tầng của nó có thể giúp bạn tránh nhiều rắc rối.

  1. Hợp đồng JSON Schema (contracts/triadev-handoff.schema.json): Đây là "điều luật". Nó định nghĩa cấu trúc hợp đồng, loại trường, các trường bắt buộc, v.v. bằng cách có thể đọc được của máy. TriaDev sẽ xác hợp đồng sau khi ghi bằng Schema này. Nếu bạn cần tùy chỉnh hoặc mở rộng hợp đồng, sửa đổi đây là gốc rễ, nhưng phải cực kỳ cẩn thận.
  2. Tệp mẫu (templates/triadev-handoff.json): Đây là "biểu mẫu trống". Mỗi khi khởi tạo dự án mới, TriaDev sẽ sao chép nó làm điểm khởi đầu. Nếu bạn muốn tất cả dự án mới mặc định chứa một số trường nhất định, có thể sửa tệp mẫu này.
  3. Tham chiếu có thể đọc được bởi con người (references/handoff-contract.md): Đây là "giải thích điều luật bằng ngôn ngữ đời thường". Nó mô tả bằng văn bản ý nghĩa của mỗi trường, quyền đọc/ghi của mỗi kỹ năng. Khi bạn bối rối về một trường hợp đồng, nên tham khảo tệp này.
  4. Quy chuyển giai đoạn (references/phase-transitions.md): Đây là "sổ tay quy trình luồng công việc". Nó định nghĩa trường current_phase có thể chuyển từ trạng thái nào sang trạng thái nào (ví dụ, từ scheduling có thể chuyển sang gating, nhưng không thể nhảy thẳng về planning), và "giá trị tiêu chuẩn" của một số trường ở mỗi giai đoạn nên là gì (trộn lẫn done và completed). Khi can thiệp thủ công hoặc gỡ lỗi, trước khi thay đổi current_phase, phải tham khảo tệp này.

5.3 Gỡ lỗi các vấn đề thường gặp và kỹ thuật khắc phục

Dù thiết kế hoàn hảo đến đâu, trong thao tác thực tế vẫn có thể gặp vấn đề. Dưới đây là một số tình huống phổ biến và cách giải quyết:

Vấn đề 1: Gọi kỹ năng thất bại hoặc không tìm thấy.

  • Triệu chứng: TriaDev công bố vào một giai đoạn nào đó (như "bắt đầu lập kế hoạch"), nhưng sau đó không có phản hồi từ kỹ năng tương ứng (như planning-with-files).
  • Khắc phục:
  1. Kiểm tra cài đặt kỹ năng: Xác nhận tất cả kỹ năng phụ thuộc (planning-with-files, task-workflow, v.v.) đã được cài đặt đúng và phiên bản phù hợp. Bạn có thể thử gọi trực tiếp kỹ năng trong Claude để xem nó có phản hồi không.
  2. Kiểm tra ngữ cảnh Claude: Một số môi trường Claude có giới hạn độ dài hoặc quyền đối với việc gọi kỹ năng. Đảm bảo phiên làm việc hiện tại không vượt quá giới hạn.
  3. Xem tệp tiến độ: Kiểm tra progress.md, xem mục cuối cùng là gì, có thể bị kẹt ở một bước nào đó.

Vấn đề 2: triadev-handoff.json trạng thái lộn xộn hoặc hỏng.

  • Triệu chứng: Hành vi luồng công việc bất thường, hoặc TriaDev báo lỗi trạng thái không nhất quán.
  • Khắc phục và sửa:
  1. Sao lưu: Đầu tiên, sao lưu tệp handoff.json hiện tại.
  2. Xem xét thủ công: Mở tệp, so sánh với references/handoff-contract.md, kiểm tra dữ liệu ở các khối thuộc về từng kỹ năng có ở vị trí chính xác không, giá trị current_phase có hợp lý không.
  3. Sử dụng Schema xác thực: Có thể dùng công cụ xác thực JSON Schema (hoặc thư viện jsonschema trong Python) để xác thực tệp có tuân thủ schema.json không. Điều này có thể nhanh chóng xác định lỗi định dạng.
  4. Tham khảo quy chuyển giai đoạn: Kiểm tra thay đổi lịch sử của current_phase có tuân thủ quy tắc được định nghĩa trong phase-transitions.md không.
  5. Sửa cẩn thận: Nếu phát hiện lỗi rõ ràng (ví dụ, giá trị trường rõ ràng không đúng), có thể cẩn thận sửa thủ công. Nhưng sau khi sửa, tốt nhất nên kích hoạt hoạt động "đọc" của kỹ năng thuộc về trường đó, để nó đồng bộ lại trạng thái. Cách tốt hơn là nói với TriaDev "nhận thấy trạng thái không nhất quán, vui lòng重建 handoff.json dựa trên tệp dự án hiện tại", nó có thể thử tự sửa chữa.

Vấn đề 3: Cổng kiểm tra đánh giá giá trị luôn từ chối hoặc yêu cầu sửa.

  • Triệu chứng: Dự án kẹt ở giai đoạn gating, không thể tiến đến phát triển.
  • Giải quyết: Đây không phải là vấn đề, mà là tính năng đang hoạt động. Hãy đọc kỹ phản hồi do value-first-gate đưa ra. Thường thì nguyên nhân có thể là:
  • Mô tả nhiệm vụ mơ hồ: Tiêu chí chấp nhận không rõ ràng, không thể xác định khi nào hoàn thành. Bạn cần quay lại task_plan.md, hợp tác với kỹ năng chịu trách nhiệm nhiệm vụ (ban đầu là planning-with-files) để làm rõ mô tả.
  • Rủi ro kỹ thuật chưa được nhận diện: Đánh giá cho rằng giải pháp thực hiện có rủi ro. Điều này có nghĩa là bạn cần bổ sung nghiên cứu kỹ thuật (cập nhật findings.md), hoặc điều chỉnh giải pháp kỹ thuật.
  • Giá trị không khớp: Đánh giá cho rằng lô nhiệm vụ này đóng góp không cao cho mục tiêu dự án hiện tại. Lúc này bạn cần xem lại mức độ ưu tiên dự án, có lẽ nên điều chỉnh thứ tự hoặc phạm vi nhiệm vụ.

Vấn đề 4: Chu kỳ phát triển rơi vào bế tắc hoặc tạo ra mã chất lượng thấp.

  • Triệu chứng: Mã do kỹ năng tdd-sdd-development tạo ra có lỗi logic, hoặc bài kiểm thử không qua.
  • Giải quyết:
  1. Can thiệp chu kỳ TDD: Bạn có thể ngắt quá trình trong lúc phát triển, xem xét mã và bài kiểm thử nó tạo ra, chỉ ra lỗi logic. AI sẽ điều chỉnh dựa trên phản hồi của bạn. Hãy nhớ rằng bạn là người chịu trách nhiệm cuối cùng của dự án, AI là trợ lý mạnh mẽ, nhưng không hoàn toàn tự chủ.
  2. Xem xét tệp SPEC: Mã chất lượng thấp thường bắt nguồn từ SPEC mơ hồ. Kiểm tra tệp SPEC.yaml, đảm bảo nó mô tả chính xác, không mơ hồ về đầu vào, đầu ra, điều kiện biên và hành vi ngoại lệ.
  3. Cung cấp mẫu cụ thể hơn: Trong mô tả nhiệm vụ hoặc SPEC, hãy cung cấp các mẫu đầu vào/đầu ra chi tiết hơn. Đối với công cụ đếm từ, thay vì nói "có thể xử lý khối mã", hãy nói "với đầu vào 'văn bản mã thêm văn bản', kết quả đếm chỉ nên chứa 'văn bản' và 'thêm văn bản'".

Vấn đề 5: Dự án có nhiều tệp, làm thế nào để hiểu mối quan hệ?

  • Mẹo: Hình thành thói quen xem xét một số tệp cốt lõi cố định:
  • Xem tiến độ: progress.md là dòng thời gian.
  • Xem toàn cảnh: task_plan.md là bản thiết kế tổng thể.
  • Xem trạng thái: triadev-handoff.json là snapshot hiện tại.
  • Xem kết quả: Thư mục src/ và tests/ là kết quả mã. Các tệp khác (findings.md, SPEC.yaml, v.v.) chỉ cần tham khảo khi cần tìm hiểu chi tiết. Đừng cố gắng hiểu tất cả tệp cùng một lúc.

Cuối cùng, hãy kiên nhẫn. Cấu trúc hóa và tự động hóa mà TriaDev mang lại có thể ban đầu khiến bạn cảm thấy quy trình "rườm rà", nhưng một khi đã thích ứng, nó mang lại độ rõ ràng dự án đáng kinh ngạc, khả năng truy vết trạng thái và sự cải thiện chất lượng kết quả cuối cùng. Nó đặc biệt phù hợp với các dự án có bước rõ ràng, có thể phân chia có độ phức tạp trung bình. Đối với nguyên mẫu nhanh hoặc các nhiệm vụ mang tính khám phá cao, hướng thay đổi liên tục, mô thức hội thoại tự do truyền thống có thể linh hoạt hơn.

Thẻ: AI workflow-orchestration project-automation claude-skills TDD

Đăng vào ngày 20 tháng 5 lúc 05:26

Thẻ Phổ Biến

©2026 Thành phố Cuồng loạn