Pilot Shell là gì? Hướng dẫn dùng cho Claude Code và Codex

Pilot Shell là một lớp quy trình và công cụ chạy phía trên Claude Code cùng Codex CLI, giúp bạn chuyển từ kiểu viết code tự do sang quy trình có kế hoạch: đặc tả yêu cầu, lập spec, ép TDD và kiểm soát chất lượng ở mọi cấp độ. Repo này giải quyết vấn đề mà nhiều lập trình viên gặp phải khi dùng AI agent: viết nhanh nhưng thiếu test, mất ngữ cảnh giữa phiên làm việc, kết quả không nhất quán. Nó dành cho những ai đã có sẵn Claude Code hoặc Codex CLI và muốn biến chúng thành công cụ production-ready.

Nội dung

Thank you for reading this post, don't forget to subscribe!

Những điểm chính

Pilot Shell bổ sung quy trình /prd, /spec, /fix để biến ý tưởng mơ hồ thành feature hoàn chỉnh có kế hoạch và kiểm thử.
TDD là quy tắc bắt buộc: mọi tính năng hoặc bản sửa lỗi phải có test thất bại trước khi triển khai.
Quality hooks tự động chạy lint, format, type-check và test để chặn code kém chất lượng.
Context engineering giúp agent nhớ quyết định, phát hiện và kiến thức giữa các phiên làm việc.
Hỗ trợ Claude Code đầy đủ và Codex CLI ở các workflow chính, kèm Console web quản lý phiên, spec và memory.

Pilot Shell là gì và giải quyết vấn đề gì?

Pilot Shell là lớp quy trình và công cụ chạy phía trên Claude Code cùng Codex CLI, giúp mã nguồn sinh ra từ AI đi qua các bước: đặc tả, lập kế hoạch, viết test, kiểm tra chất lượng rồi mới gộp vào dự án. Thay vì thêm hàng chục agent và hàng nghìn dòng cấu hình, nó tập trung vào các thành phần nhỏ giải quyết đúng vấn đề.

Vấn đề khi dùng AI agent không có cấu trúc

Claude Code và Codex CLI viết code rất nhanh, nhưng nếu không có quy trình bao quanh, chúng dễ bỏ qua test, mất ngữ cảnh và cho kết quả không nhất quán. Các framework khác thường xử lý bằng cách thêm nhiều agent phức tạp, tốn công cấu hình mà đầu ra không cải thiện rõ rệt. Pilot Shell xuất phát từ góc nhìn khác: mỗi thành phần trong repo đều gắn với một vấn đề cụ thể và có cách giải quyết có chủ đích.

Cách tiếp cận của Pilot Shell

Ba cụm từ trong README tóm tắt toàn bộ triết lý: kế hoạch theo spec, cổng chất lượng bắt buộc và tri thức bền vững. Pilot Shell dùng spec làm hợp đồng giữa người và máy, ép TDD trong quá trình triển khai, rồi lưu các quyết định và phát hiện qua từng phiên làm việc. Kết hợp thêm semantic search, code graph và nén token, nó giúp agent làm việc chính xác hơn mà không đốt quá nhiều chi phí.

Nếu bạn muốn đọc tài liệu gốc và xem changelog, hãy ghé qua repository gốc trên GitHub.

Những tính năng chính của Pilot Shell

Pilot Shell không phải một lệnh duy nhất mà là một hệ thống gồm quy trình phát triển, cơ chế ghi nhớ, tìm kiếm ngữ cảnh, console giám sát và khả năng mở rộng. Dưới đây là những nhóm tính năng đáng chú ý nhất được mô tả trong README, từ quy trình spec cho đến các công cụ hỗ trợ kiểm thử và quản lý phiên làm việc.

Quy trình ba lệnh chính: /prd dùng để brainstorm yêu cầu, /spec lập kế hoạch và triển khai feature theo TDD, /fix xử lý bug cục bộ với vòng lặp kiểm thử ngắn.
Spec collaboration: chia sẻ spec với đồng nghiệp qua một đường link, nhận phản hồi theo từng tác giả và xem lại ngay trong Console.
Quality hooks: tự động chạy lint, formatting, type-check và test như cổng chặn trước khi code được coi là hoàn thành.
Context engineering: lưu quyết định, kiến thức và phát hiện để agent không bắt đầu lại từ đầu sau mỗi phiên.
Code intelligence: dùng Semble để tìm kiếm ngữ nghĩa và CodeGraph để xây đồ thị tri thức của mã nguồn.
Token optimization: RTK compression kết hợp Semble giúp giảm 60-90% chi phí token.
Pilot Bot: agent tự động hóa nền tảng, có thể chạy tác vụ theo lịch và xử lý background jobs.
Extensions: tái sử dụng rules, skills và MCP servers, cho phép chia sẻ và tùy chỉnh trong nhóm.

