Bỏ qua tới nội dung
Ông T.vn

snarktank/ralph: vòng lặp AI tự code xong cả danh sách việc — hướng dẫn cài đặt và dùng

11 phút đọcCập nhật

Bài này là một góc nhìn khác về snarktank/ralph — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: snarktank/ralph: vòng lặp AI tự code đến khi xong PRD — hướng dẫn cài đặt và dùng →

snarktank/ralph: vòng lặp AI tự code xong cả danh sách việc — hướng dẫn cài đặt và dùng

Tóm tắt nhanh

Ralph là một vòng lặp tự động chạy công cụ AI viết code (Amp hoặc Claude Code) lặp lại cho đến khi mọi mục trong PRD hoàn thành. Mỗi lượt là một phiên AI mới, trí nhớ được giữ qua git, progress.txt và prd.json. Cài không khó nếu bạn đã quen terminal: chép vài file vào dự án, cần thêm jq và một công cụ AI đã đăng nhập.

Ralph là một vòng lặp tự động: nó gọi công cụ AI viết code (Amp hoặc Claude Code) hết lần này đến lần khác, mỗi lần làm một việc nhỏ trong danh sách, cho đến khi cả danh sách xong. Thực chất lõi của nó là một script bash tên ralph.sh, kèm file prompt và hai skill hỗ trợ viết yêu cầu.

Vấn đề nó giải quyết rất quen thuộc. Bạn giao cho AI một tính năng lớn, nó làm được một nửa thì đầy bộ nhớ hội thoại, bắt đầu quên và viết code kém dần. Ralph tránh chuyện đó bằng cách chia tính năng thành nhiều việc nhỏ, và mỗi việc được làm bởi một phiên AI mới tinh, bộ nhớ sạch. Những gì cần nhớ được ghi lại trong lịch sử git, file progress.txt và file prd.json.

Repo này hợp với lập trình viên (kể cả mới) đã có dự án trong git và đã dùng Claude Code hoặc Amp. Điểm đáng giá nhất là cách làm: bạn viết yêu cầu cẩn thận một lần, rồi để máy lặp lại phần còn lại. Hiện repo có khoảng 22.224 sao và 2.116 fork, giấy phép MIT. Ý tưởng gốc dựa trên mẫu "Ralph" của Geoffrey Huntley.

Skill

snarktank/ralph

Ralph chạy Amp hoặc Claude Code lặp đi lặp lại, mỗi lượt làm một user story trong prd.json cho đến khi cả danh sách hoàn thành.

★ 22kTypeScriptMIT
Xem repo trên GitHub

I.Ralph làm được gì

Chạy lặp tự động đến khi xong. Bạn chạy một lệnh, Ralph tự lần lượt xử lý từng user story. Bạn không phải ngồi nhắc AI "làm tiếp đi" sau mỗi bước.

Mỗi lượt là một phiên AI mới. Nhờ vậy ngữ cảnh luôn sạch, AI ít bị "loãng" như khi làm một phiên dài. Trí nhớ giữa các lượt chỉ gồm ba thứ: lịch sử git (các commit trước), progress.txt (ghi chú học được) và prd.json (việc nào đã xong).

Mỗi lượt làm theo quy trình cố định. Theo README, Ralph sẽ:

  • tạo nhánh tính năng (lấy từ branchName trong PRD);
  • chọn story ưu tiên cao nhất còn passes: false;
  • làm đúng một story đó;
  • chạy kiểm tra chất lượng (typecheck, test);
  • commit nếu kiểm tra qua;
  • đánh dấu story là passes: true trong prd.json;
  • ghi bài học vào progress.txt.

Có sẵn hai skill hỗ trợ. Skill prd giúp bạn tạo tài liệu yêu cầu sản phẩm (PRD), skill ralph chuyển PRD đó sang prd.json. Nghĩa là bạn không phải tự viết JSON bằng tay.

Tự cập nhật AGENTS.md. Sau mỗi lượt, Ralph ghi lại các quy ước, mẹo và chỗ dễ sai vào các file AGENTS.md liên quan. Công cụ AI tự đọc các file này, nên lượt sau (và cả đồng nghiệp của bạn) hưởng lợi.

Tự lưu trữ lần chạy cũ. Khi bạn bắt đầu tính năng mới (đổi branchName), Ralph lưu lần chạy trước vào thư mục archive/ theo ngày và tên tính năng.

Có sơ đồ tương tác. Thư mục flowchart/ chứa mã nguồn một trang minh hoạ từng bước chạy, có thể chạy trên máy.

