SpecDeck
Điều phối coding agents bất đồng bộ bằng spec-first workflow.
Mỗi card là một Spec đi qua các cổng quyết định của con người.
SpecDeck mượn tính quen thuộc của board, nhưng các cột đại diện cho nơi cần quyết định của con người, không phải mọi trạng thái nội bộ của agent.
Làm rõ ý tưởng sản phẩm trước khi agent bắt đầu sửa code.
Review Goal, Acceptance và Checks trước khi Builder chạy.
Kiểm tra Checks và Evidence từ agent run đã hoàn thành.
Đóng băng Spec như hợp đồng cho phần đã ship.
Async agents chuyển bottleneck từ gõ code sang review công việc.
Khi nhiều agent chạy song song, terminal output và PR diff quá thấp tầng cho lớp điều phối của con người.
Terminal agents khó quan sát
Chúng có thể thực thi tốt, nhưng không tạo control surface rõ ràng để theo dõi nhiều luồng song song.
IDE agents vẫn đồng bộ
Chúng hiệu quả ở cấp file, nhưng vẫn giả định một developer đang steer một phiên edit chủ động.
Kanban theo dõi trạng thái, không tạo niềm tin
Board cho biết công việc đang ở đâu, nhưng không giải thích kết quả đã đủ bằng chứng để duyệt hay chưa.
Đọc Checks, không phải đọc code.
Mỗi Spec mang theo Checks và Evidence phía sau. Check pass nhưng không có Evidence sẽ không bao giờ được tính là xanh.
- Evidence là bắt buộc: test, log, screenshot hoặc video.
- Checker độc lập xác minh công việc, không phải Builder.
- Deterministic checks chạy trước; model judging chạy sau cùng.
Shopping cart calculation
Người dùng review kết quả ở tầng Check và Evidence.
Thuế được áp dụng theo region
Evidence: unit tests pass, 12 trên 12.
Discount codes được validate
Thiếu Evidence: chưa có end-to-end trace đính kèm.
Bốn cột, từ trái sang phải.
Backlog và Plan định hình intent trước khi code. Review là nơi kết quả đã xong chờ duyệt. Done đóng băng Spec như hợp đồng.
- Backlog01
Ý tưởng nằm ở đây trước khi Planner biến chúng thành Spec.
- Plan02
Review thứ sắp được build: Goal, Acceptance và Checks.
- Review03
Duyệt công việc đã hoàn tất ở tầng Check và Evidence.
Bạn review ở đây - Done04
Spec đã được chấp nhận được đóng băng như hợp đồng đã ship.
Planner, Builder, Checker.
Agent relay tách việc tạo intent, thực thi code và xác minh để cùng một actor không tự chấm công việc của mình.
- Planner
Biến intent thành Spec: Goal, Acceptance và Checks.
- Builder
Thực thi một Spec trong isolation. Một agent cho mỗi đơn vị công việc.
- Checker
Một model độc lập xác minh Evidence. Nó không bao giờ tự chấm công việc của chính mình.
Topology ba tầng giữ agent ở sau gateway.
Web app nói chuyện với FastAPI gateway qua REST và SSE. Gateway điều phối LangGraph Agent Server riêng và giữ secrets, persistence, realtime fan-out.
Web deck
Next.js render board, project context, Spec detail, Checks, Evidence và diff views.
FastAPI gateway
REST commands và SSE streams đi qua gateway để client không gọi trực tiếp agent server.
Agent server
Planner, Builder và Checker chạy như LangGraph workflows sau structured event contract.
Persistence và realtime
Postgres lưu app state, Redis pub/sub fan-out sự kiện Builder và Checker về board.
Thiết kế làm review rẻ hơn bằng cách giới hạn rõ thứ nó giải quyết.
SpecDeck không thay thế IDE. Nó là lớp điều phối để quyết định agent nên làm gì và kết quả có đủ bằng chứng hay chưa.
- 01
Review ở tầng intent
Giữ quyền kiểm soát
Tối ưu cho việc duyệt Goal, Acceptance, Checks và Evidence nhanh hơn.
Chi phí chấp nhận
Developer vẫn cần lối thoát diff cho thay đổi rủi ro và spot check cuối.
- 02
Checker độc lập
Giữ quyền kiểm soát
Tối ưu để tránh Builder tự xác minh blind spot của chính nó.
Chi phí chấp nhận
Tăng latency, model cost và thêm một event stream cần vận hành.
- 03
Single-user coordination trước
Giữ quyền kiểm soát
Tối ưu cho một operator chạy nhiều agent mà chưa phải gánh collaboration overhead.
Chi phí chấp nhận
Multi-user review, canvas workflows và full IDE replacement là non-goals có chủ đích ở giai đoạn này.
Concept đã được kiểm chứng bằng deck scaffolded và mock-driven.
Repo đã có architecture decisions, self-host skeleton và frontend có hình dạng sản phẩm. Logic Planner, Builder, Checker thật vẫn là mốc tiếp theo.
Product UI đã rõ hình
Landing, workspace, board/list views, grouped swimlanes, filters, project context, Spec detail, Checks, Evidence và Diff đã có dưới dạng mock-driven flows.
Stack skeleton chạy local
Repo có boundary cho web, gateway, agent packages, Postgres, Redis và docker-compose wiring.
Mốc tiếp theo là orchestration thật
Phần còn mở là wire Planner, Builder và Checker execution vào workspace state thật và evidence capture.
Self-host toàn bộ deck.
SpecDeck được thiết kế để chạy trong môi trường của chủ sở hữu, với model keys và project workspaces nằm sau backend boundary.
- Postgres, Redis, gateway, agents và web được compose cùng nhau.
- Model keys ở phía server; frontend nhận events, không nhận secrets.
- Repository vẫn là system of record cho Specs, context và implementation.