Pilot Shell Console

Console là web dashboard chạy tại localhost:41777, gồm 10 khu vực: Dashboard, Sessions, Memories, Requirements, Specifications, Extensions, Changes, Usage, Settings và Documentation. Bạn có thể duyệt lại phiên làm việc, đọc memory, xem spec, theo dõi chi phí token và quay lại session cũ bằng /resume với Claude Code.

Các lệnh /prd, /spec và /fix hoạt động ra sao?

Ba lệnh chính tương ứng với ba nhu cầu: /prd dùng khi ý tưởng còn mơ hồ, /spec dùng khi muốn xây tính năng hoặc refactor có kế hoạch, /fix dùng cho lỗi cục bộ cần sửa nhanh. Cả ba đều bị ràng buộc bởi TDD và quality hooks, khác nhau chủ yếu ở độ sâu trong từng bước.

/prd — Từ ý tưởng đến bản yêu cầu

/prd hoạt động ở hai chế độ: Ideate khi ý tưởng còn mơ hồ và Clarify rồi Converge rồi Write khi hình dạng yêu cầu đã rõ. Bạn có thể chọn mức research Quick, Standard hoặc Deep. Kết quả là một PRD chứa problem statement, luồng người dùng, phạm vi và bối cảnh kỹ thuật, sau đó có thể bàn giao sang /spec.

/spec — Lập kế hoạch và triển khai theo TDD

/spec tự động nhận diện request là feature hay bugfix. Với feature, nó thăm dò codebase, đặt câu hỏi, viết spec chi tiết, tạo worktree riêng, triển khai theo chu kỳ RED – GREEN – REFACTOR và xác minh bằng test cùng E2E cho UI. Sau khi bạn duyệt spec, agent thực hiện từng task, quality hooks chạy trên mỗi chỉnh sửa, rồi squash merge vào nhánh chính khi thành công.

/fix — Sửa lỗi cục bộ nhanh

/fix đi theo chuỗi Investigate, RED, Fix, Audit rồi Quality Gate. Nó viết test thất bại trước, sửa đúng root cause, chạy lại test và kiểm tra toàn bộ hệ thống. Nếu bug liên quan nhiều thành phần hoặc mang tính kiến trúc, /fix chủ động dừng và gợi ý dùng /spec thay vì cố sửa theo cách không bền vững.

Ngoài ra, Pilot Shell còn có /setup-rules để sinh rules theo từng dự án, /create-skill để đóng gói workflow tái sử dụng, /benchmark để đo tác động của rules và skills, và /ask-codex để chạy Codex như một sub-agent trong Claude Code.

Hướng dẫn cài đặt và sử dụng Pilot Shell

Cài đặt Pilot Shell chỉ mất dưới 2 phút trên macOS, Linux và Windows WSL2 bằng một lệnh curl duy nhất. Trước khi chạy lệnh, bạn cần cài sẵn ít nhất một agent là Claude Code hoặc Codex CLI, vì installer không tự cài chúng và sẽ báo lỗi nếu không phát hiện agent nào.

Điều kiện cần chuẩn bị

Cài Claude Code hoặc Codex CLI bằng native installer, gỡ bỏ bản npm hoặc brew nếu có.
Tài khoản Claude hoặc OpenAI có subscription phù hợp.
Một terminal hiện đại như Ghostty, iTerm2 hoặc cmux nếu muốn chạy nhiều session song song.
Pilot Shell hoạt động với project có sẵn, không yêu cầu tạo project mới.

Các bước cài đặt

Mở terminal và kiểm tra lệnh claude hoặc codex đã hoạt động.
Chạy lệnh cài đặt: curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash
Installer kiểm tra Homebrew, Node.js, Python 3.12+, uv, git, jq và agent đã cài.
Installer ghi các file cấu hình vào thư mục tương ứng, hợp nhất settings.json ba chiều nếu dùng Claude Code.
Chờ thông báo hoàn tất, sau đó chạy pilot update để kiểm tra bản mới.
Trong project, chạy claude hoặc codex, rồi gõ /setup-rules hoặc $setup-rules để tạo rules theo codebase.

Cập nhật, gỡ cài đặt và reset

Bạn có thể cập nhật bằng pilot update. Nếu gặp lỗi ở bản mới, hãy chạy export VERSION=9.14.0 rồi cài lại. Muốn gỡ hoàn toàn, chạy lệnh curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/uninstall.sh | bash. Khi reset, README khuyên bạn đăng xuất Claude Code, backup các thư mục ~/.claude, ~/.codex và ~/.pilot, cài lại và kích hoạt license key bằng lệnh pilot activate nếu cần.

