Trellis: Training wheels cho AI coding agent của bạn

Mồng 1 Tết, mình ngồi undo cái commit mà Claude Code tự ý push lên main lúc 2h sáng.

Nó xoá hết validation layer, rename mấy cái handler từ GetMenuByID thành fetchMenuByID — phá convention Go exported function PascalCase mà cả team đã thống nhất. Bug thì không hẳn, nhưng code nhìn như chó cắn. Review reject, pull rollback, cả đội mất nửa ngày.

Lỗi tại Claude Code? Cũng không hẳn. Nó làm đúng những gì được yêu cầu. Vấn đề là nó không biết project convention — không biết team dùng PascalCase cho exported functions, không biết validation layer phải giữ nguyên, không biết có spec nào cấm đập đi xây lại.

Mấy tháng sau, mình tìm thấy Trellis. Một cái repo trên GitHub gọi mình là “training wheels cho AI coding assistants.” Đọc xong README là mình biết — cái hole mà team mình đang chui vào, có người đã đào exit tunnel từ trước rồi.

Agent thì nhanh, nhưng Harness mới là thứ giữ cho nó khỏi ngã

Có một sự nhầm lẫn phổ biến mà mình thấy khắp nơi: mọi người cứ nghĩ Trellis là một AI coding agent. Không phải.

Trellis là Agent Harness — một workflow layer nằm giữa bạn và coding agent (Claude Code, Codex, Cursor, OpenCode, Copilot, Gemini CLI, v.v.). Nó không viết code. Nó quản lý context, spec, task, journal — tất cả những thứ mà coding agent “quên” mỗi lần khởi động session mới.

You → Trellis (.trellis/) → Claude Code / Codex / Cursor → Code

Cách Trellis giải quyết vấn đề cũng hơi ngược đời: file-based knowledge. Không database. Không vector store. Không cloud service. Mọi thứ nằm trong folder .trellis/ ở ngay repo bạn — markdown, JSON, YAML — git-tracked hết. Ai clone repo là có luôn spec.

Cực kỳ đơn giản. Cực kỳ inspectable.

Setup: 30 giây, không đau đớn

Cài Trellis qua npm:

npm install -g @mindfoldhq/trellis@latest

Init trong project:

cd my-project
trellis init --claude --codex --cursor

Lệnh này tạo ra cấu trúc:

.trellis/
├── workflow.md           # executable workflow contract
├── spec/                 # coding standards, conventions
├── tasks/<slug>/         # PRD, design, implement/check manifests
├── workspace/<dev>/      # per-developer journals
└── .runtime/             # active session pointers

Mất 30 giây. Không cần config gì thêm. --claude --codex --cursor là nói với Trellis: mày support cả 3 platform này, một .trellis/ chạy được hết.

Kiến trúc bên trong: Spec, Task, và cái vòng lặp học

Trellis có 3 concept chính, nếu hiểu được 3 cái này là hiểu được toàn bộ.

1. Spec Library (.trellis/spec/)

Đây là nơi chứa coding standards của project. Mỗi file spec mô tả convention cho một package hoặc layer cụ thể. Không phải viết tay — Trellis có thể auto-draft spec từ codebase hiện tại, bạn chỉ cần tighten lại phần quan trọng.

Ví dụ spec cho backend Go với Gin + gRPC:

# spec/backend/go-conventions.md

## Naming
- Exported functions: PascalCase (`GetMenuByID`, `CreateOrder`)
- Unexported functions: camelCase (`fetchMenuByID`, `saveOrder`)
- Proto files: snake_case (`menu_service.proto`)

## Validation
- Tất cả input từ client PHẢI validate qua `binding:"required"` tag + custom validator
- Không dùng `interface{}` cho request body — define concrete DTO struct

Khi bạn tạo task mới, Trellis compos spec: chỉ lấy những spec liên quan tới task đó, inject vào context của coding agent. Agent code đúng ngay lần đầu.

2. Task Tree (.trellis/tasks/)

Mỗi task là một folder slug, bên trong có:

• prd.md — Product Requirement Document
• design.md — Technical design decisions
• implement.json — Manifest cho sub-agent implement
• check.json — Manifest cho sub-agent check

