リポジトリを読む前に、ファイルや API、機能を想像で決めない

「ボタンを統一する」という要件を見ると、すぐに BaseButton、新しい props、置き換えるページを思い浮かべるかもしれません。しかし、このサイトにはすでに Button があり、出力要素の選択、variants、props の型にも独自の契約があります。別のものを作ると、同じ責任を二つの実装に分けるだけになりかねません。

AI は、もっともらしい形のコードを素早く書けます。ただし、既存プロジェクトの変更では、それだけでは足りません。ファイル、インターフェース、機能が、このリポジトリの実態につながっている必要があります。そうでなければ、別のプロジェクト向けの提案にすぎません。

私はまず、要件がどの観察可能な結果を指しているかを確認し、現在その責任を持つ場所をたどります。定義と使用箇所を見つけてから、新しいものが必要かを判断します。

要件を実際の使用箇所につなげます

「ボタンの統一」には、色や余白をそろえる、HTML の意味を適切にする、操作の動作をそろえる、といった複数の意味があります。これは要件を分解するための例で、このサイトで新たなボタンの問題が起きたという記録ではありません。

見た目をそろえるなら、共通コンポーネントと tokens を先に見ます。リンクが新しいタブで開けないなら、実際に出力される要素と href を確認します。アバターの操作部品が反応しないなら、イベントとダイアログまでたどります。どれもボタンに見えるからといって、同じ種類の操作に変えるべきではありません。

このサイトの作品カードにある Demo へのリンクは、ローカルの Button に as="a" を渡しています。プロフィールページのアバター拡大にも Button を使いますが、こちらは操作用です。共通なのは表示の一部で、動作の責任は各使用箇所に残ります。

ボタンの意味を扱った記事では、要素の選び方を説明しています。ここで補いたいのは、変更前の調査の順序です。まずこの二つの使い方を見つけ、次に共通コンポーネントがどう支えているかを確認します。コンポーネント名から要件を逆算してはいけません。

慣れた名前ではなく、定義と参照をたどります

現在、このサイトの Button は、ディレクトリのエントリーポイントからローカルの .astro コンポーネントとしてエクスポートされています。コンポーネント内で受け付ける props と variants を定義し、cn で class を結合します。さらに cn の定義をたどると、実際に使っているパッケージにつながります。

この調査によって、変更に必要なことが分かります。

• すでに対応している出力要素は何か。同じ選択肢を作り直す必要はありません。
• variant が変えるのは見た目であり、要素の選択とは別であること。
• class をどう結合し、呼び出し側の調整をどの helper が処理するか。
• デフォルトを変えた場合、どのページにも影響する可能性があるか。

これらは、現在の定義と参照を読むことで得られる答えです。別のプロジェクトで使った className、to、asChild が、このサイトにもあるとは推定できません。他のコンポーネントライブラリで一般的な API でも、ここでそのまま渡せるとは限りません。

manifest も確認します。例にパッケージの import があれば、まずインストール済みか、そのバージョンとプロジェクトの契約が用途に合うかを調べます。慣れた import を貼り付け、不足する依存関係をユーザーが見つけるまで放置するべきではありません。

ファイルがあっても要件とは限らず、名前だけでは動作も分かりません

このサイトの再構築では、すでに一つの例を整理しています。旧プロジェクトには技術別の絞り込みコンポーネントがありましたが、追跡できる入口から調べても、その操作部品がマウントされている根拠は見つかりませんでした。実際に引き継いだのは作品カテゴリの切り替えであり、残っていたすべての実装を新しい機能にはしませんでした。

旧コンポーネントの調査記事に、その入口の追跡を記録しています。そこで扱うのは、ファイルを元のサイトの機能と数えてよいかという問題です。AI による変更では、もう一つ境界が必要です。新しい操作部品が合理的でも、その追加まで許可されたことにはなりません。

現在の作品ページには、#development と #design へのリンクがあります。スクリプトは hash に応じて該当セクションを切り替え、aria-current を更新します。この動作を変更するなら、新しいグローバルな絞り込み state を作る前に、この実際の経路を理解する必要があります。

コードの形を推測で決めると、AI は小さな要件を新しい state、イベント、操作部品へと広げ、その追加によって生じた問題をさらに別のコードで解こうとすることがあります。既存の責任を先に確認すれば、提案の段階から変更範囲を外れるのを避けやすくなります。これは作業方法の説明であり、エラー率がどれだけ下がったかを示す実験結果ではありません。

「存在しない」と「まだ見つかっていない」を分けます

検索で該当がなかった場合、まず言えるのは、その検索では見つからなかったということだけです。名前が違うかもしれませんし、エクスポートの入口、データファイル、動的な取得元を通じてつながっているかもしれません。ある能力が存在しないと断言するには、より十分な調査が必要です。

私はページの入口に戻って import を見直し、コンポーネント、データ、スクリプトへとたどります。要件が目に見える動作を扱うなら、実際の出力も確認します。API、ログイン、外部サービスに関係するなら、それに対応する実行の根拠と権限・許可の情報も必要です。フロントエンドの名前だけでは結論を出せません。

リポジトリや外部環境を確認できないときは、提案を仮定として示し、どの情報が不足しているかを明確にします。たとえば、「既存の送信フローはまだ見つかっていません。バックエンドのインターフェースがすでにあるか確認が必要です」と伝えます。これは伝え方の例で、このサイトにフォームや API を追加したという意味ではありません。

仮定は選択肢を話し合うために使えます。しかし、既存の関数シグネチャに見せかけてはいけません。空白を埋めるために、成功したように見えるリクエスト結果を作ることもできません。

変更前に、どこにつなぐのかを説明できるようにします

小さな変更のたびに、アーキテクチャ全体の報告書を作る必要はありません。現在は誰が責任を持つのか、今回はどの契約を変えるのか、どの使用箇所を維持するのか。こうしたことを確かめられる短い説明のほうが役立ちます。

Button なら、共通の見た目だけを調整する場合、元のリンク要素と操作要素を変えないことを先に確認します。type のデフォルトを変えるなら、呼び出し側が既存の動作に依存しているかを調べます。二つの変更では影響が違うため、「ボタンを統一する」という一言だけを、すべての受け入れ条件にはできません。

変更後は、新しいファイルがあることだけでなく、実際の結果を確認します。型、ビルド、HTML、ブラウザーでの操作には、それぞれ検証できる範囲があります。具体的な分担は、ビルドと完成の境界を扱った記事を参照してください。

この順序でも、新しい機能を追加する余地は残ります。既存の構造で要件を本当に満たせないなら、不足する点と変更の許可を確認してから追加します。変更するファイルを減らすためだけに、無理に再利用する必要はありません。先にリポジトリを読む目的は、新しい設計に根拠を持たせることであり、アーキテクチャを永久に変えないことではありません。

記録の範囲

この記事は、このサイトの現在の Button の定義と使用箇所、class 結合 helper、作品ページ、公開済みの再構築調査記録をもとに整理しています。ボタンの要件、API の不足、伝え方の引用は説明用の例であり、新しい障害、サービス、実行済みのリクエストではありません。モデルの能力比較や開発効率の測定も行っていません。

私は、どの変更でも、なぜその場所につなぐのかを説明できるようにしたいと考えています。根拠が見えないときは、結論を狭めるか、必要な情報を補うほうが、このプロジェクトに属さない別の実装を一式書くより役立ちます。