AIを"使う"から"住まわせる"へ ── Claude Codeが変えるエンジニアリングの思想【完全版】

KINTETSU ELECK出版／ AI時代の新しい稼ぎ方

もともと私は、Kindle電子書籍の出版から情報発信をスタートしました。

そこからChatGPTをはじめとしたAIツールの活用にハマり、プロンプトエンジニアリング、コンテキストエンジニアリングと学びを深めていった頃——Claude Codeの登場で、空気が変わったのを感じました。

「これは今までと違う。ちゃんと向き合わないといけない」

そう思ってから約1ヶ月。YouTubeを漁り、有料記事を読み漁り、自分の作業をどう自動化・効率化できるかを試行錯誤してきました。

そんな中、Facebookで目に留まった記事がありました。Claude Codeの使い方について書かれた投稿だったんですが、読めば読むほど「これは面白い。ちゃんと自分なりに考察してまとめたい」と思って。

今回はその記事をベースに、AIも使いながら自分なりに深掘りした内容をお届けします。ちょっと長めですが、Claude Codeを使っている方・これから使おうとしている方には刺さる内容になっていると思います。ぜひ最後まで読んでみてください。

// 序論

プロンプト工学から「環境設計」へのパラダイムシフト

従来のLLM活用は「いかに良いプロンプトを書くか」という発想に支配されてきました。これは本質的にはセッション単位の思考です。会話が終われば消える、揮発性の知性をその都度呼び出す行為。

ところが、Claude Codeのように長期的にコードベースに住まわせるエージェントには、まったく別の発想が必要になります。それはプロンプトを書くのではなく、環境をデザインするという発想です。

人間のシニアエンジニアを新しくチームに迎えるとき、私たちは毎朝彼に巨大な指示書を渡しません。代わりに、READMEを整備し、ADRを書き、ディレクトリ構造で意図を表現し、CIで規律を強制します。優れたエンジニアは「環境に組み込まれた規範」を読み取って動きます。Claudeに対しても、同じ扱いをせよ。

// 01

「短く保て」という逆説 ── 削る技術

CLAUDE.mdを知識の捨て場にするな。直感的には「Claudeにより多く教えれば、より賢く動くだろう」と思ってしまいますが、実際には逆です。

LLMの本質として、コンテキストウィンドウは有限であるだけでなく、注意は希釈される。100行の指示に埋もれた重要な制約は、5行の指示の中の同じ制約より守られにくい。情報量とシグナル強度はトレードオフ関係にあります。

CLAUDE.md の設計は「書く技術」ではなく「削る技術」になる。これは多くの開発者がドキュメントに対して持つ直感と真逆で、習得には意識的な訓練が要る。

// 02

四つの柱：目的駆動エージェントの最小構成

WHY / MAP / RULES / WORKFLOW という分類は、人間の認知が必要とするものと完全に一致しています。この四つは、目的駆動の知的エージェントが動作するための最小集合です。

FIG.01 — 四つの柱とその認知的役割

// 補足図解

二つの視点から見る構造：概念軸とファイルシステム軸

同じリポジトリ構造でも「4本の柱（WHY/MAP/RULES/WORKFLOW）から見るか」「ファイルシステムから見るか」で、まったく異なる図になります。この二つは矛盾ではなく、同じ対象を異なる切断面で見たものです。まず概念軸から——

FIG.05 — 4本柱とリポジトリ実装の対応関係（概念軸）

この図で注目すべきは、WHY列だけが1つの実装（CLAUDE.md）に絞られていることです。目的は本来「単一の北極星」であるべきで、他の三つの柱はそれを支える多面的な構造だからです。MAP・RULES・WORKFLOWはそれぞれ複数のファイルで実装される多面的な支えです。

続いて、視点を「概念」から「ファイルシステム」へと切り替えます——

FIG.06 — Claude Codeプロジェクト構造（ファイルシステム軸）

マインドマップでは .claude/ が一つの操作層としてまとめられ、内部にskills・hooks・settingsが入る階層関係が前景化されます。「リポジトリのトップレベルから見たときの構造」という視点です。

同じ .claude/skills/ が二つの図で違う色を持つ。最初の図ではWORKFLOW（琥珀色）、マインドマップでは .claude/ 層の一部（珊瑚色）。これは矛盾ではなく、同じ実装が複数の役割を兼ねていることを示す。一つのファイルが一つの役割だけを担うのではなく、複数の概念軸の交点に位置している。これこそが、優れたアーキテクチャの特徴だ。

// 03

リファレンス実装：ディレクトリ構造の全体像

思想を「実装テンプレート」として具体化すると、以下のリポジトリ構造になります。各ファイルとディレクトリは単なる整理以上の意味を持ちます。

FIG.02 — AI協働リポジトリの推奨ディレクトリ構造

二重の読者モデル：README と CLAUDE.md の並置が意味すること

ルートに CLAUDE.md と README.md が並列に置かれているのは重要な設計判断です。人間は曖昧さに強く行間を読みますが、Claudeは曖昧さに弱く明示的な構造を必要とします。つまりリポジトリは二つの知性のために書かれる——これはAI協働時代に特有の構造です。

// 04

Hooks：確率論と決定論のギャップを埋める

LLMは確率的存在です。「フォーマッタを必ず実行する」と CLAUDE.md に100回書いても、確率1で守られることはない。一方で本番システムでは「必ず」を要求される操作が数多くあります——マイグレーション前のバックアップ、テスト通過の確認、認証コードへの監査ログ。

