Claude Codeへの初期セットアップが開発品質を決める——プロジェクト開始時にやるべきこと

在庫数が閾値を下回ったら一覧画面で赤字表示したい。
承認待ちのレコードを色分けして、ひと目で状況を把握したい。

こういった要件を、1行もコードを書かずにClaude Codeだけで実現した実験を以前行いました。
プラグインは完成しました。

ただ、振り返ると「最初にやっておけばよかった」ことがいくつかあります。

Claude Codeは優秀なエージェントです。
でも、初期状態ではあなたの現場のルールを何も知らない状態でスタートします。
それが、出力品質のムラや「直したはずなのに変わらない」という迷走を生みます。

簡単な原因ではありましたが、実際に私が体験したことです。

この記事では、Claude Codeに自社のナレッジを渡す方法を全て整理し、どう使い分けるかを解説します。
前回のプラグイン開発に当てはめながら、「あのとき何を整備しておけばよかったか」を具体的に示します。

結論：Claude Codeにナレッジを渡す方法は6つある

先に全体像を示します。

方法 一言で言うと 適用範囲
CLAUDE.md（プロジェクト） プロジェクト固有のルールを自動で読み込ませる プロジェクト全体
CLAUDE.md（ユーザー） 自分の作業スタイルを全プロジェクトに適用する 全プロジェクト
.claude/rules/ 詳細なルールを別ファイルで管理する プロジェクト全体
.claude/skills/ 繰り返す手順・ワークフローを定義する タスク単位
.claude/agents/ 専門サブエージェントを定義する タスク単位
MCPサーバー 外部データ・ツールをリアルタイムで参照させる セッション全体

これらは排他ではなく、組み合わせて使います。
最初はCLAUDE.md（プロジェクト）だけで十分で、使いながら必要に応じて追加していけばOKです。

なぜ最初の整備が品質を左右するのか

Claude Codeはプロンプトに対して的確なコードを返します。
でも「的確なコード」は必ずしも「あなたの現場で使えるコード」ではありません。

前回のkintoneプラグイン開発では、CLAUDE.mdをはじめとした初期設定を何も用意しませんでした。
その結果として次のことが起きました。

  • 社内の共通モジュール（AdiemLicense.js・AdiemMessage.js など）を知らないまま、似た機能を一から実装した
  • DEV用ビルドと本番用ビルドの区別をClaude Codeに伝えていなかったため、「修正したはずなのに変わらない」状況が続いた
  • 「とにかく直して」と指示し続けたことで、場当たり的な修正が泥沼化した

これらは全て、初期整備があれば防げた問題です。
教えた分だけ精度が上がる——初期整備はその「一括投資」だと考えてください。

6つの方法を詳しく解説

① CLAUDE.md（プロジェクト単位）

プロジェクトルートに置くマークダウンファイルです。
Claude Codeがプロジェクトを開いたとき、自動で読み込みます。

書くべき内容は主に4つです。

  • プロジェクト概要：何を作るプロジェクトか、全体構成はどうなっているか
  • コーディング規約：命名規則・クラス設計の方針・禁止事項
  • 共通モジュール一覧：既存の共通部品の場所と用途（「これを使え、一から作るな」）
  • 進め方のルール：「設計書から始める」「TDDで実装する」「planモードで根本原因を特定してから修正する」

前回のプラグイン開発に当てはめると、以下をCLAUDE.mdに書いておけばよかったと思います。

# kintoneプラグイン開発

## プロジェクト概要
フィールドの値に応じて文字色・背景色・フォントスタイルを変えるプラグイン。
設定画面（条件・色の定義）＋本体画面（書式適用）のMVC構成。

## 共通モジュール（src/common/js/ に存在）
- license.js  ：ライセンス認証
- message.js  ：メッセージ表示
- configFile.js：設定の入出力
これらは実装済み。同等の機能を新たに作らないこと。

## コーディング規約
- 'use strict' 必須
- クラス名：先頭大文字CamelCase
- privateメソッドには # プレフィックス
- console.error 以外の console.* は禁止

## ビルドの注意（最重要）
| 用途 | コマンド | 出力先 |
|------|---------|--------|
| DEV確認用 | npx webpack --config webpack.dev.config.js | plugin_dev/js/ |
| 本番 | npm run build | plugin/js/ |
DEV動作確認中は必ずDEV用コマンドでビルドすること。
npm run build だけでは plugin_dev/ は更新されない。

## 進め方のルール
- 実装前に必ず設計書（クラス構成）を作成すること
- テスト駆動（TDD）で実装すること
- 修正が行き詰まったら「planモードで根本原因を特定してから修正して」と指示すること

② CLAUDE.md（ユーザー単位）

~/.claude/CLAUDE.md に置くと、全プロジェクトに適用されます。
つまり、この.mdファイルに記述する内容はプロジェクト固有のものではなく、統一したい規格です。

書くのは自分の作業スタイルや好みです。

# 作業スタイル

- 出力は日本語で
- コードの説明は簡潔に。コメントは「なぜそうするか」だけ書く
- 実装前に必ず設計を確認させる
- 提案は3案以内に絞って比較できる形で出す

プロジェクトのCLAUDE.mdと競合する場合は、プロジェクト側が優先されます。

③ .claude/rules/（詳細ルールファイル）

CLAUDE.mdに直接書くと長くなるルールを、別ファイルに分けて管理します。

