AS-IS / TO-BE
変更が触れるレイヤーを見つけ、各レイヤーにAS-ISとTO-BEを左右に並べ、証拠で裏付けられた矢印で結び付けます。「このフィールドが削除されたので、このレスポンスが変わり、この画面要素が消える(または現れる)」といった形です。コードは変わってもユーザーが見るものが変わらない場合は、その旨を結論として述べます。変更をでっち上げてはいけません。
以下のコマンドの<skill>は、このスキルのベースディレクトリ、つまりこのSKILL.mdを格納するフォルダです(ユーザーレベルインストールでは~/.claude/skills/asis-tobe、プロジェクトレベルでは<project>/.claude/skills/asis-tobe)。コマンドを実行する前に、実際のパスに置き換えてください。
原則
- 並べて表示。 AS-ISを左、TO-BEを右に。決して縦に重ねない。
- 実際の成果物を比較する。 ペイロードは「実物を選ぶ順序」(後述)に従い、画面は実際のスクリーンショットから、スキーマは実際のマイグレーションとモデルの差分から取得する。実物がない場合:「実物なし:<理由>」と表示する。手作り例:「例(手作り)」と表示する。
- 変更があったレイヤーのみ描画する。 変更がないレイヤーは「変更なし」と一行の根拠のみ。空のテーブルは作らない。
- すべての矢印には根拠がある。 影響経路の各リンクには
ファイル:行またはコミットを記載する。根拠がない場合は「推定:」と明記する。 - 古い仕様をまだ使っているものを明記する。 この変更が出荷後も古いコードを使い続けるもの:すでにストアにあるアプリビルド、古いページを開いたままのブラウザタブ、他のサービス、管理ツールやボットなどの他の呼び出し元。これによりマージとロールアウトの順序が決まる。
- 最初に要約。 上部の要約ボックスだけで判断が下せること:ユーザーの言葉で一文の結論(フィールド名やステータスコードは不可)、ユーザーにとって何が変わるか、どのように出荷されるか、ロールバック可能かどうか;各グループ3項目以内。その直下に、読者が次に知りたがることを尋ねる名前で(役割名ではなく質問で名付ける)三つのカード:「決めるべきこと」(変更が誰かの代わりに決定したこと)、「最初に見る場所」(サイズ、最初に開くファイル、コードが主張する前提)、「直接確認する方法」(確認項目、そして実行方法)— ルールはreferences/document.md(「質問カード」)にあり。判断の要となる二つのこと、バッジとロールバックは、最初の画面で最も目立つようにする。各事実は一度だけ述べる:すでに結論または警告に含まれる文は、リード、質問カード、シナリオで繰り返さない。以下はすべて証拠となる。長いペイロードや網羅的なテーブルは
<details>に折りたたむ;削除しない。導入、進行の説明、結びの言葉は不要。 - レイアウトはコンテンツ。 幅420pxでページが水平スクロールしないこと(テーブルのみ可)。本文の幅は880pxに制限;テーブルと並列比較のみが全幅を使用。テーブル内の
codeは識別子のみ;ファイルパスと識別子のみが等幅フォント、韓国語の説明は決して等幅にしない。文は70文字程度、修飾語は削る。タイトルの上にあるトグルで切り替える二つのカラースキーム:デフォルトのダスク(黄昏)(AS-IS:ベージュ、TO-BE:スレートブルー);ブルーム(Bloom)(AS-IS:ピンク、TO-BE:ミント)。システムのダークモード設定には従わない。点線と実線は常に色と共に使用する。インラインコードのハイライトは、暗いチップ色ではなく明るい--a-mark、--b-markを使用する。各スキームで一度、そして420pxで一度レンダリングする。 - 業界用語は一度だけ説明する。 開発者、QA、企画者がすぐに理解できる言葉を使う。韓国語の文書では、레이어(レイヤー)、필드(フィールド)、API 스펙(API仕様)、호출처(呼び出し元)、deprecated(非推奨)、breaking change(破壊的変更)、mock 응답(モック応答)を使用し、初出時のみ平易な説明を括弧書きで添える(例:codegen(サーバースペックで自動生成した型ファイル))。社内用語(「AC」、自作の画面ニックネーム)については、初出時にその内容を明記する。用語集:references/terms.md。用語が障害になる場合は、そこを読むこと;手順を飛ばさないこと。
レイヤー
| レイヤー | 比較対象 | 実成果物の入手先 |
|---|---|---|
| データ(데이터) | テーブル、フィールド、型、列挙型、制約、インデックス。変更されたエンティティのみのエンティティ図、およびモデルコード | マイグレーション、ORMスキーマ(prismaなど)、DDL差分 |
| API仕様(API 스펙) | リクエストとレスポンスのペイロード、イベント、codegen型。フィールドごとの追加、削除、型変更、意味的変更 | OpenAPI差分、レスポンスDTO、テストフィクスチャ |
| 動作(동작) | 同じ入力に対してサーバーとクライアントが生成する結果 | テストアサーション差分、状態遷移コード |
| 画面(화면) | 同じ状態における画面の二つのキャプチャ | プロジェクトのスクリーンショットツール(references/adapters.md、「プロジェクトアダプター」) |
| ユーザー影響(사용자 영향) | ユーザーが新たにできるようになること、できなくなること、変化する数値。ロールアウト順序による中間状態を含む | IssueのAC、上記レイヤーの総和、互換性テーブル |
レイヤーごとのチェックリストとよくある落とし穴:references/layers.md
実物を選ぶ順序(API仕様)
サーバーテストフィクスチャ > OpenAPIサンプル > 記録された実コール > クライアントモック応答。完全に存在する最初のものを採用する。より上位のソースが部分的(変数から構築されたフィクスチャ、またはインラインでリクエストを構築してフィールドごとにアサーションするテスト)であり、実コールを記録した場合は、パネルには上位ソースを表示し、全文は記録されたコールを表示し、それぞれにソースを明記する。記録されたコールには実行ごとに異なる値(ID、タイムスタンプ)が含まれる;そのようなペイロードはcode_diff.py --mask id,timeで比較し、その旨をソース行に記載することで、新しいIDが変更フィールドとしてカウントされないようにする。クライアントモック(例:スクリーンショット用のフェイクレスポンス)はサーバーの実成果物ではない。ペイロードの下に選択したソースのパスを記述する。フィクスチャが変数から構築されており完全なJSONがない場合は、テストの期待値から書き起こし、「例(テスト期待値から転記)」とラベルを付け、省略部分には…を使用する。期待値に存在しないフィールドを埋めてはならない;…のままにする。他の場所(モック応答など)から値を借用した場合は、そのフィールドの隣にソースを記載する。
手順
1. スコープを設定する
- PR入力:PR番号で差分を取得する(
gh pr diff <n> -R <repo>)。パスまたはブランチのみでは、スタックされたPRのメインをベースとし、他人の変更が混ざる。 - Issue入力:各リポジトリのPRを見つける(
gh pr list -R <repo> --search <key> --state all)。複数のリポジトリがある場合は一つのドキュメントにまとめる。 - PRなし:ワークツリーで
git diff <base>...HEADを実行する。<base>はフォークポイントで、リポジトリルートから計算する(ローカルのmainは古く、何百ものファイルが混ざる):
差分にIssueに関係のないファイルが含まれている場合、ベースが間違っている。レイヤーに分割する前に再計算する。git fetch origin main git merge-base origin/main HEAD - リモートなし:fetchをスキップし、ユーザーが指定したベースを使用する。指定がない場合は、作業を開始したコミット(
git merge-base main HEAD、未コミット作業の場合はHEAD自身)を使用する。 - 未コミット作業ツリー:AS-ISは
HEAD、TO-BEは作業ツリー。git diff HEADでは新しいファイルが検出されないので、git ls-files --others --exclude-standardも読むこと。HEAD SHAが必要な場所には「コミット前」と記述する。比較のためにコミット、スタッシュ、チェックアウトは行わない。 - PRまたはIssueなし:対象はその内容で命名する(「<リポジトリ> 作業ツリー変更」、「<ブランチ> ブランチ」)。ロールアウトテーブルは、出荷される単位ごとに一行(ブランチ、「作業ツリーコミット」)とし、PRセルにその名前を記載;Issueキーはドロップされ、でっち上げない。
- リポジトリごとに、一行
<リポジトリ> <短いベースSHA> → <短いブランチSHA>と記述する。レポート内でそのまま使用する。ドキュメント内では、PRとSHAはサマリーカードのロールアウト順序テーブルとベーステーブル(references/document.md)に一度だけ記載し、ヘッダーには記載しない。
2. 変更されたファイルをレイヤーに割り当てる
各ファイルは一つ以上のレイヤーに割り当てる;不明な場合は開く。テストファイルは割り当てない;動作(동작)レイヤーの証拠として使用する。このテーブルはドキュメントが取得するレイヤーセクションを決定する;作業用の材料であり、ドキュメントには出力しない。
3. まず画面が実際に変わるかどうかを判断する
画面コードが変更されていても、キャプチャの前に問う:変更されたブランチは現在のデータで到達可能か? ブランチが依存する値を一つ選び、サーバーが実際にその値を生成するかどうかを調べる。
# 例:stockState === 'SOLD_OUT' のときにアプリが「품절」(売り切れ)バッジを表示するブランチが削除された場合
git -C <server repo> grep -n "SOLD_OUT" -- <source files> # サーバーはこの値をレスポンスのどこかに設定しているか?
git -C <app repo> grep -n "stockState" -- <generated types> # 生成された型が許可する値
サーバーコードが値を設定していない(型や列挙型の定義のみ)場合は、生成された型が許可していても到達不能。ファイル:行を「変更なし」の根拠として記録する。
値を計算する場所が移動しただけの場合(例:サーバーのERRORがアプリでlastErrorとして計算されるようになった)、両方の式をファイル:行とともに並べて表示する。同じ入力に対して同じ値:同じ画面。異なる:異なる値を生成する入力を一つ見つけ、その状態をキャプチャする。
- 到達可能:ステップ4でキャプチャする。
- 到達不能:画面レイヤーは「現在のデータでは変更なし:<理由と根拠>」とする。消失した状態は「実物なし」の下に記録し、その状態をチェックしていたテスト文字列を使って旧表示を示す。確認が必要な場合は、代表的なシナリオを一つキャプチャし、md5で同一性を示す。
- 不明:キャプチャする。
4. レイヤーごとに実成果物を収集する
- データ:以下の3部構成。この順序で。
- エンティティ図、開いた状態。変更されたエンティティとそれに直接接続されているエンティティのみ、片側6つ以下。JSONで記述し、スクリプトに両側をインラインSVGで描画させる:
python3 -I <skill>/scripts/erd.py <spec.json>(仕様フォーマットはスクリプトのヘッダーにあり)。SVGを手書きしたり、図ライブラリを読み込んだりしてはならない;ページは自己完結する。スクリプトは両側を比較して追加、削除、変更されたフィールドとエンティティを自身でマークするので、各側をそのコミットでの実際の状態のまま記述すること。 - モデルコード、折りたたみ(
<details>):ベース時と現在時の、コードが保持するモデル(構造体、クラス、ORMスキーマ)。モデルごとにpython3 -I <skill>/scripts/code_diff.py <ASIS.txt> <TOBE.txt> --label "<名前 (パス)>" --start-a <行> --start-b <行>から一行差分を取得;新しいモデルまたは削除されたモデルは、欠落している側に/dev/nullを使用する。スクリプトは変更行を計算し、読者が切り替えられるように両方のビュー(並べて、統合)を表示する;決して手動で行をマークしない。 - フィールドテーブル、折りたたみ:図が省略するもの(デフォルト値、制約、インデックス、既存行の処理)。
関連するリレーションのない単一の変更フィールドは図を必要としない:フィールドテーブルに一行、開いた状態で表示する。AS-ISに保存されたスキーマがない場合(メモリ内、ファイル)、
asis_noteでデータが存在した場所(ファイル:行)を指定してスクリプトにtobeのみを渡す;モデルコードがAS-ISの証拠となるので、その<details>は開いたままにする。最初のテーブルを作成するマイグレーションはTO-BEである。これがすでに出荷されたマイグレーションの後始末をする場合は、「すでに反映()」が影響経路の最初のリンクとなる。
- エンティティ図、開いた状態。変更されたエンティティとそれに直接接続されているエンティティのみ、片側6つ以下。JSONで記述し、スクリプトに両側をインラインSVGで描画させる:
- API仕様:変更前後のペイロードを
scripts/code_diff.pyからの行差分として表示(モデルコードと同じスクリプト;ペイロードごとに一回の呼び出し、長いものは--context 3、記録されたコールは--mask id,time)。その下に、「フィールド | AS-IS | TO-BE | 意味的変更」。名前または型のみの変更は両方のセルを一行に統合:<code class="old">start_time</code> → <code class="new">starts_at</code>。呼び出し元:- 各リポジトリで
git grep <フィールド>を実行。リポジトリルートから実行すること(サブディレクトリではパスが相対パスになり、0ヒットとなる)。 - リリース版でも:
git grep -n <フィールド> <sha>を実行。その結果がマージとロールアウトの順序、およびバッジを決定する。これを行う前にreferences/adapters.md(「リリース版を見つける」)を読むこと。 必須事項:ビルドリストからのSHAのみ確認済み、その他は「推定:」;ソース間で矛盾する場合、すべてのSHAをgrepし、ヒットがあれば「リリースされたアプリが読んでいる」とカウントする;タグ名だけで選択しない(タグは同じリポジトリ内の別のデプロイ対象に属する可能性がある)。ビルドリストが失敗した場合の軽量フォールバック(例:ビルドサービスへのログインなし):IssueまたはリリースノートからのSHA、それ以外は「推定:」下限。 - codegen出力は呼び出し元ではない;サーバー仕様から再生成される。「再生成すると何が変わるか」を別途記載する。
- クライアントのモック応答とテストフィクスチャでも削除されたフィールドを
git grepする。残っている場合、サーバーが出荷された後にcodegenが再生成されると型チェックが壊れる可能性がある。それらのファイルを最後のロールアウトステップ(「codegen再生成とフィクスチャ整理」)としてリストする。
- 各リポジトリで
- 動作:「入力・状態 | AS-IS | TO-BE | 根拠(テスト名)」
- 画面:キャプチャの前にreferences/screens.md(「キャプチャ」)を読むこと。 同じシナリオ、データ、言語、サイズで両側を、一時的なワークツリー(AS-ISはベース、TO-BEはブランチ)で、または未コミット作業や触ってはいけないリポジトリの場合はリポジトリ外の二つのコピーで;インストールとキャプチャはバックグラウンドで行い、md5比較し、その後ステップ10で必要なものを再測定したら、サーバーを停止して一時的なワークツリーまたはコピーを削除する(ユーザーが再現可能な実行を望む場合は保持する);決してコミットしない。モックキャプチャツールがない場合は、各バージョンの実際のサーバーをそれぞれのポートで実行してキャプチャする。プロジェクトごとのキャプチャコマンド:references/adapters.md。キャプチャをスキップするのは、プラットフォームがキャプチャできない場合(例:ネイティブ)またはステップ3でブランチが到達不能であることが判明した場合のみ;その場合は「実物なし:<理由>」とテストアサーション文字列を記載する。不明な場合はキャプチャする。
4b. シナリオレールを埋める
「シナリオレール」を埋める前にreferences/scenario-rail.mdを読むこと。 他ドメインのセル名はreferences/domains.md参照。
| スケルトン | Web/アプリの… |
…(元のmarkdownが途中で切れているため、ここまでで生成を終了します。完全なSKILL.mdが必要な場合は原文全体を入力してください。)