UGA Boxxx

つぶやきの延長のつもりで、知ったこと思ったこと書いてます

【ClaudeCode】agent-browserの新しいスキルに electron が追加された

ClaudeCode

vercelが出している agent-browser のskillsに electron が追加された

Discord、Figma、Notion、Spotify、VS CodeなどのElectronで構築されたデスクトップアプリを制御できるようになるみたい

Electronアプリ一覧

www.electronjs.org

$ npx skills add vercel-labs/agent-browser --skill electron

自分は元々インストールしていたので、marketplaceを更新で利用可能になった

【DB】B-treeインデックス

DB PostgreSQL

以前にB-treeインデックスを調べていたが、どんな概念なのかまでは掘り下げでなく、分かった気のまま分かってなかったのでまた調べた

uga-box.hatenablog.com

基本概念

B-tree は1972年に Rudolf Bayer と Edward McCreight によって発明された 自己平衡木構造

「B」の由来は諸説あり、Balanced、Bayer、Boeing（開発された場所）などが挙げられるが、公式な説明はない

特徴

特性 説明
自己平衡 挿入・削除時に自動的にバランスを維持
多分岐 二分木と異なり、1ノードが複数の子を持つ
ディスク最適化 ディスクI/Oを最小化する設計
計算量 検索・挿入・削除すべて O(log n)

B-tree の構造

基本構成

                    [Root Node]
                [  30 |    70  |   90  ]
               /         |           \          \
              /          |            \          \
[10|20]    [40|50|60]  [75|80]  [95|100]
    ↓                ↓                ↓            ↓
[Data]        [Data]        [Data]    [Data]

構成要素

要素 説明
ルートノード 木の最上位。検索の起点
内部ノード（ブランチ） キーと子ノードへのポインタを格納
リーフノード 実際のデータまたはデータへのポインタを格納
キー ソートされた値。検索・比較に使用

B-tree の規則

次数 m の B-tree は以下の規則に従う：

  1. すべてのリーフノードは同じ深さ（高さが均一）
  2. ルート以外の各ノードは最低 ⌈m/2⌉ 個の子を持つ
  3. 各ノードは最大 m 個の子を持つ
  4. ノード内のキーは常にソートされている

検索の仕組み

検索アルゴリズム

email = 'user@example.com' を検索する場合：

1. ルートノードから開始
2. ノード内のキーと比較
   - 一致 → 発見
   - 小さい → 左の子ノードへ
   - 大きい → 右の子ノードへ
3. リーフノードに到達するまで繰り返し

具体例：値 45 を検索

Step 1: ルート [30 | 70 | 90]
        → 45 は 30 < 45 < 70 なので2番目の子へ

Step 2: 内部ノード [40 | 50 | 60]
        → 45 は 40 < 45 < 50 なので2番目の子へ

Step 3: リーフノード到達、データ取得

わずか3回のノードアクセスで目的のデータに到達

なぜ B-tree はディスクに最適なのか

ディスクI/Oのコスト

操作 速度
メモリアクセス ~100 ナノ秒
SSD ランダムリード ~100 マイクロ秒（1,000倍遅い）
HDD ランダムリード ~10 ミリ秒（100,000倍遅い）

ディスクアクセスは圧倒的に遅い

最小化することで性能を向上させる

B-tree の最適化ポイント

  1. ノードサイズ = ディスクページサイズ

    • 一般的に 4KB〜16KB
    • 1回のI/Oで多くのキーを読み込める

  2. 高いファンアウト（分岐数）

    • 1ノードに数百〜数千のキーを格納可能
    • 木の高さを低く保てる

  3. 低い木の高さ

    • 100万件でも高さは3〜4程度
    • I/O回数 = 木の高さ

計算例

ノードサイズ 16KB、キーサイズ 8バイト、ポインタ 8バイトの場合：

1ノードあたりのキー数 ≈ 16KB / 16バイト ≈ 1,000個
高さ2: 1,000 × 1,000 = 100万件
高さ3: 1,000 × 1,000 × 1,000 = 10億件

10億件のデータでも 最大3回のディスクアクセス で検索可能

B-tree と B+tree の違い

この２つあるの知らなかった

実際のデータベースでは B-tree の変種である B+tree がよく使われるらしい

構造の違い

特性 B-tree B+tree
データ格納場所 全ノード リーフノードのみ
リーフの連結 なし リンクリストで連結
内部ノード キー + データ キーのみ

B+tree の構造

                    [Root Node]
                [  30 |    70  |   90  ]
               /         |           \          \
              /          |            \          \
[10|20]    [40|50|60]  [75|80]  [95|100]
    ↓                ↓                ↓            ↓
[Data] ←→ [Data] ←→ [Data] ←→[Data]
              リンクリストで連結