Khi bạn chạy trellis start task/<slug>, nó kick off 4-phase workflow:

Plan → Implement → Verify → Finish

• Phase 1 (Plan): Brainstorm skill hỏi từng câu, viết PRD. Sub-agent trellis-research (read-only) tra spec, research rồi propose giải pháp.
• Phase 2 (Implement): Sub-agent trellis-implement đọc context manifest, viết code. Không commit, không push. Chỉ git diff ra file patch.
• Phase 3 (Verify): Sub-agent trellis-check review diff, chạy lint + typecheck + test. Nếu fail, tự động sửa và chạy lại (self-fix loop).
• Phase 4 (Finish): trellis-update-spec phân tích xem có learning mới không, nếu có thì propose update spec. Archive task. Ghi journal.

Cái hay là mỗi phase có sub-agent riêng với permission giới hạn — trellis-research không được viết file, trellis-implement không được commit, trellis-check không được push lên remote. Giống như mô hình quản lý code trong team: dev viết, reviewer check, chỉ lead mới merge.

3. Journal & Knowledge Capture

Mỗi lần làm task Trellis ghi journal vào workspace/<dev>/. Đây không chỉ là log cho vui — nó là input cho feedback loop.

Có một skill mình thấy ấn tượng nhất: trellis-break-loop. Sau khi debug một bug khó, Trellis tự động phân tích 5 chiều:

• Root cause là gì?
• Sao attempt trước fail?
• Làm sao prevent future?
• Systematic expansion (bug này xuất hiện ở chỗ khác không?)
• Knowledge capture: ghi vào spec luôn

Càng dùng, spec library càng dày, agent càng ít sai.

Dùng thử: Ấn tượng đầu tiên

Mình test Trellis với Claude Code trên một cái microservice Go xử lý menu cho merchant — Gin + gRPC, tầm 20 file. Workflow nó chạy mượt hơn mình tưởng.

Điểm sáng đầu tiên là cái task plan. Khi chạy trellis start, thay vì Claude Code nhảy vào code ngay (và thường code sai hướng), Trellis bắt nó dừng lại, hỏi từng câu “mục tiêu của task là gì?”, “có spec nào ảnh hưởng?”, “approach nào phù hợp?” — giống như một senior engineer đang hướng dẫn junior, chứ không phải AI chạy đầu.

Kết quả: lần đầu implement pass test luôn. Cảm giác nó… lạ. Mình quen với kiểu “chạy AI, đọc output, sửa lần 2, lần 3, cay vcl” rồi. Trellis làm mình nghi ngờ — chắc tại task dễ thôi. Nhưng thử task khó hơn (thêm Redis caching layer cho API get menu theo merchant, có tính đến cache invalidation khi menu thay đổi) thì nó vẫn pass ở lần 2. Không phải phép màu, nhưng cải thiện rõ.

Developer Experience: Có sướng không?

Điểm cộng lớn nhất: Multi-platform từ đầu. Một .trellis/ chạy được trên Claude Code, Codex, Cursor, Copilot, Gemini CLI — 16+ nền tảng. Chia 3 class:

• Class 1 (hook-based): Claude Code, Cursor, OpenCode, Kiro — auto-inject context mỗi session
• Class 2 (pull-based): Codex, Copilot, Gemini, Qoder — dùng prelude injection
• Class 3 (extension): Pi Agent

Nếu team bạn dùng Claude Code, còn thằng bạn dùng Cursor — cả 2 vẫn share chung .trellis/. Hợp tác mà không cần thống nhất tool.

Điểm cộng thứ hai: Parallel execution qua git worktrees. Mỗi agent chạy trong một worktree riêng. Muốn 2 task chạy đồng thời? Cứ spawn thêm worktree. Không cần orchestrator complex.

Điểm trừ: Workflow ban đầu hơi nhiều bước. Nếu bạn chỉ muốn “AI ơi sửa dùm cái bug này nhanh”, phải chạy qua 4 phases khá nặng. May là Trellis cho phép skip phase nếu muốn.

So sánh với Hermes Agent và OpenClaw

Mình đã dùng cả Hermes Agent lẫn OpenClaw, nên nói thử góc nhìn so sánh.

