# 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

> Ralph là một vòng lặp bash chạy công cụ AI viết code (Amp hoặc Claude Code) liên tục, mỗi vòng làm đúng một việc nhỏ trong file prd.json cho đến khi xong hết. Repo kèm hai skill: một để viết PRD, một để đổi PRD sang prd.json. Cài không khó nếu bạn đã quen terminal, nhưng cần sẵn Amp hoặc Claude Code, jq và một repo git.

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

Ralph là một đoạn script bash nhỏ, bắt công cụ AI viết code (Amp hoặc Claude Code) làm việc lặp đi lặp lại cho đến khi xong cả danh sách yêu cầu sản phẩm (PRD). Mỗi vòng lặp, Ralph gọi một phiên AI mới tinh, giao đúng một việc nhỏ, chạy kiểm tra, commit nếu đạt, rồi sang việc kế tiếp.

Vấn đề nó giải quyết rất quen thuộc: khi bạn nhờ AI làm một tính năng lớn trong một cuộc trò chuyện dài, AI dần "quên", context đầy và code bắt đầu tệ đi. Ralph né chuyện này bằng cách chia nhỏ việc và cho mỗi việc một phiên AI sạch. Trí nhớ giữa các vòng không nằm trong đầu AI mà nằm 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ả người mới) đã có dự án git và muốn giao AI làm cả loạt việc nhỏ trong lúc mình đi làm việc khác. Điểm đáng giá nhất là sự đơn giản: cốt lõi chỉ là một script bash cộng vài file prompt. Repo hiện có khoảng 22.224 sao và 2.116 fork, giấy phép MIT. Tác giả dựa trên ý tưởng "Ralph pattern" của Geoffrey Huntley.

```repo
- repo | snarktank/ralph
- kind | Skill
- desc | Ralph chạy Amp hoặc Claude Code lặp đi lặp lại, mỗi vòng làm xong một user story trong prd.json cho đến khi cả danh sách hoàn thành.
- stars | 22k
- lang | TypeScript
- license | MIT
```

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

### Chạy AI lặp lại đến khi xong việc

Script `ralph.sh` lặp tối đa số vòng bạn đặt (mặc định 10). Mỗi vòng, Ralph chọn story ưu tiên cao nhất còn `passes: false`, làm xong thì đánh dấu `passes: true`. Bạn không phải ngồi nhắc AI từng bước.

### Mỗi vòng là một phiên AI mới

Vì context luôn sạch, AI không bị "nặng đầu" sau nhiều giờ làm việc. Đổi lại, nó chỉ biết những gì được ghi lại: các commit trước, `progress.txt` và `prd.json`. Bạn có thể mở ba nơi này ra đọc bất cứ lúc nào để biết AI đã làm gì.

### Hai skill đi kèm

Repo có skill `prd` để AI hỏi bạn vài câu rồi viết tài liệu yêu cầu, và skill `ralph` để đổi tài liệu đó thành `prd.json` có cấu trúc cho vòng lặp đọc. Nhờ vậy bạn không phải tự viết JSON bằng tay.

### Tự 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 điều học được (quy ước của codebase, chỗ dễ sai). Công cụ AI tự đọc các file này nên vòng sau, và cả lập trình viên người thật, đều hưởng lợi.

### Chạy được với hai công cụ

Mặc định là Amp. Muốn dùng Claude Code thì thêm `--tool claude`. Mỗi công cụ có một file prompt riêng: `prompt.md` cho Amp, `CLAUDE.md` cho Claude Code.

### 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ự đưa lần chạy trước vào thư mục `archive/`, nên không bị lẫn dữ liệu cũ.

## Cần chuẩn bị gì

Theo README, bạn cần:

- Một trong hai công cụ AI viết code đã cài và đăng nhập sẵn: 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 repo git cho dự án của bạn.

README không nói gì về hệ điều hành, phiên bản Node hay phần cứng. Lưu ý Ralph là script bash, nên nếu bạn dùng Windows thì README chưa hướng dẫn; bạn cần một môi trường chạy được bash. Bạn cũng cần tài khoản/quyền dùng Amp hoặc Claude Code, và chi phí sử dụng do bên đó tính, README không nêu con số.

```note
Ralph để AI tự chạy nhiều vòng liên tiếp mà không có người duyệt từng bước, nên mỗi vòng đều tốn lượt dùng (và có thể tốn tiền) ở Amp hoặc Claude Code. Hãy bắt đầu với số vòng nhỏ và chạy trên nhánh git riêng. README cũng nhấn mạnh code hỏng sẽ "cộng dồn" qua các vòng nếu CI không xanh.
```

## 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 để cài skill dùng chung.