B+tree のメリット

  1. 内部ノードにデータがない

    • より多くのキーを格納可能
    • 木の高さがさらに低くなる

  2. リーフノードの連結

    • 範囲検索が高速
    • WHERE age BETWEEN 20 AND 30 などで威力を発揮

  3. シーケンシャルアクセス

    • ORDER BY が効率的
    • フルスキャンもリーフを順番に辿るだけ

インデックスの種類と B-tree

RDBMSでの使用例

RDBMS デフォルトインデックス 備考
MySQL (InnoDB) B+tree クラスタインデックスを採用
PostgreSQL B-tree GiST、GIN など他も選択可能
SQLite B-tree テーブル自体も B-tree で格納
Oracle B-tree B*tree（変種）を使用

クラスタインデックス vs セカンダリインデックス

クラスタインデックス（主キー）

B+tree のリーフノード = 実際の行データ

セカンダリインデックス（その他のインデックス）

B+tree のリーフノード = 主キーへの参照
→ 主キーのB+treeを再度検索（二重検索）

B-tree が得意なクエリ

完全一致検索

SELECT * FROM users WHERE id = 12345;
-- O(log n) で高速

範囲検索

SELECT * FROM orders WHERE created_at BETWEEN '2024-01-01' AND '2024-12-31';
-- リーフノードの連結リストを活用

プレフィックス検索

SELECT * FROM products WHERE name LIKE 'iPhone%';
-- 前方一致は B-tree で対応可能

ソート

SELECT * FROM users ORDER BY created_at DESC LIMIT 10;
-- インデックス順 = ソート順なので追加のソート不要

B-tree が苦手なクエリ

後方一致・中間一致

SELECT * FROM users WHERE email LIKE '%@gmail.com';
-- フルスキャンが必要
-- 対策: 全文検索インデックス、または逆順カラムを追加

否定条件

SELECT * FROM users WHERE status != 'deleted';
-- インデックスが効きにくい

関数・演算を含む条件

SELECT * FROM users WHERE YEAR(created_at) = 2024;
-- インデックスが使われない
-- 対策: WHERE created_at >= '2024-01-01' AND created_at < '2025-01-01'

カーディナリティが低いカラム

SELECT * FROM users WHERE gender = 'male';
-- 値の種類が少ない（true/false、性別など）カラムは効果が薄い

インデックス設計のベストプラクティス

1. 複合インデックスの順序

-- クエリ
SELECT * FROM orders 
WHERE user_id = 123 
  AND status = 'shipped'
ORDER BY created_at DESC;

-- 効果的なインデックス
CREATE INDEX idx_orders ON orders(user_id, status, created_at);

原則: 等価条件 → 範囲条件 → ソートの順

2. カバリングインデックス

-- クエリ
SELECT id, name FROM users WHERE email = 'user@example.com';

-- インデックスだけで完結（テーブルアクセス不要）
CREATE INDEX idx_users_email ON users(email, id, name);

3. インデックスの過剰作成を避ける

  • INSERT/UPDATE/DELETE のたびにインデックスも更新
  • インデックスが多いとストレージ消費も増加
  • 本当に必要なインデックスを見極める

実行計画で確認の仕方

PostgreSQL

EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'user@example.com';

Index Scan using idx_users_email on users  (cost=0.42..8.44 rows=1 width=...)
  Index Cond: (email = 'user@example.com'::text)
  Actual time: 0.025..0.026 rows=1 loops=1

参考資料

【つぶやき】人が書いたskillとかcommandに愛着が湧かない

つぶやき AI ClaudeCode

人が書いたClaudeCodeのskillとかcommandに愛着が湧かないという意見を聞いた

これはチーム開発する上で、モチベーションの低下（誰かがやってくれる）に繋がりそうな新しい課題かも

この辺りをChatGPTにぼんやり相談

愛着が湧かない理由

  • 自分の意思決定の痕跡がない
    skill / command は設計思想やトレードオフの集合体
    そこに自分の判断が入ってないと「ただの成果物」になる

  • 編集する動機が弱い
    「動いてるし触らなくていいか」になりがち
    結果として ownership が生まれない

  • ClaudeCode という名前自体が“人”を感じさせない
    作者が見えないコードは、責任も感情も乗りにくい

そのままだと起きそうなこと

結論から言うと、モチベ低下の方向に倒れやすい構造だと思う
特にこうなる可能性が高い

  • 「誰かがメンテするでしょ」思考が広がる
  • skill / command が触ってはいけない神殿になる
  • 不満はあるけど誰も直さない → 属人化 or 放置

愛着を湧かせるための具体策

精神論じゃなく、構造で解決するのが大事

1. 「共同所有」にしない（あえて）

全員のもの = 誰のものでもない、になりがち

  • skill / command ごとに オーナーを明示
  • README に「この設計を決めた人」を書く（途中で変わってOK）

→ 名前があるだけで、扱いがかなり変わる

