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

Ralph: vòng lặp AI tự code xong cả PRD — 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 →

Ralph: vòng lặp AI tự code xong cả PRD — hướng dẫn cài đặt và dùng

Tóm tắt nhanh

Ralph (snarktank/ralph) là bộ script bash cùng hai skill giúp AI lập trình (Amp hoặc Claude Code) tự làm lần lượt từng mục trong danh sách yêu cầu, mỗi lượt một phiên sạch bộ nhớ. Bạn viết PRD, chuyển thành prd.json rồi chạy ralph.sh để nó tự code, kiểm tra và commit. Cài khá nhẹ vì chỉ copy file, nhưng cần sẵn một công cụ AI đã đăng nhập, jq và một repo git.

Ralph là một vòng lặp tự động: nó gọi công cụ AI lập trình (Amp hoặc Claude Code) hết lần này đến lần khác, mỗi lần làm đúng một mục trong danh sách yêu cầu (PRD), cho đến khi mọi mục đều xong. Repo gồm một script bash ralph.sh, hai file prompt mẫu và hai skill để viết PRD rồi đổi sang định dạng Ralph đọc được.

Vấn đề Ralph 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 đầu", quên đoạn trước và sinh ra code ngày càng tệ. Ralph tránh chuyện này bằng cách chia nhỏ việc ra, rồi mỗi lượt mở một phiên AI hoàn toàn mới với ngữ cảnh sạch. Trí nhớ giữa các lượt không nằm trong đầu AI mà nằm trong lịch sử git, file progress.txt và file prd.json.

Ai nên dùng? Lập trình viên (kể cả người mới) đã quen chat với AI để viết code và muốn nó tự chạy qua một danh sách việc nhỏ trong lúc mình đi làm việc khác. Điểm đáng giá nhất là cách làm gọn: không cần framework phức tạp, chỉ vài file copy vào dự án. Repo hiện có khoảng 22.223 sao và 2.115 fork, giấy phép MIT. Ý tưởng gốc dựa trên "Ralph pattern" của Geoffrey Huntley.

Skill

snarktank/ralph

Ralph là vòng lặp tự động gọi Amp hoặc Claude Code, làm từng user story trong prd.json cho đến khi xong hết, mỗi lượt dùng một phiên AI mới.

★ 22kTypeScriptMIT
Xem repo trên GitHub

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

  • Chạy lặp đến khi xong. Bạn chạy một lệnh, Ralph tự lặp. Mỗi lượt nó chọn mục ưu tiên cao nhất còn passes: false, làm đúng mục đó rồi chuyển sang mục tiếp. Bạn không phải ngồi nhắc AI "làm tiếp đi".
  • Mỗi lượt một phiên AI mới. Ngữ cảnh luôn sạch nên AI ít bị rối khi dự án dài. Đổi lại, mọi thứ cần nhớ phải được ghi ra file hoặc commit.
  • Tự kiểm tra trước khi commit. Sau khi code xong một mục, Ralph chạy kiểm tra chất lượng (typecheck, test). Chỉ khi qua thì mới commit và đánh dấu mục đó passes: true.
  • Ghi lại bài học. Sau mỗi lượt, nó ghi thêm vào progress.txt và cập nhật các file AGENTS.md liên quan. Các công cụ AI tự đọc AGENTS.md, nên lượt sau (và cả đồng nghiệp của bạn) được hưởng lợi từ những điều đã khám phá.
  • Hai skill đi kèm. Skill prd giúp bạn tạo tài liệu yêu cầu bằng cách hỏi lại vài câu làm rõ. Skill ralph đổi tài liệu đó thành prd.json, tức danh sách user story có trạng thái.
  • Kiểm tra giao diện bằng trình duyệt. Với việc về giao diện, README yêu cầu ghi trong tiêu chí nghiệm thu câu "Verify in browser using dev-browser skill". Khi đó Ralph dùng skill dev-browser để mở trang, thao tác và xác nhận thay đổi hoạt động.
  • Tự lưu trữ lần chạy cũ. Khi bạn bắt đầu tính năng mới (branchName khác), Ralph lưu lần chạy trước vào archive/YYYY-MM-DD-feature-name/.
  • Có sơ đồ tương tác. Thư mục flowchart/ chứa sơ đồ động giải thích từng bước của vòng lặp.

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

