Claude Codeのすべての機能を活用する方法

 (blog.sshh.io)
84 ポイント 投稿者 GN⁺ 2025-11-03 | 2件のコメント | WhatsAppで共有
  • Claude Code を個人プロジェクトと企業向けモノレポ環境で広範に活用し、主要コンポーネントと高度な機能の実際の使い方を整理
  • 効果的なエージェント運用の核心は 出力スタイルやUIではなく最終PRの品質 にあり、「設定して放置（shoot and forget）」型の委任が目標
  • コードベースの中心は CLAUDE.md ファイルで、エージェントの行動規範とツール利用法を定義する「憲法」の役割を担う
  • コンテキスト管理、スラッシュコマンド、サブエージェント、Hooks、GitHub Action(GHA) など多様な機能を通じて協業と自動化の水準を向上
  • Skills と MCP(Model Context Protocol) の関係を区別し、スクリプティング中心の柔軟なエージェント構造を強調
  • Claude Codeを単なるCLIツールではなく、エンタープライズ級のAI開発インフラ へ拡張できる実践的ガイドを提供
  • Claude Codeを非常に多用している
    • 趣味プロジェクトではVM上で週に何度も実行し、--dangerously-skip-permissions で思いついたアイデアを即座にコード化
    • 業務ではチームでAI IDEのルールとツールを整備しており、私たちのエンジニアリングチームは コード生成だけで毎月数十億トークンを消費 している
  • CLIエージェント市場はClaude Code、Gemini CLI、Cursor、Codex CLIで混み合っているが、実質的な競争はAnthropicとOpenAI の2社の争い
    • ただし開発者と話してみると、ツール選定は 表面的な要素に依存 している
      • 「たまたまうまくいった」機能実装や、好みのシステムプロンプトの「雰囲気」など
    • 現時点では、これらのツールはいずれもかなり優秀な状態にある
  • 一部では 出力スタイルやUIへの過度な集中 も見られる
    • you're absolutely right! のようなおべっかは、注目すべきバグではない
    • むしろ ユーザーがループに過度に関与しているサイン だ
  • 私の中核となる利用哲学は 「Shoot and Forget」 だ
    • 委任、コンテキスト設定、作業実行 の順で進める
    • ツールは 最終PRで判断 し、到達過程ではなく成果物で評価する
  • この記事は、ここ数か月のClaude Code利用経験に基づく エコシステム全体への考察 である
    • 私が使っているほぼすべての機能（そして使っていない機能）
    • 基本的な CLAUDE.md ファイル
    • カスタムスラッシュコマンド
    • Subagent、Hook、GitHub Actionsの強力な世界
  • かなり長文になっているため、通読するよりリファレンスとして活用するのがおすすめ

CLAUDE.md: エージェントの憲法

  • ルートの CLAUDE.md は、リポジトリの動作方法に関するエージェントの主要な真実の情報源
    • 趣味プロジェクト: Claudeが好きなように自由に書く
    • エンタープライズモノレポ: 13KB規模で厳格に管理（25KBまで拡張可能）
    • エンジニアの30%以上が使うツールだけを文書化
    • 各内部ツールの文書化に最大トークン数を割り当てる（「広告枠」を売る方式）
    • ツールを簡潔に説明できないなら、CLAUDE.md の準備はまだ不十分

  • ヒントと一般的なアンチパターン

    • ガードレールから始める、マニュアルではない: Claudeが間違えやすい部分を基に小規模な文書化から始める
    • @-ファイルの文書化は禁止
      • 他所の大規模な文書を @ で参照すると、実行のたびにファイル全体がコンテキストウィンドウへ埋め込まれて肥大化する
      • 単にパスだけを記すと、Claudeは無視する傾向がある
      • エージェントに対して、なぜそのファイルを読むべきか、いつ読むべきかを「提案」 しなければならない
      • 例: 「複雑な使い方や FooBarError が発生した場合は、高度なトラブルシューティングのために path/to/docs.md を参照」
    • 「絶対ダメ」だけを言わないこと
      • 「絶対に --foo-bar フラグを使うな」のような否定形の制約は避ける
      • エージェントがそのフラグを使う必要があると思ったときに行き詰まる
      • 必ず代替案を示す
    • CLAUDE.md を強制関数として活用する
      • CLIコマンドが複雑で冗長なら、説明文を書くべきではない（人間側の問題へのパッチにすぎない）
      • 代わりに 明確で直感的なAPIを持つシンプルなbashラッパーを書き、そのラッパーを文書化する
      • CLAUDE.md をできるだけ短く保つことは、コードベースと内部ツールを単純化するための素晴らしい強制関数 になる

  • 例の構成

    # Monorepo  