2. 一度“壊して”再構築する

既存のものをそのまま使うと愛着は湧きにくい

  • 既存 skill を 一度写経 or 分解
  • 「ここは自分ならこうする」を最低1箇所入れる
  • 変更ログに「why」を書く

→ 1ミリでも自分の判断が入ると、一気に“自分のコード”になる

3. skill / command を「プロダクト扱い」する

単なる補助コードだと温度が上がらない

  • 目的・ユーザー（誰が楽になるか）を書く
  • 使われなかったら消す前提にする
  • 小さくても 改善リリースノートを書く

→ 「使われる／評価される」ものになると愛着が乗る

4. 「誰かがやってくれる」を逆手に取る

これ自体は悪じゃない
問題は可視化されてないこと

  • 「今月この skill を触った人」ログを残す
  • 改善した人の名前が残る仕組みにする

→ ゲーム的だけど、チームには効く

所感

とりあえず写経して、自分なりの書き方に変えてみるか、付け足してみるとかが良さそう

【Claude Code】Claude Code の開発者 がシェアした10個の Tips

ClaudeCode AI Anthropic 開発効率化

Claude Code 開発者 Boris Cherny 氏が共有する10個の Tips が話題になったのでメモ

Claude Code チームから集めた10個の Tips ではあるが、チームメンバーそれぞれの使い方は異なり、「正解」は一つではないという前提で、実践的なテクニックが紹介している

1. 並列作業を最大化する

Git worktrees を使って 3〜5 個のセッションを同時に実行する。 これがチームからの一番の生産性向上 Tips。

# worktree を作成
git worktree add ../project-feature-a feature-a
git worktree add ../project-feature-b feature-b
git worktree add ../project-analysis main

実践的なセットアップ

  • worktree に名前を付け、シェルエイリアス（za, zb, zc）で瞬時に切り替え
  • 分析専用の worktree を用意し、ログ確認や BigQuery 実行に使用
  • Claude Desktop アプリには worktree のネイティブサポートが組み込まれている

参考: Run parallel Claude Code sessions with git worktrees

2. 複雑なタスクは Plan Mode から始める

計画に全力を注げば、Claude が実装を一発で仕上げてくれる

チームの実践方法

  • ダブル Claude 戦略: 1つ目の Claude に計画を書かせ、2つ目の Claude がスタッフエンジニアとしてレビュー
  • 軌道修正: 何かがうまくいかなくなったら、すぐに Plan Mode に戻って再計画。無理に push し続けない
  • 検証にも Plan Mode: 実装だけでなく、検証ステップでも明示的に Plan Mode を指示

3. CLAUDE.md に投資する

間違いを修正したら、必ずこう伝える：

"Update your CLAUDE.md so you don't make that mistake again."

Claude は自分自身のためのルールを書くのが驚くほど上手い。

ベストプラクティス

  • CLAUDE.md を継続的に編集し、Claude のミス率が測定可能なレベルで下がるまで改善を続ける
  • タスク/プロジェクトごとに notes ディレクトリを維持させ、PR ごとに更新。CLAUDE.md からそのディレクトリを参照

4. 独自のスキルを作成して Git にコミット

プロジェクトを跨いで再利用可能なスキルを構築する。

チームからの Tips

ユースケース スキル/コマンド例
日常的な作業 1日に1回以上やることはスキル化
技術的負債 /techdebt コマンドでセッション終了時に重複コードを検出・削除
コンテキスト同期 Slack、GDrive、Asana、GitHub の7日分を1つのコンテキストにまとめるコマンド
データエンジニアリング dbt モデルの作成、コードレビュー、dev 環境でのテストを行うエージェント

5. バグ修正は Claude に任せる

実践的なワークフロー

# Slack MCP を有効化して、バグスレッドを貼り付けるだけ
"fix"

# CI テストの修正
"Go fix the failing CI tests."

# 分散システムのトラブルシュート
"Check the docker logs and fix the issue"

コンテキストスイッチングをゼロに

「どうやって」は指示せず、結果だけを求める

6. プロンプティングをレベルアップ

a. Claude に挑戦させる

"Grill me on these changes and don't make a PR until I pass your test."

Claude をレビュアーとして使う。または：

"Prove to me this works"

main ブランチと feature ブランチの振る舞いの差分を Claude に示させる

b. より良い解決策を求める

中途半端な修正の後に：

"Knowing everything you know now, scrap this and implement the elegant solution"

c. 詳細な仕様を書く

作業を渡す前に曖昧さを減らす

具体的であればあるほど、出力の質が上がる

7. ターミナル環境のセットアップ

推奨ツール

Ghostty がチームで人気

理由：

生産性向上のセットアップ

設定 効果
/statusline コンテキスト使用量と現在の Git ブランチを常に表示
ターミナルタブの色分け・命名 タスク/worktree ごとに識別しやすく（tmux 使用も可）
音声入力 タイピングの3倍速。プロンプトがより詳細に（macOS: fn キーを2回押し）

