claude-md-architect

CLAUDE.md アーキテクトスキル

コードベースのコンテキストを分析し、Anthropic のエンジニアリングのベストプラクティスを適用することで、ソフトウェアプロジェクト向けの CLAUDE.md ファイルを生成・最適化します。簡潔で保守しやすいプロジェクト指示を作成し、トークン消費を抑えながら Claude Code の効果を最大化します。

基本原則

1. 網羅性より簡潔さ：CLAUDE.md は包括的なドキュメントではなく、頻繁に使うプロンプトとして扱います
2. 根拠に基づくコンテキスト：推奨事項を提示する前に、実際のコードベースを分析します
3. 段階的な改善：最小限の内容から始め、効果に基づいて反復的に改善します
4. トークン効率：すべての行がコンテキストウィンドウに含める価値を持つようにします
5. 人が読みやすい構成：解析しやすいよう、XML タグを使って明確に整理します

このスキルを使用するタイミング

ユーザーが次のように依頼した場合に有効にします：

• 「init CLAUDE.md」または「プロジェクトの指示を作成して」
• 既存の CLAUDE.md を「最適化」または「改善」
• 「プロジェクト用に Claude をセットアップして」
• Claude Code 向けのプロジェクト固有の指示
• ドキュメントが必要な新しいプロジェクトで作業を開始する
• 既存の CLAUDE.md が古くなっている、または効果がない

クイック判断ツリー

User Request
    │
    ├─→ "init" or "create" → Initialize New CLAUDE.md
    │   └─→ Follow: @refs/initialization-workflow.md
    │
    ├─→ "optimize" or "improve" → Optimize Existing CLAUDE.md
    │   └─→ Follow: @refs/optimization-patterns.md
    │
    └─→ "integrate" or "setup MCP/slash commands" → Integration
        └─→ Follow: @refs/integration-strategies.md

ワークフローの概要

新しい CLAUDE.md を初期化する

手順の概要：

1. 調査 - コードベースを分析します（言語、フレームワーク、構成、テスト）
2. 抽出 - コードスタイル、コマンド、パターンを特定します
3. 生成 - テンプレートを選択し、プロジェクトに合わせてカスタマイズします
4. 検証 - コマンドを確認し、トークン数を確認します
5. 提示 - 説明を添えて出力を示します

詳細な手順： @refs/initialization-workflow.md

既存の CLAUDE.md を最適化する

手順の概要：

1. 分析 - トークン効率、正確性、関連性を評価します
2. 特定 - 重複、古い情報、内容の薄い一般論を見つけます
3. リファクタリング - トークン削減、構成の再編、明瞭さの向上を行います
4. テスト - トークンを 40% 以上削減し、重要な情報が保持されていることを確認します
5. 提示 - 指標とともに変更前後を示します

詳細な手順： @refs/optimization-patterns.md

トークン削減のクイックリファレンス

変更前（冗長）

When you are implementing new features in this codebase, it's very important that you always make sure to write comprehensive tests for all the functionality you add. We use Jest as our testing framework, and we expect all new code to have at least 80% code coverage.

変更後（簡潔）

### Testing Requirements
- New features require tests (Jest, >80% coverage)
- Unit tests: Individual functions in `src/lib/`
- Integration tests: API endpoints with Supertest

結果： 同じ情報を維持しながら、トークンを 70% 削減

テンプレート選択ガイド

プロジェクトの種類	主な指標	テンプレートの重点
Web アプリ	React/Vue/Angular、フロントエンドのビルド	UI コンポーネント、レスポンシブデザイン、ルーティング
バックエンド API	Express/FastAPI、データベース、認証	RESTful の規約、バリデーション、セキュリティ
CLI ツール	Commander/Click、stdio	コマンド、ユーザー体験、ファイル操作
ライブラリ	パッケージのエクスポート、アプリのロジックなし	API 設計、バージョニング、後方互換性
モノレポ	ワークスペース、複数のパッケージ	パッケージ間の変更、ワークスペースのコマンド

品質チェックリスト

CLAUDE.md を提示する前に：

• ✓ ファイルが 400 行未満（250 行未満を推奨）
• ✓ package.json/Makefile に照らしてコマンドを検証済み
• ✓ パターンが実際のコードベースの規約に合致
• ✓ README にすでにある冗長な情報がない
• ✓ コンテキストの読み込みが網羅的ではなく選択的
• ✓ 見出しを使った明確なセクション構成
• ✓ 具体的な例を使用し、一般論に頼っていない
• ✓ セキュリティとテストの要件が実際のニーズを反映

トークン予算のガイドライン

プロジェクトの複雑さ	目標トークン数
シンプル（単一目的のツール）	100-200 tokens
中程度（一般的な Web アプリ）	200-400 tokens
複雑（複数サービスのプラットフォーム）	400-800 tokens
最大（例外のみ）	1000 tokens

上限に近づいた場合は、次のように分割します：