## Python  
- Always ...  
- Test with <command>  
... 10개 항목 ...  

## <Internal CLI Tool>  
... 80% 사용 사례에 집중한 10개 불릿 ...  
- <usage example>  
- Always ...  
- Never <x>, prefer <Y>  

복잡한 사용법이나 오류 시 path/to/<tool>_docs.md 참조
  • AGENTS.md ファイルと同期し、エンジニアが使う他のAI IDEとの互換性を維持
  • 追加のヒント: "AI Can't Read Your Docs", "AI-powered Software Engineering", "How Cursor (AI IDE) Works" を参照

Compact, Context, Clear: コンテキストウィンドウ管理

  • /context コマンドで200kトークンウィンドウの使用状況を確認
    • Sonnet-1Mでもコンテキストウィンドウ全体が効果的に使われているかは不確か
    • モノレポの新規セッションではデフォルトで約20kトークン（10%）を消費し、残り180kは変更作業用（すぐに使い切る）
  • 3つの主要ワークフロー
    • /compact（回避）: 自動圧縮は不透明で、エラーも出やすく、最適化も不十分なので、できる限り避ける
    • /clear + /catchup（単純再起動）: 基本の再起動方式で、/clear で状態を消した後、カスタム /catchup でgitブランチの全変更ファイルを読む
    • 「Document & Clear」（複雑な再起動）: 大規模作業向けで、Claudeが計画と進捗を .md にダンプ → /clear → 新しいセッションで .md を読んで継続

カスタムスラッシュコマンド

  • スラッシュコマンドは よく使うプロンプトへの単純なショートカット にすぎず、それ以上でもそれ以下でもない
  • 最小構成
    • /catchup: gitブランチの全変更ファイルを読むためのプロンプト
    • /pr: コード整理、ステージング、PR準備のヘルパー
  • 複雑なカスタムコマンド一覧はアンチパターン
    • Claudeのようなエージェントの核心は、ほぼあらゆる自然言語入力から有用でマージ可能な結果を生成できること
    • エンジニア（あるいは非エンジニア）に、作業遂行のための「魔法のコマンド」の必須リスト習得を強いるのは失敗につながる
    • より直感的な CLAUDE.md と、より優れたツールを備えたエージェントを構築することが目標

カスタム Subagent

  • 理論上は強力なコンテキスト管理機能
    • 複雑な作業: X トークンの入力コンテキスト + Y トークンの作業コンテキスト + Z トークンの回答
    • N 個の作業 = メインウィンドウで (X + Y + Z) * N トークン
    • Subagent ソリューション: (X + Y) * N の作業を特化エージェントに委任し、最終的な Z トークンの回答のみを返す
  • 実運用でカスタム Subagent が生む 2 つの新たな問題
    • コンテキストのゲートキーピング: PythonTests Subagent を作成すると、メインエージェントからすべてのテストコンテキストが隠される → 全体的な推論が不可能に → 自身のコードをどう検証するか知るために Subagent 呼び出しが強制される
    • 人間のワークフローの強制: Claude を硬直した人間定義のワークフローに無理やり従わせる → 委任方法を指示すること自体が、エージェントが解くべき問題になる

  • 個人的には Task(...) 機能のほうを好む

    • Claude 組み込みの Task(...) 機能で汎用エージェントのクローンを作成
      • CLAUDE.md にすべての中核コンテキストを配置
      • メインエージェントが、自身のコピーへいつ・どのように作業を委任するかを決定
      • Subagent のコンテキスト節約という利点は維持しつつ、欠点は取り除く
      • エージェントが自身のオーケストレーションを動的に管理
    • "Building Multi-Agent Systems (Part 2)" で "Master-Clone" アーキテクチャと命名
      • カスタム Subagent が誘導する "Lead-Specialist" モデルよりも強く好む

