はじめに — Rasen Docs

はじめに

このガイドでは、rasen をインストールして初期化したあと、それがどう動くかを説明します。インストール手順については Installation guide を参照してください。ドキュメント全体がまだよくわからない場合は、documentation home で全体像を確認できます。

これらのコマンドはどこに入力すればいいですか？ 場所は2つあり、これを混同するのが最初につまずきやすいポイントです。

rasen ... コマンド（rasen init など）はターミナルで実行します。

/rasen:... コマンド（/rasen:propose など）はAI アシスタントのチャット、つまりコードを書いてもらうときと同じ入力欄で実行します。

あらためて開始する「インタラクティブモード」のようなものはありません。チャットにスラッシュコマンドを入力するだけで、あとはアシスタントが引き継いでくれます。詳しくは How Commands Work を参照してください。

最初の5分間

流れ全体を、どこで実行するかのラベル付きで示すとこうなります。

TERMINAL   $ npm install -g @atelierai/rasen@latest
TERMINAL   $ cd your-project && rasen init
AI CHAT      /rasen:explore                    (optional: think it through first)
AI CHAT      /rasen:propose add-dark-mode      (AI drafts the plan; you review it)
AI CHAT      /rasen:apply                      (AI builds it)
AI CHAT      /rasen:archive                    (specs updated, change filed away)

セットアップはターミナルでの2ステップだけで、あとはずっとチャットの中で作業します。このガイドの残りでは、各ステップで具体的に何が起きるのかを見ていきます。

まだ何を作るか決まっていませんか？ /rasen:explore から始めましょう。 これはリスクゼロの思考パートナーで、あなたのコードベースを読み、選択肢を比較検討し、成果物やコードが1つも存在しないうちに曖昧なアイデアを具体的なプランへと研ぎ澄ませてくれます。像がはっきりしたら、/rasen:propose へと引き継がれます。曖昧な指示から自信満々に間違ったものを作ってしまいがちな AI と付き合う上で、これが何よりの習慣です。詳しくは Explore guide を参照してください。

仕組み

Rasen は、コードを書き始める前に、あなたと AI コーディングアシスタントが「何を作るか」について合意するのを助けます。

クイックパス（コアのコマンドセット）：

/rasen:explore ──► /rasen:propose ──► /rasen:apply ──► /rasen:sync ──► /rasen:archive
   (optional)

何をすべきか考えている段階なら /rasen:explore から、すでにわかっているなら /rasen:propose に直行してかまいません。explore はデフォルトの full プロファイルにも、絞り込んだ core プロファイルにも含まれているため、explore を外した custom プロファイルを選んでいない限り、常に利用できます。

拡張パス（成果物を1つずつ制御する）：

/rasen:new ──► /rasen:ff or /rasen:continue ──► /rasen:apply ──► /rasen:verify ──► /rasen:archive

デフォルトのグローバルプロファイルは full で、すべてのワークフローコマンドをインストールします。つまり上記のどちらのパスも、あなたにはすでに使える状態にあります。必要最小限（propose、explore、apply、sync、archive）に絞りたい場合は、rasen config profile core に切り替えたあと rasen update を実行してください。

Rasen が作るもの

rasen init を実行すると、プロジェクトには次の構造ができます。

rasen/
├── specs/              # Source of truth (your system's behavior)
│   └── <domain>/
│       └── spec.md
├── changes/            # Proposed updates (one folder per change)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Delta specs (what's changing)
│           └── <domain>/
│               └── spec.md
└── config.yaml         # Project configuration (optional)

2つの重要なディレクトリ：

specs/ — 唯一の事実源です。あなたのシステムが今どう振る舞っているかを記述するスペックが入っています。ドメインごとに整理されます（例：specs/auth/、specs/payments/）。
changes/ — 提案中の変更です。それぞれの変更は、関連する成果物一式をまとめた専用フォルダを持ちます。変更が完了すると、そのスペックはメインの specs/ ディレクトリにマージされます。

成果物を理解する