II.Cần chuẩn bị gì

Theo README, bạn cần:

  • Một trong hai công cụ AI code, đã cài và đã đăng nhập:
    • Amp CLI (là mặc định), hoặc
    • Claude Code (cài bằng npm install -g @anthropic-ai/claude-code).
  • jq đã cài (README ghi brew install jq cho macOS).
  • Một repo git cho dự án của bạn.

README không nói gì về hệ điều hành cụ thể, phiên bản Node hay phần cứng. Lưu ý riêng: vì ralph.sh là script bash, người dùng Windows có lẽ sẽ cần một môi trường chạy bash (như Git Bash hoặc WSL). Đây là suy luận của mình, README không xác nhận, nên bạn tự thử trước khi tin.

Về chi phí: README không nói giá. Amp và Claude Code là dịch vụ của bên thứ ba, bạn cần tự xem gói và mức tính phí của họ.

Ralph chạy vòng lặp nhiều lượt và tự commit code vào nhánh. Hãy chạy trên một nhánh riêng, trong repo đã có bản sao lưu, và nhớ rằng mỗi lượt AI chạy là một lần dùng hạn mức (hoặc tiền) của công cụ AI bạn đang dùng. Đặt số lượt tối đa thấp khi mới thử.

III.Cài đặt từng bước

README đưa ra ba cách. Cách 1 (chép file vào dự án) là cách chính để chạy vòng lặp. Cách 2 và 3 chủ yếu để cài hai skill. Mình tóm tắt trước:

  1. Cài công cụ nềnCó Amp hoặc Claude Code đã đăng nhập, và có jq
  2. Chép file Ralph vào dự ánĐặt ralph.sh và file prompt vào scripts/ralph/
  3. Cài skill prd và ralphChép thủ công, hoặc dùng marketplace của Claude Code
  4. (Tuỳ chọn) Bật auto-handoff cho AmpThêm một dòng vào settings.json
  5. Tạo PRD rồi chạyTạo PRD, đổi sang prd.json, chạy ralph.sh

A.Cài công cụ nền

Nếu dùng Claude Code, README ghi lệnh cài như sau (cần có npm sẵn):

Terminal
npm install -g @anthropic-ai/claude-code

Nếu dùng Amp, bạn cài Amp CLI theo hướng dẫn trên trang của Amp (README chỉ dẫn link, không ghi lệnh). Còn jq trên macOS thì:

Terminal
brew install jq

README không ghi cách cài jq trên hệ điều hành khác, bạn xem trang chính thức của jq.

B.Chép file Ralph vào dự án

Đầu tiên tải repo Ralph về một thư mục riêng, rồi chép file sang dự án của bạn:

Terminal
git clone https://github.com/snarktank/ralph.git

Sau đó mở terminal tại thư mục gốc dự án của bạn (không phải thư mục của Ralph) và chạy. Thay /path/to/ralph bằng đường dẫn thật tới thư mục vừa clone:

Terminal
# From your project root
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/

# Copy the prompt template for your AI tool of choice:
cp /path/to/ralph/prompt.md scripts/ralph/prompt.md    # For Amp
# OR
cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md    # For Claude Code

chmod +x scripts/ralph/ralph.sh

Chỗ hay vấp: chỉ chọn một trong hai dòng chép prompt, tuỳ công cụ bạn dùng. chmod +x để cho phép chạy script, thiếu dòng này lúc chạy sẽ báo không có quyền.

C.Cài skill prd và ralph

Có hai đường. Đường thủ công cho Amp:

Terminal
cp -r skills/prd ~/.config/amp/skills/
cp -r skills/ralph ~/.config/amp/skills/

Đường thủ công cho Claude Code:

Terminal
cp -r skills/prd ~/.claude/skills/
cp -r skills/ralph ~/.claude/skills/

Các lệnh này chạy từ thư mục repo Ralph (nơi có thư mục skills/).

Hoặc dùng marketplace trong Claude Code. Gõ trong Claude Code:

Terminal
/plugin marketplace add snarktank/ralph

Rồi cài skill:

Terminal
/plugin install ralph-skills@ralph-marketplace

Sau khi cài sẽ có hai lệnh: /prd (tạo tài liệu yêu cầu) và /ralph (chuyển PRD sang prd.json). README cũng nói các skill tự được gọi khi bạn nhờ Claude những câu như "create a prd" hay "convert this prd".

D.Bật auto-handoff cho Amp (khuyến nghị)