8. サブエージェントを活用する

a. 計算リソースを増やす

リクエストの末尾に追加：

"use subagents"

より多くの計算リソースを問題に投入したい場合に有効

b. コンテキストウィンドウをクリーンに保つ

個別のタスクをサブエージェントにオフロードし、メインエージェントのコンテキストを集中させる

c. 権限リクエストの自動化

Hook を使って権限リクエストを Opus 4.5 にルーティング

安全なものは自動承認

参考: Permission Request Hooks

9. データ分析に Claude を使う

# BigQuery CLI を使った分析
"Use bq CLI to pull the metrics for last week's user signups"

チームは BigQuery スキルをコードベースにコミットしており、全員が Claude Code 内で直接分析クエリを実行している

Boris 本人は6ヶ月以上 SQL を1行も書いていないとのこと

CLI、MCP、API があるデータベースなら何でも対応可能

10. Claude で学習する

a. 出力スタイルを変更

/config で "Explanatory" または "Learning" 出力スタイルを有効化

Claude が変更の「なぜ」を説明してくれる

b. ビジュアルプレゼンテーションの生成

"Generate a visual HTML presentation explaining this unfamiliar code"

Claude は意外と良いスライドを作る

c. ASCII ダイアグラム

"Draw ASCII diagrams of this protocol/codebase to help me understand"

新しいプロトコルやコードベースの理解に有効

d. 間隔反復学習スキル

自分の理解を説明 → Claude がギャップを埋めるフォローアップ質問 → 結果を保存、という学習フローを構築

【ClaudeCode】Best Practices（公式）を眺める

ClaudeCode

Anthropic 公式ドキュメントにある Best Practices のページを読む

code.claude.com

最重要ルール：コンテキストウィンドウの管理

なぜコンテキストが重要か

ほとんどのベストプラクティスは一つの制約に基づいている：

Claude のコンテキストウィンドウはすぐに埋まり、埋まると性能が低下する

コンテキストウィンドウには以下が含まれる：

  • 会話全体
  • Claude が読んだすべてのファイル
  • すべてのコマンド出力

一回のデバッグセッションやコードベース探索で、数万トークンを消費することもある

コンテキストが埋まると起きること

状態 影響
余裕あり 正確な応答、指示の遵守
埋まりつつある 初期の指示を「忘れ」始める
満杯に近い ミスの増加、矛盾した出力

対策

  • カスタム statusLine でコンテキスト使用量を常時監視
  • /clear コマンドで定期的にクリア
  • サブエージェントで調査を分離

ここで、カスタム statusLine とは ~/.claude/statusline.sh を作って ~/.claude/settings.json に

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

と記載しておくと、以下のような表示をさせておけるというもの

https://code.claude.com/docs/en/statusline
Claude Code statusline完全ガイド｜設定方法とカスタマイズ例 #ClaudeCode - Qiita

原則1: 検証手段を与える

最もレバレッジの高い行動

テスト、スクリーンショット、期待される出力を提供し、Claude が自分自身をチェックできるようにする

検証手段がないと、Claude は「正しそうに見える」が実際には動かないものを生成する可能性がある

すべてのフィードバックループが人間依存になり、すべてのミスに人間の注意が必要になる

Before / After 比較

戦略 Before After
検証基準の提供 「メールアドレスを検証する関数を実装して」 「validateEmail関数を書いて。テストケース: user@example.com → true, invalid → false, user@.com → false。実装後にテストを実行して」
UI変更の視覚的検証 「ダッシュボードを見やすくして」 「[スクリーンショット貼付] このデザインを実装して。結果のスクリーンショットを撮って元と比較。差異をリストアップして修正」
根本原因への対処 「ビルドが失敗している」 「ビルドがこのエラーで失敗: [エラー貼付]。修正してビルド成功を確認。エラー抑制ではなく根本原因に対処」

検証方法の例

検証手段の種類
├── テストスイート
├── リンター
├── スクリーンショット比較
├── 出力をチェックするBashコマンド
└── Chrome拡張でのUI検証

原則2: 探索 → 計画 → 実装

なぜ段階を分けるか

Claude にいきなりコーディングさせると、間違った問題を解決するコードが生成されることがある。Plan Mode を使って探索と実行を分離する

推奨ワークフロー

Phase 1: 探索（Plan Mode）
↓
Phase 2: 計画（Plan Mode）
↓
Phase 3: 実装（Normal Mode）
↓
Phase 4: コミット

各フェーズの詳細

Phase 1: 探索

Plan Mode に入り、Claude にファイルを読ませ、変更なしで質問に答えさせる

/src/auth を読んで、セッションとログインの処理方法を理解して。
シークレット用の環境変数の管理方法も確認して。

Phase 2: 計画

