Ferret の使い方

プロジェクトと URL

プロジェクトは1つのフォルダです(たいていはリポジトリのルート)。プロジェクトごとに URL を登録しておけるので、ローカル・開発・本番をワンクリックで行き来できます。

#プロジェクトを追加する

  1. ファイル → プロジェクトフォルダを開く…(⌘O / CtrlO)、サイドバーの プロジェクトを追加、またはタイトルバーのプロジェクトメニューの プロジェクトを追加… を使います。
  2. プロジェクトをどこから持ってくるかを選びます。
    • 自分の PC で開く: フォルダを選びます。
    • GitHub / GitLab から取得: 自分のリポジトリ(gh か glab のログインで一覧を出します)から選ぶか URL を貼り、置き場所の親フォルダを選ぶと、Ferret が clone して開きます。
    • SSH で開く: ~/.ssh/config からホストを選びます。ターミナルとエージェントはリモートのマシンで動き、レビューはこの PC に残ります。

Finder(Windows ではエクスプローラー、Linux ではファイルマネージャー)からフォルダをドラッグして、サイドバーのプロジェクト一覧にドロップしても追加できます。ドラッグしている間は一覧が強調表示されます。ファイルではなくフォルダをドロップしてください。複数のフォルダをドロップすると、それぞれを追加して最後のものを開きます。

名前は最初はフォルダ名になります。すでに登録してあるフォルダを追加すると、追加せずにそれを開きます(macOS と Windows ではパスの大文字・小文字を区別せずに比べます)。サイドバーのメニューから、プロジェクトの 名前を変更 や 登録を外す ができます。登録を外してもフォルダは消えません。

一覧の順番を変えるには、プロジェクトを上下にドラッグします(移る先に線が出ます)。選んだプロジェクトで ⌥↑ / Alt↑ / ⌥↓ / Alt↓ を押すか、メニューの 上へ移動 / 下へ移動 でも動かせます。順番は保存され、再起動しても残ります。

レビューの検索欄の横にある絞り込みボタンでは プロジェクトの並び順 も選べます: 手動(ドラッグの順)、動いている順(エージェントがあなたを待っている・作業中・作業を終えたばかりのプロジェクトが上)、最近使った順、名前順、追加した順。手動以外の並び順のときにプロジェクトをドラッグすると、表示している並びが手動の順になり、並び順は 手動(ドラッグの順) に切り替わります。プロジェクトの行の星、またはメニューの ☆ を付ける で星を付けると、どの並び順でも一覧の上に置かれます。☆ のみ表示 にすると、ほかのプロジェクトは隠れます。星と並び順は再起動しても残ります。

ターミナルはプロジェクトのフォルダで開き、レビューは <project>/.ferret/ の下に保存します。

#GitHub に private のリポジトリを作る

まだ GitHub に無いプロジェクトを private のリポジトリにするには、サイドバーでプロジェクトを右クリックし、GitHub に private で作る を選びます。自分の gh のログインを使うので、gh を入れてログインしておく必要があります。対応しているのは GitHub だけで、GitLab には対応していません。

  1. 置き場(自分のアカウントか所属する組織)と リポジトリ名(フォルダ名から候補を出します。英数字・.・_・-)を選びます。説明(任意) も付けられます。
  2. フォルダにまだコミットが無ければ、最初のコミットを作って push する で最初のコミットを作ります。.gitignore の対象と、秘密を含みうるファイルは入れません: .env のファイル(.env.example などの雛形は入れます)、*.pem や id_rsa などの鍵、.npmrc、.netrc、credentials.json、*.tfstate など。外したものは画面に一覧で出ます。そのパスは .git/info/exclude に書くので、あとのコミットにも入りません。プロジェクトのファイルと .gitignore は変えません。まだ git のリポジトリでないフォルダは、ブランチ main で初期化します。
  3. 次へ を押し、リポジトリ・公開範囲・push を確かめてから 作成 を押します。リポジトリは必ず private です。フォルダの origin になり、フォルダのコミットを push します。

