ガイド

既存プロジェクトで Rasen を使用

あなたは全体のコードベースを文書化する必要はありません。変更しようとしている内容に対してのみ仕様を書きます。 これは既存プロジェクトに rasen を採用することについて知っておくべき最も重要なことであり、rasen がブラウンフィールド優先に構築される理由です。

一般的な懸念は次のような音がします：「私のアプリは 80,000 行の古いです。Rasen が有用である前に、それのすべてに対して仕様を書かなければなりませんか？」いいえ。あなたはそれを嫌い、私たちもそうでしょう。Rasen は一度に 1 つの変更で仕様を成長させます。最初の変更はタッチしたスライスを文書化し、次の変更はそのスライスを文書化し、数ヶ月以上かけてあなたの仕様は実際に行う仕事の周りに自然に埋まっています。

このガイドは、海を沸騰させずに初日から始める方法を示しています。

30 秒バージョン

$ cd your-existing-project
$ rasen init          # rasen/ と AI ツールのコマンドを追加

その後、AI チャットで：

/rasen:explore            # オプション：AI があなたがタッチする領域を読むようにします
/rasen:propose <本当に、小さな変更が実際に必要です>
/rasen:apply
/rasen:archive

あなたの仕様は現在、その変更がタッチしたシステムの正確な部分だけを説明し、他には何もありません。それは正しいです。他の 80,000 行について心配するのを終えています。

デルタファーストが全トリックである理由

Rasen の変更は デルタ として書かれています：ADDED、MODIFIED、REMOVED。デルタは全体的なシステムではなく、現在の動作に対して何が変わっているかを説明しています。

これはまさにブラウンフィールド作業が必要なものです。あなたはめったに何もないから構築しません。あなたはフィールドを追加し、リダイレクトを修正し、タイムアウトを締め付けています。デルタを使用すると、その周りのすべてのものの 40 ページの仕様を最初に書く必要なく、1 つの変更を正確に指定できます。

したがって、あなたの rasen/specs/ ディレクトリは完全かつ完全には始まりません。それはほぼ空で始まり、蓄積されます。各アーカイブされた変更はデルタをマージします。auth/ の仕様は、いくつかの認証変更を行った後のみ徹底的になります。これはまさにあなたが徹底的になりたいときです。

より深い力学を希望する場合は、Concepts: Delta Specs を参照してください。

本当のコードベースでの最初の変更

小さくて本当のものを選んでください。おもちゃではなく、書き直しではなく。とにかく今週変更しようとしていた変更。小さな最初の変更はあなたにワークフローを低ステークスで教えます。

ステップ 1：AI に関連する領域を読むようにしてください。 これが /rasen:explore が不慣れまたは大きなコードベースで給与を稼ぐ場所です。それがタッチしようとしている部分を指し、何かを提案する前に物事がどのように機能するかをマッピングするようにします。

あなた： /rasen:explore

AI：  何を探索したいですか？

あなた： 我々の公開 API にレート制限を追加する必要がありますが、要求が現在どのようにミドルウェアを流れるかについては確認していません。

AI：  それをトレースさせてください... [ルーター、ミドルウェアスタック、設定を読む]
     リクエストは Express にヒット、認証ミドルウェアを通過し、その後
     コントローラー。今日はレート制限レイヤーはありません。最も清潔な
     挿入点は認証直後のミドルウェアです。スコープしてもいいですか？

AI が今あなたの実際の構造を理解していることに注意してください。書く提案はジェネリックテンプレートではなくコードに適合します。大きなコードベースでは、この単一の習慣はほとんどの痛みを救います。Explore First を参照してください。

ステップ 2：変更を提案します。 提案とそのデルタ仕様はこの変更だけをキャプチャしています。

あなた： /rasen:propose add-api-rate-limiting

ステップ 3：構築と終了 /rasen:apply と /rasen:archive で、他のすべての変更と同じ。アーカイブ後、とにかく必要だった変更から生まれたレート制限動作のための本当の仕様があります。

ガイド付きツアーを好みますか？オンボードを使用

全体的なループがナレーション付きの独自のコードで発生するのを見たいのであれば、拡張コマンド /rasen:onboard はまさにそれを行います：コードベースをスキャンして小さく安全な改善を見つけ、提案、構築、アーカイブを歩みます。各ステップを説明します。