```steps
- Lấy repo về | Tải ralph về máy bằng git clone
- Chép file vào dự án | Đưa ralph.sh và file prompt vào scripts/ralph/
- Cài skill (tuỳ chọn) | Chép skills/prd và skills/ralph vào thư mục cấu hình, hoặc dùng marketplace của Claude Code
- Bật auto-handoff cho Amp (khuyến nghị) | Thêm một dòng cấu hình vào settings.json của Amp
```

### Lấy repo về máy

Mở terminal ở thư mục nào đó bạn thích (không phải thư mục dự án), rồi tải ralph về:

```bash
git clone https://github.com/snarktank/ralph.git
cd ralph
```

Lệnh đầu tải mã nguồn về, lệnh sau đi vào thư mục vừa tải. Bạn sẽ chép file từ đây sang dự án của mình.

### Cách 1: chép Ralph vào dự án

Mở terminal ở thư mục gốc của dự án (nơi có thư mục `.git`). Dòng chú thích trong README là "From your project root", đây là chỗ người mới hay vấp: nếu đứng sai thư mục, file sẽ chép nhầm chỗ. Thay `/path/to/ralph` bằng đường dẫn tới thư mục ralph bạn vừa tải:

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

Lệnh `mkdir -p` tạo thư mục `scripts/ralph`. Hai lệnh `cp` chép script và file prompt. Chỉ chọn một trong hai dòng prompt tuỳ bạn dùng Amp hay Claude Code. Dòng `chmod +x` cho phép script được chạy.

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

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

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

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

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

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

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

Trong Claude Code, thêm marketplace của Ralph:

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

Rồi cài skill:

```bash
/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 sản phẩm và `/ralph` để đổi PRD sang định dạng `prd.json`. Hai lệnh này gõ trong khung chat của Claude Code, không phải trong terminal thường.

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

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

```json
{
  "amp.experimental.autoHandoff": { "context": 90 }
}
```

Cài đặt này cho phép Amp tự bàn giao khi context đầy, giúp Ralph xử lý được story lớn hơn một cửa sổ context. Nếu file đã có nội dung khác, hãy thêm dòng này vào chứ đừng xoá phần cũ.

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

README không có lệnh "kiểm tra cài đặt" riêng, nhưng có vài cách để biết mọi thứ ổn:

- Skill: sau khi cài, hỏi Claude "create a prd" hoặc gõ `/prd`. Nếu skill nhận ra yêu cầu và bắt đầu hỏi bạn các câu làm rõ, vậy là skill đã hoạt động.
- Vòng lặp: chạy `./scripts/ralph/ralph.sh` với số vòng nhỏ rồi xem trạng thái bằng các lệnh debug của README:

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

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

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

### Thêm tính năng cho web app của dự án nhỏ

Bạn là lập trình viên tự do, có một web app và muốn thêm bộ lọc cho danh sách đơn hàng. Bước đầu, trong Amp hoặc Claude Code, bạn gõ:

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

Trả lời các câu hỏi làm rõ, skill sẽ lưu tài liệu vào `tasks/prd-[feature-name].md`. Sau đó đổi sang JSON:

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

Kết quả là file `prd.json` gồm các user story. Bạn đọc lại, sửa nếu thấy story nào quá to, rồi chạy `./scripts/ralph/ralph.sh --tool claude 10`.

### Chia nhỏ việc "quá to" trước khi giao

Bạn muốn "làm toàn bộ dashboard". README nói rõ đây là kiểu việc phải chia nhỏ, vì AI hết context trước khi xong và code sẽ kém. Hãy tách thành các story cỡ vừa như README gợi ý: thêm một cột database kèm migration, thêm một component vào trang có sẵn, cập nhật một server action, thêm một dropdown lọc vào danh sách. Mỗi story đủ nhỏ để một phiên AI làm trọn.

> Ralph chỉ chạy tốt khi mỗi việc đủ nhỏ để làm xong trong một lần và có kiểm tra tự động bắt lỗi.
>
> — Ông T

### Để AI chạy trong lúc bạn làm việc khác

Bạn có sẵn một repo có typecheck và test. Bạn viết PRD buổi chiều, chạy Ralph rồi đi họp. Mỗi vòng AI làm một story, chạy typecheck và test, chỉ commit khi qua. Quay lại, bạn xem `git log --oneline -10` và `progress.txt` để biết AI đã làm gì, rồi duyệt code như duyệt pull request bình thường. Vì phụ thuộc vào kiểm tra tự động, README coi "feedback loop" là điều kiện bắt buộc để Ralph hoạt động.

### Làm việc với giao diện web

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 và xác nhận thay đổi hoạt động. Lưu ý đây là skill riêng, README không hướng dẫn cài nó trong repo này, nên bạn cần tự tìm cách có skill đó trong công cụ của mình.

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

### Lệnh chạy báo thiếu jq hoặc không tìm thấy lệnh

Ralph cần `jq`. Nếu chưa cài, các lệnh đọc `prd.json` sẽ lỗi. Trên macOS README dùng `brew install jq`; hệ điều hành khác bạn cài jq theo cách của hệ đó. Sau khi cài, mở terminal mới rồi chạy lại.

### Permission denied khi chạy ralph.sh

Thường do chưa cấp quyền chạy. Chạy lại lệnh `chmod +x scripts/ralph/ralph.sh` trong thư mục gốc dự án rồi gọi lại `./scripts/ralph/ralph.sh`.

### AI chạy hết số vòng mà vẫn chưa xong

Có hai nguyên nhân hay gặp: story quá to nên AI hết context, hoặc số vòng quá ít (mặc định chỉ 10). Hãy mở `prd.json`, tách story to thành nhiều story nhỏ, rồi chạy lại. Có thể tăng số vòng bằng tham số `[max_iterations]` nhưng nên chia nhỏ việc trước.

### Code hỏng cộng dồn qua các vòng

Nếu typecheck hoặc test đang đỏ, lỗi của vòng này truyền sang vòng sau. README nói CI phải luôn xanh. Dừng vòng lặp, quay lại commit tốt gần nhất bằng git, sửa test hoặc cấu hình kiểm tra rồi chạy tiếp. Hãy luôn để Ralph làm trên nhánh riêng để dễ bỏ đi.

### Dùng nhầm file prompt cho công cụ

`prompt.md` dành cho Amp còn `CLAUDE.md` dành cho Claude Code. Nếu bạn dùng Claude Code mà chỉ chép `prompt.md` (hoặc ngược lại), vòng lặp sẽ không có đúng chỉ dẫn. Kiểm tra thư mục `scripts/ralph/` xem đã có đúng file chưa, và nhớ thêm `--tool claude` khi dùng Claude Code.

## Có nên dùng không

Điểm mạnh: ý tưởng gọn, dễ hiểu, ít thành phần (một script bash, vài file prompt, hai skill). Mọi trạng thái nằm trong file và git nên bạn dễ kiểm tra, dễ dừng, dễ sửa. Giấy phép MIT, và việc ghi bài học vào `AGENTS.md` giúp dự án "khôn dần" theo thời gian.

Giới hạn cần biết: Ralph không thay thế việc suy nghĩ. Chất lượng phụ thuộc hoàn toàn vào việc bạn chia story nhỏ và có typecheck, test để bắt lỗi. Nếu dự án chưa có test, kết quả khó tin cậy. README chỉ nói đến Amp và Claude Code, và không hướng dẫn riêng cho Windows. Repo cũng lâu rồi chưa được cập nhật, nên bạn nên đọc kỹ prompt trước khi dùng và chuẩn bị tự chỉnh cho hợp dự án.

Nếu bạn chỉ cần AI sửa một lỗi nhỏ hay hỏi đáp về code, cứ dùng thẳng Amp hoặc Claude Code, không cần Ralph. Còn nếu bạn có một danh sách việc nhỏ, rõ ràng, có kiểm tra tự động và muốn giao cho AI làm hàng loạt, Ralph là cách thử rất đáng giá.

## 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 bạn dùng và chỉnh sửa tự do. Tuy nhiên Ralph chạy Amp hoặc Claude Code, và chi phí dùng hai công cụ đó phụ thuộc gói của bạn; README không nêu giá cụ thể.

### Ralph có cần GPU không?

README không nhắc đến yêu cầu GPU hay phần cứng nào. Ralph chỉ là script bash gọi công cụ AI đã cài sẵn, nên phần nặng nằm ở dịch vụ của Amp hoặc Claude Code.

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

README chưa ghi cách chạy trên Windows. Vì ralph.sh là script bash và cần jq, bạn cần một môi trường chạy được bash; nếu gặp khó, hãy xem phần issues trong repo hoặc thử một cách khác.

### Ralph dùng được với Claude Code không?

Được. Chép file CLAUDE.md vào scripts/ralph/ và chạy ./scripts/ralph/ralph.sh --tool claude [max_iterations]. Mặc định Ralph dùng Amp nếu bạn không chọn công cụ.

### 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 context sạch. Trí nhớ giữa các vòng nằm ở lịch sử git, file progress.txt và file prd.json cho biết story nào đã xong.

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

Phải đủ nhỏ để làm xong trong một context window. README lấy ví dụ: thêm một cột database kèm migration, thêm một component vào trang có sẵn, thêm dropdown lọc. Những việc như xây cả dashboard hay thêm xác thực nên được chia nhỏ.

### Khác gì so với việc chat với AI để code?

Chat một cuộc dài thì context đầy dần và chất lượng giảm. Ralph chia việc thành story nhỏ, mỗi story một phiên AI mới, có chạy kiểm tra và commit riêng, nên kết quả dễ theo dõi hơn. Tài liệu chưa có so sánh chi tiết với công cụ khác.
