コンセプト
このガイドでは、Rasen の背後にあるコア概念と、それらがどのように適合するかを説明しています。実践的な使用方法については、Getting Started と Workflows を参照してください。
哲学
Rasen は 4 つの原則の周りに構築されています：
流動的、固くない — フェーズゲートなし、意味のあることに取り組む
イテレーティブ、ウォーターフォールではない — 構築しながら学び、進むにつれて洗練する
簡単、複雑ではない — 軽量セットアップ、最小限のセレモニー
存量優先 — 既存コードベースで機能し、グリーンフィールドだけではありません
これらの原則が重要な理由
流動的、固くない。 従来の仕様システムはあなたをフェーズにロックします：最初に計画し、次に実装し、次に完了です。Rasen はより柔軟です — あなたの仕事にとって意味のある任意の順序で成果物を作成できます。
イテレーティブ、ウォーターフォールではない。 要件は変わります。理解が深まります。始めに良いアプローチに思えたことは、コードベースを見た後は成立しないかもしれません。Rasen はこの現実を受け入れます。
簡単、複雑ではない。 一部の仕様フレームワークでは、広範なセットアップ、堅いフォーマット、または重いプロセスが必要です。Rasen はあなたの邪魔になりません。数秒で初期化し、即座に作業を開始し、必要な場合のみカスタマイズしてください。
存量優先。 ほとんどのソフトウェアのことは最初から構築するのではなく、既存のシステムを変更しています。Rasen のデルタベースのアプローチにより、新しいシステムを説明するのではなく、既存の動作への変更を指定することが簡単になります。
大きな絵
Rasen は、あなたの作業を 2 つの主要な領域に組織します：
┌────────────────────────────────────────────────────────────────────┐
│ rasen/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ 唯一事実来源 │◄─────│ 提案された変更 │ │
│ │ システムがどう │ merge│ 各変更 = 1 つのフォルダ │ │
│ │ 現在機能するか │ │ 成果物 + デルタを含む │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘
仕様は唯一事実来源です — システムが現在どのように動作するかを説明しています。
変更は提案された変更です — マージする準備ができるまで別のフォルダに住んでいます。
この分離は重要です。複数の変更を並行して作業でき、競合が発生しません。変更を主な仕様に影響を与える前にレビューできます。変更をアーカイブすると、デルタは唯一事実来源にきれいにマージされます。
仕様
仕様は構造化された要件とシナリオを使用してシステムの動作を説明しています。
構造
rasen/specs/
├── auth/
│ └── spec.md # 認証動作
├── payments/
│ └── spec.md # 支払い処理
├── notifications/
│ └── spec.md # 通知システム
└── ui/
└── spec.md # UI 動作とテーマ
ドメイン別に仕様を組織してください — システムにとって意味のある論理的なグループ化。一般的なパターン：
- 機能領域別：
auth/、payments/、search/ - コンポーネント別：
api/、frontend/、workers/ - 有界コンテキスト別：
ordering/、fulfillment/、inventory/
仕様フォーマット
仕様には要件が含まれ、各要件にはシナリオがあります：
# 認証仕様
## 目的
アプリケーションの認証とセッション管理。
## 要件
### 要件：ユーザー認証
システムは正常なログイン時に JWT トークンを発行しなければなりません（SHALL）。
#### シナリオ：有効な認証情報
- GIVEN 有効な認証情報を持つユーザー
- WHEN ユーザーがログインフォームを送信
- THEN JWT トークンが返される
- AND ユーザーはダッシュボードにリダイレクトされる
#### シナリオ：無効な認証情報
- GIVEN 無効な認証情報
- WHEN ユーザーがログインフォームを送信
- THEN エラーメッセージが表示される
- AND トークンは発行されません
### 要件：セッション有効期限
システムは 30 分の非アクティビティ後、セッションを有効期限切れにしなければなりません（MUST）。
#### シナリオ：アイドルタイムアウト
- GIVEN 認証されたセッション
- WHEN 30 分のアクティビティなし
- THEN セッションが無効化される
- AND ユーザーは再度認証する必要があります
主な要素：
| 要素 | 目的 |
|---|---|
## 目的 |
この仕様のドメインの高レベルの説明 |
### 要件: |
システムが持つ必要がある特定の動作 |
#### シナリオ: |
実際の要件の具体的な例 |
| SHALL/MUST/SHOULD | 要件の強度を示す RFC 2119 キーワード |
なぜこのように仕様を構造化するか
要件は「何」 — 実装を指定せずに、システムが何をすべきかを述べています。
シナリオは「いつ」 — 検証できる具体的な例を提供しています。良いシナリオ：
- テスト可能（自動化されたテストを書くことができます）
- ハッピーパスとエッジケースの両方をカバー
- Given/When/Then または同様の構造化フォーマットを使用
RFC 2119 キーワード（SHALL、MUST、SHOULD、MAY）意図を伝えます：
- MUST/SHALL — 絶対的な要件
- SHOULD — 推奨されますが、例外は存在します
- MAY — オプション
仕様とは何か（そして何でないか）
仕様は 動作契約、実装プランではありません。
良い仕様の内容：
- ユーザーまたはダウンストリームシステムが依存する観察可能な動作
- 入出力とエラー条件
- 外部制約（セキュリティ、プライバシー、信頼性、互換性）
- テストまたは明示的に検証できるシナリオ
仕様に含めるべきではありません：
- 内部クラス/関数名
- ライブラリまたはフレームワークの選択
- ステップバイステップの実装の詳細
- 詳細な実行プラン（それらは
design.mdまたはtasks.mdに属しています）
クイックテスト：
- 実装が外部から見える動作を変わることなく変わることができれば、それは仕様に属さない可能性が高いです。
軽量に保つ：段階的厳密性
Rasen は官僚主義を避けることを目指しています。変更を検証可能にしながら、最も軽い水準を使用してください。
ライト仕様（デフォルト）：
- 短い動作ファースト要件
- 明確なスコープと非目標
- いくつかの具体的な受け入れチェック
完全仕様（より高いリスク）：
- クロスチーム または クロスレポの変更
- API/契約の変更、移行、セキュリティ/プライバシーの懸念
- あいまいさが高価なリワークを引き起こしそうな変更
ほとんどの変更はライトモードにとどまるべきです。
ヒューマン + エージェント協力
多くのチームでは、ヒューマンが探索し、エージェントが成果物を作成します。意図されたループは：
- ヒューマンが意図、コンテキスト、制約を提供します。
- エージェントはこれを動作ファースト要件とシナリオに変換します。
- エージェントは実装の詳細を
spec.mdではなくdesign.mdとtasks.mdに保持しています。 - 検証は実装前に構造と明確さを確認しています。
これで仕様はヒューマンが読みやすく、エージェントにとって一貫性があります。
変更
変更は提案された変更であり、それを理解して実装するために必要なすべてのもの有するフォルダとしてパッケージ化されています。
変更構造
rasen/changes/add-dark-mode/
├── proposal.md # 理由と何
├── design.md # 方法（技術的アプローチ）
├── tasks.md # 実装チェックリスト
├── .openspec.yaml # 変更メタデータ（オプション）
└── specs/ # デルタ仕様
└── ui/
└── spec.md # ui/spec.md で何が変わっているか
各変更は自己完結しています。それには以下があります：
- 成果物 — 意図、設計、タスクを取得するドキュメント
- デルタ仕様 — 追加、変更、削除されている内容の仕様
- メタデータ — この特定の変更のためのオプションの設定
なぜ変更はフォルダなのか
変更をフォルダとしてパッケージ化することにはいくつかの利点があります：
すべて一緒に。 提案、設計、タスク、仕様は 1 つの場所に住んでいます。異なる場所を探し歩くことはありません。
並行作業。 複数の変更は競合することなく同時に存在できます。
add-dark-modeで作業しながらfix-auth-bugも進行中です。クリーンな履歴。 アーカイブされたら、変更は
changes/archive/に完全なコンテキストを保存されて移動します。戻って、何が変わったのかだけでなく、なぜ変わったのかを理解できます。レビューフレンドリー。 変更フォルダは簡単にレビューできます — それを開き、提案を読み、設計を確認し、仕様のデルタを確認します。
成果物
成果物は、作業をガイドする変更内のドキュメントです。
成果物フロー
提案 ──────► 仕様 ──────► 設計 ──────► タスク ──────► 実装
│ │ │ │
なぜ 何が どのように 実行する
+ スコープ 変わるか アプローチ ステップ
成果物は相互に構築されます。各成果物は次のコンテキストを提供します。
成果物タイプ
提案（proposal.md）
提案は 意図、スコープ、アプローチ を高いレベルでキャプチャしています。
# 提案：ダークモードを追加
## 意図
ユーザーは夜間の使用中に目の疲れを軽減し、システム設定に合わせるためにダークモードオプションを要求しています。
## スコープ
スコープ内：
- 設定のテーマトグル
- システム設定の検出
- localStorage への設定の永続化
スコープ外：
- カスタムカラーテーマ（将来の作業）
- ページごとのテーマオーバーライド
## アプローチ
テーマにCSS カスタムプロパティを使用し、状態管理用に React コンテキストを使用してください。最初の読み込みでシステムの設定を検出し、手動オーバーライドを許可します。
提案を更新する場合：
- スコープの変更（縮小または拡張）
- 意図を明確にします（問題をより理解）
- アプローチが根本的にシフト
仕様（specs/ のデルタ仕様）
デルタ仕様は、現在の仕様に対して 何が変わるか を説明しています。以下の Delta Specs を参照してください。
設計（design.md）
設計は 技術的アプローチ と アーキテクチャの決定 をキャプチャしています。
# 設計：ダークモードを追加
## 技術的アプローチ
React Context を使用したテーマ状態管理は、props ドリリングを回避します。
CSS カスタムプロパティにより、クラス切り替えなしでランタイム切り替えが可能になります。
## アーキテクチャの決定
### 決定：Context vs Redux
テーマ状態に React Context を使用する理由：
- シンプルなバイナリ状態（ライト/ダーク）
- 複雑な状態遷移はありません
- Redux 依存を追加しない
### 決定：CSS カスタムプロパティ
CSS-in-J の代わりに CSS 変数を使用する理由：
- 既存のスタイルシートで機能
- ランタイムオーバーヘッドなし
- ブラウザネイティブソリューション
## データフロー
```
ThemeProvider（コンテキスト）
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS 変数（:root に適用）
```
## ファイルの変更
- `src/contexts/ThemeContext.tsx`（新規）
- `src/components/ThemeToggle.tsx`（新規）
- `src/styles/globals.css`（変更）
設計を更新する場合：
- 実装はアプローチが機能しないことを明らかにする
- より良いソリューションが発見されました
- 依存関係または制約が変わります
タスク（tasks.md）
タスクは 実装チェックリスト — チェックボックス付きの具体的なステップ。
# タスク
## 1. テーマインフラストラクチャ
- [ ] 1.1 ライト/ダーク状態の ThemeContext を作成
- [ ] 1.2 色の CSS カスタムプロパティを追加
- [ ] 1.3 localStorage 永続化を実装
- [ ] 1.4 システム設定の検出を追加
## 2. UI コンポーネント
- [ ] 2.1 ThemeToggle コンポーネントを作成
- [ ] 2.2 設定ページにトグルを追加
- [ ] 2.3 クイックトグルを含めるようにヘッダーを更新
## 3. スタイリング
- [ ] 3.1 ダークテーマカラーパレットを定義
- [ ] 3.2 CSS 変数を使用するようにコンポーネントを更新
- [ ] 3.3 アクセシビリティのためのコントラスト比をテスト
タスクベストプラクティス：
- 関連するタスクを見出しの下でグループ化
- 階層的な番号付けを使用（1.1、1.2 など）
- タスクを 1 つのセッションで完了するのに十分小さく保つ
- 完了したタスクをチェックオフします
デルタ仕様
デルタ仕様は Rasen がブラウンフィールド開発に対して機能するようにする主な概念です。全体の仕様を述べ直すのではなく、何が変わるか を説明しています。
フォーマット
# 認証のためのデルタ
## ADDED 要件
### 要件：二要素認証
システムは TOTP ベースの二要素認証をサポートしなければなりません（MUST）。
#### シナリオ：2FA 登録
- GIVEN 2FA が有効になっていないユーザー
- WHEN ユーザーが設定で 2FA を有効化
- THEN QR コードが認証アプリセットアップのために表示される
- AND ユーザーは有効化の前にコードで確認する必要があります
#### シナリオ：2FA ログイン
- GIVEN 2FA が有効になっているユーザー
- WHEN ユーザーが有効な認証情報を送信
- THEN OTP チャレンジが提示される
- AND ログインは有効な OTP の後でのみ完了します
## MODIFIED 要件
### 要件：セッション有効期限
システムは 15 分の非アクティビティ後、セッションを有効期限切れにしなければなりません（MUST）。
（以前：30 分）
#### シナリオ：アイドルタイムアウト
- GIVEN 認証されたセッション
- WHEN 15 分のアクティビティなし
- THEN セッションが無効化される
## REMOVED 要件
### 要件：メモアラン
（2FA を支持して廃止されました。ユーザーは各セッションで再度認証する必要があります。）
デルタセクション
| セクション | 意味 | アーカイブ時に何が起こるか |
|---|---|---|
## ADDED 要件 |
新しい動作 | メイン仕様に追加 |
## MODIFIED 要件 |
変わった動作 | 既存の要件を置き換え |
## REMOVED 要件 |
廃止された動作 | メイン仕様から削除 |
デルタの代わりに全仕様を使用しない理由
明確さ。 デルタはまさに何が変わっているかを示しています。全仕様を読んでいるとすると、心の中で現在のバージョンに対して比較する必要があります。
競合回避。 2 つの変更が異なる要件を変更する限り、同じ仕様ファイルに触れることができます。
レビュー効率。 レビュアーは変更されていないコンテキストではなく変更を見ます。重要なもの目指します。
ブラウンフィールドフィット。 ほとんどの仕事は既存の動作を変更しています。デルタは変更を最初のクラスにします。
スキーマ
スキーマはワークフローの成果物タイプと依存関係を定義しています。
スキーマの動作方法
# rasen/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # 依存なし、最初に作成できます
- id: specs
generates: specs/**/*.md
requires: [proposal] # 作成する前に提案が必要
- id: design
generates: design.md
requires: [proposal] # 仕様と並行して作成できます
- id: tasks
generates: tasks.md
requires: [specs, design] # 最初に仕様と設計の両方が必要
成果物は依存関係グラフを形成します：
提案
（ルートノード）
│
┌─────────────┴─────────────┐
│ │
▼ ▼
仕様 設計
（requires： （requires：
提案） 提案）
│ │
└─────────────┬─────────────┘
│
▼
タスク
（requires：
仕様、設計）
依存関係はイネーブラー、ゲートではありません。 作成可能なものを示していますが、次に何を作成する必要があるかを示していません。必要がなければ設計をスキップできます。仕様は設計の前後に作成できます — 両方とも提案のみに依存しています。
組み込みスキーマ
spec-driven（デフォルト）
仕様駆動開発の標準的なワークフロー：
提案 → 仕様 → 設計 → タスク → 実装
最適用途：実装の前に仕様に同意したい大部分の機能の仕事。
カスタムスキーマ
チームのワークフロー用にカスタムスキーマを作成します：
# 最初から作成
rasen schema init research-first
# または既存のものを fork
rasen schema fork spec-driven research-first
カスタムスキーマの例：
# rasen/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # 最初にリサーチを実行
- id: proposal
generates: proposal.md
requires: [research] # リサーチによって知らされた提案
- id: tasks
generates: tasks.md
requires: [proposal] # 仕様/設計をスキップし、タスクに直進
カスタムスキーマの作成と使用の詳細については、Customization を参照してください。
アーカイブ
アーカイブは、デルタ仕様をメイン仕様にマージし、変更を履歴のために保存することで変更を完了します。
アーカイブ時に何が起こるか
アーカイブ前：
rasen/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ マージ
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
アーカイブ後：
rasen/
├── specs/
│ └── auth/
│ └── spec.md # 現在 2FA 要件を含む
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # 履歴のために保存
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.md
アーカイブプロセス
デルタをマージ。 各デルタ仕様セクション（ADDED/MODIFIED/REMOVED）が対応するメイン仕様に適用されます。
アーカイブに移動。 変更フォルダは
changes/archive/に日付プレフィックス付きで移動され、時系列順序付けされます。コンテキストを保存。 すべての成果物はアーカイブ内に無傷のままです。戻って変更が行われたのか理解できます。
アーカイブが重要な理由
クリーンな状態。 アクティブな変更（changes/）は進行中の作業のみを表示します。完了した仕事は邪魔にならなくなります。
監査証跡。 アーカイブは、すべての変更の完全なコンテキスト — 何が変わったのか、提案が説明する理由、設計がどのように説明するか、タスクが示す仕事を保存しています。
仕様進化。 変更がアーカイブされるにつれて仕様は有機的に成長しています。各アーカイブはデルタをマージし、時間の経過とともに包括的な仕様を構築します。
すべてがどのように適合するか
┌──────────────────────────────────────────────────────────────────────────────┐
│ RASEN フロー │
│ │
│ ┌────────────────┐ │
│ │ 1. 開始 │ /rasen:propose（コア）または /rasen:new（拡張） │
│ │ 変更を │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. 作成 │ /rasen:ff または /rasen:continue（拡張ワークフロー） │
│ │ 成果物を │ 提案 → 仕様 → 設計 → タスクを作成 │
│ │ │ （スキーマ依存に基づいて） │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. 実装 │ /rasen:apply │
│ │ タスクを │ タスクを処理し、チェックオフします │
│ │ │◄──── 学ぶにつれて成果物を更新 │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. 検証 │ /rasen:verify（オプション） │
│ │ 作業を │ 実装が仕様と一致するか確認 │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. アーカイブ │────►│ デルタ仕様がメイン仕様にマージ │ │
│ │ 変更を │ │ 変更フォルダが archive/ に移動 │ │
│ └────────────────┘ │ 仕様は現在、更新された唯一事実来源 │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
有徳なサイクル：
- 仕様は現在の動作を説明します
- 変更は変更を提案します（デルタとして）
- 実装は変更を現実にします
- アーカイブはデルタを仕様にマージ
- 仕様は現在、新しい動作を説明します
- 次の変更は更新された仕様を構築
用語集
| 用語 | 定義 |
|---|---|
| 成果物 | 変更内のドキュメント（提案、設計、タスク、またはデルタ仕様） |
| アーカイブ | 変更を完了し、デルタをメイン仕様にマージするプロセス |
| 変更 | 成果物を持つフォルダとしてパッケージ化されたシステムへの提案された変更 |
| デルタ仕様 | 現在の仕様に対する変更（ADDED/MODIFIED/REMOVED）を説明する仕様 |
| ドメイン | 仕様の論理的なグループ化（例：auth/、payments/） |
| 要件 | システムが持つ必要がある特定の動作 |
| シナリオ | 通常は Given/When/Then フォーマットの要件の具体的な例 |
| スキーマ | 成果物タイプとそれらの依存関係の定義 |
| 仕様 | 要件とシナリオを含むシステム動作を説明する仕様 |
| 唯一事実来源 | rasen/specs/ ディレクトリ、現在合意された動作を含む |
次のステップ
- Getting Started — 実践的な最初のステップ
- Workflows — 一般的なパターンと各パターンを使用する場合
- Commands — 完全なコマンドリファレンス
- Customization — カスタムスキーマを作成し、プロジェクトをカスタマイズ