Nếu dùng Amp, README khuyên thêm vào ~/.config/amp/settings.json:

JSON
{
  "amp.experimental.autoHandoff": { "context": 90 }
}

Theo README, cài đặt này cho phép tự chuyển giao khi ngữ cảnh đầy, giúp Ralph xử lý được story lớn hơn một cửa sổ ngữ cảnh. Nếu file đã có nội dung khác, hãy thêm dòng này vào đúng chỗ, đừng ghi đè mất cài đặt cũ.

IV.Kiểm tra đã chạy được chưa

README không có lệnh "kiểm tra cài đặt" riêng. Cách thực tế là xem từng mảnh:

  • Skill: trong Claude Code, gõ /prd hoặc /ralph thấy lệnh xuất hiện nghĩa là skill đã nhận (README ghi hai lệnh này sẽ có sau khi cài).
  • Script: chạy thử với số lượt nhỏ, ví dụ 1 lượt, khi đã có prd.json. Nếu thấy Ralph tạo nhánh, làm một story rồi commit, là chạy đúng.
  • Trạng thái: dùng ba lệnh gỡ lỗi của README.
Terminal
# See which stories are done
cat prd.json | jq '.userStories[] | {id, title, passes}'

# See learnings from previous iterations
cat progress.txt

# Check git history
git log --oneline -10

Khi mọi story có passes: true, Ralph phát tín hiệu hoàn thành và vòng lặp tự thoát. Nếu chưa xong mà hết số lượt tối đa, nó cũng dừng.

Muốn xem sơ đồ cách Ralph hoạt động trên máy, vào thư mục flowchart/:

Terminal
cd flowchart
npm install
npm run dev

V.Dùng vào việc thật

Quy trình chung gồm ba bước: tạo PRD, đổi sang prd.json, chạy Ralph. Mình đi qua vài tình huống cụ thể.

A.Dev thêm tính năng cho web app có sẵn

Bạn là lập trình viên đang giữ một web app và cần thêm bộ lọc cho trang danh sách đơn hàng. Mở Claude Code trong dự án và gõ prompt mẫu của README:

Code
Load the prd skill and create a PRD for [your feature description]

Thay phần trong ngoặc bằng mô tả tính năng của bạn. Skill sẽ hỏi lại vài câu làm rõ, bạn trả lời, rồi nó lưu kết quả vào tasks/prd-[feature-name].md. Đọc lại file này và sửa chỗ chưa đúng ý trước khi sang bước sau, vì chất lượng PRD quyết định chất lượng code.

Kết quả: một tài liệu yêu cầu rõ ràng, nằm sẵn trong dự án, có thể đưa cả cho đồng nghiệp xem.

B.Biến PRD thành danh sách việc cho máy

Tiếp theo, chuyển PRD thành định dạng Ralph đọc được:

Code
Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json

Bạn sẽ có prd.json gồm các user story, mỗi story có trạng thái passes. Hãy mở ra kiểm tra kích cỡ từng story. README nhấn mạnh mỗi story phải đủ nhỏ để làm xong trong một cửa sổ ngữ cảnh. Việc vừa sức là "thêm một cột database kèm migration", "thêm một ô lọc dạng dropdown vào danh sách". Việc quá lớn cần chia nhỏ là "xây cả dashboard", "thêm đăng nhập", "refactor toàn bộ API".

Ralph chỉ giỏi khi việc đủ nhỏ và có test canh chừng; việc to thì chia nhỏ rồi hãy giao.

Ông T

Kết quả: một danh sách việc nhỏ, rõ, có thứ tự ưu tiên, sẵn sàng cho máy chạy.

C.Chạy qua đêm với giới hạn lượt

Bạn muốn để máy làm trong lúc đi ngủ. Chạy từ thư mục gốc dự án, với Amp (mặc định):

Terminal
./scripts/ralph/ralph.sh [max_iterations]

Hoặc với Claude Code:

Terminal
./scripts/ralph/ralph.sh --tool claude [max_iterations]

Thay [max_iterations] bằng một con số, ví dụ số lượt bằng khoảng số story cộng thêm vài lượt dự phòng. Mặc định là 10 lượt. Sáng hôm sau, xem git log --oneline -10 để biết đã commit những gì, và progress.txt để biết AI đã học được gì.

Kết quả: các commit riêng cho từng story trên nhánh tính năng, mỗi commit chỉ có khi typecheck và test qua.

D.Làm việc với giao diện (UI)