各変更フォルダには、作業の道しるべとなる成果物が入っています。

Artifact	Purpose
`proposal.md`	「なぜ」と「何を」— 意図・スコープ・アプローチを記録する
`specs/`	ADDED/MODIFIED/REMOVED の要件を示すデルタ仕様
`design.md`	「どうやって」— 技術的なアプローチとアーキテクチャ上の決定
`tasks.md`	チェックボックス付きの実装チェックリスト

成果物は互いの上に積み上がります。

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            update as you learn

実装を進める中で新しくわかったことがあれば、いつでも前の成果物に戻って書き直せます。

デルタ仕様の仕組み

デルタ仕様は rasen の中核となる概念です。今のスペックに対して何が変わるのかを示します。

形式

デルタ仕様は、セクションによって変更の種類を示します。

# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA)

アーカイブ時に起きること

変更をアーカイブすると：

ADDED の要件はメインのスペックに追加されます
MODIFIED の要件は既存のバージョンを置き換えます
REMOVED の要件はメインのスペックから削除されます

変更フォルダは監査履歴として rasen/changes/archive/ に移動します。

例：最初の変更を作ってみる

ダークモードをアプリケーションに追加する例を見てみましょう。

1. 変更を開始する（デフォルト）

You: /rasen:propose add-dark-mode

AI:  Created rasen/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

拡張ワークフロープロファイルを有効にしている場合は、これを2ステップに分けることもできます。/rasen:new を実行してから /rasen:ff（または /rasen:continue で段階的に）を実行する形です。

2. 作られるもの

proposal.md — 意図を記録します。

# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage.

## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage

## Approach
Use CSS custom properties for theming with a React context
for state management.

specs/ui/spec.md — 新しい要件を示すデルタです。

# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions

#### Scenario: System preference
- GIVEN a user with no saved preference
- WHEN the application loads
- THEN the system's preferred color scheme is used

tasks.md — 実装チェックリストです。

# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle

## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables

3. 実装する

You: /rasen:apply

AI:  Working through tasks...
     ✓ 1.1 Created ThemeContext with light/dark state
     ✓ 1.2 Added CSS custom properties to globals.css
     ✓ 1.3 Implemented localStorage persistence
     ✓ 2.1 Created ThemeToggle component
     ...
     All tasks complete!

実装の途中で設計を見直す必要が出てきたら、成果物を更新してそのまま進めるだけです。

4. アーカイブする

You: /rasen:archive

AI:  Archiving add-dark-mode...
     ✓ Merged specs into rasen/specs/ui/spec.md
     ✓ Moved to rasen/changes/archive/2025-01-24-add-dark-mode/
     Done! Ready for the next feature.

これでデルタ仕様はメインのスペックの一部になり、システムがどう動くかを記録しています。

検証とレビュー

CLI を使って変更の状況を確認できます。

# List active changes
rasen list

# View change details
rasen show add-dark-mode

# Validate spec formatting
rasen validate add-dark-mode

# Interactive dashboard
rasen view

次のステップ

Explore First — 取りかかる前に /rasen:explore でアイデアを練る
Reviewing a Change — コードの前に、AI が起草したプランで何を確認すべきか
Writing Good Specs — 良い要件・良いシナリオとはどんなものか
Using Rasen in an Existing Project — 大規模なブラウンフィールドのコードベースで始める
Editing & Iterating on a Change — 成果物の更新、後戻り、手動編集の突き合わせ
Core Concepts at a Glance — メンタルモデル全体を1ページで
Examples & Recipes — 実際の変更を最初から最後まで
Workflows — よくあるパターンと、どのコマンドをいつ使うか
Commands — すべてのスラッシュコマンドの完全なリファレンス
Concepts — スペック・変更・スキーマのより深い理解
Customization — rasen を自分のやり方に合わせる
Stores — 計画が複数のリポジトリやチームにまたがる？専用のリポジトリに置きましょう（ベータ）
FAQ と Troubleshooting — 行き詰まったときに