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

snarktank/ralph: vòng lặp AI tự code đến khi xong PRD — hướng dẫn cài đặt và dùng

11 phút đọcCập nhật
snarktank/ralph: vòng lặp AI tự code đến khi xong PRD — hướng dẫn cài đặt và dùng

Tóm tắt nhanh

Ralph (snarktank/ralph) là một vòng lặp tự động chạy công cụ AI viết code (Amp hoặc Claude Code) nhiều lần, mỗi lần làm đúng một đầu việc trong file prd.json cho đến khi xong hết. Bạn dùng nó để giao cho AI một tính năng lớn đã được chia nhỏ rồi để máy tự làm từng phần. Cài không quá khó: copy vài file vào dự án, cài jq và có sẵn Amp hoặc Claude Code đã đă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 đúng một đầu việc nhỏ, cho tới khi mọi đầu việc trong danh sách đều xong. Về bản chất, đó là một script bash (ralph.sh) cộng với vài file prompt và hai skill hỗ trợ lập kế hoạch. Repo dựa trên ý tưởng "Ralph pattern" của Geoffrey Huntley.

Vấn đề nó giải quyết rất quen thuộc. Khi bạn bảo AI làm một tính năng lớn trong một phiên chat dài, ngữ cảnh đầy dần, AI quên mất đoạn đầu và code bắt đầu kém đi. Ralph tránh việc đó bằng cách chia tính năng thành nhiều đầu việc nhỏ, rồi mở một phiên AI mới, sạch ngữ cảnh, cho từng đầu việc. Trí nhớ giữa các phiên nằm trong lịch sử git, file progress.txt và file prd.json.

Bạn nên đọc bài này nếu bạn là lập trình viên (kể cả mới) đã quen dùng Claude Code hoặc Amp và muốn giao cho AI làm việc theo kiểu "chạy qua đêm". Điểm đáng giá nhất là quy trình rõ ràng: viết PRD, đổi sang JSON, chạy vòng lặp, rồi kiểm tra lại bằng git. Hiện repo có khoảng 22.223 sao và 2.115 fork, dùng giấy phép MIT. Repo cũng lâu rồi chưa cập nhật, bạn nên đọc kỹ README trước khi dùng.

Skill

snarktank/ralph

Ralph là vòng lặp bash gọi Amp hoặc Claude Code lặp lại, mỗi lần làm một user story trong prd.json, đến khi tất cả hoàn thành.

★ 22kTypeScriptMIT
Xem repo trên GitHub

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

A.Chạy lặp cho đến khi xong

Bạn chạy một lệnh, Ralph tự lặp. Mặc định tối đa 10 vòng, bạn có thể đổi con số này. Mỗi vòng, Ralph làm theo trình tự trong README: tạo nhánh tính năng từ branchName trong PRD, chọn đầu việc ưu tiên cao nhất còn passes: false, làm đúng một đầu việc đó, chạy kiểm tra chất lượng (typecheck, test), commit nếu qua, đánh dấu passes: true và ghi bài học vào progress.txt. Lợi ích thực tế: bạn không phải ngồi nhắc AI "làm tiếp đi" sau mỗi bước.

B.Mỗi vòng là một AI mới, sạch ngữ cảnh

Mỗi vòng sinh ra một phiên Amp hoặc Claude Code mới. Nhờ vậy AI không bị "đầy đầu" như phiên chat dài. Phần nhớ được truyền qua git, progress.txt và prd.json, nên vòng sau vẫn biết vòng trước đã làm gì.

C.Hai skill: viết PRD và đổi sang prd.json

Repo kèm hai skill. Skill prd hỏi bạn vài câu làm rõ rồi viết tài liệu yêu cầu sản phẩm (PRD) vào tasks/prd-[feature-name].md. Skill ralph đổi PRD đó thành prd.json, tức danh sách user story có trạng thái passes. Bạn không phải tự tay viết JSON.

D.Ghi bài học vào AGENTS.md

Sau mỗi vòng, Ralph cập nhật các file AGENTS.md liên quan với những gì nó học được (quy ước, bẫy hay gặp, vị trí các thành phần). Các công cụ AI tự đọc file này, nên vòng sau, và cả người đồng nghiệp sau này, đều hưởng lợi.

E.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 tự lưu lần chạy trước vào archive/YYYY-MM-DD-feature-name/. Bạn không lo mất dữ liệu cũ.

F.Có sơ đồ minh hoạ

Thư mục flowchart/ chứa một sơ đồ tương tác giải thích cách Ralph hoạt động, bạn có thể chạy trên máy mình.

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

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

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