.claude/
└── rules/
    ├── security-guidelines.md    # セキュリティガイドライン
    ├── coding-standards.md       # コーディング規約の詳細
    └── testing-strategy.md       # テスト方針

CLAUDE.md から次のように参照します。

## セキュリティ
詳細は `.claude/rules/security-guidelines.md` を参照すること。

前回のプラグイン開発に当てはめると、kintone固有のルール（フィールドコードのハードコーディング禁止・セッションストレージの命名規則）をrulesに分離できました。
CLAUDE.mdをシンプルに保ちながら、詳細は必要なときだけ参照させる使い方です。

④ .claude/skills/（スキル定義）

繰り返し使う手順・ワークフローをスキルとして定義します。
/スキル名 で呼び出せます。

.claude/
└── skills/
    └── plugin-dev-cycle.md    # プラグイン開発サイクル

スキルファイルの中身はこんなイメージです。

# kintoneプラグイン開発サイクル

## 手順
1. 要件を日本語で整理し、設計書（クラス構成・シーケンス図）を作成する
2. TDDで実装する（テスト→実装の順）
3. 以下のコマンドを順番に実行してDEVプラグインを更新する：
   - npx webpack --config webpack.dev.config.js --mode development
   - kintone-plugin-packer plugin_dev --ppk develop_xxx.ppk --out dist/dev_xxx.zip
   - node /opt/homebrew/.../cli.js dist/dev_xxx.zip --base-url ...
4. kintone上で動作確認する
5. バグがあれば「planモードで根本原因を特定してから修正して」と指示する

前回の開発では、ビルド→アップロード→確認の3コマンドを毎回手入力していました。
スキルに定義しておけば /plugin-dev-cycle と呼ぶだけで同じ流れを実行できます。

⑤ .claude/agents/（カスタムエージェント）

特定の役割に特化したサブエージェントを定義します。
大きなタスクを役割分担して並列処理させるときに使います。

.claude/
└── agents/
    ├── kintone-implementer.md    # 実装専門エージェント
    └── kintone-tester.md         # テスト専門エージェント

エージェントファイルには「このエージェントの役割・得意なこと・守るべきルール」を書きます。

前回のプラグイン開発では、実装・デバッグ・テストを1セッションで全部行いました。
実装はkintone-implementerに任せ、テストはkintone-testerが独立して実行する形にしておけば、コンテキストが長くなって精度が落ちる問題も防げました。

⑥ MCPサーバー

外部データ・ツールをClaude Codeからリアルタイムで参照させる仕組みです。

kintoneプラグイン開発での活用例を示します。

MCPサーバー できること
kintone公式ドキュメント 最新APIの仕様をリアルタイムで参照
社内Notion・Confluence 自社の設計書・仕様書を参照
GitHub PRやIssueの状況を参照
kintoneアプリ 実際のフィールド構成を取得

前回の開発でkintone JavaScript APIの仕様をMCPで参照させていれば、APIの使い方を誤ったコードが出てくる頻度が下がった可能性があります。

MCPの設定は ~/.claude/settings.json（ユーザー全体）またはプロジェクトの .claude/settings.json で行います。

まとめ：粒度と用途で使い分ける

使い分けの指針

渡したいナレッジ 推奨する方法 理由
プロジェクトのルール・構成 CLAUDE.md（プロジェクト） 自動読み込みで毎回説明不要
自分の作業スタイル CLAUDE.md（ユーザー） 全プロジェクトに一括適用できる
詳細な規約・ガイドライン .claude/rules/ CLAUDE.mdをシンプルに保てる
繰り返す作業手順 .claude/skills/ 呼び出しが簡単で再利用しやすい
役割を分けた大規模タスク .claude/agents/ コンテキスト汚染を防げる
外部の最新データ・仕様書 MCPサーバー 常に最新の情報を参照できる

最初はCLAUDE.md（プロジェクト）だけで十分です。
使いながら「この手順は毎回説明している」と気づいたらスキルへ。
「コンテキストが長くなって精度が落ちてきた」と感じたらエージェントへ——

という順番で整備していけばOKです。

今日から始める3ステップ

Step 1：自社プロジェクトのルールと共通モジュールをリストアップする
コーディング規約・命名規則・既存の共通部品の場所と用途を書き出します。
「毎回新人に説明していること」がそのままCLAUDE.mdに書くべき内容です。

Step 2：プロジェクトルートに CLAUDE.md を作り、内容を書く
完璧である必要はありません。
箇条書きで十分ですので、まず動かすことを優先してください。

Step 3：使いながら rules・skills・agents を追加していく
繰り返す手順が出てきたらスキルに。
詳細なルールが増えてきたらrulesに分離していきましょう。

CLAUDE.mdを整備したら、次はClaude Codeを自走させるための許可設計も整えておくとさらに効果的です。
詳しくはClaude Codeを長時間自走させる方法——許可設計で「止まらないAI開発」を実現するをご覧ください。

また、Claude Codeを導入する前に確認しておきたいセキュリティ設定については、Claude Codeを使う上で最低限知っておきたいセキュリティ対策にまとめています。

「自社プロジェクト向けのCLAUDE.mdを一緒に作りたい」「Claude Code活用の進め方を相談したい」という方は、ぜひアディエムまでご相談ください。

参照元

関連記事