詳細な実装計画を作成させる

Google OAuthを追加したい。どのファイルを変更する必要がある？
セッションフローは？計画を作成して。

Ctrl+G でテキストエディタで計画を開き、直接編集可能

Phase 3: 実装

Normal Mode に戻り、計画に沿って実装させる

計画に基づいてOAuthフローを実装して。
コールバックハンドラのテストを書いて、テストスイートを実行し、
失敗があれば修正して。

Phase 4: コミット

説明的なメッセージでコミットしてPRを開いて

計画をスキップすべきとき

スキップOK 計画すべき
タイポ修正 アプローチが不確実
ログ行追加 複数ファイルの変更
変数名変更 不慣れなコードの修正
1文でdiffを説明可能 複雑なリファクタリング

原則3: 具体的なコンテキストを提供

曖昧さを減らす

Claude は意図を推測できるが、心を読むことはできない

具体的なファイル参照、制約の言及、パターンの指示が重要

Before / After 比較

戦略 Before After
タスクのスコープ 「foo.pyのテストを追加して」 「foo.pyのテストを書いて。ユーザーがログアウトしている場合のエッジケースをカバー。モックは避けて」
ソースの指定 「ExecutionFactoryのAPIがなぜ変なの？」 「ExecutionFactoryのgit履歴を調べて、APIがどのようにして今の形になったかまとめて」
既存パターンの参照 「カレンダーウィジェットを追加して」 「ホームページの既存ウィジェットの実装パターンを見て。HotDogWidget.phpが良い例。同じパターンでカレンダーウィジェットを実装して」
症状の記述 「ログインバグを直して」 「ユーザーがセッションタイムアウト後にログイン失敗と報告。src/auth/の認証フローをチェック、特にトークンリフレッシュ。問題を再現する失敗テストを書いてから修正」

リッチコンテンツの活用

方法 説明
@ でファイル参照 コードの場所を説明する代わりに
画像を直接貼付 コピペまたはドラッグ&ドロップ
URLを提供 ドキュメントやAPI参照用
データをパイプ cat error.log | claude

原則4: コンテキストの効率的な管理

サブエージェントの活用

コンテキストが最も重要な資源である以上、サブエージェントは最も強力なツールの一つ

サブエージェントを使って、認証システムがトークンリフレッシュを
どのように処理しているか調査して。再利用できる既存のOAuth
ユーティリティがあるかも確認して。

サブエージェントの利点：

側面 メインセッション サブエージェント
コンテキスト 共有（埋まる） 分離（報告のみ）
用途 実装 調査・レビュー
出力 詳細なコード サマリー

チェックポイントと巻き戻し

Claude は変更前に自動的にチェックポイントを作成。Escape を2回押すか /rewind で巻き戻しメニューを開く

復元オプション
├── 会話のみ復元
├── コードのみ復元
├── 両方を復元
└── 選択したメッセージから要約

リスキーなことを試して、うまくいかなければ巻き戻して別のアプローチを試すことが可能

セッションの再開

claude --continue    # 最新の会話を再開
claude --resume      # 最近の会話から選択

/rename でセッションに説明的な名前を付けて後で見つけやすくする（例: "oauth-migration", "debugging-memory-leak"）

自動化とスケーリング

ヘッドレスモード

claude -p "プロンプト" で対話なしに実行。CI パイプライン、pre-commit フック、自動化ワークフローに統合可能

# 単発クエリ
claude -p "このプロジェクトが何をするか説明して"

# スクリプト用の構造化出力
claude -p "すべてのAPIエンドポイントをリスト" --output-format json

# リアルタイム処理用ストリーミング
claude -p "このログファイルを分析" --output-format stream-json

並列セッション

方法 説明
Claude Desktop 複数のローカルセッションを視覚的に管理
Claude Code on the web Anthropic のセキュアクラウドで分離VMで実行
Agent teams 共有タスク、メッセージング、チームリードによる自動調整

Writer/Reviewer パターン

Session A (Writer) Session B (Reviewer)
APIエンドポイント用のレートリミッターを実装して
@src/middleware/rateLimiter.ts のレートリミッター実装をレビュー。エッジケース、レースコンディション、既存ミドルウェアパターンとの一貫性を確認
レビューフィードバック: [Session Bの出力]。これらの問題に対処して

ファンアウト（大規模処理）

# 1. タスクリストを生成
# 例: 「移行が必要な2,000個のPythonファイルをリスト」

# 2. ループスクリプト
for file in $(cat files.txt); do
  claude -p "$file をReactからVueに移行。OKかFAILを返して" \
    --allowedTools "Edit,Bash(git commit *)"
done

# 3. 最初の2-3ファイルでテスト、その後本番実行

よくある失敗パターン

1. キッチンシンクセッション

症状: 1つのタスクで始め、無関係なことを聞き、また最初のタスクに戻る。コンテキストが無関係な情報で埋まる。

