プロジェクト用 CLAUDE.md / instructions の書き方 | 生成AIxPythonで始める株式分析|Python×J-Quants

生成AI に毎回同じ前提を伝える手間は、プロジェクトのルートに置く 指示書ファイル で大幅に減らせます。本記事では CLAUDE.md / .cursorrules / instructions と総称される指示書の役割と、書き方の型を整理します。

指示書ファイルとは
何を書くか(コア 5 項目)
1. プロジェクトの目的・ターゲット
1. ディレクトリ構成
ディレクトリ構成
1. 言語・ライブラリ・バージョン
環境
1. コーディング規約・スタイル
コードスタイル
1. やってはいけないこと
やってはいけないこと
短さと厚みのバランス
ファイルへの誘導はツール依存
サンプル指示書(短縮版)
プロジェクト目的
ディレクトリ
環境
コードスタイル
やってはいけないこと
指示書を更新するタイミング

指示書ファイルとは

プロジェクトのルート(またはサブフォルダ)に置いて、生成AI が 作業を始める前に必ず読むコンテキスト を記述するファイルです。ツールごとに名前が違うことがあります。

ツール / 用途	代表的なファイル名
Claude Code	`CLAUDE.md`
Cursor	`.cursorrules`
GitHub Copilot Chat	`.github/copilot-instructions.md`
汎用(自前で読み込ませる)	`instructions.md` / `AGENTS.md`

ファイル名はツール依存ですが、書き方の型は共通 です。本記事では「指示書ファイル」と総称します。

何を書くか(コア 5 項目)

最低限、次の 5 項目があれば「毎回の説明」を 8 割は減らせます。

プロジェクトの目的・ターゲットユーザー
ディレクトリ構成
言語・ライブラリ・バージョン
コーディング規約・スタイル
やってはいけないこと

順番は固定で構いません。読み手(生成AI)にとっての作業前チェックリスト を意識します。

1. プロジェクトの目的・ターゲット

冒頭で、プロジェクトが何のためにあるか・誰が読むかを 2〜3 行で書きます。

# プロジェクト目的

- 日本株の日次データを J-Quants API から取得し、ローカルに蓄積する
- 教育目的(投資助言ではない)
- ターゲット: Python と株式分析が初めての学習者

「教育目的」「投資助言ではない」のような トーン に関わる情報も含めると、生成AI が出力する文体に反映されやすくなります。

2. ディレクトリ構成

主要なディレクトリと、それぞれの役割を書きます。生成AI に「どこに何を置くか」を判断させるためです。

## ディレクトリ構成

```text
src/
  fetch/         # J-Quants API 呼び出し
  storage/       # ローカル DB(parquet)の読み書き
  analysis/      # 集計・指標計算
  notebooks/     # 探索的分析(本流コードからは import しない)
tests/           # pytest 用テスト
data/            # ローカルキャッシュ(git 管理外)

新規ファイルを作るときに、生成AI が場所を悩まなくなります。

## 3. 言語・ライブラリ・バージョン

依存関係の中心となる情報をまとめます。

```markdown
## 環境

- Python 3.12
- pandas 2.2 系
- numpy 2.x
- ruff(リンター)
- pytest(テスト)

依存ライブラリの追加には pyproject.toml の更新が必要です(prompt で必ず指示してください)。

