.claude/フォルダーの構造

2026年3月27日原文(blog.dailydoseofds.com)

概要

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 が最重要。ここを最適化することで 修正指示の手間削減と生産性向上 を実現
小さく始めて、必要に応じて分割・最適化していく運用が推奨
日々のインフラ同様、継続的な改善で大きな効果

ご覧いただきありがとうございました！

Hackerたちの意見

それが今の「ソフトウェアエンジニアリング」ってことなの？なんかカルトみたいだね。マジで、これには赤信号が点滅してるよ。ここにある主張はどれも証明できないし。言ってることは、賞賛されてたlangchainと同じで、みんながそれがクソだって気づいたみたいなもんだよね。MCPも同じだし。2026年の仕事は本当に悲しいね。

└

正直、自分に合ったニッチを見つけてる気がする。個人的には、ソフトウェアエンジニアリングは、作り出す仕事に基づいて異なる職業に分かれていく感じだと思う。この「プロンプトして祈る」流れは、製品やお金を作るのに本当に効果的だけど、成功してる人たちは5年前にノーコードツールに手を伸ばして、似たような成功を収めてたはずだと思う。今はもっと速くて包括的になってるけど、製品の一般的なテーマは変わらないと思う。重要じゃないわけじゃないけど、ソフトウェアの領域内で効果を持つソフトウェアが多い気がする。そういう市場はずっとあったと思うし、重要だからこそ、そういうツールを「エンジニアリング」するために時間とお金をかける価値がある人には合わないんだよね。多くのSaaS製品がそのニッチを埋めてきたし。自分がやりたい働き方ではないけど、特定のブランドの価値のあるソフトウェアを生み出すための異なる職業として尊重することに慣れてきてる。そこにチャンスがあるのに、自分はそれを逃してる。取る人に責任はないけどね！飛行機の空中衝突回避システムを書くソフトウェアエンジニアは、自分の仕事を真剣に受け止めて、変更点を理解し、ソフトウェアを無限に維持できるようにしないとね。売上追跡ソフトウェアのエンジニアリングにあまり関心がない人も多いけど、飛行機のソフトウェアのエンジニアリングには本当に気を使ってると思う。

└

いつから貨物カルトじゃなくなったの？

最近、みんなが人工的な壁を作って、エージェント的なコーディングを試すのに登らなきゃいけないみたいな風潮が増えてるのを感じる。それって全然正しいスタートじゃないよ。まずは新しい.claudeから始めて、空っぽのAGENTS.mdを使って、スキルゼロでMCPを学んで、まずはそのツールを操作することから始めるべきだよ。

└

そうなんだけど、他の開発者とプロジェクトを共有したりアクセスをチェックインしたりすると、これらのことは共有されるようになるんだよね。エージェント的なサポートを使って自分だけでコードを作業するのは一つのことだけど、各開発者がエージェントツールを使ってチームで作業するのは全然違う話だよ。

└

そのスタートの仕方が間違ってるっていうのには完全に同意するよ。でも、自分の経験では、ツールを使えば使うほど「感覚」がつかめるし、いろんなパーツがどう機能して連携するかを知るのは結構役立つよ（必須ではないけどね）。ネット上には低品質な情報が多すぎて、必要な情報を見つけるのが本当にイライラする。

└

誰が人工の壁を作ってるの？もしかしたら投稿を読み飛ばしちゃったかもしれないけど、この情報は「エージェント工学を始める前に知っておくべきこと」って感じじゃなくて、「知っておくべきことがいくつかあるよ」っていう印象だね。

└

この記事は、始める前に大きな.claudeフォルダを設定しなきゃいけないって言ってるわけじゃないよ。小さく始めて短く保つことが大事だって何度も繰り返してる。初めてAIコーディングを体験する人向けでもないし、これらのツールを使ってAIコーディングで避けられないフラストレーションに対処するためのガイドなんだ。実際、HNでのAIコーディングに関する不満の多くは、初心者が書いてるもので、彼らも自分の好みやガイドラインを含むシンプルな.claude設定から恩恵を受けるはず。AIコーディングツールを試してみて諦める人たちがよく言う不満は、ツールが自分の考えを読み取ってくれないとか、ユーザーが望まないことをし続けるってこと。AGENTS.mdや.claudeフォルダに数行書くだけで、そういう問題がすぐに解決できるよ。

└

これは、大きなエンジニアリングチームがClaudeの周りに何らかのガードレールを設けたい場合に重要だよ。例えば、私はClaudeにいくつかの前提条件が満たされるまで作業を始めないように指示するルールがあるんだ。[0] これがうまく機能していて、何かをする前に必ずこれらの条件をチェックしてるみたい。セキュリティチームは、開発者がエージェントツールを使って何かをすることに対して、あまり心配せずに安心感を持ちたいと思っているだろうね。それに、エージェント開発を本当に始めたばかりの私にとって、どうやって作業しているかをルールに落とし込む時間が、Claudeが私が嫌がること、例えばGPGキーでコミットにサインしないことをしないように助けてくれた。ただし、これらのルールは決して固定されることはないし、少なくとも最初はね。[0]: https://github.com/carlosonunez/bash-dotfiles/blob/main/ai/c...

└

さらに言うと、自分で作ったスキル以外は絶対にインストールしない方がいいと思う。自分で作ったスキルをガイドしてもらうのもアリだけど、既存のものをフォークして必要な部分だけ持ってくるのがベスト。みんなのワークフローは違うし、どれが正解かなんて誰にもわからないからね。ランダムなスキルを詰め込んだハーネスにすると、また新たな非決定性が加わって、コンテキストウィンドウも大きくなっちゃう。自分でメンテナンスする代わりにインストールすべきスキルはplaywright-cliだけだと思うけど、それくらいかな。

└

組織を巻き込むのは、こんなにのんびりしたもんじゃないよ。今はClaudeを使うことにかなりオープンだけど、未知のことはやっぱり未知だから、.claudeフォルダが提供するガードレールがあると、ツールに慣れるときに安心できるんだ。

└

ピーター・スタインバーガー本人が、クレイジーなコーディングワークフローを考える代わりにAIとチャットしてるって言ってるよ。

Hacker Newsで議論の続きを見る

ハクソク