Resume, Continue, History

  • 基本レベルの活用
    • claude --resume と claude --continue を頻繁に使用
    • バグのあるターミナルの再起動、または古いセッションの迅速な再始動
    • 数日前のセッションを claude --resume し、特定のエラーをどう克服したかを要約 → CLAUDE.md と内部ツールを改善
  • 高度な活用
    • Claude Code はすべてのセッション履歴を ~/.claude/projects/ に保存
    • 生の履歴セッションデータを活用するスクリプトを保有
    • ログに対してメタ分析を実行: 共通例外、権限リクエスト、エラーパターンを検索 → エージェント向けコンテキストを改善

Hooks

  • エンタープライズのリポジトリでは重要: 趣味プロジェクトでは未使用
  • CLAUDE.md の "should-do" 提案を補完する決定論的な "must-do" ルール
  • 2 つのタイプ
    • コミット段階をブロックする Hook (Block-at-Submit): 主要戦略
      • PreToolUse Hook で、すべての Bash(git commit) コマンドをラップ
      • /tmp/agent-pre-commit-pass ファイルを確認（テストスクリプトが全テスト通過時のみ作成）
      • ファイルがなければコミットをブロック → ビルド成功まで Claude を「テスト→修正」ループに強制
    • ヒント Hook: 単純な非ブロッキング Hook で、エージェントが次善策を取ったときに「fire-and-forget」型のフィードバックを提供
  • 書き込み段階をブロックする Hook は意図的に使わない (Edit または Write 時)
    • 計画の途中でエージェントを止めると、混乱や「フラストレーション」を招く
    • 作業完了後、コミット段階で最終成果を確認するほうがはるかに効果的

プランニングモード

  • AI IDE で「大規模な」機能変更を行う際はプランニングが必須
  • 趣味プロジェクト: 組み込みのプランニングモードを専用で使用
    • Claude 開始前に足並みをそろえる方法
    • ビルド方法と、作業を中断して結果を表示すべき「検査チェックポイント」を定義
    • 定期的な使用により、Claude が実装を台無しにせず良い計画を得るために必要な最小コンテキストについて、強い直感を構築
  • エンタープライズのモノレポ: Claude Code SDK ベースのカスタムプランニングツールの展開を開始
    • ネイティブのプランモードに似ているが、既存の技術設計フォーマットに出力を合わせることに集中したプロンプト
    • コード構造からデータプライバシー、セキュリティまで、社内ベストプラクティスの強制を標準搭載
    • エンジニアがシニアアーキテクトのように新機能を「vibe plan」できる（少なくともそういう提案）

Skills

  • Simon Willison の意見に同意: Skills は（おそらく）MCP より大きなディール
  • エージェント自律性のメンタルモデル、3 段階の進化
    • Single Prompt: すべてのコンテキストを 1 つの巨大なプロンプトとしてエージェントに渡す（脆弱で、スケールしない）
    • Tool Calling: 「古典的な」エージェントモデル。ツールを手作業で作り、エージェント向けに現実を抽象化する（改善はしたが、新たな抽象化とコンテキストのボトルネックを生む）
    • Scripting: エージェントに生の環境アクセスを与える（バイナリ、スクリプト、ドキュメント）→ エージェントがその場でコードを書いて相互作用する
  • Agent Skills は明らかな次の機能: 「Scripting」レイヤーの正式な製品化
  • CLI を MCP より好む なら、すでに暗黙のうちに Skills の利点を得ている
    • SKILL.md ファイルは、こうした CLI やスクリプトを文書化し、エージェントに公開するより整理され、共有可能で、発見しやすい方法
  • Skills は正しい抽象化: MCP が表す硬直した API 的モデルよりも、より堅牢で柔軟な「スクリプティング」ベースのエージェントモデルを正式化する