Với story liên quan giao diện, README yêu cầu ghi trong tiêu chí nghiệm thu dòng "Verify in browser using dev-browser skill". Khi đó Ralph dùng skill dev-browser để mở trang, thao tác thử và xác nhận thay đổi chạy đúng. Lưu ý skill dev-browser là thứ README nhắc tới nhưng không nằm trong repo này, bạn cần tự có nó. Với chủ shop nhờ freelancer sửa trang web bán hàng, đây là cách để kiểm tra phần nhìn thấy được thay vì chỉ tin vào test.

Sau lần chạy đầu, hãy mở prompt.md (Amp) hoặc CLAUDE.md (Claude Code) đã chép vào dự án và chỉnh cho đúng dự án: thêm lệnh kiểm tra riêng, quy ước code, các lỗi hay gặp của công nghệ bạn dùng. README gọi đây là bước tuỳ biến nên làm.

VI.Lỗi hay gặp và cách xử lý

README không có mục xử lý lỗi, nên dưới đây là các tình huống dễ xảy ra với loại công cụ này, kèm hướng xử lý an toàn.

A.Báo không có quyền chạy ralph.sh

Nguyên nhân thường là chưa cấp quyền thực thi. Chạy lại dòng chmod +x scripts/ralph/ralph.sh trong phần cài đặt, và chắc chắn bạn đang đứng ở thư mục gốc dự án khi gõ lệnh.

B.Báo không tìm thấy jq

Ralph cần jq để đọc prd.json. Hãy cài jq (macOS: brew install jq), mở lại terminal rồi chạy lại. Gõ jq --version để xem máy đã nhận chưa.

C.Chọn nhầm công cụ hoặc nhầm file prompt

Mặc định Ralph dùng Amp. Nếu bạn dùng Claude Code mà quên --tool claude, nó sẽ gọi sai công cụ. Ngược lại, hãy kiểm tra bạn đã chép đúng file: prompt.md cho Amp, CLAUDE.md cho Claude Code.

D.AI làm dở, code chất lượng thấp, hết lượt mà chưa xong

Theo README, nguyên nhân phổ biến là story quá lớn, AI hết ngữ cảnh trước khi làm xong. Cách xử lý: mở prd.json, chia story lớn thành nhiều story nhỏ, đặt lại passes cho đúng, rồi chạy tiếp. Đồng thời xem progress.txt để biết nó đã vướng ở đâu.

E.Code hỏng lan sang các lượt sau

README nêu rõ Ralph chỉ chạy tốt khi có vòng phản hồi: typecheck, test, và CI phải luôn xanh, vì code hỏng sẽ cộng dồn qua các lượt. Nếu dự án chưa có test hay typecheck, hãy bổ sung trước khi giao việc cho Ralph. Vì mọi thứ nằm trên nhánh riêng, bạn luôn có thể xem git log và quay về commit tốt gần nhất.

VII.Có nên dùng không

Điểm mạnh. Ý tưởng đơn giản, dễ hiểu: một script bash, vài file văn bản, không cần dịch vụ lạ. Mỗi lượt dùng ngữ cảnh mới nên tránh được cảnh AI "lú" khi làm lâu. Trí nhớ nằm trong git và file thường nên bạn đọc, sửa, kiểm soát được mọi thứ. Việc ghi bài học vào AGENTS.md cũng có ích cho cả người lẫn máy về sau.

Giới hạn. Ralph không thay bạn nghĩ về yêu cầu. PRD mơ hồ thì kết quả cũng mơ hồ. Nó đòi hỏi dự án đã có test hoặc typecheck, nếu không thì không có gì canh chừng. Nó cần Amp hoặc Claude Code đã đăng nhập, nên có chi phí từ các dịch vụ đó mà README không nói rõ mức nào. README cũng chưa nói về Windows, và theo thông tin hiện có, repo lâu rồi chưa được cập nhật, nên bạn nên tự thử trên dự án nhỏ trước.

Khi nào chọn cách khác. Nếu bạn chỉ cần sửa một lỗi nhỏ hoặc làm một việc đơn lẻ, cứ trò chuyện trực tiếp với Claude Code, không cần dựng cả vòng lặp. Nếu bạn không dùng git hoặc dự án không có kiểm tra tự động, hãy lo phần nền đó trước. Còn nếu bạn có một tính năng chia được thành nhiều việc nhỏ, đã có test, và muốn máy làm dần trong lúc bạn làm việc khác, Ralph là một lựa chọn đáng thử.

5.0/5 · Ông T chấm

