🤖

Claude Code のグローバルプロンプトについて考える

に公開
AI
Claude Code
tech

Claude Codeでは.claude/CLAUDE.md内に書かれた内容がプロジェクト全体の定義となるグローバルプロンプトとして認識されるため、書きぶりについて考察していきます。

基本的な構造

.claude/CLAUDE.mdではh1タイトル、つまり#から始まるセクションをAIのメモリに保持させることができるため、h1タイトル以下にプロンプトのリストを含む形が基本形となります。
h1タイトルの内容や粒度は、様々な試行錯誤が試されていますが、おおよそ以下の形が定型になっています。

  • Project Overview
    • プロジェクトの目的、構成技術、全体像を簡潔に明示
  • Coding Standards
    • 型、スタイルガイド、命名規則などを明示
  • Folder Structure
    • ディレクトリ構造の説明
  • Design Principles
    • 設計ポリシー（SOLID原則やアーキテクチャ方針など）を明示
  • Claude Usage Guidelines
    • Claude への指示（何をすべきか／避けるべきか）を明示

ドメインの扱い方

業務知識や専門用語などのドメインの扱い方については以下の2つの方法があります。
ただし、それぞれの方法でAIの振る舞いが変わるため、それにあった情報を記述する必要があります。

  • 専用のプロンプト.claude/context/*.mdを作成し参照させる
    • AIの常識とさせる必要がある「プロジェクト全体の背景知識」を記述する
  • コード内にコメントで記述する
    • 各関数・クラスが何をしているかなどの「ローカルな意図や補足」を記述する

日本語の扱い方

日本語は世界でも類を見ないほど難解な言語であり、英語から日本語、日本語から英語への変換が重なるたびにコンテキストが変化してしまう可能性があります。
これを解決するために以下ようなプロンプトを記述する必要がありそうです。

  • Language Policy
    • 言語の使い分けルールを明示
    • 対話は日本語、理解・設計は英語というルールをはっきり定義することで再翻訳を防ぐ
    • 具体的なプロンプト例：
      - Communication with the AI (Claude) occurs in Japanese.
- However, Claude should interpret prompts and context **as if written in English internally**.
- Claude should **not back-translate** Japanese input into literal English; instead, understand the *intended meaning* in English from a developer’s perspective.
- Code comments should be written in clear, reader-friendly Japanese.
- Architectural reasoning and logic flows should follow English technical conventions.

上に加えて、基本構造のプロンプトにも日本語の扱い方について記述すると Claude の判断にぶれが出にくくなります。

  • Coding Standards
    • 命名は英語、コメントは日本語など、命名規則や注釈スタイルの言語を分離することを明示
    • 具体的なプロンプト例：
      - Comments should clearly explain "why" something is done (in Japanese).
- Avoid katakana-English in code (e.g., use `submitForm`, not `サブミットフォーム`).
  • Claude Usage Guidelines
    • 英語の開発スタイルで理解・提案するように指示
    • 具体的なプロンプト例：
      - Generate code, naming, and architecture based on English best practices, even if the description is in Japanese.
- Always output function/variable names in English.
- Use Japanese for human-facing content (UI labels, comments, explanations).

Discussion