Pilot Shell cũng hoạt động trong Dev Container. Bạn chỉ cần copy thư mục .devcontainer từ repo vào project và chạy installer bên trong container; installer tự phát hiện môi trường và bỏ qua các bước cài đặt hệ thống như Homebrew.

Ai nên dùng và ai không nên dùng Pilot Shell?

Pilot Shell phù hợp nhất với lập trình viên hoặc nhóm đã quen dùng Claude Code, cần quy trình rõ ràng và muốn AI agent tạo ra code đáng tin cậy hơn. Ngược lại, nó không dành cho người mới chưa biết terminal, chưa có tài khoản trả phí của Claude hoặc OpenAI, hoặc chỉ cần một công cụ chat code đơn giản.

Nên dùng nếu

Bạn đã dùng Claude Code hoặc Codex CLI và muốn chúng tuân theo kỷ luật TDD, lint, type-check và test.
Dự án của bạn có nhiều phiên làm việc, cần giữ ngữ cảnh và lịch sử quyết định.
Bạn muốn giảm chi phí token nhờ nén RTK và tìm kiếm mã nguồn ngữ nghĩa.
Bạn cần chia sẻ spec, đánh giá code và quản lý quy trình qua một dashboard local.

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

Bạn chưa có subscription của Claude hoặc OpenAI, vì Pilot Shell không tự cài hoặc thay thế agent.
Bạn chỉ dùng Codex CLI và cần đầy đủ tính năng nền tảng như trên Claude Code.
Bạn không muốn học các khái niệm như TDD, spec hoặc quy trình kiểm thử.
Dự án của bạn quá nhỏ và chỉ cần sinh code nhanh, không cần quality gate phức tạp.

Một điểm cần kiểm tra là Pilot Shell không tự cài agent và yêu cầu agent có subscription hợp lệ; khi reset hoặc cài lại, README còn nhắc đến license key. Bạn vẫn phải đọc spec, review diff và chịu trách nhiệm về sản phẩm cuối cùng, vì đây là công cụ hỗ trợ quy trình chứ không phải phép màu.

Câu hỏi thường gặp

Pilot Shell có dùng được với Codex CLI không?

Có. Pilot Shell hỗ trợ Codex CLI cho các workflow chính như /prd, /spec, /fix với cú pháp $prd, $spec, $fix. Tuy nhiên, Codex CLI có ít tính năng nền tảng hơn: một số công cụ như Console, E2E UI và một số reviewer chỉ hoạt động đầy đủ trên Claude Code.

Pilot Shell có thay thế Claude Code hoặc Codex CLI không?

Không. Pilot Shell không phải agent thay thế mà là lớp cấu hình và quy trình chạy phía trên. Bạn vẫn mở terminal, chạy lệnh claude hoặc codex, sau đó dùng các lệnh /prd, /spec, /fix. Pilot Shell đảm nhận việc cài rules, hooks, skills, subagents và MCP servers để agent làm việc bài bản hơn.

Cài Pilot Shell có làm hỏng cấu hình hiện tại không?

Theo README, installer có 8 bước, theo dõi tiến trình, quay lại trạng thái trước nếu thất bại và hỗ trợ chạy lại an toàn. Với Claude Code, settings.json được gộp ba chiều. Khi làm sạch toàn bộ, bạn nên backup các thư mục ~/.claude, ~/.codex và ~/.pilot trước khi cài lại.

Tôi có cần giỏi lập trình mới dùng Pilot Shell?

Có, bạn nên thoải mái với terminal, Git, dòng lệnh và khái niệm test. Pilot Shell không phải công cụ dành cho người không biết code; nó giúp kỹ sư kiểm soát agent tốt hơn, nhưng bạn vẫn phải duyệt spec, đọc diff, chạy lệnh và đánh giá mức độ hoàn thành.

Kết luận

Pilot Shell mang đến một cách tiếp cận thực tế cho vấn đề AI agent viết code thiếu kiểm soát: lập kế hoạch trước, ép TDD, xác minh bằng test và giữ memory xuyên phiên. Nó không biến bạn thành lập trình viên giỏi hơn ngay lập tức, nhưng giúp bạn biến Claude Code và Codex CLI thành công cụ đáng tin cậy hơn trong dự án thực tế. Nếu bạn đang dùng một trong hai agent này và muốn thử quy trình production-ready, hãy đọc README trên repository gốc rồi bắt đầu với /setup-rules trong một project nhỏ.