README không nói về hệ điều hành cụ thể, chỉ cho lệnh cài jq trên macOS. Vì ralph.sh là script bash, trên Windows bạn thường sẽ cần một môi trường chạy bash như WSL hoặc Git Bash. Đây là suy luận của mình, README chưa xác nhận. README cũng không nói về chi phí; Amp và Claude Code có điều kiện sử dụng riêng của họ, bạn tự xem ở trang của từng công cụ.

Ralph chạy AI nhiều vòng liên tiếp, tự sửa file và tự commit trong dự án của bạn. Hãy chạy trên nhánh riêng, trong kho git đã commit sạch, và theo dõi mức dùng của tài khoản AI. Số vòng tối đa là cách đơn giản để giới hạn.

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

  1. Chuẩn bị công cụCài Amp CLI hoặc Claude Code, cài jq, có sẵn kho git
  2. Lấy mã RalphClone repo về máy
  3. Copy file vào dự ánĐưa ralph.sh và file prompt vào scripts/ralph
  4. Cài skillCopy skill prd và ralph vào thư mục cấu hình AI (hoặc dùng marketplace)
  5. Tạo prd.jsonDùng skill để viết PRD rồi đổi sang JSON

A.Chuẩn bị công cụ AI và jq

Nếu dùng Claude Code, cài bằng lệnh sau (cần Node.js và npm, README không nói rõ phiên bản):

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

Với Amp, bạn cài Amp CLI theo hướng dẫn ở trang của họ. Trên macOS, cài jq bằng:

Terminal
brew install jq

Sau đó nhớ đăng nhập công cụ AI bạn chọn. Người mới hay quên bước này, rồi vòng lặp chạy mà không có gì xảy ra.

B.Lấy mã nguồn Ralph

Mở terminal ở thư mục bạn muốn chứa repo, rồi chạy:

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

Bạn sẽ cần đường dẫn của thư mục này ở bước kế tiếp.

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

Mở terminal ở thư mục gốc của dự án (không phải thư mục ralph) rồi chạy. Thay /path/to/ralph bằng đường dẫn thật tới nơi bạn 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

Các lệnh trên tạo thư mục scripts/ralph, chép script vòng lặp 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) rồi cấp quyền chạy cho script. Chỉ chọn một trong hai dòng cp của prompt.

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

Nếu muốn dùng skill ở mọi dự án, chép chúng vào thư mục cấu hình. Chạy từ thư mục repo ralph đã clone. Với Amp:

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

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

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

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

Trong Claude Code, thêm marketplace rồi cài skill:

Terminal
/plugin marketplace add snarktank/ralph
Terminal
/plugin install ralph-skills@ralph-marketplace

Sau khi cài, bạn có hai lệnh /prd (tạo PRD) và /ralph (đổi PRD sang prd.json). Claude cũng tự kích hoạt skill khi bạn nói 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".

F.Bật tự chuyển phiên 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 }
}

Cài đặt này cho phép Amp tự chuyển phiên khi ngữ cảnh đầy, giúp Ralph xử lý được đầu việc lớn hơn một cửa sổ ngữ cảnh.

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

Cách kiểm tra nhanh là đi qua workflow một vòng nhỏ. Trước hết, mở công cụ AI của bạn và gõ câu sau để thử skill:

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

Nếu skill chạy, AI sẽ hỏi bạn vài câu làm rõ và lưu kết quả vào tasks/prd-[feature-name].md. Đó là dấu hiệu skill đã cài đúng.

Tiếp theo, đổi PRD sang JSON:

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

Bạn sẽ thấy file prd.json xuất hiện với các user story. Rồi chạy thử vòng lặp:

Terminal
# Using Amp (default)
./scripts/ralph/ralph.sh [max_iterations]

# Using Claude Code
./scripts/ralph/ralph.sh --tool claude [max_iterations]

Bạn biết nó chạy đúng khi có commit mới và trạng thái story đổi sang passes: true. Để xem, README gợi ý các lệnh sau:

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 đều passes: true, Ralph in ra dấu hiệu COMPLETE và vòng lặp dừng.

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

A.Dev làm một tính năng nhỏ cho ứng dụng có sẵn

Bối cảnh: bạn là lập trình viên đang giữ một ứng dụng web, cần thêm một ô lọc dạng dropdown cho danh sách. Việc này đúng cỡ "vừa một vòng" theo README.

Cách làm: nhờ skill prd viết PRD cho tính năng, trả lời các câu hỏi làm rõ, rồi nhờ skill ralph đổi sang prd.json. Sau đó chạy:

Terminal
./scripts/ralph/ralph.sh --tool claude 10

