一目でわかるコア概念
Rasen は、あなたと AI の間に置く軽量な合意レイヤーです。 変更が何をすべきかを書き出すと、AI がその詳細を下書きし、両者が同じプランを見て、その後で初めてコードが書かれます。このページには、メンタルモデルの全体が1画面に収まっています。長いバージョンが欲しくなったら、Concepts を見てください。
このアイデア全体は、5つの言葉で言い表せます。まず合意し、それから自信を持って作る。
5つのアイデア
rasen のすべては、5つの概念から組み立てられています。これらを覚えれば、あとは細部です。
1. スペックは真実です。 スペックは、システムが今この瞬間どう振る舞うかを記述します。rasen/specs/ に置かれ、ドメインごとに整理されます（auth/、payments/、ui/）。スペックは要件（「システムは30分後にセッションを失効させなければならない（SHALL）」）とシナリオ（具体的な given/when/then の例）でできています。スペックは、「このソフトウェアは何をするのか」という問いに対する、唯一の合意された答えだと考えてください。
2. 変更は1つの作業単位です。 振る舞いを追加・変更・削除したいとき、あなたは変更（change）を作ります。rasen/changes/ の中にあるフォルダで、その作業に関するすべてを1か所にまとめて持ちます。提案、設計、タスクリスト、そしてスペックの編集内容です。1つの変更、1つのフォルダ、1つの機能。
3. デルタ仕様が記述するのは変化そのものであり、世界の全体像ではありません。 変更の中では、スペック全体を書き直したりはしません。小さな差分だけを書きます。この要件は ADDED、あの要件は MODIFIED、この要件は REMOVED、というように。これが、rasen がグリーンフィールドだけでなく既存システムの編集にも強い理由の仕掛けです。到達点ではなく、差分そのものを記述するのです。
4. 成果物は互いの上に積み上がります。 1つの変更にはいくつかのドキュメントが含まれ、自然な順序で作られ、それぞれが次のものへとつながっていきます。
proposal ──► specs ──► design ──► tasks ──► implement
why what how steps do it
これらはいつでも、何度でも見直すことができます。ゲートではなく、イネーブラーです（詳しくは後述します）。
5. アーカイブが変更を真実へと折り込みます。 作業が終わったら、変更をアーカイブします。デルタ仕様はメインのスペックにマージされ、変更フォルダは日付付きで changes/archive/ に移動します。これでスペックは新しい現実を記述するようになり、あなたは次の変更に取りかかる準備が整います。サイクルが1周します。
全体像
┌─────────────────────────────────────────────────────────────────┐
│ rasen/ │
│ │
│ ┌──────────────────┐ ┌──────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ ◄───── │ │ │
│ │ source of truth │ merge │ one folder per change │ │
│ │ how things work │ on │ proposal · design · │ │
│ │ today │ archive │ tasks · delta specs │ │
│ └──────────────────┘ └──────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
2つのフォルダがあります。specs/ は「今、真実であること」。changes/ は「あなたが提案していること」。アーカイブは、提案を真実の側へ移す操作です。
実際に回すことになるループ
デフォルトの構成では、日々の作業はこうなります。まずは考えを整理したければそれもよし、そこから1つのコマンドがプランを起草し、あなたがそれを読み、次のコマンドがそれを組み立て、最後のコマンドがそれを片付けます。
/rasen:explore → (optional) think it through with the AI first
/rasen:propose add-dark-mode → AI drafts proposal, specs, design, tasks
(you read and adjust the plan)
/rasen:apply → AI builds it, checking off tasks
/rasen:archive → specs updated, change archived
迷ったら、まず探索から始めましょう。 /rasen:explore は、リスクゼロの思考パートナーです。あなたのコードを読み、選択肢を並べ、成果物が1つも存在しないうちに曖昧なアイデアを具体的なプランへと変えていきます。曖昧なプロンプトから何かを勝手に作ってしまう AI に対する、何よりの処方箋です。すでに何を作りたいか正確にわかっていますか？ それなら /rasen:propose に直行してかまいません。いずれにせよ explore はデフォルトのプロファイルに含まれているので、常にそこにあります。詳しくは Explore guide を参照してください。
これらはスラッシュコマンドで、AI アシスタントのチャットに入力するものです。セットアップ（rasen init）はターミナルで行います。この使い分けが初耳なら、まず How Commands Work を読んでください。最もよくある混乱ポイントです。
「ゲートではなくイネーブラー」
このフレーズは rasen のあらゆるところに出てきますので、ここで平たく説明しておきます。
昔ながらのスペックプロセスはウォーターフォールです。計画を終えて、それからようやく実装が許され、後戻りは苦痛を伴います。Rasen はこれを拒否します。proposal → specs → design → tasks という順序が示しているのは、次に強制されることではなく、次に可能になることです。
実装中に設計が間違っていたと気づいたら？ design.md を編集して、そのまま進めばいいのです。スコープを縮めるべきだと気づいたら？ 提案を更新すればいいのです。何もロックされません。この依存関係が存在するのは、AI が必要なコンテキストを持てるようにするためだけであり（スペックなしに良いタスクは書けません）、あなたを縛るためではありません。
ここでの強みは正直さです。実際の作業は雑然としていて反復的であり、rasen はそれをそのまま許容します。トレードオフは規律です。何もあなたを前へ押し出してくれない以上、変更を焦点の合った状態に保つのはあなた自身の責任であり、際限なく広がらせないことも同様です。良い習慣については Workflows ガイドを参照してください。
なぜこの小さな手間に見合うのか
正直に言えば、rasen は1つ工程を増やします。作り始める前に短いプランを書くのです。それで何が得られるのでしょうか。
- 間違った方向へ進んだことを、コストがかかる前に見つけられます。 1段落の提案の中で誤解を正すのはタダ同然です。AI が400行書いたあとで正すのはそうはいきません。
- プランとコードが同じリポジトリにとどまります。 半年後、そのスペックがあなたに（そして次の AI セッションに）、システムがなぜそういう形で動いているのかを教えてくれます。
- 変更はレビューしやすいものになります。 変更フォルダはきちんとまとまったパッケージです。提案を読み、差分にざっと目を通し、タスクを確認する。チャット履歴を発掘する考古学作業は要りません。
- 既存のコードベースに馴染みます。 デルタという仕組みのおかげで、5万行のアプリ全体をまず文書化しなくても、1つの変更を仕様として書けます。
そして正直なトレードオフもあります。本当にささいな1行の修正なら、この手順は見合わないかもしれません。それはそれで構いません。Rasen は軽量であるよう設計されていますが、無料ではありません。合意が重要な場面で使ってください。そしてそれは、あなたが曖昧に頼んだことでも自信満々に作り上げてしまう AI と組んで仕事をする限り、たいていの場面がそれに当てはまるということでもあります。
次に読むべきもの
- 初めてですか？ Getting Started が最初の変更をひと通り歩いてくれます。
- まだ何を作るか決まっていませんか？ Explore First から始めましょう。
- コマンドがどこで動くのか混乱していますか？ How Commands Work。
- 上記すべての詳しいバージョンが欲しいですか？ Concepts。
- 実例で学びたいですか？ Examples & Recipes。
- 用語の定義が必要ですか？ Glossary。