• #claude-code
  • #worktree
  • #workflow
  • #research
  • #svg
  • #translation
開発mdx-playgroundメモ

Claude Codeの/worktree機能とプロジェクト深掘り調査

朝のターミナルで /worktree と打ち込んだ瞬間、見慣れないディレクトリ構造が .claude/worktrees/ の下に出現した。メインツリーから完全に切り離されたブランチが、そこに静かに待機していた。

/worktree 機能を初めて試す

Claude Codeの /worktree コマンドは、gitの worktree 機能をラップしたものだ。実行すると .claude/worktrees/ 配下に新しいブランチが切られ、メインの作業ツリーとは独立して開発を進められる。

動作確認でやったこと

小さなテストとして、ワークツリー内でREADMEのポート番号を修正した。

3000 → 3200

メインツリーのREADMEは変更されず、ワークツリー側だけが書き換わる。当たり前の挙動だが、実際に手を動かして確認すると「メインを壊さずに試行錯誤できる」感覚が腹落ちする。

.gitignore への追加

ワークツリーのディレクトリはgit管理に入れる必要がないため、.gitignore に追加した。

.claude/worktrees

これでワークツリーの中身がメインリポジトリのdiffに混入しなくなる。

/worktree の使いどころ

  • 実験的な変更を本線から分離して試す
  • 破壊的リファクタリングを安全に進める
  • 複数の機能を並行して開発する（メインで記事執筆、ワークツリーでUI改修など）

まだ本格的な活用には至っていないが、「壊しても平気な砂場」が一瞬で手に入る点は覚えておきたい。

並行エージェントでプロジェクト全体を深掘り調査

mdx-playgroundの全体像を棚卸しするため、並行エージェントを使ってコードベースを徹底的に読み込ませた。Boris Tane氏のワークフローでいう「リサーチフェーズ」を自分のプロジェクトで実践した形だ。

research.md の作成

調査結果を research.md に書き出させた。表面をなぞるのではなく、ディレクトリを1つずつ潜って実態を数え上げた結果がこれだ。

項目数量
Markdownファイル622個
Vueコンポーネント194個
ルーティングページ80ページ

622個のMarkdown記事が1つのNuxtプロジェクトに詰まっている。SSGビルドでメモリが逼迫する理由が、数字を並べた瞬間に見えた。

調査で浮かんだ構造上の特徴

  • コンテンツは日付ベースのディレクトリ構成（content/YYYY-MM-DD/）
  • 財務データ・書籍OCR・教育コンテンツが同居する独特な構成
  • 画像172個、HTML 21個、Draw.io 8個がコンテンツと混在
  • Cloudflare Pages の _routes.json 100エントリ上限との戦いが続いている

研究ノートを成果物として残すことで、「次にこのプロジェクトを触るとき」の立ち上がりが段違いに速くなる。チャットログは流れるが、Markdownファイルは残る。

Boris Tane氏のClaude Code記事を日本語訳・編集

Cloudflare Engineering LeadのBoris Tane氏が公開した「How I Use Claude Code」を日本語訳し、記事として整備した。

編集で加えたもの

  1. frontmatter: title, description, path, tags, category を設定
  2. ポイントまとめ: 記事冒頭に6つの要点を箇条書きで挿入。長文を読む前に全体像をつかめるようにした
  3. ワークフロー図（SVG）: 6フェーズの流れをSVGで可視化

SVG図解の6フェーズ

リサーチ → 計画 → 注釈サイクル → Todoリスト → 実装 → フィードバック

テキストだけでは流れが頭に入りにくい。図を1枚差し込むことで、注釈サイクルが中央に位置する構造が一目で伝わるようになった。

翻訳で意識したこと

  • 原文の口語的なトーンを保つ（「ダメだ」「ぐちゃぐちゃで」など）
  • 技術用語は無理に訳さず原語併記（「shared mutable state」→「共有可変状態」）
  • 「まだ実装しないでください」のガードの重要性を、原文と同じ強度で伝える

今日の学び

  • /worktree は「一瞬で作れる使い捨てブランチ環境」。本格活用はこれからだが、存在を知っているだけで選択肢が広がる
  • research.md を書き出させる習慣は、プロジェクトの規模を数値で突きつけてくれる。622記事という数字を見て初めて、ビルド時間の問題に真正面から向き合えた
  • 翻訳記事にポイントまとめとSVG図を加えると、読者が本文に入る前に構造を把握できる。自分が後で読み返すときにも効く

関連記事