FIG.03 — Hook が橋渡しする「確率的領域」と「決定論的領域」

「モデルは忘れる。フックはしない。」
AIシステム設計のもっとも重要な原則——重要なことを確率的なコンポーネントに任せない。型システムが静的に保証し、テストが動的に検証するように、Hookは防護壁を形成する。

// 05

局所 CLAUDE.md：シグナルは希少だからこそ機能する

src/api/CLAUDE.md のような局所配置はプロキシミティ原則の応用です。コードに関するコメントが関数の上にあるべき理由と同じで、文脈はそれが必要な場所に配置されるべきです。

局所配置は条件付き文脈ロードを可能にします。グローバルなCLAUDE.mdに「認証ディレクトリではこうしろ」と書くと、認証と無関係なタスクでもその指示がコンテキストを占有します。局所配置なら、Claudeがそのディレクトリに踏み込んだときだけ規則が活性化する。

普段は気にしないが、payments/を触る瞬間に背筋が伸びる、あの感覚。人間のシニアエンジニアの振る舞いと完全に一致している。シグナルは希少だからこそシグナルとして機能する。

// 06

スキルはミニ・パッケージ、プロンプトは二層構造

skills/ の下に各スキルがフォルダとして配置されているのは単なる整理以上の意味があります。スキルが将来的に成長するからです。SKILL.md 本体に加えてチェックリスト・サンプル・補助スクリプトなどが入りえます。Python のモジュール、npm のパッケージと同じ思想——再利用可能な単位を一つの境界線で囲む。

プロンプトの二層構造

tools/prompts/ は「プロンプトは一時的」という主張と矛盾するように見えますが、これはプロンプトの二層構造を示しています。揮発性プロンプト（一回限り）は捨てる。永続化プロンプト（再利用可能なテンプレート）は資産化する。スキルはClaudeが自律的に呼び出す手順書、プロンプトは人間が明示的に投入する起動キー——役割が違うので場所も違う。

// 07

ADR：AIへの「経路依存性」の伝達手段

docs/decisions/（Architecture Decision Records）はAI協働時代に新しい役割を帯びています。コードを見れば「何が」は分かりますが、「なぜ他の選択肢を採らなかったか」は分からない。

「PostgreSQLを選び、MongoDBを採用しなかった。なぜなら……」という形式は、Claudeに「この選択を逆方向に変えてはいけない」というシグナルを送ります。ADRは人間の知的継承のためのものであると同時に、AIに対する経路依存性の伝達手段でもある——これはADRの全く新しい役割です。

// 08

「プロジェクトネイティブ・エンジニア」という到達点

BEFORE — チャットボット型

呼び出される API

毎回ゼロから始まる
外部からの指示で動く
汎用的だが浅い知性
セッションが終われば消える
コードベースを「知らない」

AFTER — プロジェクトネイティブ型

常駐する同僚

コードベースを地形として把握
規範を内面化している
なぜその選択かを説明できる
経験と文脈が蓄積される
プロジェクトの「歴史」を知る

後者を実現するには、Claudeに与える情報を増やすのではなく、Claudeが住む環境の解像度を上げる必要があります。これが構造化の本質的な意味です。

// 09

「AIへの組織設計」という統合的視点

ここまでの要素を統合すると、根底にある設計原理が浮かび上がります。Claudeを「新入社員」として迎えるための構造をリポジトリの中に作る——これはソフトウェア工学と組織論の交差点に立つ新しい営みです。

FIG.04 — 組織概念とリポジトリ実装の対応関係

この対応は驚くほど綺麗にはまります。私たちが今やっているのは、ソフトウェアプロジェクトを「AIが働ける職場」として組織設計するという、ソフトウェア工学と組織論の交差点に立つ新しい営みです。

// 10

批判的視点と四つの留意点

この思想を盲目的に適用すべきではありません。以下の留保が必要です。

小規模プロジェクトではオーバーエンジニアリングになる

週末に書く100行のスクリプトに .claude/skills/ を整備するのは本末転倒。この構造はチーム開発・長期保守・リスクのある領域でこそ価値を発揮する。

構造を維持するコストがある

スキルやHooksは書きっぱなしでは陳腐化する。「コードと共に進化するドキュメント」として扱い、レビュー対象に含める規律が要る。

CI/CD層との連携を考慮せよ

.claude/hooks/ が決定論的制御を担うとしても、プロジェクトのCIにどう統合されるかは別問題。Hookが壊れたときに誰が気づくのか、監視プロセスが必要。

機密情報の境界線を明確に引く

.claude/ 配下にAPIキーやセンシティブな設定を置く誘惑があるが、その境界線を明確にする必要がある。セキュリティポリシーとの整合性を必ず確認すること。

まとめ

正直、1ヶ月前の自分はClaude Codeを「ちょっと賢いチャットツール」くらいに思っていました。

でも今は違います。どう「住まわせるか」を設計すること自体が、AI活用の本質だと感じています。

Kindle出版でも、AI画像生成でも、ブログ執筆でも——結局、「仕組みを持っている人」と「その都度やっている人」の差は、時間が経つほど開いていきます。

私自身、今はClaude Codeに全力投球しています。自分の作業を自動化して、いずれは「人に教えられるレベル」まで持っていくのが目標です。

これからも初心者向けの導入記事や、実際に試してみた記録など、リアルな発信を続けていきます。一緒にAI時代を生き抜いていきましょう。

また面白い気づきがあれば、こうやって発信していきます。