対策: 無関係なタスク間で /clear

2. 繰り返しの修正

症状: Claude が間違える → 修正指示 → まだ間違い → 再度修正。コンテキストが失敗したアプローチで汚染される。

対策: 2回失敗したら /clear して、学んだことを組み込んだより良い初期プロンプトを書く

3. 過剰指定の CLAUDE.md

症状: CLAUDE.md が長すぎて、重要なルールがノイズに埋もれて Claude が半分を無視する。

対策: 容赦なく剪定。Claude が指示なしで正しく行うことは削除するかフックに変換

4. 信頼してから検証のギャップ

症状: Claude がもっともらしい実装を生成するが、エッジケースを処理していない。

対策: 常に検証手段（テスト、スクリプト、スクリーンショット）を提供。検証できないものは出荷しない

5. 無限の探索

症状: スコープを限定せずに「調査して」と依頼。Claude が数百のファイルを読み、コンテキストが埋まる。

対策: 調査を狭くスコープするか、サブエージェントを使って探索がメインコンテキストを消費しないようにする

直感を育てる

パターンは出発点

このガイドのパターンは固定されたルールではない

一般的にうまく機能する出発点だが、すべての状況に最適とは限らない

コンテキストを蓄積させるべき時: - 1つの複雑な問題に深く取り組んでいて、履歴が価値を持つ場合

計画をスキップすべき時: - タスクが探索的で、Claude にまかせて様子を見たい場合

曖昧なプロンプトが適切な時: - 制約をかける前に Claude がどう解釈するか見たい場合

学びを蓄積する

  • Claude が優れた出力を生成したとき、何をしたかに注目（プロンプト構造、提供したコンテキスト、モード）
  • Claude が苦労したとき、なぜかを問う（コンテキストがノイジー？プロンプトが曖昧？タスクが大きすぎ？）

時間とともに、ガイドでは捉えられない直感が育つ。

まとめ

Claude Code ベストプラクティスの要点

原則 キーポイント
コンテキスト管理 最も重要な資源。使用量を監視し、定期的にクリア
検証手段を提供 最もレバレッジの高い行動。テスト、スクリーンショット、期待出力
探索→計画→実装 間違った問題を解決しないために段階を分ける
具体的なコンテキスト 曖昧さを減らし、修正回数を減らす
サブエージェント活用 調査を分離してメインコンテキストをクリーンに
自動化とスケーリング ヘッドレスモード、並列セッション、ファンアウト

参考資料

【Design Token】デザイントークンの命名規則

Figma Design Token

5年前に読んだDesignTokenの命名の話

medium.com

久々に読み直してみて、まとめてなかったのでまとめる

デザイントークンとは

デザイントークンは、色、フォント、スペーシングなどのビジュアルスタイルを一元管理するための仕組み

2014年に Salesforce が先駆けて導入し、現在では多くのデザインシステムで採用されている

効果的なトークン名は、デザイン、コード、ドキュメント間でチームの共通理解を向上させる

ツールでの検索・閲覧時に、意図した決定を素早く認識・想起できることが重要

デザイントークンの構造化がなぜ必要か

構造化してない世界で起きること

color: colors.black900;
background: colors.gray0;

こういう実装をしていると、次の瞬間に辛くなる

  • dark modeやりたい
  • コントラスト基準変わった
  • Primary textを少し弱くしたい
  • 特定の画面だけトーン変えたい

→ 「どこで使われてるか全部探す」が地獄

構造化＝「意味の層」を作ること

トークンを構造化するとは

値（raw）
  ↑
意味（semantic）
  ↑
用途（component）

例

// raw
black900 = "#111";

// semantic
text.primary = black900;

// component
<CardTitle color={theme.text.primary} />

コンポーネントが「色」を知らないことが重要

構造化すると何が良くなるか

① 変更の影響範囲が一気に狭くなる

「Primary text、少し薄くしたい」

  • ❌ 非構造化 → 全コンポーネント修正
  • ✅ 構造化 → text.primary の割当を1行変えるだけ

② dark mode / theme切替が自然に入る

text.primary =
  light ? black900 : gray0;

コンポーネントは一切変更なし

これが Nathan Curtis の言う token taxonomy（トークン分類学）

③ デザインと言語が一致する

デザイナーが言う：

「Primary text を使ってください」

これがコードでも

theme.text.primary

になる

black900 とか言い出さない世界

④ 意図しない再利用を防げる

raw色を直接使うと起きがち：

「このグレーいい感じだから流用しよ」

→ 本来 divider 用の色が text に混ざる

semanticを挟むと

  • 「これは text.primary 用か？」
  • 「divider.primary じゃない？」

という 設計上のブレーキがかかる

⑤ “将来の変更”に耐えられる