• .claude/CLAUDE.md（必須事項）
• .claude/ARCHITECTURE.md（参照用、自動読み込みなし）
• .claude/commands/*.md（スラッシュコマンドとしてのワークフロー）

コンテンツの優先順位

残す（価値が高い）

• プロジェクト固有のコマンドとスクリプト
• このプロジェクト固有のコードスタイル規約
• ファイル構成のパターン
• テスト要件とテスト戦略
• セキュリティ上の制約
• パフォーマンスに関する考慮事項

削除する項目（価値が低いもの）

• 一般的なソフトウェアエンジニアリングのアドバイス
• README にすでに記載されている情報
• 明らかなベストプラクティス（DRY、SOLID など）
• フレームワークの詳細な説明（context7 を使用）
• 手順を追ったチュートリアル（ドキュメントへのリンクを使用）

コンテキストの読み込み戦略

@ 構文を使用するのは次の場合のみ：

• 小規模で、あらゆる場面で関連性のあるファイル（100 行未満）
• すべての変更に影響する設定ファイル（tsconfig、.eslintrc）
• あらゆる場所で使用されるコア型定義

必要に応じて読み込む：

When working on authentication:
  @src/lib/auth.ts
  @src/middleware/authenticate.ts

避けること：

• ディレクトリ全体を @src/** で読み込む
• 常に必要とは限らない大きなファイルを追加する
• 公式ソースと重複するドキュメントを注入する

グローバル CLAUDE.md との統合

ユーザーが ~/.claude/CLAUDE.md（グローバル）を持っている場合：

• 普遍的な原則（SOLID、DRY、YAGNI）
• MCP ツールのドキュメント
• 希望するコミュニケーションスタイル

プロジェクトの CLAUDE.md では：

• プロジェクト固有のガイダンスだけに専念する
• MCP ツールの使用方法を重複して記載しない（すでにグローバルにあるため）
• プロジェクト固有の MCP ツールの活用方法のみを追加する

ヘッダーの例：

# MyProject - Development Guide

> Note: General software engineering principles are in your global CLAUDE.md.
> This guide focuses on project-specific patterns and requirements.

MCP ツールの設定

活用機会を検出する：

• React/Vue/Angular のインポート → 公式ドキュメントには context7 を提案する
• UI コンポーネントのリクエスト → パターンには magic MCP を提案する
• E2E テストファイル → ブラウザーの自動化には Playwright MCP を提案する

CLAUDE.md に追加する：

## MCP Tools Configuration

### context7 (Official Documentation)
Use for React hooks, Next.js routing, Prisma schema

### magic (UI Component Generation)
Use for new components, accessibility improvements

### Playwright (E2E Testing)
Use for user flows, visual regression, accessibility audits

詳細な統合ガイド： @refs/integration-strategies.md

出力形式

新しい CLAUDE.md を生成する場合

1. 生成した内容をコードブロックで表示する
2. 分析に基づくカスタマイズ内容を説明する
3. 主な決定事項を強調する
4. 任意で追加できる項目を提案する
5. 保存場所と次の手順を示す

既存の CLAUDE.md を最適化する場合

1. 見つかった問題を要約する
2. 主なセクションの変更前／変更後を比較する
3. 最適化した完全版を提示する
4. 改善効果を定量化する（トークン削減率）
5. 反復的な改善方法を提案する

詳細なテンプレート： @refs/output-templates.md

よくある間違いと回避方法

問題	解決策
ドキュメントの過剰な記載	プロジェクト固有の決定事項のみを記載する
古い情報	現在の package.json とファイルに照らして確認する
重複するコンテキスト	README にリンクし、固有のパターンのみを追加する
トークンの浪費	機能領域ごとに必要に応じてコンテキストを読み込む
一般論に終始した冗長な記述	具体的なパターン：「Zod によるバリデーション、Prisma のトランザクションを使用する」

成功指標

効果的な CLAUDE.md

• Claude が確認の質問をする回数が減る
• コードが最初からプロジェクトの規約に沿っている
• コマンドがエラーなく動作する
• ユーザーが不足しているコンテキストを手動で補うことがほとんどない

効果のない CLAUDE.md

• Claude が「どのフレームワークですか？」と頻繁に尋ねる
• 生成されたコードが既存のスタイルに合わない
• ユーザーが同じコンテキストファイルを何度も提供する
• CLAUDE.md に一度も参照されない情報が含まれている

基本方針

覚えておくこと：

• CLAUDE.md は継続的に更新するドキュメントであり、固定的なドキュメントではありません
• 最小限から始め、実際に問題が発生した箇所に基づいて追加する
• Claude の出力を改善しないガイダンスは削除する
• 効果を測定する：質問が少ないほど、CLAUDE.md の質が高い

判断に迷った場合：

• 網羅的な内容より簡潔な内容を優先する
• 一般的な内容より具体的な内容を優先する
• 説明より例を優先する
• 自動読み込みより必要に応じた読み込みを優先する

参照ファイル

• @refs/initialization-workflow.md - 新しい CLAUDE.md ファイルをゼロから作成するための完全ガイド
• @refs/optimization-patterns.md - トークンを削減し、効果を高めるための手法
• @refs/integration-strategies.md - グローバル設定、MCP ツール、スラッシュコマンドとの統合
• @refs/output-templates.md - ユーザーに結果を提示するための標準形式

---

クイックスタート： ユーザーから CLAUDE.md の作成または最適化を依頼されたら、上記の判断ツリーに従い、詳細な手順について関連する参照ファイルを確認してください。