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

> 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.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-05-13 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/snarktank-ralph-vong-lap-ai-tu-code-den-khi-xong-prd

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.

```repo
- repo | snarktank/ralph
- kind | Skill
- desc | 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.
- stars | 22k
- lang | TypeScript
- license | MIT
```

## Ralph làm được gì

### 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.

### 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ì.

### 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.

### 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.

### 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ũ.

### 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.

## 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ụ.

```note
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.
```

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

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

### 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):

```bash
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:

```bash
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.

### Lấy mã nguồn Ralph

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

```bash
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á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:

```bash
# 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.

### 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:

```bash
cp -r skills/prd ~/.config/amp/skills/
cp -r skills/ralph ~/.config/amp/skills/
```

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

```bash
cp -r skills/prd ~/.claude/skills/
cp -r skills/ralph ~/.claude/skills/
```

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

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

```bash
/plugin marketplace add snarktank/ralph
```

```bash
/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".

### 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.

## 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:

```
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:

```
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:

```bash
# 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:

```bash
# 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.

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

### 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:

```bash
./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.

### 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.

### Độ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á.

### 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.

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

### 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`.

### 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:

```bash
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`.

### 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.

### 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.

### 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`.

## 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.

## 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.
