Skip to content

Commit 840014e

Browse files
abu-ismail-01abu-ismail-01
committed
Add docs site and multi-language support
1 parent 9f18850 commit 840014e

7 files changed

Lines changed: 555 additions & 3 deletions

File tree

‎README.ja.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# ralphy-spec
2+
3+
[English](README.md) | [简体中文](README.zh.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
4+
5+
以下のツール向けに **Ralph ループ + OpenSpec** ワークフローを1つのコマンドでセットアップ：
6+
- Cursor
7+
- OpenCode
8+
- Claude Code
9+
10+
**ウェブサイト:** [https://ralphy-spec.org](https://ralphy-spec.org)
11+
12+
## Ralphy-Specとは？
13+
14+
Ralphy-Specは2つの強力なAI開発方法論を組み合わせています：
15+
16+
### Ralph Wiggumループ
17+
18+
Ralph方法論（[Geoffrey Huntley](https://ghuntley.com/ralph)が提唱）は、AIエージェントがタスクを完了するまで**同じプロンプトを繰り返し**受け取る開発アプローチです。各イテレーションで、AIはファイルとgit履歴で以前の作業を確認し、自己修正フィードバックループを形成します。
19+
20+
```
21+
while true; do
22+
ai_agent "機能Xを構築してください。完了したら<promise>DONE</promise>を出力してください。"
23+
# AIは以前の作業を見て、ミスを修正し、進捗を続けます
24+
done
25+
```
26+
27+
### OpenSpec（スペック駆動開発）
28+
29+
[OpenSpec](https://github.com/Fission-AI/OpenSpec)は、コードの前にスペックを要求することでAIコーディングに構造をもたらします：
30+
- `openspec/specs/` - 真実の情報源となるスペック
31+
- `openspec/changes/` - 受け入れ基準を含む変更提案
32+
- 完了した変更をマージするアーカイブワークフロー
33+
34+
### なぜ組み合わせるのか？
35+
36+
| 問題 | 解決策 |
37+
|------|--------|
38+
| チャット履歴の曖昧な要件 | OpenSpecが意図を構造化されたスペックに固定 |
39+
| AIが途中で停止したりミスをする | Ralphループが完了するまでリトライ |
40+
| 正確性を検証する方法がない | 受け入れ基準 + テストで出力を検証 |
41+
| ツール固有のセットアップが面倒 | 1つのコマンドでCursor、OpenCode、Claude Codeをセットアップ |
42+
43+
## プロジェクトにインストールされるもの
44+
45+
- `openspec/` スキャフォールド：
46+
- `openspec/specs/`（真実の情報源）
47+
- `openspec/changes/`（アクティブな変更）
48+
- `openspec/archive/`（完了した変更）
49+
- `openspec/project.md`（プロジェクトコンテキスト）
50+
- ツール統合：
51+
- Cursor: `.cursor/prompts/ralphy-*.md`
52+
- Claude Code: `.claude/commands/ralphy-*.md`
53+
- OpenCode: `AGENTS.md`
54+
- Ralphループ状態/設定：
55+
- `.ralphy/config.json`
56+
- `.ralphy/ralph-loop.state.json`
57+
58+
## インストール
59+
60+
### npm（グローバル）
61+
62+
```bash
63+
npm install -g ralphy-spec
64+
```
65+
66+
### npx（インストール不要）
67+
68+
```bash
69+
npx ralphy-spec init
70+
```
71+
72+
### curlインストールスクリプト
73+
74+
```bash
75+
curl -fsSL https://raw.githubusercontent.com/anthropics/ralphy-openspec/main/scripts/install.sh | sh
76+
```
77+
78+
## 使用方法
79+
80+
### プロジェクトで初期化
81+
82+
```bash
83+
cd your-project
84+
ralphy-spec init
85+
```
86+
87+
非対話的なツール選択：
88+
89+
```bash
90+
ralphy-spec init --tools cursor,claude-code,opencode
91+
```
92+
93+
既存ファイルの上書き：
94+
95+
```bash
96+
ralphy-spec init --force
97+
```
98+
99+
### セットアップの検証
100+
101+
```bash
102+
ralphy-spec validate
103+
```
104+
105+
### テンプレートの更新
106+
107+
```bash
108+
ralphy-spec update --force
109+
```
110+
111+
## ワークフロー（PRD -> リリース）
112+
113+
```
114+
PRD/要件 --> OpenSpec（スペック + タスク + 受け入れ基準）
115+
|
116+
v
117+
Ralphループ（テストが通るまで反復）
118+
|
119+
v
120+
アーカイブ（ソーススペックにマージ）
121+
```
122+
123+
### 1) 計画：PRD -> OpenSpec変更
124+
125+
AIツールで`/ralphy:plan`（Cursor / Claude Code）を使用するか、OpenCodeに`AGENTS.md`に従うよう依頼します。
126+
127+
リポジトリでの期待される出力：
128+
129+
```
130+
openspec/changes/<change-name>/
131+
proposal.md
132+
tasks.md
133+
specs/
134+
<domain>/
135+
spec.md
136+
```
137+
138+
### 2) 実装：完了するまで反復
139+
140+
`/ralphy:implement`を使用してタスクを実装し、テストを追加します。
141+
142+
Ralphループランナーで実行する場合、エージェントは**すべてのタスクが完了しテストが通った場合のみ**以下を出力します：
143+
144+
```
145+
<promise>TASK_COMPLETE</promise>
146+
```
147+
148+
### 3) 検証：テストで受け入れ基準を証明
149+
150+
`/ralphy:validate`を使用してテストを実行し、通過したテストをOpenSpecシナリオにマッピングします。
151+
152+
### 4) アーカイブ：変更をスペックにマージ
153+
154+
`/ralphy:archive`を使用し、利用可能であればOpenSpec CLIを使用します：
155+
156+
```bash
157+
openspec archive <change-name> --yes
158+
```
159+
160+
## 謝辞
161+
162+
Ralphy-Specは巨人の肩の上に立っています：
163+
164+
- **Ralph Wiggum方法論** - [Geoffrey Huntley](https://ghuntley.com/ralph)が考案。AIエージェントが反復を通じて自己修正できるという洞察は、AI支援開発についての私たちの考え方を変えました。
165+
166+
- **[opencode-ralph-wiggum](https://github.com/Th0rgal/opencode-ralph-wiggum)** by [@Th0rgal](https://github.com/Th0rgal) - 私たちの統合アプローチにインスピレーションを与えたOpenCode用のクリーンなRalphループCLI実装。
167+
168+
- **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** by [Fission-AI](https://github.com/Fission-AI) - AIコーディングに構造と予測可能性をもたらすスペック駆動開発フレームワーク。
169+
170+
これらのアプローチを開拓したこれらのプロジェクトとメンテナーに感謝します。
171+
172+
## 開発
173+
174+
```bash
175+
npm install
176+
npm run build
177+
node bin/ralphy-spec.js --help
178+
```
179+
180+
## ライセンス
181+
182+
BSD-3-Clause

‎README.ko.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# ralphy-spec
2+
3+
[English](README.md) | [简体中文](README.zh.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
4+
5+
다음 도구를 위한 **Ralph 루프 + OpenSpec** 워크플로우를 한 번의 명령으로 설정:
6+
- Cursor
7+
- OpenCode
8+
- Claude Code
9+
10+
**웹사이트:** [https://ralphy-spec.org](https://ralphy-spec.org)
11+
12+
## Ralphy-Spec이란?
13+
14+
Ralphy-Spec은 두 가지 강력한 AI 개발 방법론을 결합합니다:
15+
16+
### Ralph Wiggum 루프
17+
18+
Ralph 방법론([Geoffrey Huntley](https://ghuntley.com/ralph)가 제안)은 AI 에이전트가 작업을 완료할 때까지 **동일한 프롬프트를 반복적으로** 받는 개발 방식입니다. 각 반복에서 AI는 파일과 git 히스토리에서 이전 작업을 보고 자기 수정 피드백 루프를 형성합니다.
19+
20+
```
21+
while true; do
22+
ai_agent "기능 X를 구축하세요. 완료되면 <promise>DONE</promise>을 출력하세요."
23+
# AI가 이전 작업을 보고, 실수를 수정하고, 진행을 계속합니다
24+
done
25+
```
26+
27+
### OpenSpec (스펙 기반 개발)
28+
29+
[OpenSpec](https://github.com/Fission-AI/OpenSpec)은 코드 전에 스펙을 요구하여 AI 코딩에 구조를 부여합니다:
30+
- `openspec/specs/` - 진실의 원천 스펙
31+
- `openspec/changes/` - 인수 기준이 있는 변경 제안
32+
- 완료된 변경을 다시 병합하는 아카이브 워크플로우
33+
34+
### 왜 결합하는가?
35+
36+
| 문제 | 해결책 |
37+
|------|--------|
38+
| 채팅 기록의 모호한 요구사항 | OpenSpec이 의도를 구조화된 스펙에 고정 |
39+
| AI가 중간에 멈추거나 실수함 | Ralph 루프가 완료될 때까지 재시도 |
40+
| 정확성을 검증할 방법 없음 | 인수 기준 + 테스트로 출력 검증 |
41+
| 도구별 설정이 번거로움 | 한 번의 명령으로 Cursor, OpenCode, Claude Code 설정 |
42+
43+
## 프로젝트에 설치되는 내용
44+
45+
- `openspec/` 스캐폴드:
46+
- `openspec/specs/` (진실의 원천)
47+
- `openspec/changes/` (활성 변경)
48+
- `openspec/archive/` (완료된 변경)
49+
- `openspec/project.md` (프로젝트 컨텍스트)
50+
- 도구 통합:
51+
- Cursor: `.cursor/prompts/ralphy-*.md`
52+
- Claude Code: `.claude/commands/ralphy-*.md`
53+
- OpenCode: `AGENTS.md`
54+
- Ralph 루프 상태/설정:
55+
- `.ralphy/config.json`
56+
- `.ralphy/ralph-loop.state.json`
57+
58+
## 설치
59+
60+
### npm (전역)
61+
62+
```bash
63+
npm install -g ralphy-spec
64+
```
65+
66+
### npx (설치 없이)
67+
68+
```bash
69+
npx ralphy-spec init
70+
```
71+
72+
### curl 설치 스크립트
73+
74+
```bash
75+
curl -fsSL https://raw.githubusercontent.com/anthropics/ralphy-openspec/main/scripts/install.sh | sh
76+
```
77+
78+
## 사용법
79+
80+
### 프로젝트에서 초기화
81+
82+
```bash
83+
cd your-project
84+
ralphy-spec init
85+
```
86+
87+
비대화형 도구 선택:
88+
89+
```bash
90+
ralphy-spec init --tools cursor,claude-code,opencode
91+
```
92+
93+
기존 파일 덮어쓰기:
94+
95+
```bash
96+
ralphy-spec init --force
97+
```
98+
99+
### 설정 검증
100+
101+
```bash
102+
ralphy-spec validate
103+
```
104+
105+
### 템플릿 업데이트
106+
107+
```bash
108+
ralphy-spec update --force
109+
```
110+
111+
## 워크플로우 (PRD -> 출시)
112+
113+
```
114+
PRD/요구사항 --> OpenSpec (스펙 + 작업 + 인수 기준)
115+
|
116+
v
117+
Ralph 루프 (테스트 통과까지 반복)
118+
|
119+
v
120+
아카이브 (소스 스펙에 병합)
121+
```
122+
123+
### 1) 계획: PRD -> OpenSpec 변경
124+
125+
AI 도구에서 `/ralphy:plan` (Cursor / Claude Code)을 사용하거나 OpenCode에 `AGENTS.md`를 따르도록 요청합니다.
126+
127+
저장소에 예상되는 출력:
128+
129+
```
130+
openspec/changes/<change-name>/
131+
proposal.md
132+
tasks.md
133+
specs/
134+
<domain>/
135+
spec.md
136+
```
137+
138+
### 2) 구현: 완료될 때까지 반복
139+
140+
`/ralphy:implement`를 사용하여 작업을 구현하고 테스트를 추가합니다.
141+
142+
Ralph 루프 러너를 통해 실행하는 경우, 에이전트는 **모든 작업이 완료되고 테스트가 통과했을 때만** 다음을 출력해야 합니다:
143+
144+
```
145+
<promise>TASK_COMPLETE</promise>
146+
```
147+
148+
### 3) 검증: 테스트로 인수 기준 증명
149+
150+
`/ralphy:validate`를 사용하여 테스트를 실행하고 통과한 테스트를 OpenSpec 시나리오에 매핑합니다.
151+
152+
### 4) 아카이브: 변경을 스펙에 병합
153+
154+
`/ralphy:archive`를 사용하고, 가능하다면 OpenSpec CLI를 사용합니다:
155+
156+
```bash
157+
openspec archive <change-name> --yes
158+
```
159+
160+
## 감사의 말
161+
162+
Ralphy-Spec은 거인의 어깨 위에 서 있습니다:
163+
164+
- **Ralph Wiggum 방법론** - [Geoffrey Huntley](https://ghuntley.com/ralph)가 고안. AI 에이전트가 반복을 통해 자기 수정할 수 있다는 통찰력은 AI 지원 개발에 대한 우리의 생각을 바꾸었습니다.
165+
166+
- **[opencode-ralph-wiggum](https://github.com/Th0rgal/opencode-ralph-wiggum)** by [@Th0rgal](https://github.com/Th0rgal) - 우리의 통합 방식에 영감을 준 OpenCode용 깔끔한 Ralph 루프 CLI 구현.
167+
168+
- **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** by [Fission-AI](https://github.com/Fission-AI) - AI 코딩에 구조와 예측 가능성을 부여하는 스펙 기반 개발 프레임워크.
169+
170+
이러한 접근 방식을 개척한 이 프로젝트들과 유지 관리자들에게 감사드립니다.
171+
172+
## 개발
173+
174+
```bash
175+
npm install
176+
npm run build
177+
node bin/ralphy-spec.js --help
178+
```
179+
180+
## 라이선스
181+
182+
BSD-3-Clause

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# ralphy-spec
22

3+
[English](README.md) | [简体中文](README.zh.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
4+
35
One-command setup for **Ralph loop + OpenSpec** workflows across:
46
- Cursor
57
- OpenCode

0 commit comments

Comments
 (0)