Hermes Agent (của Nous Research) cũng là harness, nhưng hướng khác hẳn. Hermes sinh ra để làm personal agent — chat với bạn, dùng tools, có memory, chạy nhiều nền tảng. Nó giống một trợ lý cá nhân hơn. Trellis thì không — Trellis là engineering framework cho coding workflow. Nếu Hermes là anh bạn ngồi cùng bàn giúp bạn search Google với summarize email, thì Trellis là cái playbook team dùng khi code — spec ở đâu, convention nào, làm task ra sao.

OpenClaw mình từng viết bài, nó gần với Trellis hơn — cũng là harness cho coding agent. Nhưng OpenClaw yếu ở multi-platform: chủ yếu support Claude Code. Trellis có 16+ platform out of the box. Về spec management, Trellis cũng structured hơn hẳn với spec library + compos pattern.

Còn về độ maturity: Trellis v0.6.x đã GA (General Availability), 10.8k stars, community khá active. OpenClaw nhỏ hơn. Hermes thì mới hơn nhưng phát triển nhanh.

Weaknesses: Không có gì là hoàn hảo

Trellis có mấy điểm yếu mình note lại:

1. AGPL-3.0 license. Đây là vấn đề nếu bạn làm product commercial. AGPL yêu cầu nếu bạn modify code và deploy network-accessible, bạn phải open source toàn bộ. Team startup cần check với legal trước.

2. Spec management là responsibility của team. Trellis tự động draft spec, nhưng tighten — chốt spec — vẫn là việc của con người. Nếu team lười, spec library sẽ mục nát dần, và Trellis cũng chẳng còn tác dụng. Garbage in, garbage out.

3. Workflow overhead. 4-phase workflow hay, nhưng với task cực nhỏ (fix typo, rename variable), nó hơi overkill. Trellis có skip phase nhưng phải biết dùng.

4. Windows support. Cộng đồng report vài issue về đường dẫn trên Windows. Nếu team bạn dùng Windows, nên test kỹ trước khi commit.

Mình cũng thấy trên GitHub issues (#234-#277) vài bug về codex sub-agent recursion và manifest over-hashing. Bản chất của open source project ở giai đoạn growth — feature chạy nhanh hơn bug fix.

Nên dùng khi nào? Khi nào không?

Nên dùng nếu:

• Team bạn dùng AI coding agents và muốn code ra chuẩn nhất quán
• Bạn muốn share convention giữa Claude Code, Codex, Cursor mà không viết lại config cho từng tool
• Bạn đang scale từ 1 dev dùng AI lên cả team dùng AI — cần workflow chuẩn
• Project của bạn có nhiều task parallel, muốn tận dụng git worktrees

Không nên dùng nếu:

• Bạn là dev solo, chỉ cần AI sửa code nhanh — Trellis overhead không đáng
• Project của bạn không có convention rõ ràng (còn early stage, đang explore)
• Bạn cần license thương mại không phải AGPL
• Team bạn ở Windows và không có ai chịu debug

Bottom line

Trellis giải quyết một vấn đề có thật: AI code nhanh, nhưng code không đúng convention. Nếu team của bạn đã từng revert commit của Claude Code lúc 2h sáng, bạn sẽ hiểu cái pain đó.

File-based, git-tracked, không cần cloud — đó là design decisions mình rất tôn trọng. Nó làm cho Trellis dễ thử nghiệm, dễ rollback, và dễ hiểu. Không magic, không black box.

So với Hermes Agent và OpenClaw, Trellis chuyên sâu nhất cho engineering workflow. Có spec library, có 4-phase workflow, có feedback loop tự học. Đúng cái niche của nó.

Số GitHub stars (10.8k) không nói dối — community đang vote.

Nếu bạn muốn: npm install -g @mindfoldhq/trellis@latest, chạy trellis init, và cho Claude Code của bạn một spec để nó code có kỷ luật hơn. Còn không thích thì uninstall cũng dễ, không dính gì.

Repo: https://github.com/mindfold-ai/trellis

Dùng rồi có ý kiến gì để lại comment bên dưới nhé. Mình cũng đang test Trellis cho dự án food delivery mới (menu service + merchant portal) với OpenCode — có gì hay sẽ viết tiếp.