フォルダに origin が既にあるとき、別の git のリポジトリの中にあるとき(モノレポの中のフォルダなど)、同じ名前のリポジトリが既にあるとき、最初のコミットのファイルが 20,000 を超えるとき、git にユーザー名とメールが設定されていないとき、SSH で開いたプロジェクトのときは、作らずに断ります。

最初に選ばれる置き場は自分のアカウントです。組織にしたいときは、設定 → よく使うサービスの CLI の 新しいリポジトリの置き場(GitHub)(settings.json の github.defaultOwner)で決めます。

#URL を登録する

  1. 内蔵ブラウザでページを開きます。
  2. ブラウザのツールバーの +(表示中のURLを登録)を押します。いまの URL が入った状態で開きます。
  3. 名前 を入れて 保存 を押します。

登録した URL には、確認するもの で種類が付きます。アプリ(作っているアプリ)、デザイン(Figma、Penpot、Canva、プロトタイプ)、設計書・文書(Google Docs、Notion、Confluence、GitHub 上の Markdown の仕様書、PDF)、参考(競合など、自分では直せない外部のサイト)のどれかです。種類は URL と名前から推測し、あとから変えられます。コードだけでなく、デザインや文書もレビューすると外部のサイトを参考にするを見てください。

使える URL は http:// と https:// だけです。アプリの URL では、名前を提案のまま残すと、ホストから次のように決まります。

ホスト名前
localhost、127.*、::1、0.0.0.0、*.localhostlocal
dev、develop、development を含むdev
stg、stage、staging を含むstg
それ以外prd
ブラウザのツールバーに並ぶ登録済みの URL
ブラウザのツールバーに並ぶ登録済みの URL

#レビュー対象のパネル

録画を止めずに、レビューの対象やページを切り替える。

フィードバックモードでは、右の レビュー対象 パネルに、いまのプロジェクトでレビューできるものが並びます。対象を切り替えても録画は止まりません。パネルは 表示 → レビュー対象の表示を切り替える(⌘⇧K / CtrlShiftK)か パネルを隠す で出し入れします。

  • 確認先: プロジェクトに登録した URL。それぞれの下に、そのサイトで開いたページがツリーで並びます。登録していないサイトを開いた場合は、そのサイトが別のグループとして並びます。
  • ファイル: プロジェクトのフォルダ。ファイルはプレビューで開く(Markdown と Mermaid は描画し、ほかのテキストは読み取り専用)ので、ドキュメントもレビューできます。鉛筆(エディタで開く)でエディタで開きます。

対象を絞り込む は、確認先・ページ・ファイルをまとめて絞り込みます。あいまい一致の仕方は ファイルを名前で開く… と同じです。一覧では ↑ ↓ Enter か 1〜9 で対象を切り替えます。URL を開く… はその場限りの URL を開き、プロジェクトの URL に登録 で残せます。

確認先は settings.json の projects[].urls から読みます(例を参照)。各項目には url、launchCommand(ターミナルで実行します。たとえばデスクトップアプリの起動)、windowMatch(録画するウインドウ)のどれかが要り、purpose(app、design、doc、reference)も付けられます。録画の前にウインドウの対象を選ぶと、それが録画の対象になります。録画中に選ぶと、そのウインドウを録画に足して映します(複数のウインドウを同時に録画する)。開いたページはプロジェクトごとに、この端末にだけ覚えます(200件まで)。

#開く・環境を切り替える

登録した URL を押すと開きます。いまのページが別の登録 URL の下にあるときは、Ferret はパス・クエリ・ハッシュを保ったまま、オリジンだけを入れ替えます。たとえば http://localhost:3000/pricing?plan=pro で prd を押すと、https://example.com/pricing?plan=pro が開きます。

いまのページに合うチップ(前方一致が最も長いもの)が強調されます。チップを右クリックするか鉛筆のアイコンで、編集や 削除 ができます。プロジェクトを開いたときに前回の URL が無ければ、最初に登録した URL を読み込みます。

チップは種類ごとにまとまります。アプリの URL が先で、そのあとにデザイン、文書、参考が続き、種類ごとに区切り線とアイコンが付きます。デザイン・文書・参考へ(またはそこから)切り替えるときは、パスを引き継がず、登録した URL をそのまま開きます。

