【Claude Code内部解剖】システムプロンプト5階層アーキテクチャ──914ブックマークの価値

「Claude Codeは便利だけど、なぜこう動くのか分からない」──多くの開発者がそう感じています。しかし、Daniel Avila氏（CodeGPT CTO）が2025年10月13日に公開したシステムプロンプト分析は、この疑問に明確な答えを提供しました。

彼の投稿は914ブックマーク、656いいねを獲得。開発者コミュニティで「保存して後で勉強する価値がある」と評価されています。

Avila氏の分析によると、Claude Codeとのすべてのやり取りは5つの階層（Tier）を通じて処理されます。本記事では、この5階層アーキテクチャを徹底解説し、「TIER 2のCLAUDE.md設定」という最大のレバレッジポイントを実践的に活用する方法を紹介します。

1. Claude Codeシステムプロンプト解剖──開発者が知らない5階層アーキテクチャ

Daniel Avila氏は、aitmpl.comとCodeGPTの共同創設者兼CTO。TypeScriptとAI開発ツールの専門家として、15,538人のフォロワーを持つインフルエンサーです。

彼が公開したClaude Codeのシステムプロンプト分析は、AI開発ツールの「ブラックボックス」を解き明かす画期的な内容でした。

なぜ914人がブックマークしたのか？

エンゲージメント指標	数値	意味
ブックマーク	914	「後で実践する価値」の証明
リツイート	96	情報拡散価値
いいね	656	即座の共感
閲覧数	46,922	関心の高さ

ブックマーク率1.95%（914 / 46,922）は、技術投稿としては異例の高さ。通常0.5%以下のため、約4倍の保存価値があることを示しています。

Avila氏は次のように述べています：

「最大のレバレッジポイントはTIER 2、特にCLAUDE.md（Project Memory）です。ここには500行以上のプロジェクト固有のコンテキストを注入でき、全セッションにわたり永続化されます。ほとんどの開発者はこれを無視しています。」

– Daniel Avila (@dani_avila7)

この発言が、記事全体のテーマです。では、5階層アーキテクチャを詳しく見ていきましょう。

2. TIER 1（Critical）──変更不可の「憲法」レイヤー

TIER 1は「憲法」に相当する絶対的ルール層です。いかなる状況下でも上書きできません。

TIER 1の3要素

1. システムのアイデンティティと目的
   • 「あなたはClaude Code、Anthropic公式CLIツールです」という定義
   • ユーザー支援の基本姿勢
   • プロフェッショナルな客観性の維持
2. セキュリティポリシー（防御のみ、悪意のあるコードを拒否）
   • 防御的セキュリティタスクのみ許可
   • 悪意のあるコード作成・改善の拒否
   • 認証情報収集（SSH鍵、ブラウザクッキー等）の禁止
3. ツール使用ポリシー（bashコマンドより専用ツールを優先）
   • ファイル操作：Read / Edit / Write ツール優先
   • 検索：Grep / Glob ツール優先
   • bashは「システムコマンド実行」に限定

なぜ「憲法」なのか？

このレイヤーは、Claude Codeの信頼性と安全性の基盤です。例えば、ユーザーが「全ファイルを削除するスクリプトを書いて」と指示しても、TIER 1のセキュリティポリシーが拒否します。

3. TIER 2（Core Behaviors）──「人格」を定義する運用層

TIER 2こそが、Avila氏が「最大のレバレッジポイント」と呼ぶ層です。ここでClaude Codeの「振る舞い」が定義されます。

TIER 2の5つの要素

要素	説明	実用的影響
プロフェッショナルな客観性	事実を優先し、正当化を後回し	冗長な説明を避け、効率的な対話
タスク管理	TodoWriteの使用は必須	複雑なタスクの進捗可視化
Gitワークフローの安全性	破壊的操作は明示的承認必要	git push –force等の事故防止
利用可能なツール	40以上の関数	Read, Edit, Bash, Grep等
CLAUDE.md	プロジェクトの記憶（500行以上）	全セッション永続化コンテキスト

CLAUDE.md：500行のプロジェクト記憶

CLAUDE.mdは、Claude Codeが最初に読み込むプロジェクト固有の設定ファイルです。ここに以下を記述できます：

• プロジェクト概要：技術スタック、アーキテクチャ、開発方針
• 開発コマンド：テスト実行、ビルド、デプロイ手順
• コーディング規約：命名規則、ファイル構成、ベストプラクティス
• 禁止事項：使ってはいけないライブラリ、避けるべきパターン
• ワークフロー：PR作成手順、レビュープロセス

例えば、Pythonプロジェクトの場合：

# CLAUDE.md

## Project Overview
This is a Django REST API project with PostgreSQL database.

## Development Commands
- `python manage.py runserver` - Start development server
- `pytest` - Run all tests
- `black .` - Format code