Theo README, bạn cần ba thứ:

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

README không nêu yêu cầu về phiên bản Node hay Python, cũng không nói gì riêng về Windows. Vì ralph.sh là script bash, bạn cần một môi trường chạy được bash. Chi phí dùng Amp hoặc Claude Code do chính các dịch vụ đó quyết định, README không đề cập.

Ralph tự chạy nhiều lượt liên tiếp và tự commit code. Hãy chạy trên một nhánh riêng, trong repo đã commit sạch, và đặt số lượt tối đa vừa phải. Mỗi lượt gọi công cụ AI của bạn nên có thể tốn quota hoặc tiền, tuỳ gói bạn đang dùng.

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

README có ba cách cài. Cách 1 (copy vào dự án) là cách cần thiết để chạy vòng lặp. Hai cách còn lại chủ yếu để có sẵn skill prd và ralph.

  1. Chuẩn bị công cụCài Amp hoặc Claude Code, đăng nhập, cài jq, có sẵn repo git
  2. Tải Ralph vềgit clone repo snarktank/ralph về một thư mục riêng
  3. Copy file vào dự ánChép ralph.sh và file prompt vào scripts/ralph/ trong dự án
  4. Cài skillChép skills/prd và skills/ralph, hoặc dùng marketplace của Claude Code
  5. Cấu hình Amp (nếu dùng Amp)Bật auto-handoff trong settings.json

A.Tải Ralph về máy

Mở terminal ở nơi bạn muốn lưu bản tải về (không phải trong dự án của bạn) rồi chạy:

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

Lệnh này tạo thư mục ralph chứa toàn bộ file mẫu. Ở các lệnh dưới, /path/to/ralph chính là đường dẫn tới thư mục này.

B.Cách 1: copy file vào dự án

Mở terminal ở thư mục gốc dự án của bạn (nơi có thư mục .git). Người mới hay vấp ở chỗ này: nếu đứng nhầm thư mục, file sẽ chép sai chỗ.

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

Các lệnh trên làm bốn việc: tạo thư mục scripts/ralph, chép script chính vào đó, chép file prompt đúng với công cụ bạn dùng (prompt.md cho Amp, CLAUDE.md cho Claude Code) và cấp quyền chạy cho script. Bạn chỉ cần chọn một trong hai dòng cp của file prompt, rồi thay /path/to/ralph bằng đường dẫn thật.

C.Cách 2: cài skill dùng chung cho mọi dự án

Nếu muốn skill prd và ralph dùng được ở mọi dự án, chép vào thư mục cấu hình. Với Amp:

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

Với Claude Code (cài thủ công):

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

Hãy chạy các lệnh này khi đang đứng trong thư mục ralph bạn vừa clone, vì đường dẫn skills/... là đường dẫn tương đối.

D.Cách 3: dùng marketplace của Claude Code

Nếu bạn dùng Claude Code, có thể không cần chép tay. Trong Claude Code, gõ:

Terminal
/plugin marketplace add snarktank/ralph

Sau đó cài bộ skill:

Terminal
/plugin install ralph-skills@ralph-marketplace

Cài xong sẽ có hai lệnh: /prd (tạo tài liệu yêu cầu) và /ralph (đổi PRD sang prd.json). Skill cũng tự được gọi khi bạn nhờ Claude những câu như "create a prd", "write prd for", "plan this feature", "convert this prd", "turn into ralph format" hay "create prd.json".

E.Bật auto-handoff cho Amp (README khuyên dùng)

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

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

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

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

README không có lệnh "kiểm tra cài đặt" riêng. Bạn có thể tự soát bằng ba dấu hiệu dựa trên những gì README mô tả:

  • Trong dự án có scripts/ralph/ralph.sh cùng file prompt (prompt.md hoặc CLAUDE.md).
  • Với Claude Code qua marketplace, gõ / sẽ thấy /prd và /ralph.
  • Sau khi tạo prd.json và chạy Ralph, bạn xem được tiến độ bằng các lệnh trong phần Debugging 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

Lệnh đầu liệt kê từng story kèm trạng thái passes. Lệnh thứ hai đọc những gì AI đã ghi lại. Lệnh thứ ba cho thấy các commit Ralph vừa tạo. Nếu có commit mới và có story chuyển sang passes: true, vòng lặp đang chạy đúng. Khi tất cả story đều passes: true, Ralph in ra dấu hiệu COMPLETE và dừng.