#コードだけでなく、デザインや文書もレビューする

フィードバックの対象はコードに限りません。内蔵ブラウザで開けるものなら、同じように録画してペンで書き込めます。Figma や Penpot のデザイン、プロトタイプ、Google Docs や Notion の仕様書、GitHub 上の設計書、PDF などです。レビューの前に、こうした URL を local や dev と並べてプロジェクトに登録しておきます。

  1. サイドバーのメニューから プロジェクトを編集… を開き(またはブラウザのツールバーの + を押し)、確認先を追加 を押します。
  2. URL を貼り付けます。figma.com のリンクは デザイン、docs.google.com や notion.so のリンクは 設計書・文書 になり、名前は Figma や Spec になります。推測が違うとき(自前のサーバー上のプロトタイプなど)は、確認するもの で種類を変えます。
  3. 確認先を開き、サイトがログインを求めるなら内蔵ブラウザで一度ログインします。ブラウザは起動をまたいで Cookie を残すので、ログインしたままになります。
  4. いつもどおり録画します。話し、指し示し、デザインや文書にペンで書き込みます。

デザインや文書の上で録った指摘には、指摘の一覧と feedback.md でその種類が付き、エージェントへ送る指示にもそう書かれます。エージェントはコードではなく、デザインや文書のほうを直します。

  • 文書がプロジェクトの中にある(Markdown の仕様書、ADR など)なら、エージェントがそのファイルを書き換えます。
  • 書き換えられないもの(Figma のファイル、Google ドキュメントなど)でも、エージェントは止まってあなたに質問しません。その指摘を 確認待ち にし、どう直すかをメモに1行で具体的に書きます。自分で反映するか、担当者に渡してください。

例: Google Docs で料金の仕様書を読みながら、プランの表を丸で囲んで「Pro プランはいま 8,800 円ではなく 9,800 円」と話したとします。feedback.md ではこの指摘が Spec の確認先の下に Kind: document で並び、エージェントは料金ページのコードには触らず、仕様書の直した文を返します。仕様書と動いているアプリを同じ録画で録ると、指摘は確認先ごとに分かれるので、エージェントは先に仕様書を、次にそれを実装するコードを直せます。

登録していないページでも、figma.com、docs.google.com、notion.so などのホストなら見分けます。プロジェクトのフォルダの中のファイル(Markdown、Mermaid)は、レビュー対象 パネルの ファイル の一覧からレビューします。

#外部のサイトを参考にする

競合のサイトや、見た目の良いページを録画して、何を取り入れたいかを話すこともできます(「これを参考にして」「この黒背景はダメ」など)。そのサイトは自分では直せないので、エージェントも直そうとはしません。こうした指摘は、自分のアプリへの参考として扱います。

  1. そのサイトを確認先に足し、確認するもの で 参考 を選びます。名前に「競合」「参考」などを入れると(たとえば 競合:調達info)、自動でこの種類になります。
  2. いつもどおり録画します。同じ録画の中で、そのサイトと自分のアプリを行き来してもかまいません。

参考のサイトで録った指摘には、指摘の一覧で 参考 が付き、feedback.md では Kind: reference の区分が付きます。エージェントは指摘ごとに次のようにします。

  • 良いと言った点は、自分のアプリの合う箇所に取り入れ、どこに取り入れたかをメモに書きます。
  • ダメと言った点は、自分のアプリが同じことをしていないかを確かめ、していれば自分のアプリを直します。
  • 自分のアプリに生かせることが無い感想なら何も変えず、「外部サイトのため対応不要(参考)」のようなメモを付けて 確認待ち にします。

外部のサイトを書き換えることも、止まってあなたに質問することもありません。種類を選ばなくても、確認先の名前に「competitor」「reference」(または 競合 / 参考)が入っているとき、またはプロジェクトのどのアプリの URL ともホストが合わない、登録していないサイトで録ったときも、参考として扱います。localhost やプライベートのアドレスは外部に数えません。アプリの URL を1つも登録していないプロジェクトでは、この推測はしません。

GitHub でこのページの翻訳を手伝う (新しいタブで開きます)