MCP (Model Context Protocol)

  • Skills があるからといって MCP が死んだわけではない（"Everything Wrong with MCP" 参照）
  • 以前の問題点: 多くの人が、REST API をミラーした数十個のツールで、ひどくコンテキストの重い MCP を構築していた（read_thing_a(), read_thing_b(), update_thing_c()）
  • 「Scripting」モデル（Skills によって正式化）がよりよい方法だが、環境アクセスのための安全な方法が必要 → MCP の新しく、より焦点の絞られた役割

  • MCP の新たな役割: データゲートウェイ

    • 肥大化した API の代わりに、少数の強力な高レベルツールを提供するシンプルで安全なゲートウェイ
      • download_raw_data(filters…)
      • take_sensitive_gated_action(args…)
      • execute_code_in_environment_with_state(code…)
    • MCP の役割: エージェント向けの現実抽象化ではなく、認証・ネットワーキング・セキュリティ境界を管理したら、その後は邪魔をしないこと
      • エージェント用の入口を提供 → エージェントはスクリプティングと markdown コンテキストで実作業を行う
    • 現在使っている唯一の MCP: Playwright（複雑で状態を持つ環境なので妥当）
      • すべてのステートレスなツール（Jira、AWS、GitHub）は単純な CLI に移行

Claude Code SDK

  • Claude Codeは対話型CLIであるだけでなく、コーディング作業・非コーディング作業の両方に対応する、まったく新しいエージェント構築のための強力なSDK
  • 最近の個人プロジェクトの大半では、LangChainやCrewAIのようなツールよりも、標準のエージェントフレームワークとして使い始めている
  • 主な使い方は3つ
    • 大規模並列スクリプティング: 大規模リファクタリング、バグ修正、移行時には対話チャットを使わない
      • claude -p &quot;in /pathA change all refs from foo to bar&quot; を並列実行するシンプルなbashスクリプトを書く
      • メインエージェントに数十個のSubagentタスクを管理させるより、はるかにスケーラブルで制御しやすい
    • 社内チャットツールの構築: 非技術系ユーザー向けに、複雑なプロセスをシンプルなチャットインターフェースでラップするのに最適
      • 例: エラー時にClaude Code SDKへフォールバックしてユーザー問題を解決するインストーラー
      • 例: デザインチームが社内UIフレームワークでモックアップのフロントエンドをvibe-codeできる社内版「v0-at-home」ツール（アイデアの高忠実度を担保し、フロントエンドの本番コードにもより直接使える）
    • 迅速なエージェントプロトタイピング: 最も一般的なユースケースで、コーディング専用ではない
      • エージェント作業のアイデア（例: カスタムCLIまたはMCPを使う「脅威調査エージェント」）があるとき
      • 完全なデプロイスキャフォールドをコミットする前に、Claude Code SDKでプロトタイプを素早く構築してテストする

Claude Code GitHub Action (GHA)

  • 最も気に入っていて、しかも過小評価されている機能の1つ: コンセプトは単純（GHAでClaude Codeを実行すること）だが、その単純さこそが強さの源泉
  • Cursorのバックグラウンドエージェント や CodexのマネージドWeb UIに似ているが、はるかにカスタマイズしやすい
    • コンテナと環境全体を制御できる → データアクセス性が向上
    • 他製品よりもはるかに強力なサンドボックス化と監査制御
    • HookやMCPのようなすべての高度な機能をサポート

  • 活用例

    • カスタム「どこからでもPR」ツールの構築
      • Slack、Jira、さらにはCloudWatchアラートからもPRをトリガー可能
      • GHAがバグ修正または機能追加の後、完全にテスト済みのPRを返す
    • データ駆動のフライホイール
      • GHAログ = エージェントの完全なログ
      • 会社レベルで定期的にログをレビュー: 共通ミス、bashエラー、足並みのそろっていないエンジニアリング慣行を発見
      • フライホイール: バグ → CLAUDE.md/CLI改善 → より良いエージェント
      • $ query-claude-gha-logs --since 5d | claude -p &quot;see what the other claudes were getting stuck on and fix it, then put up a PR&quot;