「pandas 2.2 系」と書くだけで、ハルシネーション(廃止 API の使用)を抑制できます(#7-5「ハルシネーション(存在しない関数)への対処」)。

4. コーディング規約・スタイル

コーディング規約は、サンプルを 1 つ載せると伝わりやすくなります。

## コードスタイル

- 関数には型ヒント必須
- docstring は日本語、Google スタイル
- main 関数を持つ単一スクリプト形式を基本
- I/O は CSV / Parquet。Excel への直接書き出しは行わない

例:

```python
def calc_sma(series: pd.Series, window: int = 5) -> pd.Series:
    """単純移動平均を計算する。

    Args:
        series: 終値などの時系列。
        window: 平均期間。

    Returns:
        移動平均の Series。
    """
    return series.rolling(window).mean()

例があると、生成AI は **そのスタイルに揃える** 確率が高くなります。

## 5. やってはいけないこと

明文化することで、出力にブレーキをかけます。

```markdown
## やってはいけないこと

- API キーをコードに直書きする(必ず os.environ 経由)
- 既存ファイルを大量に書き換える(diff が小さくなるよう、最小変更を原則)
- requirements を勝手に追加する(必要なら依頼者に確認)
- 投資推奨にあたる文言を出力する(教育目的に限定)
- テスト未実行のコードを「動作確認済み」と書く

否定的な指示は、肯定的な指示よりも効果が出やすいことがあります。

短さと厚みのバランス

指示書ファイルは長くしすぎると、ツールの読み込み量に対する効率が落ちます。目安は次の通りです。

200〜500 行が現実的なライン
階層構造で 目次が見えるように する
「いつ参照するか」を最初の数行に書く

長くなりすぎる場合は、領域別にファイルを分けます。

CLAUDE.md                       # 全体目次・必読リンク集
docs/
  writing-style.md              # スタイルガイド
  api-conventions.md            # API 設計ルール

この pykabu.com リポジトリ自身も、ルートに CLAUDE.md を置き、執筆スタイルは docs/writing-style.md に分けています。

ファイルへの誘導はツール依存

「生成AI が自動で読んでくれる」かどうかはツール依存です。読まないツールでは、チャット冒頭で明示的に誘導 します。

作業を始める前に、リポジトリルートの CLAUDE.md を読んでください。
本リポジトリの前提・スタイル・禁止事項が記載されています。

ツールによっては、ルートにファイルを置くだけで自動的に読み込まれるものもあります(Claude Code 等)。

サンプル指示書(短縮版)

最小限の指示書テンプレートを載せます。プロジェクト名と該当箇所だけ書き換えれば動く形です。

# このリポジトリで作業する生成AI 向けの指示書

作業を始める前に、本ファイルを読んでください。

## プロジェクト目的

- (1〜2 行で書く)
- ターゲット: (誰が使うか)

## ディレクトリ

- src/  : 本番コード
- tests/: pytest 用テスト
- data/ : ローカルデータ(git 管理外)

## 環境

- Python 3.12 / pandas 2.2 / numpy 2.x

## コードスタイル

- 関数に型ヒント必須
- docstring は日本語

## やってはいけないこと

- API キーの直書き
- 既存ファイルの大規模な書き換え
- 依存ライブラリの勝手な追加

最初はこれでスタートし、運用しながら追記していくのが現実的です。

指示書を更新するタイミング

指示書は「書きっぱなし」では効果が薄れていきます。次のタイミングで見直します。

新しいライブラリ・規約を採用した時
生成AI が同じ間違いを 2 回以上した時(その間違いを禁止項目に追加)
ディレクトリ構成を変えた時
プロジェクトのターゲットが変わった時

「同じ説明を毎回書いている」と感じたら、指示書に昇格させます。

生成AI へのプロンプト例

既存リポジトリから指示書の素案を作るには、生成AI の力を借りる手があります。

リポジトリ全体を読んで、生成AI 向けの instructions.md の素案を作ってください。

含める項目:
1. プロジェクト目的
2. ディレクトリ構成
3. 環境(Python とライブラリのバージョン)
4. コーディング規約
5. やってはいけないこと

形式: Markdown。長さの目安は 200 行以内。

返ってきた素案を、人間が読みながら埋めていきます。100% を生成AI に書かせるのではなく、たたき台 として扱うのが現実的です。

まとめ

指示書ファイル(CLAUDE.md など)に前提を集約すると、毎回の説明が減る
コア 5 項目: 目的・構成・環境・規約・禁止事項
ツール依存だが、書き方の型は共通
200〜500 行が目安。長くなる場合は領域別に分割
同じ説明を 2 回したら、指示書に昇格させる