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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

Sau đó cài bộ skill:

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

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

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

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

```bash
cd flowchart
npm install
npm run dev
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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