概要
- AI導入 は多くのチームで進んでいるが、 ROI(投資対効果) との間には大きなギャップが存在
- Postman によるAPI開発ワークフローのコスト削減分析の紹介
- Claude Code の .claudeフォルダ はプロジェクト制御の中心
- CLAUDE.md や コマンド・スキル・エージェント による柔軟なカスタマイズ方法を解説
- 段階的なセットアップ手順 と運用のコツを具体的に提案
AI導入とROIのギャップ
- 多くのチームが AIを何らかの形で利用 している現状
- しかし、 AI活用による明確なROI(投資対効果) を得るにはさらなる工夫が必要
- Postman が公開したコスト削減分析では、 AIをプラットフォーム内蔵型と外部追加型で比較 し、実際の時間・コスト差をデータで可視化
- エンジニアリングリーダーが AIネイティブツールの有効性を説明 する際に役立つ資料
- 無料ガイドとして提供されており、 導入判断の参考資料 として活用可能
Claude Codeの. claudeフォルダ 徹底解説
- .claudeフォルダ は Claude Code の挙動を制御する中心的なディレクトリ
- プロジェクト単位 の .claude/ と、 ユーザー単位 の ~/.claude/ の2種類が存在
- プロジェクト側は チーム共通設定 を格納し、 git管理 対象
- グローバル側は 個人設定やセッション履歴 などマシンローカルな情報を保存
CLAUDE.mdの役割と書き方
- CLAUDE.md は Claudeのシステムプロンプト として最初に読み込まれる最重要ファイル
- 記述したルールや指示は Claudeの動作方針に直結
- プロジェクトルート、~/.claude/、サブディレクトリにも配置可能で、 階層ごとにマージして適用
- 効果的な記述例(20行程度):
- ビルド・テスト・リントコマンドの指定
- 主要なアーキテクチャ方針
- 非常に重要な注意点や命名規則
- ファイル・フォルダ構成
- 記載不要な内容:
- linterやformatterの設定内容
- 既存ドキュメントへのリンクで済む説明
- 理論的な長文解説
- 200行以内 に収めるのが推奨
個人設定とルールの分割管理
- CLAUDE.local.md で個人の好みや微調整をプロジェクト単位で管理(自動でgitignore)
- .claude/rules/ ディレクトリで 役割ごとに指示を分割管理
- 例:api-conventions.md、testing.mdなど
- YAMLフロントマターで パススコープ 指定可能(特定ディレクトリのみルール適用)
カスタムコマンドとスキル
- .claude/commands/ にMarkdownファイルを追加すると 独自スラッシュコマンド を定義可能
- ファイル名がコマンド名となり、 /project:コマンド名 で実行
- シェルコマンド埋め込みや引数展開($ARGUMENTS)も対応
- .claude/skills/ は 自動トリガー型ワークフロー
- SKILL.mdで発動条件を記述
- 補助ファイル同梱やパッケージ化が可能
- 個人用は~/.claude/skills/に設置
サブエージェント(Subagent)の活用
- .claude/agents/ で 専用エージェント をMarkdownで定義
- 例:code-reviewer.md
- system prompt、利用ツール、モデル指定が可能
- タスクごとに 分離されたコンテキスト で処理し、結果のみをメインセッションに返却
- モデル指定で コスト最適化 も実現
権限管理とセキュリティ
- .claude/settings.json で 許可・禁止コマンドやファイル操作範囲 を定義
- $schemaでエディタ補完やバリデーション対応
- allowリスト:即時実行許可(npm run系、gitのread系、Read/Write/Glob等)
- denyリスト:絶対禁止(rm -rf、curl、.envやsecrets/等)
- どちらにも該当しない場合は 都度確認
- .claude/settings.local.json で個人用の権限設定(自動gitignore)
グローバルディレクトリの役割
- ~/.claude/CLAUDE.md :全プロジェクト共通の個人指針やスタイル
- ~/.claude/projects/ :プロジェクトごとのセッション履歴・自動メモリ
- ~/.claude/commands/ ・ ~/.claude/skills/ :全プロジェクト共通の個人コマンド・スキル
Claude Codeセットアップの推奨手順
- Step 1 :/init実行でCLAUDE.mdの雛形生成、必要最小限に編集
- Step 2 :.claude/settings.jsonで権限ルール設定(実行コマンド許可・.env禁止等)
- Step 3 :よく使うワークフロー用のコマンド作成(例:コードレビュー・イシュー修正)
- Step 4 :プロジェクト拡大時は.rulse/で指示を分割管理、パススコープ活用
- Step 5 :~/.claude/CLAUDE.mdで個人の好みを全体適用
運用のコツとまとめ
- .claudeフォルダ は Claudeに「自分たちのルール」を伝えるためのプロトコル
- CLAUDE.md が最重要。ここを最適化することで 修正指示の手間削減と生産性向上 を実現
- 小さく始めて、必要に応じて分割・最適化していく運用が推奨
- 日々のインフラ同様、継続的な改善で大きな効果
ご覧いただきありがとうございました!