Kết quả: Ralph tạo nhánh mới, làm từng story, chạy typecheck và test, commit từng phần. Sáng hôm sau bạn xem git log --oneline -10 và duyệt lại như duyệt code của đồng nghiệp.

B.Chia một yêu cầu lớn thành các story nhỏ

Bối cảnh: sếp bảo "làm cho tôi cái trang quản lý đơn hàng". Nếu giao nguyên câu đó cho AI, kết quả thường kém. README nói rõ các việc kiểu "Build the entire dashboard" hay "Add authentication" là quá lớn, cần chia nhỏ.

Cách làm: khi viết PRD, bạn chủ động chia thành các việc như "thêm một cột vào cơ sở dữ liệu 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".

Mỗi đầu việc phải đủ nhỏ để xong trong một cửa sổ ngữ cảnh, nếu không AI sẽ hết chỗ nhớ trước khi làm xong.

Ông T

Kết quả: prd.json có nhiều story nhỏ, mỗi vòng Ralph xong một story và code ít bị lỗi dây chuyền.

C.Đội nhóm muốn AI "học" quy ước của dự án

Bối cảnh: nhóm của bạn có nhiều quy ước riêng, ví dụ lệnh kiểm tra chất lượng riêng hoặc vài điểm dễ sai. Bạn muốn AI nhớ chúng.

Cách làm: sau khi copy prompt.md hoặc CLAUDE.md vào dự án, sửa nó theo README gợi ý: thêm lệnh kiểm tra chất lượng của dự án, quy ước code, và các bẫy thường gặp của công nghệ bạn dùng. Ralph cũng tự ghi thêm bài học vào AGENTS.md sau mỗi vòng.

Kết quả: các vòng sau, và cả người mới vào nhóm, đọc AGENTS.md là nắm được những gì đã khám phá.

D.Story giao diện cần thử trên trình duyệt

Bối cảnh: bạn làm việc trên giao diện web và muốn AI tự kiểm tra bằng cách mở trang thật.

Cách làm: theo README, với story giao diện, hãy ghi vào tiêu chí chấp nhận câu "Verify in browser using dev-browser skill". Ralph sẽ dùng skill dev-browser để mở trang, thao tác và xác nhận thay đổi hoạt động. README không nêu cách cài skill dev-browser, bạn cần tự tìm nó riêng.

Kết quả: story giao diện được kiểm tra bằng thao tác thật chứ không chỉ bằng typecheck.

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

A.Lệnh jq không tìm thấy

Các lệnh debug trong README và script đều dựa vào jq. Nếu terminal báo không có jq, hãy cài nó (trên macOS: brew install jq) rồi mở terminal mới. README không nêu cách cài trên hệ điều hành khác, bạn xem hướng dẫn chính thức của jq.

B.Chạy script bị từ chối quyền

Nếu gặp lỗi kiểu "permission denied", rất có thể bạn chưa chạy bước cấp quyền. Chạy lại:

Terminal
chmod +x scripts/ralph/ralph.sh

Và nhớ chạy lệnh từ thư mục gốc của dự án, nơi có thư mục scripts/ralph.

C.AI chạy hết vòng mà story chưa xong, code kém

Nguyên nhân hay gặp nhất là story quá to. README nói rõ: nếu việc quá lớn, AI hết ngữ cảnh trước khi làm xong và ra code kém. Cách xử lý: mở prd.json, tách story đó thành các story nhỏ hơn rồi chạy lại. Bạn cũng có thể kiểm tra progress.txt để xem Ralph vướng ở đâu.

D.Code hỏng làm các vòng sau hỏng theo

Ralph chỉ hoạt động tốt khi có "vòng phản hồi": typecheck, test và CI phải xanh, vì code lỗi sẽ tích tụ qua các vòng. Nếu dự án chưa có test hay typecheck, hãy bổ sung trước. Nếu đã lỡ hỏng, xem git log --oneline -10 để biết vòng nào gây ra rồi quay lại commit tốt bằng cách bạn quen dùng.

E.Dùng sai công cụ so với file prompt

Nếu chạy bằng Claude Code mà quên thêm --tool claude, script sẽ dùng Amp mặc định. Hãy kiểm tra bạn đã copy đúng file prompt (prompt.md cho Amp, CLAUDE.md cho Claude Code) và dùng đúng cờ --tool.

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

Điểm mạnh: cách làm rất gọn (một script bash cộng prompt), dễ đọc và dễ chỉnh. Mỗi vòng là một phiên sạch nên tránh được tình trạng ngữ cảnh đầy. Mọi thứ để lại dấu vết trong git, progress.txt và prd.json, nên bạn kiểm tra lại được. Giấy phép MIT, và có sẵn sơ đồ để hiểu cách hoạt động.