Chưa có độc giả chấm

Bài này có ích với bạn không?

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

Ralph có miễn phí không?

Bản thân repo dùng giấy phép MIT, nên dùng và sửa tự do. Tuy nhiên Ralph chỉ gọi Amp hoặc Claude Code, và chi phí của hai công cụ này README không nói rõ. Bạn cần tự xem gói và mức tính phí của họ.

Ralph có cần GPU không?

README không nhắc đến GPU hay yêu cầu phần cứng nào. Ralph chỉ là script bash chạy các công cụ AI dòng lệnh, nên phần xử lý AI nằm ở dịch vụ của Amp hoặc Claude Code.

Ralph chạy được trên Windows không?

README chưa có thông tin về Windows. Vì ralph.sh là script bash và cần jq, bạn có lẽ sẽ phải dùng môi trường bash như Git Bash hoặc WSL. Đây là suy luận, bạn nên thử trên dự án nhỏ trước.

Ralph khác gì việc chat với Claude Code bình thường?

Chat thường là một phiên dài, dễ đầy ngữ cảnh. Ralph chạy nhiều lượt, mỗi lượt là một phiên AI mới làm đúng một story, rồi lưu trí nhớ vào git, progress.txt và prd.json. Nhờ vậy nó tự làm lần lượt cả danh sách việc.

Mã nguồn của tôi có an toàn không?

README không nói riêng về bảo mật dữ liệu. Ralph chạy ngay trên máy bạn và gọi công cụ AI bạn đã chọn, nên mức độ an toàn phụ thuộc vào chính sách của Amp hoặc Claude Code. Hãy chạy trên nhánh riêng, trong repo có sao lưu.

Một story nên lớn cỡ nào?

Theo README, mỗi story phải đủ nhỏ để hoàn thành trong một cửa sổ ngữ cảnh. Ví dụ vừa sức: thêm cột database kèm migration, thêm ô lọc dropdown. Việc như xây cả dashboard hay thêm đăng nhập thì cần chia nhỏ.

Ralph dừng khi nào?

Ralph dừng khi mọi story trong prd.json có passes là true, hoặc khi chạm số lượt tối đa bạn đặt. Số lượt mặc định theo README là 10.

Chuyển nhanh tới mục

  1. I.Ralph làm được gì
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Cài công cụ nền
    2. B.Chép file Ralph vào dự án
    3. C.Cài skill prd và ralph
    4. D.Bật auto-handoff cho Amp (khuyến nghị)
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Dev thêm tính năng cho web app có sẵn
    2. B.Biến PRD thành danh sách việc cho máy
    3. C.Chạy qua đêm với giới hạn lượt
    4. D.Làm việc với giao diện (UI)
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Báo không có quyền chạy ralph.sh
    2. B.Báo không tìm thấy jq
    3. C.Chọn nhầm công cụ hoặc nhầm file prompt
    4. D.AI làm dở, code chất lượng thấp, hết lượt mà chưa xong
    5. E.Code hỏng lan sang các lượt sau
  7. VII.Có nên dùng không

Repo & Skill · 13/11/2026 · 11 phút đọc

Garden Skills: bộ skill thiết kế web, tạo ảnh, làm video cho AI — hướng dẫn cài đặt và dùng

Garden Skills là bộ sưu tập Agent Skills (kỹ năng cho AI) của tác giả ConardLi, dùng được với Claude Code, Cursor, Codex và các AI coding agent khác. Mỗi skill dạy agent làm tốt một việc như thiết kế trang web, tạo ảnh, làm video bằng code, biến tài liệu thành bài viết đẹp. Cài không khó, nhưng README có nhiều cách cài nên bạn cần chọn một cách hợp với công cụ đang dùng.

Repo & Skill · 13/11/2026 · 15 phút đọc

thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng

OpenUI là framework full-stack, độc lập framework, giúp mô hình AI sinh giao diện có cấu trúc và hiển thị dần khi dữ liệu streaming về. Bạn có thể dựng nhanh một ứng dụng chat bằng CLI hoặc cài từng gói cho React, Vue, Svelte, Angular và LangChain. Việc bắt đầu khá đơn giản nếu máy có đúng phiên bản Node; README chưa ghi đầy đủ lệnh chạy ứng dụng sau khi scaffold.

Repo & Skill · 13/11/2026 · 11 phút đọc

Ruflo: điều phối nhóm agent AI cho Claude Code và Codex — hướng dẫn cài đặt và dùng

Ruflo (trước đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.