拡張コマンドを最初にオンにします：

$ rasen config profile      # 拡張ワークフローを選択
$ rasen update              # このプロジェクトに適用

その後、チャットで：

/rasen:onboard

これは本当のプロジェクトでの最も穏やかな紹介であり、保持または破棄できる本当の（小さな）変更をあなたに残します。Commands: /rasen:onboard を参照してください。

「しかし、私はすでに要件ドキュメントを持っています」

多分あなたは PRD、SRS、正式な仕様、さらに TLA+ モデルを持っています。良い。あなたはそれらを卸売りでインポートしません。そして、あなたもそれらを捨てません。

既存のドキュメントを 探索のための source 材料 として扱う。仕様に変換するドキュメントではなく。変更を開始するときに、関連するセクションを貼り付けるか AI に指をさし、それから集中した rasen デルタをシェイプアップさせてください。デルタは、rasen のテスト可能な要件とシナリオフォームで、あなたが今変更している動作をキャプチャしています。あなたの元のドキュメントは背景として住んでいます。

正直な理由：rasen の仕様は意図的に動作優先であり、変更に限定されています。40 ページの PRD は異なるアーティファクトで異なるタスクを持っています。ワンタイム一括変換を強制するのは大規模で古い仕様を誰も信頼できない傾向があります。仕様を本当の変更から成長させることは、それらを正確に保ちます。

あなた： /rasen:explore
あなた： これは私たちの PRD のチェックアウトに関するセクションです。次は
     「ゲストチェックアウト」要件を実装しています。
     [関連する要件を貼り付け]
AI：  [それを読む、澄明な質問を尋ね、その後スコープ変更を助ける]
あなた： /rasen:propose add-guest-checkout

大きなコードベースでの仕様の組織化

仕様は rasen/specs/ の下に住んでおり、ドメイン でグループ化されています：チームがシステムについてどのように考えるかと一致する論理領域。全体的な分類法を最初に設計する必要はありません。その領域での最初の変更がサポートを必要とするときに、ドメインフォルダを作成します。

ドメインをスライスする一般的な方法：

機能領域別：auth/、payments/、search/
コンポーネント別：api/、frontend/、workers/
有界コンテキスト別：ordering/、fulfillment/、inventory/

新人がうなずく何かを選んでください。その後で洗練できます。Concepts: Specs を参照してください。

モノレポと複数のリポにまたがる仕事

モノレポの場合、最も単純なモデルはレポルートの rasen/ ディレクトリの 1 つであり、ドメインはパッケージまたはサービスにマップされます。それはほとんどのチームをカバーしています。

あなたの仕事が本当に 複数のリポジトリ にまたがっている場合（または複数のパッケージはあなたが別々として扱う）、rasen にはベータ ストア 機能があります：計画は独立したスタンドアロンレポに住んでおり、コードレポのいずれかが参照でき、計画は 1 つのレポの rasen/ フォルダ内に住む必要はありません。これはベータなので、そのコマンドと状態が進化していると扱ってください。Stores User Guide から始めて、メンタルモデルと最も小さな有用なパスを求めます。

正直な注意事項

すべてをバックフィルする衝動に抵抗してください。 変更していないコードのための仕様を書くことは生産的に見え、通常はありません。これらの仕様は古くなります。何かがそれらを現実で追跡するように強制しないためです。本当の変更があなたの仕様を駆動します。
早期の変更を小さく保ちます。 最初のいくつかの変更は配布と同じくらい、リズムの学習についてです。厳しいスコープはループを速くし、レッスンを安くします。
git に rasen/ をコミットしてください。 あなたの仕様とアーカイブは、それらが説明するコードと一緒にバージョン管理に属しています。
AI にコンテキストを与えてください。 強いコンベンションのある大きなコードベースでは、rasen/config.yaml の context: にすべての提案がスタックとパターンを尊重するようにしてください。Customization を参照してください。

次へ行く場所

Explore First — 変更する前にコードを理解するための主要な習慣
Getting Started — 完全な最初の変更ウォークスルー
Editing & Iterating on a Change — 学ぶにつれて変更を調整
Concepts: Delta Specs — なぜデルタはブラウンフィールド作業をクリーンにするか
Customization — あなたのプロジェクトのコンベンションを rasen を教える