Giới hạn: Ralph chỉ tốt khi bạn chia việc nhỏ và có test, typecheck, CI để làm phản hồi. Nó cần Amp hoặc Claude Code đã đăng nhập, cùng jq. Cách làm hướng tới người đã quen terminal và git, README không có hướng dẫn riêng cho Windows. Repo lâu rồi chưa cập nhật, nên nếu công cụ AI bạn dùng đã đổi cách hoạt động, bạn có thể phải tự chỉnh.

Khi nào chọn cách khác: nếu bạn chỉ cần sửa một lỗi nhỏ hay hỏi đáp nhanh, mở thẳng Claude Code hoặc Amp là đủ, không cần dựng PRD. Nếu dự án chưa có test và bạn không muốn bổ sung, giao cho một vòng lặp tự động sẽ khá rủi ro. Còn nếu bạn muốn thử nghiệm quy trình "giao việc rồi đi ngủ" trên một tính năng vừa phải, trong một nhánh riêng, Ralph là một điểm bắt đầu dễ hiểu.

4.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. Tuy nhiên Ralph gọi Amp hoặc Claude Code, nên chi phí phụ thuộc vào điều kiện sử dụng của các công cụ đó. README không nói gì về giá, bạn xem ở trang của từng công cụ.

Ralph cần công cụ AI nào?

README liệt kê hai lựa chọn: Amp CLI (mặc định) hoặc Claude Code. Bạn phải cài và đăng nhập một trong hai trước khi chạy. Chọn công cụ bằng cờ `--tool amp` hoặc `--tool claude`.

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

README chưa nói rõ về Windows, chỉ có lệnh cài jq cho macOS. Vì `ralph.sh` là script bash, thường bạn sẽ cần môi trường bash như WSL hoặc Git Bash. Đây là suy luận, chưa có xác nhận trong tư liệu.

Ralph có cần GPU không?

Tư liệu không nhắc đến GPU hay yêu cầu phần cứng nào. Ralph chỉ là vòng lặp gọi công cụ AI bạn đã cài, nên phần xử lý nặng do công cụ đó đảm nhiệm.

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

Mỗi vòng là một phiên AI mới với ngữ cảnh sạch. Trí nhớ giữa các vòng nằm ở lịch sử git, file `progress.txt` và file `prd.json`. Ralph còn cập nhật các file `AGENTS.md` với bài học để vòng sau dùng lại.

Một đầu việc nên lớn cỡ nào?

Đủ nhỏ để xong trong một cửa sổ ngữ cảnh. README lấy ví dụ: thêm cột cơ sở dữ liệu kèm migration, thêm một thành phần giao diện, thêm dropdown lọc. Những việc như "Build the entire dashboard" hay "Add authentication" thì nên được chia nhỏ.

Ralph khác gì việc cứ chat với Claude Code?

Chat thường chạy trong một phiên dài nên ngữ cảnh đầy dần. Ralph chia việc thành nhiều story nhỏ và mở phiên mới cho từng story, tự lặp cho đến khi xong hoặc hết số vòng tối đa. Về chất lượng so sánh trực tiếp, tư liệu chưa có thông tin.

Chuyển nhanh tới mục

  1. I.Ralph làm được gì
    1. A.Chạy lặp cho đến khi xong
    2. B.Mỗi vòng là một AI mới, sạch ngữ cảnh
    3. C.Hai skill: viết PRD và đổi sang prd.json
    4. D.Ghi bài học vào AGENTS.md
    5. E.Tự lưu trữ lần chạy cũ
    6. F.Có sơ đồ minh hoạ
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Chuẩn bị công cụ AI và jq
    2. B.Lấy mã nguồn Ralph
    3. C.Cách 1: Copy file vào dự án
    4. D.Cách 2: Cài skill dùng chung cho mọi dự án
    5. E.Cách 3: Dùng marketplace của Claude Code
    6. F.Bật tự chuyển phiên 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 làm một tính năng nhỏ cho ứng dụng có sẵn
    2. B.Chia một yêu cầu lớn thành các story nhỏ
    3. C.Đội nhóm muốn AI "học" quy ước của dự án
    4. D.Story giao diện cần thử trên trình duyệt
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Lệnh jq không tìm thấy
    2. B.Chạy script bị từ chối quyền
    3. C.AI chạy hết vòng mà story chưa xong, code kém
    4. D.Code hỏng làm các vòng sau hỏng theo
    5. E.Dùng sai công cụ so với file prompt
  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ỏ.