settings.json

  • 個人作業でも業務でも不可欠な特定の設定
  • HTTPS_PROXY/HTTP_PROXY: デバッグ用
    • 生のトラフィックを検査して、Claudeが送信している正確なプロンプトを確認
    • バックグラウンドエージェント向けには、細かなネットワークサンドボックス化の強力な手段
  • MCP_TOOL_TIMEOUT/BASH_MAX_TIMEOUT_MS: 値を増やす
    • 長く複雑なコマンドを実行することを好み、デフォルトタイムアウトはしばしば保守的すぎる
    • bashのバックグラウンド作業の後もまだ必要かは不明だが、念のため維持している
  • ANTHROPIC_API_KEY: 業務ではエンタープライズAPIキーを使用（apiKeyHelper 経由）
    • 「1席あたり」ライセンスから「従量課金」価格へ移行（この働き方にははるかに適したモデル）
    • 開発者ごとの利用量の大きな差を考慮（エンジニア間で1:100の差を確認）
    • エンジニアが単一のエンタープライズアカウントで、Claude Code以外のLLMスクリプトも試せる
  • &quot;permissions&quot;: Claudeに自動実行を許可したコマンド一覧を定期的にセルフ監査

まとめ

  • 内容は多いが、役立てばうれしい
  • Claude CodeやCodex CLIのようなCLIベースのエージェントをまだ使っていないなら、使うべき
  • こうした高度な機能に関する良いガイドはほとんどなく、学ぶ唯一の方法は自分で飛び込むこと

関連記事

