メインコンテンツへスキップ
見出し画像

【実践1ヶ月】Claude Codeで効いた設定5つと、期待外れだった設定2つ

    この記事の要点: Claude Codeを1ヶ月間、個人開発の実務で使い込んだ結果、本当に効果があった設定と、期待したほど使わなかった設定が明確に分かれました。結論から言うと、「手動で呼ぶスキル」より「CLAUDE.mdに書いて自動実行される仕組み」の方が圧倒的に定着します。CLAUDE.mdの設定術、サブエージェント委譲ポリシー、出力契約など、具体的な設定ファイルとその効果を数値付きで共有します。

    はじめに

    最初は「とりあえず全部試す」精神で、CLAUDE.mdのルール記述、サブエージェントの使い分け、スラッシュコマンド型スキルなど、思いつく限りの設定を投入しました。7つの設定を試した結果、効果が実感できたのは5つ、期待外れだったのは2つ。そして、その分かれ目には明確なパターンがありました。

    この記事では、各設定の具体的な内容と、なぜ効いた/効かなかったかの理由を、実際の設定ファイルを見せながら解説します。

    背景・きっかけ

    Claude Codeの設定自由度が高すぎる問題

    Claude Codeは設定の自由度が非常に高いツールです。`CLAUDE.md`にルールを書ける、`.claude/skills/`でスキルを定義できる、サブエージェントを呼び分けられる——AnthropicのCLAUDE.md公式ガイドにも多くの設定例が載っていますが、やれることが多すぎて、最初は「何を設定すべきか」が分かりませんでした。

    公式ドキュメント(Claude Code Overview)には機能の説明はあっても、「どの設定が実際に効くか」の優先順位は書かれていません。ネット上の情報も「こんなことができる」という紹介が中心で、「1ヶ月使った結果こうだった」という運用実績はほとんど見当たりませんでした。

    試した環境

    • プロジェクト: AI記事生成パイプライン(note.com向け記事の自動生成・校正・投稿)

    • 期間: 2026年3月初旬〜4月上旬(約1ヶ月)

    • 使用頻度: ほぼ毎日、1日あたり平均2-3セッション

    やったこと

    【効いた設定①】CLAUDE.mdに「設計ドキュメント自動生成」ルールを記述

    最も効果が大きかったのは、CLAUDE.mdに以下のようなルールを書いたことです。

    plan mode で実装計画を作成し、承認されて実装が完了したら、
    設計ドキュメントを `docs/` に保存する

    このルールのポイントは、人間が何もしなくても、Claudeが実装完了時に自動で設計ドキュメントを書き出すことです。

    導入前は、設計の意図や判断理由が頭の中にしか残らず、1週間後に「なぜこの構成にしたんだっけ?」と悩むことが頻繁にありました。導入後は、`docs/`ディレクトリに勝手にドキュメントが溜まっていきます。

    効果: 設計ドキュメント作成の手動作業 → 完全にゼロ。1ヶ月で7本のドキュメントが自動生成されました。

    【効いた設定②】CLAUDE.mdに「開発ログ自動記録」ルールを記述

    もう1つのCLAUDE.mdルールが、gitコミット後の自動ログ記録です。

    gitコミット作成後、自動でObsidianに開発ログを書き出す
    保存先: /Obsidian-Vault/dev/{プロジェクト名}/YYYY-MM-DD.md

    これにより、コミットするたびにObsidianのVaultに「何を変更したか」「なぜその判断をしたか」が自動で追記されていきます。

    開発ログは「書こうと思えば書ける」けど、忙しいときに真っ先に省略されるタスクです。CLAUDE.mdに書いておくことで、意志の力に頼らず、100%記録される仕組みになりました。

    効果: 1ヶ月で35件のコミットログが自動記録。手動で書いていた時期は週1-2回だったので、記録密度が約5倍になりました。

    【効いた設定③】エージェント委譲ポリシーの明文化

    5種類のサブエージェント(researcher、debugger、project-planner、security-reviewer、mekiki)の使い分けルールを、専用のMarkdownファイルに定義しました。

    **researcher** — 使う: 外部情報の調査、技術比較 / 使わない: コードベース内の調査
    **debugger** — 使う: 原因不明のエラー、再現困難なバグ / 使わない: エラーメッセージから原因が明白な場合
    **mekiki** — 使う: 戦略提案の品質レビュー / 使わない: 単純な調査報告

    このルールがあることで、Claudeが「この作業はresearcherに委譲すべきか、自分でやるべきか」を一貫した基準で判断できるようになりました。

    導入前の問題: 同じような調査タスクでも、あるときはメインセッションで処理し、あるときはサブエージェントに投げる、という判断のブレがありました。結果、メインセッションのコンテキストが不要な情報で汚染されることが頻発。

    導入後: 委譲判断が安定し、メインセッションのコンテキストがクリーンに保たれるようになりました。特にresearcherエージェントへの委譲が適切に行われるようになり、調査結果の品質が体感で上がりました。

    【効いた設定④】グローバル設定とプロジェクト設定の境界ルール

    Claude Codeには「グローバル設定(`~/.claude/`)」と「プロジェクト設定(プロジェクト内`.claude/`)」の2階層があります。この境界を明確にするルールを作りました。

    グローバルエージェント: 技術汎用の専門家(security-reviewer, debugger等)
    プロジェクトエージェント: ドメイン固有の専門家(cook, quality-reviewer等)
    
    衝突時はプロジェクトエージェントが優先

    これが効いたのは、複数プロジェクトで同じグローバル設定を再利用できるようになったからです。

    セキュリティレビューやデバッグの基本方針はどのプロジェクトでも共通です。一方、記事生成パイプラインのルール(テンプレート構成、SEO基準など)はこのプロジェクト固有。この分離を明文化したことで、新しいプロジェクトを始めるときに「グローバル設定はそのまま使えて、プロジェクト固有の部分だけ書けばいい」状態になりました。

    効果: 新規プロジェクトのセットアップ時間が約半分に短縮。グローバル設定(セキュリティ・デバッグ方針)はコピー不要で、プロジェクト固有ルールの記述だけで済むようになりました。

    【効いた設定⑤】出力契約(Output Contract)の標準化

    サブエージェントの出力フォーマットを標準化するルールです。

    ## 全エージェント共通ルール
    1. 固定フォーマット: 各エージェント定義に記載されたテンプレートに従う
    2. 根拠の明示: 主張にはファイルパス:行番号 または URL を付記する
    3. 確信度の明示: 判断には確信度を付ける(high / medium / low)
    4. 不明点の扱い: 推測せず「不明」と明示する

    導入前: サブエージェントの出力形式がバラバラで、あるときは長文レポート、あるときは箇条書き3行。出力を読んで「で、結局どうすればいいの?」と追加質問する手間が頻発。

    導入後: 全エージェントが根拠付き・確信度付きで出力するようになり、出力をそのまま判断材料として使えるケースが大幅に増えました。特に「確信度: low」の項目は「要追加調査」と即座に判断できるのが便利です。

    【期待外れ①】スラッシュコマンド型スキル

    `.claude/skills/`ディレクトリに定義する、`/draft`や`/polish`のようなスラッシュコマンド型スキルです。

    記事の下書き生成、校正、X投稿文の作成など、ワークフローの各ステップをスキルとして定義しました。機能としては問題なく動きます。しかし、実際の運用では思ったほど使いませんでした。

    理由は単純で、手動でコマンドを打つのが面倒だからです。

    「記事を書きたい」と思ったとき、`/draft practice テーマ キーポイント1,キーポイント2,...`と正確にタイプするより、Claudeに「この記事を書いて」と自然言語で頼む方がはるかに楽です。結果として、スキルの内部ロジック(テンプレート読み込み→プロンプト適用→保存)は価値があるのに、「手動で呼ぶ」というインターフェースがボトルネックになっていました。

    学び: スキルの価値は「処理ロジックの標準化」にあるが、トリガーが手動だと定着しない。CLAUDE.mdルールのように「AIの処理フローの中で自動的に実行される」形にした方が圧倒的に使われる。

    【期待外れ②】固定ハッシュタグの自動付与

    スキル定義の中で、記事のfrontmatterに固定ハッシュタグ(`#AI活用`、`#ClaudeCode`)を自動付与する設定をしていました。

    hashtags:
      - "AI活用"
      - "ClaudeCode"

    毎回同じタグが付くので楽ではあるのですが、記事の内容に応じた最適なタグが付かないという問題がありました。note.comでは、ハッシュタグが検索流入やおすすめ表示に影響します。固定タグだけでは、記事ごとの差別化ができず、流入の最適化ができませんでした。

    学び: ハッシュタグは固定ではなく、記事内容に応じて動的に生成すべき。「固定タグ1つ + 記事依存タグ3-4つ」の組み合わせが理想。

    結果

    設計ドキュメント作成
    手動(月1-2本、不定期) → 自動(1ヶ月で7本)

    開発ログ記録密度
    週1-2回 → 毎コミット(週平均7回)

    サブエージェント委譲の判断ブレ
    頻発 → ほぼゼロ(ポリシー参照)

    新規プロジェクトのセットアップ
    グローバル設定を毎回コピー → グローバル設定は自動適用

    エージェント出力の追加質問率
    体感50%以上 → 体感10%以下

    スラッシュコマンドの利用頻度
    最初の1週間は毎日 → 3週目以降は月1-2回

    独自の学び・失敗から得た知見

    最大の発見:「手動トリガー」vs「自動実行」の壁

    7つの設定を1ヶ月試して分かった最大のパターンは、「人間が手動で呼ぶ設定」は定着せず、「AIの処理フローの中で自動実行される設定」は定着するということです。

    • ✅ CLAUDE.mdルール → Claudeが勝手に実行する → 定着する

    • ✅ 委譲ポリシー → Claudeが判断時に参照する → 定着する

    • ❌ スラッシュコマンド → 人間が呼ぶ必要がある → 定着しない

    これは人間の習慣形成と同じ構造です。「毎朝ジョギングする」と決意しても続かないのに、「通勤を自転車に変える」は続く。行動をトリガーに組み込むことが、ツールの定着には不可欠だと実感しました。

    Claude CodeのCLAUDE.mdは「ルールブック」ではなく「自動化スクリプト」

    CLAUDE.mdの本質は、多くの人が思っている「AIへの指示書」ではなく、**「AIの行動に組み込まれる自動化スクリプト」**だと考えています。

    「こういう場合はこうしてね」という指示は、Claudeがその状況に遭遇したときに自動で発動します。つまり、CLAUDE.mdに書いたルールの一つ一つが、if-then文のように機能するのです。

    この視点で設定を設計すると、「何をCLAUDE.mdに書くべきか」の判断基準が明確になります:

    • 書くべき: 毎回同じ判断をすべき反復的な処理(ドキュメント生成、ログ記録、委譲判断)

    • 書かなくていい: 毎回異なる創造的な判断(記事のテーマ選び、文章のトーン調整)

    つまり、この記事で紹介した設定①②をif-then形式で表現するとこうなります:

    • `if: plan mode完了 → then: docs/に設計書を保存`

    • `if: git commit → then: Obsidianにログ記録`

    CLAUDE.mdとは、こうしたif-then文の集合体なのです。

    今後試したいこと

    • スラッシュコマンド型スキルの処理ロジックを、CLAUDE.mdルールに移行してみる(例:「記事を書く」と言われたら自動でテンプレートとプロンプトを読み込むルール)

    • 出力契約をプロジェクト固有エージェントにも拡張

    • ハッシュタグの動的生成ロジックの導入

    まとめ

    Claude Codeの設定で最も効果があったのは、CLAUDE.mdに「自動実行されるルール」を書くことでした。スラッシュコマンドのような手動トリガー型の設定は、機能としては正しくても運用では定着しません。設定を設計するときは、「人間が呼ぶかどうか」ではなく「AIの処理フローに自然に組み込まれるかどうか」を基準にすることをお勧めします。

    関連記事

     
     
    「AI、実際どこまで仕事で使えるの?」を非エンジニア目線で検証しています。ChatGPT・Claude・Geminiを実務で試して、使えた/ダメだったを実測と失敗談つきで正直に書きます。

    あなたへのおすすめ