構造化してると、後からこういうことができる

  • high contrast theme
  • brand refresh
  • 特定プロダクトだけ配色違い
  • A/Bテストで配色切替

コンポーネントを壊さずに実験できる

トークン名のレベル構造

トークン名は複数の「レベル」で構成される

記事では以下の4つのグループに分類：

1. Base（基盤レベル）

トークン名のバックボーンとなる3つのレベル：

レベル 説明 例
Category 視覚的スタイルのカテゴリ color, font, space
Concept カテゴリ内の意味的なグループ feedback, action, heading
Property 適用される CSS プロパティ background, text, border 
// Category + Property
$color-background: #FFFFFF;
$color-text: #000000;

// Category + Concept + Property
$color-feedback-background-error: #B90000;
$font-heading-size-1: 64px;

2. Modifier（修飾レベル）

目的を特定するための4つの修飾レベル：

レベル 説明 例
Variant 用途による分類 primary, secondary, success, error
State インタラクティブ状態 hover, focus, disabled
Scale サイズや段階 1, 2, 3 / s, m, l / 100, 200
Mode 表示モード on-light, on-dark 
// Category + Property + Variant
$color-text-primary: #000000;
$color-text-secondary: #666666;

// Category + Concept + Property + Variant + State
$color-action-background-primary-hover: #0056b3;

// Category + Concept + Scale
$font-heading-size-1: 64px;
$font-heading-size-2: 48px;

3. Object（オブジェクトレベル）

コンポーネント固有のトークン：

レベル 説明 例
Component コンポーネント名 button, input, card
Element コンポーネント内の要素 icon, label, helper-text
Component Group コンポーネントグループ forms, navigation 
// Component + Category + Property
$input-color-border: #888888;

// Component + Element + Category + Property
$input-left-icon-color-fill: #666666;

// Component Group + Category + Property
$forms-color-border: #888888;

4. Namespace（名前空間レベル）

スコープを区別するための接頭辞：

レベル 説明 例
System システム名・略称 esds-, mds-, slds-
Theme テーマ名 ocean-, courtyard-
Domain ビジネスドメイン consumer-, retail- 
// System namespace
$esds-color-text-primary: #000000;
$mds-font-family-serif: Georgia, serif;

// Theme namespace
$aads-ocean-color-primary: #0066cc;
$aads-sands-color-primary: #d4a574;

// Domain namespace
$esds-consumer-color-marquee-text: #ffffff;

よく使われるカテゴリ

カテゴリ 別名 用途
color - 色全般
font type, typography, text タイポグラフィ
space units, dimension, spacing 余白・間隔
size sizing サイズ
elevation z-index, layer 重なり順
breakpoints media-query, responsive ブレークポイント
shadow depth 影
time animation, duration アニメーション時間

スケールの種類

タイプ 説明 例
Enumerated 列挙値 1, 2, 3, 4, 5
Ordered 順序値（Material Design スタイル） 50, 100, 200, ..., 900
Bounded 範囲値（HSL の明度など） slate-42, slate-90
Proportion 比率 1-x, 2-x, half-x
T-shirt sizes Tシャツサイズ xs, s, m, l, xl

設計原則

1. 同音異義語を避ける

type は typography の略としても、カテゴリの意味としても使われる曖昧な単語

text も同様で、typography、コンテンツ、プロパティと複数の解釈が可能

そのため、多くのチームは font を選択する傾向にある

2. 内部で同質性、外部で異質性

同じクラス内では一貫性を保ち、異なるクラス間では明確に区別する

例えば visualization（チャート用）と commerce（セール・在庫表示用）は、似た色でも別の concept として分離すべき

3. 柔軟性 vs 特異性のトレードオフ

// 柔軟だが曖昧
$color-success: #28a745;

// 特異的で明確
$color-background-success: #28a745;
$color-text-success: #155724;
$color-border-success: #c3e6cb;

柔軟なトークンは様々な場面で使えるが、意図しない使い方をされる可能性がある

特異的なトークンは用途が明確だが、トークン数が増加する

4. コンポーネント内から始めて昇格させる

// Step 1: コンポーネント固有のトークンとして定義
$input-color-border: #888888;

// Step 2: 他のコンポーネントでも同じ値を使うことが判明
// → グローバルトークンに昇格
$forms-color-border: #888888;

// Step 3: input.scss から参照を更新
// border-color: $forms-color-border;

最初からグローバルに定義するのではなく、コンポーネント固有のトークンとして始め、再利用パターンが見えてきたら昇格させる。

5. 早すぎるグローバル化を避ける

tooltip の shadow が popover や menu でも使えるかは、実際に作るまでわからない

不確実な段階でグローバルトークンを作ると、無駄な議論や名前空間の汚染につながる

実践的なトークン例

各システムの primary action hover color を比較すると、アプローチの違いが見える：

