Dev và Test: cài Phillip và nhận task đầu tiên
Làm hết trang này mất khoảng 15 phút. Xong là Phillip chạy được trên máy, đã nối với Tara và GitHub hoặc GitLab, và bạn biết những lệnh dùng hằng ngày. BA muốn kiểm thử ngay trên máy mình cũng làm theo trang này được.
Chưa biết Phillip, Bandum và Tara là gì thì đọc Giới thiệu trước. Nếu chỉ dùng trình duyệt thì xem BA, PO, PM.
Chuẩn bị
Máy bạn cần Node 22 trở lên (kiểm tra bằng node --version), git, và VS Code hoặc một terminal. Trong tài liệu này, địa chỉ Tara viết là https://tara.phillipcli.cloud. Tara và Ryoma chạy online nên bạn không phải dựng gì. Bạn cũng cần tài khoản GitHub hoặc GitLab có quyền Developer trở lên trên repo của dự án, và một tổ chức trên Tara với role Member trở lên (Viewer không dùng được Phillip). Nếu chưa có, làm theo Tạo hoặc vào một tổ chức trước: tự tạo tổ chức, hoặc nhờ Owner, Admin mời bạn.
Cài Phillip
Script cài kiểm tra Node, tải bản Phillip mới nhất từ Tara, kiểm sha256 rồi cài bằng npm install -g. Script không dùng sudo, và ghi sẵn địa chỉ Tara cùng khóa công khai vào cấu hình của bạn.
curl -fsSL https://tara.phillipcli.cloud/install.sh | shCài xong, bạn kiểm tra bằng lệnh sau:
ph --versionLệnh in phiên bản Phillip, rồi phiên bản Claude Code đi kèm. ph là tên ngắn của phillip, hai tên chạy như nhau.
Nếu terminal không nhận lệnh ph, bạn mở một terminal mới. Vẫn không được thì thư mục bin của npm chưa nằm trong PATH, xem Cài đặt chi tiết hoặc Xử lý sự cố. Nếu bạn cài thẳng bằng npm thì Phillip chưa biết địa chỉ Tara, nên ở bước sau hãy chạy ph setup --tara https://tara.phillipcli.cloud.
ph --versionphillip 0.1.6Claude Code 2.1.308Thiết lập bằng ph setup
Bạn vào thư mục repo của dự án (đã clone và có origin) rồi chạy:
cd du-an-cua-ban
ph setupLệnh làm lần lượt năm việc, mỗi việc in một dòng trạng thái.
- Lấy địa chỉ và khóa công khai của Tara. Nếu máy chưa có khóa, Phillip lấy từ Tara, in vân tay và hỏi "Trust this key? [y/N]". Bạn đối chiếu vân tay với Owner hoặc Admin rồi mới trả lời
y. - Đăng nhập Tara: Phillip mở trình duyệt, bạn bấm Allow (cho phép).
- Chọn dự án: Phillip liệt kê các harness của Tara, bạn chọn một, rồi Phillip chạy
ph initgiúp bạn. - Kết nối GitHub hoặc GitLab: Phillip nhận máy chủ từ
origin, tìm token có sẵn trên máy (gh,glab, git credential) và hỏi trước khi dùng. Nếu không có, nó mở trình duyệt để bạn bấm Authorize, hoặc mở trang tạo token đã điền sẵn quyền. - Kiểm tra môi trường bằng
ph forge doctor.
Bạn chạy lại bao nhiêu lần cũng được. Bước nào xong rồi thì in ✓ … (already done) và bỏ qua. Nếu chạy ngoài repo, lệnh dừng sau bước 2, báo thư mục này không phải repo git và liệt kê sẵn lệnh git clone … && cd … cho các repo dự án của tổ chức; bạn clone một repo rồi chạy lại ph setup bên trong thư mục. Khi thấy Next: ph bandum start <issue number>, then run ph to work with the agent. là thiết lập đã xong. Ryoma chỉ đếm phiên chạy qua ph, nên sau ph bandum start hãy mở agent bằng ph; lúc này bạn commit phillip.lock, CLAUDE.md và .claude/settings.json mà bước 3 vừa tạo.
| Tùy chọn | Ý nghĩa |
|---|---|
--tara <địa chỉ> | Địa chỉ Tara, không cần nếu script cài đã ghi |
--harness <tên> | Áp harness này vào dự án và bỏ câu hỏi chọn |
--yes | Không hỏi gì: tin cậy khóa Tara, nhận tài nguyên cộng đồng khi init, dùng token có sẵn. Chỉ dùng khi bạn đã đối chiếu vân tay khóa |
Làm từng bước bằng tay
Nếu ph setup dừng giữa chừng, hoặc bạn thích tự làm, các lệnh dưới đây tương ứng với từng bước:
# đăng nhập (thêm --no-browser nếu máy không có trình duyệt)
# một lần đăng nhập thuộc về một tổ chức: thêm --org <slug> để chọn, hoặc chọn từ danh sách lệnh in ra
ph login --url https://tara.phillipcli.cloud
# sau này: ph org list, ph org switch <slug>
# áp harness vào dự án; tên harness do tổ chức của bạn quy định
ph init harness-rnd-sdlc
# nối GitHub/GitLab, tự nhận máy chủ từ origin
ph connect
# kiểm tra môi trường
ph forge doctorMáy khác clone dự án đã init thì chỉ cần ph tara install để cài đúng các version đã khóa trong phillip.lock.
ph connect nhận token của chính bạn, vì commit và duyệt đứng tên bạn. Phillip cất token trong kho bí mật của máy, không ghi vào repo.
| Nền tảng | Quyền token cần |
|---|---|
| GitHub | Classic: scope repo. Hoặc fine-grained: Issues, Pull requests, Contents đều Read and write trên repo dự án |
| GitLab | Scope api, và bạn là Developer trở lên trong project (GitLab từ 15.0) |
Cách vào tổ chức, cho Phillip kết nối và tạo token từng bước có ảnh minh họa ở Kết nối GitHub hoặc GitLab.
Kết quả của ph forge doctor
ph forge doctor đạt khi không còn dòng ✗. Node, Claude Code, git và Tara là bắt buộc. Các dòng ⚠ như Ryoma, Collector hay Guardrails là tùy chọn, lệnh có gợi ý cách sửa nhưng ph setup vẫn không thất bại.
ph forge doctorNode v24.22.0Claude Code 2.1.308 (Claude Code)git git version 2.50.1 (Apple Git-155)Tara maya.chen @ https://tara.phillipcli.cloudphillip.lock 17 resources locked (lock ba8972f416dd)Ryoma https://ryoma.phillipcli.cloud: metrics receivedCollector data received through RyomaGuardrails not installed on this machine (the Guardrails dashboard will be empty). Install: sudo "$(command -v ph)" guardrails install --tara https://tara.phillipcli.cloud --ryoma https://ryoma.phillipcli.cloud --keys ed25519:<public key>Làm việc hằng ngày
Mã task có dạng GH-12, tức là số của issue. Trên GitLab bạn vẫn dùng tiền tố GH- với số issue trong project.
Dành cho Dev
| Lệnh | Dùng khi nào |
|---|---|
ph bandum start GH-12 | Nhận task: gán cho bạn, đặt nhãn "status: in progress", tạo nhánh feature/GH-12-... và khung testcases.md |
ph bandum check | Trước khi commit file kiểm thử: kiểm testcases.md, acceptance.md, .bandum.json |
ph bandum pr GH-12 | Làm xong và đã push nhánh: mở PR (GitLab là MR) với "Closes #12" |
ph bandum review GH-12 | Chuyển sang kiểm thử: kiểm PR và testcase, đặt nhãn "status: review" |
ph bandum verify GH-12 | Chạy test nghiệm thu tự động của nhánh PR |
ph bandum pull GH-12 | Xem nhận xét khi task bị trả lại |
ph bandum fix GH-12 | Task bị trả lại: giao agent sửa theo nhận xét rồi push |
ph bandum board | Xem task của sprint theo trạng thái |
Một vòng làm việc thường đi như sau:
ph bandum start GH-12 # nhận task, có nhánh và khung testcase
# ... làm việc cùng agent, commit, push nhánh ...
ph bandum check # kiểm file kiểm thử
ph bandum pr GH-12 # mở PR
ph bandum verify GH-12 # chạy test nghiệm thu
ph bandum review GH-12 # chuyển kiểm thửph bandum verify thoát với mã 0 khi đạt và 2 khi trả lại, nên bạn dùng được trong script và CI.
ph bandum boardOpen tasks: 15Todo (6) GH-107 Export the order list to CSV for admins GH-102 Buy now without signing in GH-101 Paginated order history … and 3 moreIn progress (4) GH-111 Discount code applied twice @sam.patel [PR #112] GH-110 Remove unused environment variables @sam.patel [PR #113] GH-108 Filter products by price and brand @maya.chen [PR #114] GH-92 Promotions admin page @sam.patel [PR #96]Review (waiting for testing) (3) GH-98 Search suggestions while typing @maya.chen [PR #106] GH-91 500 error when searching special characters @maya.chen [PR #103] GH-90 Product images fail to load on Safari @maya.chen [PR #105]Rejected (being fixed) (1) GH-78 Risk: address data is not normalized @sam.patel [PR #82]Approved (1) GH-99 Pagination returns an empty page @sam.patel [PR #109]Bandum local is running: ph bandum ui opens the board on the web.Dành cho Test, và BA kiểm thử ở máy
| Lệnh | Dùng khi nào |
|---|---|
ph bandum test GH-12 | Kiểm thử tay: lấy nhánh PR về, chạy ứng dụng, mở trang task để chấm Pass hoặc Fail |
ph bandum test GH-12 --cli | Chấm ngay trong terminal, không cần web Bandum |
ph bandum test GH-12 --pass TC-1,TC-2 --fail "TC-3=lý do" | Chấm bằng cờ lệnh: ghi kết quả rồi duyệt hoặc trả lại |
ph bandum verify GH-12 | Chạy test tự động và ghi kết quả |
ph bandum bug "<tiêu đề>" | Báo bug ngoài phạm vi task đang kiểm thử, tạo issue mới có nhãn type: bug |
Nếu bug nằm ngay trong task đang kiểm thử thì bạn chấm testcase đó là Fail, đừng tạo issue mới. Xem thêm Báo bug.
Mỗi issue cần đúng một nhãn type: feature | bug | debt | risk, cạnh nhãn level: S|M|L, để Ryoma báo cáo luồng công việc. Thiếu nhãn thì ph bandum start nhắc và ph bandum check cảnh báo missing_type, nhưng không chặn bạn. Muốn xem chi phí AI của mình, bạn chạy ph ryoma.
Chạy Bandum trên máy để xem bảng task
Các lệnh ph bandum ... ở trên không cần Bandum chạy trên máy. Bạn chỉ cần khi muốn xem bảng task và chấm testcase trên web:
cd du-an-cua-ban
ph bandum uiLần đầu, Phillip tải Bandum đã ký từ Tara, kiểm sha256 và chữ ký, cấu hình, chạy nền ở 127.0.0.1 rồi mở trình duyệt. Chỉ mình bạn dùng được, và token GitHub hoặc GitLab của bạn không ghi xuống đĩa.
Mặc định Bandum dùng SQLite, không cần Docker, hợp với Dev, Test và BA làm việc một mình trên vài repo. Nếu đã quen Docker, theo dõi nhiều repo hoặc muốn giống bản online, bạn thêm --docker để chạy với PostgreSQL.
| Lệnh | Việc |
|---|---|
ph bandum ui stop | Dừng Bandum (và PostgreSQL nếu dùng --docker) |
ph bandum ui status | Liệt kê các Bandum local: máy chủ, repo, cổng, phiên bản, database, trạng thái |
ph bandum ui logs [-f] | Xem nhật ký, -f để theo dõi liên tục |
ph bandum ui reset [--yes] | Xóa dữ liệu local. Dữ liệu chỉ là bản sao nên đồng bộ lại được |
ph bandum ui upgrade | Tải Bandum mới nhất và khởi động lại |
Ngoài ra còn ba cờ: --port <n> (mặc định là cổng trống đầu tiên từ 8070), --repo <owner/repo> để thêm repo cùng máy chủ, và --no-open để không mở trình duyệt.