Bạn cũng có thể xem sơ đồ chạy thử trong thư mục flowchart/:

Terminal
cd flowchart
npm install
npm run dev

Đây chỉ là phần minh hoạ, không bắt buộc để Ralph hoạt động.

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

Quy trình chung gồm ba bước: viết PRD, đổi sang JSON, chạy Ralph. Bạn thay đổi nội dung theo dự án của mình.

A.Tình huống 1: lập trình viên thêm tính năng lọc cho một trang danh sách

Bạn đang làm một ứng dụng và muốn thêm bộ lọc cho trang danh sách. Trước hết nhờ skill viết PRD:

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

Skill sẽ hỏi lại vài câu làm rõ, bạn trả lời xong thì nó lưu tài liệu vào tasks/prd-[feature-name].md. Tiếp theo đổi sang định dạng của Ralph:

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

Cuối cùng chạy vòng lặp:

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

Kết quả: Ralph tạo nhánh từ branchName trong PRD, làm từng story, chạy typecheck và test, commit khi qua. Bạn quay lại sau và xem git log để duyệt từng commit.

B.Tình huống 2: dùng Claude Code thay vì Amp

Bạn đã có Claude Code và không dùng Amp. Hãy chắc là đã chép CLAUDE.md vào scripts/ralph/, rồi chạy kèm cờ --tool:

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

Mặc định là 10 lượt. Nếu PRD có 4 story nhỏ, 10 lượt thường là đủ chỗ cho cả việc làm lại khi kiểm tra chưa qua. Nếu story nhiều hơn, bạn tăng số lượt.

Ralph chỉ chạy tốt khi mỗi việc đủ nhỏ để AI làm xong trong một lượt và có test để biết nó làm đúng hay sai.

Ông T

C.Tình huống 3: tách một việc quá to thành các story vừa sức

Bạn viết yêu cầu "Thêm đăng nhập cho cả hệ thống". README cảnh báo kiểu việc này quá lớn: các mục như "Add authentication", "Build the entire dashboard" hay "Refactor the API" cần được chia nhỏ. Ví dụ story vừa sức theo README là thêm một cột vào database kèm migration, thêm một thành phần giao diện vào trang có sẵn, cập nhật một server action với logic mới, hoặc thêm một dropdown lọc vào danh sách. Hãy chỉnh PRD cho đến khi mỗi story nhỏ cỡ đó trước khi chuyển sang prd.json. Làm vậy bạn tránh được tình trạng AI hết ngữ cảnh giữa chừng và viết code kém.

D.Tình huống 4: tuỳ biến prompt cho dự án của bạn

Sau khi chép prompt.md hoặc CLAUDE.md vào dự án, bạn nên sửa nó cho khớp với dự án. README gợi ý ba việc: thêm lệnh kiểm tra chất lượng riêng của dự án, ghi các quy ước trong mã nguồn, và nêu những lỗi hay gặp của công nghệ bạn dùng. Ví dụ nếu đội bạn có lệnh lint riêng, hãy ghi vào để Ralph chạy nó trước khi commit. Prompt càng sát dự án thì các lượt sau càng ít phải đoán.

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

Chạy ./scripts/ralph/ralph.sh báo không có quyền hoặc không tìm thấy lệnh. Thường là do chưa chạy chmod +x scripts/ralph/ralph.sh, hoặc bạn đang đứng sai thư mục. Hãy mở terminal ở thư mục gốc dự án rồi chạy lại.

Lệnh jq báo không tìm thấy. README yêu cầu cài jq, và ghi lệnh brew install jq cho macOS. Với hệ điều hành khác, bạn cần tự cài jq theo hướng dẫn chính thức của nó.

Ralph chạy hết số lượt mà story vẫn chưa xong. Nhiều khả năng story quá to nên AI hết ngữ cảnh trước khi làm xong, hoặc kiểm tra chất lượng không qua. Hãy xem progress.txt và git log, sau đó tách story nhỏ hơn trong prd.json. Nếu dùng Amp, hãy kiểm tra thêm cấu hình auto-handoff ở trên.