システム トークン名
Bloomberg $color-action-primary-hover
Salesforce $brand-primary-active
Orbit $color-product-normal-hover
Morningstar $color-interactive-primary-hover
Infor $ids-color-interaction-hover
Adobe Spectrum $spectrum-blue-600

命名時の注意点

完全性

すべてのレベルを含める必要はない。必要なレベルのみを含め、意図を十分に表現できれば良い

// Good: 必要最小限
$shape-tile-corner-radius: 4px;

// Bad: 冗長
$shape-tile-corner-radius-default-on-light: 4px;
$shape-tile-corner-radius-default-on-dark: 4px;

順序

一般的なパターン：

  1. Namespace が最初（$esds-, $mds-）
  2. Base レベルが中央のバックボーン
  3. Modifier が最後（特に mode は末尾に配置されることが多い）
  4. Object は namespace の後、base の前
// Namespace + Object + Category + Property + Variant + State + Mode
$esds-forms-color-border-error-focus-on-dark: #ff6b6b;

多階層性（Polyhierarchy）

同じ値が複数の概念に属する場合、エイリアスで対応：

// feedback の error として定義
$color-feedback-error: #B90000;

// forms の error text もエイリアスとして参照
$forms-color-text-error: $color-feedback-error;

【AI】 agent-browser でブラウザ操作

ClaudeCode AI

Vercel Labs がagent-browser を公開した

github.com

agent-browser は、AI エージェント向けに設計されたブラウザ自動化 CLI ツール

「AI エージェント専用のブラウザ自動化ツール」という位置づけになるらしく、単なるスクレイピングツールではなく、AI が人間の代わりにブラウザを操作することを前提に設計されている

CLI 本体は Rust で実装されており、高速な起動と軽量な動作を実現。実際のブラウザ操作は Node.js 上で Playwright を使用している。Rust バイナリが使えない環境では自動的に Node.js フォールバックモードに切り替わる

インストール

公式の推奨

npm install -g agent-browser
agent-browser install    # Chromium のダウンロード

基本的な使い方

ページを開く

agent-browser open https://example.com

スナップショットの取得

ページのアクセシビリティツリーを取得し、各要素に ref（参照ID）を付与する

agent-browser snapshot -i --json

出力例：

{"success":true,"data":{
  "refs": [
    { "@e1": { "role": "heading", "name": "Example Domain" } },
    { "@e2": { "role": "link", "name": "More information..." } },
    { "@e3": { "role": "textbox", "name": "Email" } }
  ]
}, "error": null}

Ref を使った操作

スナップショットで得た ref を使って要素を操作する：

# クリック
agent-browser click @e2

# テキスト入力
agent-browser fill @e3 "user@example.com"

# スクリーンショット
agent-browser screenshot result.png

# ブラウザを閉じる
agent-browser close

主要コマンド一覧

コマンド 説明
open <url> 指定 URL を開く
snapshot アクセシビリティツリーと refs を取得
click <ref> 要素をクリック
fill <ref> <text> テキストを入力
screenshot <file> スクリーンショットを保存
get-text <ref> 要素のテキストを取得
close ブラウザを閉じる

snapshot のオプション

# インタラクティブ要素のみ
agent-browser snapshot -i

# JSON 形式で出力
agent-browser snapshot --json

# ツリーの深さを制限
agent-browser snapshot -d 3

# 全要素（コンテンツ含む）
agent-browser snapshot -c

なぜ AI エージェントに最適なのか

1. トークン効率の大幅な改善

従来の Playwright MCP や DOM ベースのアプローチでは、AI に渡すコンテキストが肥大化しがち

agent-browser の snapshot は必要な情報のみを抽出するため、約90%のトークン削減 が報告されている

従来の方式：DOM 全体 + CSS セレクタ → 大量のトークン消費
agent-browser：snapshot + refs → 最小限のトークン

2. 決定論的な要素指定

ref を使うことで、DOM の変化や複数の類似要素があっても、AI が常に同じ要素を操作できる

CSS セレクタや XPath と比較して、操作の安定性が高い

# CSS セレクタ方式
click "button.submit-btn.primary"

# agent-browser 方式
click @e5

実践的なワークフロー例

フォーム自動入力

#!/bin/bash

# ログインページを開く
agent-browser open "https://app.example.com/login"

# スナップショットを取得
agent-browser snapshot -i --json > snapshot.json

# AI がスナップショットを解析し、入力フィールドの ref を特定
# → @e3: email, @e4: password, @e5: submit button

# フォームに入力
agent-browser fill @e3 "user@example.com"
agent-browser fill @e4 "password123"
agent-browser click @e5

# ログイン後のページを確認
agent-browser snapshot -i

デバッグモード

# GUI を表示してブラウザの動きを確認
agent-browser open --headed "https://example.com"

--headed フラグでブラウザの GUI を表示

AI エージェントの挙動を目視確認しながらデバッグできる