2件のコメント

 
GN⁺ 2025-11-03
Hacker Newsの意見

  • 私たちは、他のAI IDEとの互換性のためにファイルを AGENTS.md と同期している
    最近調べたところ、Anthropicが推奨する方法は CLAUDE.md に @AGENTS.md の1行だけを書き、実際の内容は AGENTS.md に置くことらしい
    関連ドキュメント: Claude Code Best Practices

    • この点については、標準をそろえるために CLAUDE.md を AGENTS.md に リネームすべきだと思う
    • 私たちは AGENTS.md から CLAUDE.md へ シンボリックリンクを張って使っているが、うまく動いている
    • そのほうが少しすっきりした方法に思える
    • シンボリックリンクを使うのは良いアイデアなのか気になる
    • 私の経験では、Claude や他のエージェントは、各セッションで明示的に指示しない限り、AGENTS.md や CLAUDE.md を実際には読まない

  • MCPについてのこの文章が本当に気に入った
    「MCPは複雑なAPIではなく、認証、ネットワーキング、セキュリティ境界を管理し、あとは一歩引く 簡潔なゲートウェイであるべきだ」という視点が良い
    関連記事

    • MCPが最初に出てきたときは、こんな用途は想像できなかったが、今では Claude が複数の『ツール』より データスクリプティングを求めているように感じる。私の役割は、ただデータをうまく渡すことだけだ
    • 私のMCPはコードインタープリタが1つあるだけだ。最近は、MCPをコードインタープリタの中から呼び出せる プロキシMCP を試している
      それでもMCPはほとんど使わない。認証(auth)のほうに集中してほしい
      参考リンク: Xの投稿
    • 内部向けの APIゲートウェイ としてMCPを使うと、このように動作する。実質的にはOpenAPIに近いが、LLMの推論にもう少し最適化された形だ

  • 3000語の文章が「長いので参考用としてだけ見る」扱いなのは少し残念だ
    実例入りのもっと長いバージョンを見てみたい

    • 最近は、人々が文章をどれだけ読むかについて 悲観的になっている
    • 私も期待していたが、内容が限定的で残念だった。それでも、いくつか有用なポイントは得られた

  • /clear と /catchup で Claude の状態を初期化し、変更されたファイルを再読込させる シンプルな再起動ルーチンを使っている
    おそらく近いうちに /compact コマンドがこの役割を担うようになるだろう

    • /compact は レイテンシ のせいで、ほとんど使いものにならない
      「0% context remaining」と表示されても、実際には約30%が圧縮用に予約されている
      それなのに、半分くらいは圧縮に失敗するか、API制限に引っかかる

  • Claude Codeを使って 自分の設定を改善するのもよい
    planモードに切り替えて、次のプロンプトを使ってみることを勧める:
    「この文書(How I use every Claude Code feature)を読んで、私のClaude Code設定を改善する方法を教えて」

  • CLAUDE.md の簡単な命令でさえ Claude があまり従わないので、メンテナンスをあきらめた
    たとえば、生成されるスクリプト名を <foo>.aigen.ts にしろと言っても、半分は無視する
    そのため、毎回プロンプトに直接コンテキストを入れる形で回避している
    もしかして、こういう問題に悩んでいるのは私だけだろうか?

    • 私の CLAUDE.md はかなり長いが、ほとんどいつもきちんと従う。無視するときは「IMPORTANT! ALWAYS DO …」のように 大文字で強調するよう修正すると、95%は正しく動く
      複数のプロジェクトでも似たような結果だった
    • 私も同じ経験だった。ただ、もうあきらめてしまったので、最新バージョンで改善したかは分からない
    • 私たち Claudemasters の間では、すでに知られた問題だ

  • 「CLIベースのエージェントを使っていないなら使うべきだ」という話があったが、Cursorアプリより本当に良いのか気になる
    Cursor は特定のコード部分を選択して Cmd-L で「ここを直して」と言いやすいので良い
    CLIでコード片を送るのは少し面倒に見える

    • 私は VS Code で Claude と Codex を使っているが、選択したコードに直接命令する フロー がかなりうまく機能している
    • Cursorより Codex + GPT5 や Claude Code CLI を直接使うほうが良い結果が出る。Cursor はトークン節約のために 出力サイズを縮小する補正 をしているようだ
    • 私も Cursor から始めて、ハイブリッド運用を経て、最終的には完全に CLI に移行した
      軽量なUX でも効率の面でも、そのほうが良い。Claude は CC で最もうまく動く
    • Claude は VS Code で選択したコード行を自動的に認識する
    • 複数のファイルを同時に選択してフォーカスを与えることもでき、PATH 内のコマンド(gh など)も実行可能だ

  • 「Claude Codeは単なるCLIではなく、新しいエージェントを作れるSDKだ」という文句を見て、AIが書いたような文体 だと感じてうんざりした
    読者を尊重していない感じがした

    • 私も AI生成の文章には本能的な拒否感があったが、最近は 内容そのもの で判断しようとしている
      今回の文章は、著者が自分で読んで編集した痕跡が見えるので、良い例だと思う
      一方で、AIの出力をそのままコピペするのは批判されるべきだ
    • 「インターネットは死んだ。インターネット万歳」という言葉を思い出す
    • 無理やり読まされたわけでもないのに、なぜ不快だと感じるのか分からない
      私はむしろ尊重されている感じがして、最後まで読めた

  • こうしたツールは興味深いが、業界がまたしても 顧客ではなく技術そのもの に集中しているのではないかと心配だ
    （Paul Graham の "Top idea in your mind" エッセイを思い出す）

    • その通りだ。LLMベースのコーディングツールは、速度やコスト削減のような 企業指標 には良いが、顧客が求めているのは機能と安定性だ
      速く安く作った製品がバグだらけなら意味がない
      AIも同様で、CEOたちは人員削減の手段としてしか見ていないが、この技術はまだ顧客に実質的な利益を与えられる段階ではない
      AIチャットボットは、顧客をより いら立たせる だけだ
    • 「顧客」とは何を意味しているのか気になる。私はこうしたツールを、顧客をよりよく理解するために使っている

  • Claude Code の進歩の速さは 驚くほど速い
    毎週新しいことを学ばなければならないほど、継続的に良くなっている

    • CPU とメモリの使用量を見れば、驚くことではない
      私の M4 Mac（64GB RAM）を遅くせずに機能が増えるなら、それこそ本当の 魔法 だ
 
hyeonseokoh94 2025-11-05

いいんだけど..