# Claudeは、毎回のセッションを、何も見えない状態から始める。

Canonical source: https://maguyva.ai/ja/for-claude-code

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

`CLAUDE.md`は、Claudeにどう振る舞うかを教えます。あなたのリポジトリに何があるかは教えません。Maguyvaはコードベースをインデックス化し、MCP経由で返します。だから、Claudeはまるですでにコードを読んだかのように編集します。

> 振る舞いにはCLAUDE.mdを。現在のコードベースの事実にはMaguyvaを。

## CLAUDE.mdはベストプラクティスです。使いましょう。

```text
> cat CLAUDE.md
# project conventions, commands, scoped rules
```

永続的な指示は、`CLAUDE.md`に置くべきものです。以下のことを書くのに適した場所です:

- エージェントが実行すべき、ビルド、テスト、lintコマンド。
- コーディングスタイルのルールと命名規則。
- ディレクトリ単位でスコープされた「常にXをする / 決してYをしない」というガードレール。
- 正式なドキュメントや意思決定ログへのポインタ。

Anthropicの[メモリドキュメント](https://code.claude.com/docs/en/memory)が、これをよく説明しています。簡潔にまとめてください。スコープを絞ってください。コミットしてください。

しかし、`CLAUDE.md`は、あなたのコードベースの地図であることを意図されたことは一度もありません。

## CLAUDE.mdだけでは足りなくなる場所

マークダウンだけでは解決できない、4つの失敗モード。

### // ファイルはコードベースではない

Claudeに*どう振る舞うか*を教えても、*何が存在するか*は教えられません。見慣れないリポジトリでの最初の編集は、ファイルパス、関数名、呼び出し箇所についての当てずっぽうになります。CLAUDE.mdは、すべてのシンボルを列挙することはできませんし、そうすべきでもありません。

### // ドキュメントは古くなるが、コードは古くならない

認証フローを説明する`CLAUDE.md`の記述は、誰かが認証をリファクタリングするまでは正しい。今や信頼できる情報源はコードであり、ドキュメントは自信満々に間違っています。Claudeは、間違った方を読んでしまいます。

### // 依存関係はマークダウンには書かれていない

「この関数を変更したら何が壊れるか?」は、グラフの問題です。ドキュメントファイルでは答えられません。Claudeは、grepして祈るか、ファイルをチャットに貼り付けるようあなたに頼むしかありません。

### // コンテキストウィンドウには予算がある

Claudeが「十分に知っている」と思えるまでCLAUDE.mdを詰め込むと、推論に使うべきトークンを消費してしまいます。数KBを超えると、回答の質をコンテキストの量と引き換えにすることになります。

## MaguyvaはCLAUDE.mdがカバーしないレイヤーです

Claude Codeに、以下を与えるリモートMCPサーバーです:

- **Semantic、AST、グラフ、テキスト検索**: インデックス化されたリポジトリを対象に、ファイルパスと行番号付きで返します。
- **Dependency、型、呼び出し箇所のルックアップ**: グラフなら答えられて、ドキュメントファイルには答えられない質問です。
- **ブランチを認識する結果**: だから、Claudeは実際に編集しているバージョンのコードを把握できます。
- **ワークスペース単位の料金**: シート単位ではありません。リポジトリは1つでも50でもインデックスできます。エージェントはシート料金を払いません。

> CLAUDE.mdは、Claudeに*どう振る舞うか*を教える。
> Maguyvaは、Claudeに*コードの問い合わせ可能な地図*を与える。

## 3つのワークフロー

番号付きで、コードブロック中心。あなたがすでにClaudeに尋ねている質問が、実際の行に根ざした形で。

### 01. テストスタブではなく、実際の実装を見つける

```text
あなた: "うちの決済クライアントではリトライはどう動作していますか?"

Maguyvaなし → Claudeが retry をgrepし、14件のヒットから1つを選ぶ(たいていテスト用のモック)。
Maguyvaあり    → Maguyvaがシンボル定義、呼び出し箇所、そして
                   実際の実装の file:line をランク付けして返す。
```

### 02. リファクタリングの前に、影響範囲を確認する

```text
あなた: "normalizePhoneNumber を呼び出しているのは?"

Maguyvaが返す結果: 4つのパッケージにまたがる7件の呼び出し箇所。そのうち1件は
gRPCスタブ経由でインポートしているPythonサービスです。ClaudeはCIが赤くなってからではなく、
移行リストを添えてすぐに変更を提案します。
```

### 03. 差分を受け入れる前に、エージェントを検証する

```text
Claude: "トークンのリフレッシュを修正するため src/auth/session.ts:142 を編集しました。"

Maguyvaへの質問: "session.ts:130-160 と、それをインポートしているものを見せて"

Maguyvaが返すのは実際のファイルの該当箇所と、それをインポートしている3件です。この差分は
トークン#11,000あたりのClaudeの記憶ではなく、実際の行に基づいています。
```

## Claude Codeでのセットアップ

3ステップ。Freeプラン: リポジトリ3個, インデックス済みリポジトリ行数、最大5万行、カード不要。

### 01. maguyva.aiでリポジトリをインデックス化

回答を検証できるよう、よく知っているものを選びましょう。Freeプランはリポジトリ3個, インデックス済みリポジトリ行数、最大5万行をカバーします。

### 02. Claude CodeにMaguyvaプラグインをインストール

```text
/plugin marketplace add maguyva/agent-plugins
/plugin install maguyva@maguyva

# the plugin reads your key from the environment
export MAGUYVA_API_KEY=mgv_xxxx
```

### 03. 答えをすでに知っている質問をひとつ投げてみる

会社全体ではなく、1つのリポジトリと検証可能な質問1つから始めましょう。答えがあなたの想定と一致すれば、準備完了です。

完全な手順は、[Maguyvaのドキュメント](https://maguyva.ai/ja/docs)にあります。

## すでに知っているリポジトリを1つインデックス化。

検証できる質問を1つ、試してみましょう。オンボーディングは、それだけです。