Cursor を補完ツールとして使っているうちは、その本当の威力の半分も引き出せていません。1 ファイルの中で「この関数を書き換えて」とインライン編集するだけなら、Cursor は便利な賢い補完で止まってしまいます。複数のファイルにまたがる機能追加や、API シグネチャを変えたときの呼び出し側の波及修正、命名の一括変更といった「横断的な作業」を任せられるようになって、はじめて生産性の桁が変わります。それを担うのが Composer、いわゆる Agent モードです。
ただし Composer は強力なぶん、雑に使うと「意図しないファイルまで書き換えられて差分が読み切れない」「途中で方向を見失って収拾がつかなくなる」といった事故も起きやすい機能です。この記事では、FIXIT のエンジニアが日々の実装やリファクタリング案件で実際に使っている Composer の進め方を、コンテキストの渡し方・差分レビュー・タスク分割・テスト併走という観点でまとめます。
Composer と通常チャットの違い
まず押さえておきたいのが、Composer（Agent モード）と通常チャットの守備範囲の違いです。
通常チャット（Cmd + L）は、基本的に開いているファイルや明示的に渡したコンテキストに対して回答や提案を返します。提案されたコードを自分でコピーして貼り付けるか、提示された diff を 1 つずつ適用するかは人間が判断します。会話の主導権は人間側にあり、「相談しながら自分で書く」スタイルに向いています。
一方で Composer（Cmd + I）は、AI が能動的にコードベースを探索し、必要なファイルを自分で開き、複数ファイルにまたがって編集を実行します。「/services 配下の FAQ コンポーネントに新しい項目を追加して、型定義とテストも合わせて更新して」のように、目的だけを伝えれば関連ファイルを横断して書き換えてくれます。さらに Agent モードでは、コマンド実行（テストの実行や型チェックなど）まで含めて一連の作業を回せます。
ざっくり言えば、通常チャットは「壁打ち・部分修正・調べもの」、Composer は「複数ファイルにまたがる実装とリファクタリング」が得意分野です。Cursor の基本的なショートカットや使い分けは Cursor で TypeScript を爆速で書く 10 のショートカット でも整理しているので、まだ手に馴染んでいない人はあわせて読んでみてください。
横断変更を成功させるコンテキストの渡し方
Composer の成否の 8 割は、最初に渡すコンテキストの質で決まります。AI に「探させる」より「指し示す」ほうが、結果は速く正確になります。
@file で起点と参照を明示する
@ を打つと file / folder / docs / git などを選択できます。横断変更でまず効くのは、変更の起点になるファイルと、整合性を取りたい参照先を @file で渡しておくことです。たとえば API のレスポンス型を変えるなら、型定義ファイルと、それを使っている主要な呼び出し側を 2〜3 個明示します。すべてを渡す必要はなく、AI が「ここを基準に揃えればいい」と判断できる代表点を置くイメージです。
@folder で探索範囲を絞る
「@components/forms の中のバリデーションロジックを共通化して」のように @folder で範囲を指定すると、AI が無関係なディレクトリまで掘りに行くのを防げます。範囲を絞ることは精度だけでなく、後述する差分レビューの負担を下げる意味でも重要です。Composer が一度に触るファイルが多いほど、人間のレビューコストは跳ね上がります。
@docs と規約ファイルで前提を共有する
外部ライブラリの最新仕様に沿わせたいときは @docs でドキュメントを参照させます。加えて、プロジェクト固有の規約は .cursor/rules/（旧 .cursorrules）に集約しておくと、Composer が毎回それを踏まえて編集してくれます。「import の並び順」「エラーハンドリングの方針」「命名規則」などをルール化しておくと、横断変更でも出力のブレが小さくなります。最初のプロンプトに毎回同じ前提を書かなくて済むのも利点です。
プロンプト自体は、目的・対象範囲・守ってほしい制約の 3 点を簡潔に書くと安定します。「何を実現したいか」だけでなく「触ってほしくない範囲」を一言添えるだけで、暴走の確率がぐっと下がります。
実装パターン: 機能追加・API 変更の波及・命名の一括変更
実際の現場で Composer が活きる代表的な 3 パターンを、進め方とともに紹介します。
機能追加では、UI コンポーネント・状態管理・型定義・テストが同時に必要になります。このとき「フォームに項目を 1 つ足す」だけでも、入力コンポーネント、バリデーション、型、送信処理、テストの 5 ファイルに波及するのが普通です。Composer に既存の似た項目を @file で渡し、「この実装に倣って新しい項目を同じ構造で追加して」と頼むと、既存パターンを踏襲した一貫性のある変更が返ってきます。ゼロから書かせるより、既存実装を「お手本」として渡すほうが圧倒的に精度が高いのは覚えておきたいコツです。
API 変更の波及は、Composer が最も価値を発揮する場面です。関数のシグネチャや型を変えると、呼び出し側が壊れます。型エラーを Agent モードで実際に実行させ、「型チェックを通るまで呼び出し側を直して」と指示すると、エラーを足がかりに修正を反復してくれます。人間が grep して 1 箇所ずつ直していた作業が、テストと型チェックを羅針盤にして一気に片づきます。
命名の一括変更は、単純な置換ツールでは対応しきれないケースで効きます。たとえば「fetchUser を getUserProfile にリネームしつつ、戻り値の型名やコメント、テストのケース名も意味が通るように整える」といった、機械置換では文脈を壊す変更です。Composer なら意味を理解したうえで関連箇所をまとめて整えられます。
差分レビューと適用の安全運用
Composer を安全に使う鍵は、適用前の差分レビューを習慣化することです。AI が出した変更は必ず diff として提示されるので、ここを飛ばさないことが事故防止の最重要ポイントです。
提示された差分は、ファイル単位・ハンク単位で受け入れ（Accept）と却下（Reject）を選べます。「8 割は正しいが 1 ファイルだけ意図と違う」ときは、正しい部分だけ Accept して残りを Reject し、追加プロンプトで修正方針を伝え直します。全部まとめて受け入れる前に、変更が入ったファイル一覧をざっと眺め、想定外のファイルが混じっていないかを確認する癖をつけてください。想定外のファイルが触られていたら、その時点でプロンプトかコンテキストの渡し方に問題があったサインです。
万一適用してから「やはり戻したい」となっても、慌てる必要はありません。Cursor の変更はチェックポイントとして履歴に残るため、特定の地点まで巻き戻せます。さらに根本的な保険として、Composer を回す前に必ずコミットしておくことを強くおすすめします。クリーンな状態から始めれば、git diff で AI の変更だけを純粋に確認でき、いざとなれば git restore で全部捨てられます。AI に任せる作業ほど、Git のコミット粒度を細かく保つことが安全網になります。
大きすぎるタスクを分割するコツ
Composer が失敗するときの典型は、1 回のセッションに目的を詰め込みすぎているケースです。「認証を追加して、ついでにエラーハンドリングも整理して、ログ出力も入れて」と一度に頼むと、AI の判断がぶれ、差分も膨れ上がってレビュー不能になります。
原則は「1 Composer 1 目的」です。タスクは人間側で先にステップに分解し、1 ステップずつ Composer に渡します。認証なら、次のように分けると各段階で差分が小さく保たれ、レビューも巻き戻しも容易になります。
- トークン検証のロジックを追加する
- 呼び出し側を保護する
- テストを追加する
各ステップの区切りでコミットしておけば、どこで方向が逸れたかも一目瞭然です。
大きなリファクタリングを任せたいときほど、いきなり実装させず「まず変更計画を箇条書きで出して」と一度プランニングさせるのが有効です。計画を人間がレビューし、合意できた範囲だけを実装に移します。AI に方針からすべて委ねるのではなく、設計判断は人間が握り、実装の手数を AI に任せる。この役割分担が、横断変更を安全に速く進めるコツです。
テストと併走させて品質を担保する
Composer の変更を信頼できるものにする最後のピースが、テストとの併走です。Agent モードはコマンドを実行できるので、編集とテスト実行をループさせられます。
実装の前にテストを用意しておくと、Composer は「テストを通すこと」を明確なゴールにできます。先にテストを書き、それを基準に Composer へ実装を任せ、落ちたら失敗ログを足がかりに直させる。この流れは AI 駆動開発における TDD の考え方そのものです。テストがない状態で大きな変更を任せると「動いているように見えるが壊れている」状態を見抜けませんが、テストがあれば AI の出力を機械的に検証できます。詳しい考え方は AI 駆動開発時代の TDD で解説しているので、品質を担保しながら速度を出したい人は参照してください。
型チェック、Lint、テストといった自動検証を Composer のループに組み込むほど、人間のレビューは「ロジックの妥当性」という本質的な部分に集中できます。AI が機械的に直せる部分は AI に直させ、人間は判断に専念する。これが横断変更を高速かつ安全に回す土台です。
FIXIT がリファクタリング案件で使う Composer の進め方
FIXIT では、レガシーシステムの刷新やリファクタリングの案件で Composer を日常的に使っています。進め方には一定の型があります。
最初にやるのは、いきなり書き換えることではなく、対象コードの理解を Composer に手伝わせることです。「このモジュールの責務と依存関係を要約して」と探索させ、現状を把握したうえで変更計画を立てます。次に、リファクタリングの前に振る舞いを固定するテストを用意し、変更の前後で挙動が変わっていないことを保証できる状態を作ります。ここまで整えてから、小さなステップに分けて Composer に実装を任せ、各ステップで差分レビューとテスト実行を回します。
この進め方によって、属人化したコードや仕様書のないシステムでも、安全に速くリプレイスを進められます。実際にレガシー刷新を従来の半分の期間で実現した事例は レガシー刷新を半分の期間で にまとめています。Composer は魔法の杖ではなく、コンテキストの設計・差分レビュー・テスト併走という地に足のついた運用があってこそ威力を発揮するツールです。
レガシーシステムの刷新やリファクタリングを安全に速く進めたい方は、レガシー刷新を半分の期間で実現した事例やシステムリプレイスのサービスもあわせてご覧ください。FIXIT は AI 駆動開発のクリエイティブスタジオとして、現場の運用ごと伴走します。