## Coding Guidelines
- Use snake_case for variables and functions
- Use PascalCase for classes
- Maximum line length: 88 characters (Black default)

## Prohibited
- NEVER use `pip install` without updating requirements.txt
- NEVER commit directly to main branch
- NEVER use `django.db.models.raw()`

このファイルが存在すると、Claude Codeは全セッションでこのコンテキストを参照します。会話の都度「このプロジェクトはDjangoで…」と説明する必要がなくなります。

4. TIER 3（Operational）──リアルタイム実行コンテキスト

TIER 3は、「今、このプロジェクトはどんな状態か？」を把握する層です。実行時環境の認識レイヤーと言えます。

TIER 3の6要素

1. フックシステム（カスタム自動化）
   • ツール実行前後に任意のコマンドを実行
   • 例：Edit実行前に自動バックアップ
   • 例：Bash実行後にログ記録
2. タスク実行ワークフロー
   • TodoWriteによる進捗管理
   • 複数ステップのタスク追跡
3. 事前承認済みツール（許可不要）
   • 頻繁に使うツールを事前承認
   • 例：Bash(python:*), Read(/tmp/**)
   • 毎回の確認プロンプトをスキップ
4. 環境情報（作業ディレクトリ、OS、日付）
   • 現在のディレクトリパス
   • OS（darwin / linux / win32）
   • 今日の日付（タイムスタンプ計算用）
5. Gitステータススナップショット
   • 現在のブランチ
   • 変更されたファイル一覧
   • 最近のコミット履歴
6. 専用エージェント
   • 一般目的エージェント：複雑な検索・タスク
   • statusline-setupエージェント：UI設定
   • output-style-setupエージェント：出力スタイル設定

「プロジェクト状態のリアルタイム認識」とは？

例えば、あなたが「テストを実行して」と指示した場合、Claude Codeは以下を自動認識します：

• Gitステータスから「テストファイルが変更されている」ことを把握
• 環境情報から「Pythonプロジェクト」だと判断
• CLAUDE.mdから「pytestを使う」ルールを取得
• 事前承認ツールにより、確認なしでpytestを実行

この4層の情報統合により、Claude Codeは「状況に応じた最適な行動」を自律的に選択します。

5. TIER 4（Supporting Systems）──生活の質向上レイヤー

TIER 4は、「必須ではないが、すべてをより良くする」要素です。開発体験（DX: Developer Experience）の向上に寄与します。

TIER 4の5要素

要素	機能	実例
トーン＆スタイルガイドライン	応答のトーン設定	簡潔 / 説明的 / フレンドリー
MCPサーバー操作手順	Model Context Protocol統合	外部ツール連携
スラッシュコマンド	カスタムコマンド定義	/deploy, /test
ヘルプ＆フィードバック	ユーザーサポート	/helpコマンド
システムリマインダー	重要な注意喚起	「Editの前にReadが必要」等

トーン設定の実用例

CLAUDE.mdでトーンを設定できます：

# Output Style: Concise
Claude Codeは簡潔な応答を優先し、冗長な説明を避けます。

# Output Style: Explanatory
複雑な概念の解説時は、詳細な説明とInsightブロックを含めます。

これにより、プロジェクトの性質に応じた対話スタイルを設定可能です。

6. TIER 5（Metadata）──純粋な参照情報

TIER 5は、動作に直接影響しない参照情報です。主にデバッグや状態確認用です。

TIER 5の3要素

1. コード参照形式（ファイルパス:行番号）
   • 例：src/services/process.ts:712
   • ユーザーが該当コードに即座にジャンプ可能
2. トークン予算（上限20万）
   • 現在の使用量：57,829トークン
   • 残り容量：142,171トークン
   • コンテキスト管理の目安
3. ユーザーメッセージ（現在のクエリ）
   • 現在処理中のリクエスト内容
   • 会話履歴の参照

TIER 5は「情報提供のみ」の層ですが、トークン予算の監視は長時間セッションで重要です。20万トークンに近づくと、Claude Codeは自動的に要約や最適化を提案します。

7. 最大のレバレッジポイント：CLAUDE.md戦略

Avila氏が強調する「最大のレバレッジポイント」を実践的に解説します。

なぜCLAUDE.mdが強力なのか？

以下の比較を見てください：

状況	CLAUDE.mdなし	CLAUDE.mdあり
プロジェクト説明	毎回説明が必要	自動認識
コーディング規約	指摘の都度修正	最初から準拠
テスト実行	「pytestを使って」と指示	自動でpytest実行
禁止事項	危険なコードを書いてしまう	事前にブロック
セッション継続性	コンテキスト消失	永続化

実践的CLAUDE.md設定例

以下は、実際のプロジェクトで使える500行級のCLAUDE.md例です：

# CLAUDE.md

## Project Overview

This is a Next.js 14 project with TypeScript, Tailwind CSS, and Prisma ORM.

### Technology Stack
- **Frontend**: Next.js 14 (App Router), React 18, TypeScript 5.2
- **Styling**: Tailwind CSS 3.4, shadcn/ui components
- **Backend**: Next.js API Routes, Prisma ORM
- **Database**: PostgreSQL 16
- **Testing**: Jest, React Testing Library, Playwright
- **CI/CD**: GitHub Actions

## Development Commands

### Environment Setup
- `npm install` - Install dependencies
- `cp .env.example .env.local` - Create environment file
- `npx prisma generate` - Generate Prisma client
- `npx prisma db push` - Push schema to database

### Development
- `npm run dev` - Start development server (http://localhost:3000)
- `npm run build` - Build for production
- `npm run start` - Start production server
- `npm run lint` - Run ESLint
- `npm run format` - Format with Prettier

### Testing
- `npm test` - Run Jest tests
- `npm run test:watch` - Run tests in watch mode
- `npm run test:e2e` - Run Playwright E2E tests
- `npm run test:coverage` - Generate coverage report

### Database
- `npx prisma studio` - Open Prisma Studio
- `npx prisma migrate dev` - Create and apply migration
- `npx prisma migrate reset` - Reset database

## Coding Guidelines

### File Naming Conventions
- **Components**: PascalCase (`UserProfile.tsx`)
- **Utilities**: camelCase (`formatDate.ts`)
- **API Routes**: kebab-case (`/api/user-profile/route.ts`)

### TypeScript Standards
- Use `interface` for object shapes
- Use `type` for unions and intersections
- Always define return types for functions
- Avoid `any` type (use `unknown` if necessary)

### React Best Practices
- Prefer Server Components (default in App Router)
- Use Client Components only when necessary (`'use client'`)
- Extract reusable logic into custom hooks
- Use `useMemo` and `useCallback` for expensive operations

### CSS/Tailwind Guidelines
- Use Tailwind utility classes (avoid custom CSS)
- Use shadcn/ui components for UI elements
- Follow mobile-first responsive design
- Maximum container width: `max-w-7xl`

## Prohibited Practices

### NEVER
- ❌ Use `any` type without justification
- ❌ Commit `.env.local` file
- ❌ Use `console.log` in production code (use proper logging)
- ❌ Create API routes without error handling
- ❌ Skip writing tests for new features
- ❌ Use `npm install` for global packages (use `npx`)

### AVOID
- ⚠️ Client-side data fetching (prefer Server Components)
- ⚠️ Large bundle sizes (check with `npm run analyze`)
- ⚠️ Inline styles (use Tailwind classes)
- ⚠️ Direct DOM manipulation (use React refs)

## Git Workflow

### Branch Strategy
- `main` - Production-ready code
- `develop` - Development branch
- `feature/*` - Feature branches
- `fix/*` - Bug fix branches

### Commit Guidelines
- Use conventional commits: `feat:`, `fix:`, `docs:`, `style:`, `refactor:`, `test:`, `chore:`
- Example: `feat: add user authentication`
- Keep commits atomic and focused

### PR Process
1. Create feature branch from `develop`
2. Write code and tests
3. Run `npm run lint && npm test` before committing
4. Push to GitHub and create PR
5. Wait for CI checks to pass
6. Request review from team members
7. Merge after approval

## Error Handling

### API Routes
Always wrap in try-catch:

```typescript
export async function POST(request: Request) {
  try {
    const data = await request.json();
    // Process data
    return Response.json({ success: true });
  } catch (error) {
    console.error('API Error:', error);
    return Response.json({ error: 'Internal Server Error' }, { status: 500 });
  }
}
```

### Client Components
Use Error Boundaries for graceful error handling.

## Performance Optimization

### Image Optimization
- Use Next.js `
<image>` component
- Specify width and height
- Use `priority` for above-the-fold images

### Code Splitting
- Use dynamic imports for heavy components
- Example: `const Chart = dynamic(() => import('./Chart'), { ssr: false })`

### Database Queries
- Use Prisma's `select` to fetch only needed fields
- Implement pagination for large datasets
- Use database indexes for frequently queried fields

## Security Guidelines

### Environment Variables
- Prefix public variables with `NEXT_PUBLIC_`
- Never expose API keys to client
- Use separate `.env` files for dev/staging/production

### Input Validation
- Validate all user inputs
- Use Zod for schema validation
- Sanitize inputs before database operations

### Authentication
- Use NextAuth.js for authentication
- Implement CSRF protection
- Use secure, httpOnly cookies

## Deployment

### Vercel (Recommended)
- Connect GitHub repository
- Set environment variables in Vercel dashboard
- Auto-deploy on push to `main` branch

### Pre-deployment Checklist
- [ ] All tests passing
- [ ] No TypeScript errors
- [ ] No ESLint warnings
- [ ] Environment variables configured
- [ ] Database migrations applied
- [ ] Performance tested (Lighthouse score > 90)

## Troubleshooting

### Common Issues

**Issue**: Prisma Client not generating
**Solution**: Run `npx prisma generate`

**Issue**: Port 3000 already in use
**Solution**: Kill process with `lsof -ti:3000 | xargs kill`

**Issue**: Module not found after install
**Solution**: Delete `node_modules` and `.next`, then run `npm install`

## Additional Resources

- [Next.js Documentation](https://nextjs.org/docs)
- [Prisma Documentation](https://www.prisma.io/docs)
- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
- [shadcn/ui Components](https://ui.shadcn.com/)
</image>

この500行のCLAUDE.mdがあれば、Claude Codeは：

• ✅ テスト前にnpm run lintを自動実行
• ✅ any型の使用を警告
• ✅ PascalCaseでコンポーネントを作成
• ✅ PR作成時に適切なコミットメッセージを提案
• ✅ エラーハンドリングを自動追加

「ほとんどの開発者がこれを無視している」──Avila氏の指摘通り、CLAUDE.mdを設定しているプロジェクトは稀です。しかし、これこそがClaude Code生産性の10倍差を生む要因です。

8. 実践：Claude Code生産性を10倍にする設定方法

ここまでの知識を実践に落とし込みます。

ステップ1：CLAUDE.mdの作成

プロジェクトルートにCLAUDE.mdを作成：

touch CLAUDE.md

最低限の内容を記述：

# CLAUDE.md

## Project Overview
[プロジェクトの説明]

## Development Commands
- `[テスト実行コマンド]` - Run tests
- `[ビルドコマンド]` - Build project

## Coding Guidelines
- [命名規則]
- [禁止事項]

ステップ2：フックシステムの活用

Claude Codeのフックシステムで自動化：

# .claude/hooks/pre-commit.sh
#!/bin/bash

# テストを実行
npm test

# リンターを実行
npm run lint

# 失敗したら中断
if [ $? -ne 0 ]; then
  echo "❌ Tests or linter failed. Commit aborted."
  exit 1
fi

このフックにより、Claude Codeがgit commitする前に自動的にテストとリンターが実行されます。

ステップ3：事前承認ツールの設定

頻繁に使うツールを事前承認：

# CLAUDE.mdに追加

## Pre-approved Tools
- `Bash(npm test:*)`
- `Bash(npm run:*)`
- `Read(//src/**)`
- `Edit(//src/**)`

これにより、毎回の確認プロンプトをスキップできます。

ステップ4：TodoWrite自動化

複雑なタスクでは、Claude CodeにTodoWriteの使用を指示：

# CLAUDE.mdに追加

## Task Management
- For tasks with 3+ steps, ALWAYS use TodoWrite to track progress
- Mark tasks as in_progress before starting
- Mark tasks as completed immediately after finishing

生産性10倍の根拠

改善項目	時間削減	年間節約（200営業日）
プロジェクト説明	1日10分 → 0分	33時間
コード修正（規約違反）	1日30分 → 5分	83時間
テスト実行指示	1日5分 → 0分	17時間
エラーハンドリング追加	1日15分 → 0分	50時間
合計	60分 → 5分	183時間（約23営業日）

年間で約1ヶ月分の作業時間を節約できます。これが「10倍生産性」の実態です。

まとめ：Claude Codeの真の力を引き出す

Daniel Avila氏が解剖したClaude Codeの5階層アーキテクチャは、単なる技術的分析ではありません。「どこに注力すれば最大の効果を得られるか」という実践的な指針です。

5階層の要点

• TIER 1（Critical）：変更不可の安全装置
• TIER 2（Core Behaviors）：CLAUDE.mdで最大のレバレッジ
• TIER 3（Operational）：リアルタイム状態認識
• TIER 4（Supporting Systems）：開発体験の向上
• TIER 5（Metadata）：デバッグ用参照情報

今日から実践すべきこと

1. CLAUDE.mdを作成：500行まで使える、プロジェクトの全知識を注入
2. フックシステム設定：自動テスト・リンターを組み込み
3. 事前承認ツール活用：頻繁な操作の確認をスキップ
4. TodoWrite活用：複雑タスクの進捗可視化

Avila氏の言葉を再度引用します：

「ほとんどの開発者はCLAUDE.mdを無視しています。しかし、ここに500行のコンテキストを注入すれば、全セッションで永続化されます。これが最大のレバレッジポイントです。」

914人がブックマークしたこの知見を、あなたも今日から実践してください。Claude Codeは単なるAIアシスタントではなく、適切に設定すれば「プロジェクト専用のシニアエンジニア」に変貌します。

5階層アーキテクチャの理解こそが、Claude Code真の力を引き出す鍵なのです。