世界を動かす技術を、日本語で。

.claude/フォルダーの構造

概要

  • 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.mdClaudeのシステムプロンプト として最初に読み込まれる最重要ファイル
  • 記述したルールや指示は 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とチャットしてるって言ってるよ。

ほんと、まずはプランモードを使えば90%は解決するよ。CCがサブエージェントを起動して、だいたい正しいことをしてくれるしね。個人的には、この「生産性を上げるために設定をカスタマイズする」系の話は、1年以内に改善されたモデルやハーネスによって廃れると思う。1〜2年前のLLMをコードで使うためのレッスンなんて、もうすっかり忘れ去られてるしね。

それは本当だけど、最初は何かプロジェクトを始めるのが一番だと思う。ユーザーが物事をどう整理して考えるかのアイデアを得るためにね。私にとっては、これがガスタウンで、今ではおそらく最もカスタマイズされたガスタウンのインストールを持ってる。自分で作ったものこそが、AI体験の本質だってことに完全に同意するよ。製品化されたものが魔法のように生活を変えてくれるなんて思わない方がいい。これがガスタウンの本当の天才だと思う—どう動くかじゃなくて、実際に動くってこと、そしてイェッゲが自分の頭からそれを作り出したってこと。だから、私は同じ教訓を受け取って、すごく遠くまで進んだし、いろんな意味で全く違う方向にも行った。でも、これは天才の作品で、彼がそれを世に出したことを本当に尊敬してる。

すべてのモデルプロバイダーが標準的なファイルセットに統一してくれたらいいのに。そうすれば、状況に応じてClaudeからCodex、Cursor、Opencodeに簡単に切り替えられるのに。

問題は、ハーネスと特定のモデルがどのタイプの指示が最適かに大きく影響するってことだよ。AnthropicのモデルをCodexやGPTモデルの最適なプロンプト方法と組み合わせて使うと、結果がすごく悪くなるんだ。GPTモデルをCodexと一緒に使って、GPTが反応しやすいプロンプトで促すと、全然違う結果が出る。具体的なプロンプトがどれだけ重要か、みんな気づいてないと思う。同じプロンプトでも、モデルによって結果が大きく異なるし、プロンプトを繰り返し改善する時(例えば処理のために)、使うモデルによって変更内容が変わるんだよね。

なんで彼らがスイッチを許すと思うの?

同意!今はSentryのdotagentsを使って、いろいろやってるよ。

「CLAUDE.mdに書いたことは、Claudeが従う」という主張は、かなりの重みを持ってるよね。実際には、CLAUDE.mdは提案に過ぎなくて、契約じゃない。複雑なタスクや圧縮があると、CLAUDE.mdの使い方が薄まっちゃうし、特にコンテキストウィンドウが切れたらね。

その通り。これらの.mdファイルは、LLMが照合するテキストの塊に過ぎない。何かが起こる可能性を高めたり、逆に起こらない可能性を下げたりするかもしれない。実際、人々は決定論的なワークフローを構築したいみたいだけど、テキストの塊はそのための正しいアプローチじゃない。正しいツールは、特定の状態を通じてエージェントを制御し、ツールの呼び出しを一歩ずつ検証するコードだよ。

うん、これを見た瞬間、この記事はあまり役に立たないだろうなって思った。クロードにガイドファイルに従わせるのはちょっとイライラするね。

Claude Fastには、これに関する非常に良い代替ドキュメントがあるよ。[0] .claude/を定義することに対する嫌悪感が理解できない。メインエージェントにファイルを書かせるのはかなり簡単だし、一発でコーディングする代わりに、.claude/を素早く更新する方がいい。今は、.claude/が自分自身のコピーを作って、タスクを実行し、評価して、自分を更新するところまで来てる。私はコードを書くんじゃなくて、他のことを全部やるための.claude/を書いてるんだ。これは、.claudeやエージェント、指示をテストするためのメカニズムでもあって、組織内での共有や再利用に役立つよ。[0] https://claudefa.st/blog/guide/mechanics/claude-md-mastery

本当に話題にされない壁は、そう、Claudeに好きなファイルを更新するように指示できるけど、.claude/INSTRUCTIONS.mdやCLAUDE.mdの場合は、Claudeにそのファイルを再読み込みするように言わないといけないってこと。なぜなら、内容は自分で書いたけど、新しい指示として扱ってないから。最後にそのファイルを読んだ時の内容で動いちゃうから、もしそのファイルが存在しなかったら、何もわからないんだ。Claudeは、その指示をコンテキストウィンドウの非常に特定の部分に置いてると思う。

いいね!記事には書いてなかったけど、~/.claude/plansにプランのmdファイルが保存されるんだよね。ディレクトリからプランを開いたりバックアップしたりするのに便利だよ。

なんかこれ、経験に基づいてない生成物っぽい気がする。Claude.mdは短くあるべきだよ。TypeScriptの厳格モードは特に問題じゃないし、簡単に解決できると思うから、そういうのは省いた方がいいよ。みんなClaudeに詰め込みすぎなんだよね。数行とドキュメントへのリンクだけで十分だよ。@Agents.mdに全部まとめてもいいし。スキルはコマンドを上回るんじゃないの?サブエージェントはいいよ、特にモデルやフォークしたメモリ、リンクしたスキルを指定すればね。Claudeがうまくいってないときは、何を最適化できるか考えて、それをどうエンコードするか(またはスクリプトやコードの選択をリファクタリングするか)を考えるべき。プランと実装は分けて、コンテキストもクリアにしておくことが大事だよ。コンテキストが積み重なると、悪化するからね。

スキルはコマンドを上回るんじゃないの?カスタムスラッシュコマンドは手動で呼び出されるだけで、スキルはコンテキストにいるんじゃないの?その違いがよくわからない。今ググってみたら、スラッシュでスキルも呼び出せるみたいだし。

話は変わるけど、今日の早い時間にジェミニにこの記事を読んでもらって、オープンコードのために同じことをどうやってやるかアドバイスを求めたんだ。小さなローカルモデルから良いパフォーマンスを引き出すことに興味津々なんだよね。

自分のAIエージェントの「ツールキット」を作るのは、完璧な「生産性」セットアップと同じになってきてる。ブログを読んだり、生産的になる方法を教えてくれるYouTube動画を見たり、習慣や儀式を作ったりする時間を費やして、結局はシンプルなタスクリストを持ってそれをこなす人に追い越されちゃう。私の経験では、プレーン・クロードに計画を作るように頼んで、計画を見直して、実行するように指示するのが一番効果的だよ。

Emacsの初期設定ファイルの無駄話を思い出すな…

こういう罠に人を引き込むことでお金がたくさん稼がれてるね。実際に自分が何を望んでいるかを知っていて、それをうまく伝えられれば(生産性アプリが役立つところ)、AIを使ってたくさんのことができる。私の経験では、ほとんどの人は自分が何を望んでいるかを実際には知らない。あるいは、自分が望んでいるものに何が含まれているのかを理解していない。計画を求めることは、その理解を得るための近道なんだ。