Code sai lan sang các lượt sau. README nhấn mạnh Ralph cần "feedback loop": typecheck, test và CI phải xanh, vì code hỏng sẽ tích tụ qua các lượt. Nếu dự án chưa có test hay typecheck, hãy bổ sung trước khi giao cho Ralph chạy dài.

Không thấy lệnh /prd hay /ralph. Có thể skill chưa vào đúng thư mục hoặc chưa cài qua marketplace. Kiểm tra lại các lệnh cp -r skills/... (phải chạy trong thư mục ralph) hoặc chạy lại hai lệnh /plugin ở trên, rồi mở lại phiên Claude Code.

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

Điểm mạnh của Ralph là sự đơn giản và cách tiếp cận rõ ràng. Bạn chỉ copy vài file, mỗi lượt AI có ngữ cảnh sạch, tiến độ nằm trong prd.json và git nên dễ kiểm tra, và các bài học được ghi vào AGENTS.md để dùng lại. Giấy phép MIT, dùng được cho dự án cá nhân lẫn công việc.

Giới hạn cũng cần nói thẳng. Ralph không thay bạn nghĩ về yêu cầu: PRD mơ hồ hoặc story quá to thì kết quả sẽ kém. Nó phụ thuộc vào việc dự án có sẵn test và typecheck. Nó cần công cụ AI bên ngoài (Amp hoặc Claude Code) đã đăng nhập, nên chi phí và quota theo các dịch vụ đó. README không nói về Windows, và repo đã lâu chưa cập nhật, nên bạn nên tự thử trên một dự án nhỏ trước.

Nếu bạn chỉ cần AI sửa một lỗi nhỏ hay viết một đoạn code, cứ chat trực tiếp với công cụ AI là nhanh hơn. Nếu bạn là người không viết code, Ralph chưa phải công cụ cho bạn. 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 AI tự làm từng việc một trong lúc bạn đi làm việc khác, Ralph rất đáng thử.

3.9/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 tự do. Tuy nhiên Ralph gọi Amp hoặc Claude Code, nên chi phí phụ thuộc vào gói của các dịch vụ đó. README không nói chi tiết về giá.

Ralph có cần GPU không?

README không yêu cầu GPU hay cấu hình phần cứng nào. Ralph chỉ là script bash gọi công cụ AI, nên phần xử lý nặng do dịch vụ AI đảm nhận.

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

README chưa có thông tin riêng về Windows. ralph.sh là script bash và cần jq, nên bạn cần môi trường chạy được bash. Hãy thử trên một dự án nhỏ trước khi dùng thật.

Dùng Amp hay Claude Code cũng được à?

Được cả hai. Amp là mặc định. Muốn dùng Claude Code thì chạy ralph.sh với cờ --tool claude và chép file CLAUDE.md vào scripts/ralph/. Còn nếu dùng Amp thì chép prompt.md.

Ralph nhớ việc đã làm bằng cách nào?

Mỗi lượt là một phiên AI mới nên không giữ trí nhớ trong đầu. Thông tin được lưu qua lịch sử git, file progress.txt và file prd.json, ngoài ra các file AGENTS.md cũng được cập nhật.

Mỗi story nên lớn cỡ nào?

Đủ nhỏ để làm xong trong một cửa sổ ngữ cảnh, ví dụ thêm một cột database kèm migration hay thêm một dropdown lọc. Những việc như xây cả dashboard hay thêm toàn bộ hệ thống đăng nhập cần được chia nhỏ.

Khi nào Ralph dừng?

Ralph dừng khi mọi story trong prd.json đều có passes: true (nó in ra dấu hiệu COMPLETE) hoặc khi chạm số lượt tối đa. Mặc định là 10 lượt, bạn đổi bằng tham số max_iterations.

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.Tải Ralph về máy
    2. B.Cách 1: copy file vào dự án
    3. C.Cách 2: cài skill dùng chung cho mọi dự án
    4. D.Cách 3: dùng marketplace của Claude Code
    5. E.Bật auto-handoff cho Amp (README khuyên dùng)
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Tình huống 1: lập trình viên thêm tính năng lọc cho một trang danh sách
    2. B.Tình huống 2: dùng Claude Code thay vì Amp
    3. C.Tình huống 3: tách một việc quá to thành các story vừa sức
    4. D.Tình huống 4: tuỳ biến prompt cho dự án của bạn
  6. VI.Lỗi hay gặp và cách xử lý
  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ỏ.