毎回同じ説明をしないための 2 つのファイル

同じことを毎回説明していました。「.env は開かないで」「使い捨ては _scratch/ に置いて」。会話を新しく始めるたびに、また最初から言い直す。

その説明は、ファイルに置けます。置いておくと、次からは言わなくて済みます。

決まりは CLAUDE.md、権限は settings.json

前者は「知っておいてほしいこと」、後者は「勝手にやっていいかどうか」です。混ぜて書くとどちらも効きません。

読まれるタイミングも違います。もう 1 つ、ファイルの種類ごとに読ませる置き場所もあるので、先に 3 つ並べておきます。

まず 1 枚ずつ作ってみる

読む前に置いてしまうほうが早いです。3 分で終わります。

# CLAUDE.md

- 返信は日本語で
- 一時ファイルは `_scratch/` に置く
- `.env` は開かない

{
  "permissions": {
    "deny": ["Read(./.env)"]
  }
}

ここから先は、私が実際に何を書いているかです。

毎回読ませるものを、できるだけ減らす

置いたあとに効いてくるのは、長さです。CLAUDE.md は毎回読まれるので、 書けば書くほど「関係ない話まで毎回読まれる」状態に寄っていきます。 私は毎回効くものだけを CLAUDE.md に残し、残りは種類ごとに分けています。

CLAUDE.md には、毎回効くことだけ書く

この章を書いた時点で、私の CLAUDE.md は 57 行です。短くしているのは、毎回読まれるからです。

# CLAUDE.md

## セキュリティ（最優先）

**判断基準の正本は guide/principles.md「セキュリティ（最優先）」**（どこまでが「公開」か・匿名化の具体例）。

- **API キー・トークン・個人情報を外に出さない。** ログ・デバッグ出力にキーの値を含めない。
  パス・コマンド例のユーザー名・フォルダ名は匿名化する（`C:/Users/<username>/` の形）
- **`.env` の読み取り・表示・出力・アップロードは、ユーザー承認があっても実行しない**
- **外部に出す操作は事前承認。** サーバーへのアップロードは対象ファイルと送信先を明示する。
  外部サービスへの投稿・書き込みは明示的な OK なしに実行しない
- **GitHub リポジトリは必ず Private**
- **API キー・認証・外部公開・課金を扱う実装の前に guide/dev/security.md を読む**
- **どの操作にユーザー承認が要るかの一覧は CONTRIBUTING.md「人間の承認」**

## Git・共同編集

**複数 AI が同時に編集する。git 操作の前に CONTRIBUTING.md（誰が・どこで・何をしてよいか）と
guide/ops/git.md（git の使い方）を読む。**

- **ブランチを切る・切り替える前に `git status` / `git worktree list` を確認する。**
  身に覚えのない変更があればユーザーに聞く（勝手に stash / checkout しない）

## ドキュメントルーティング（作業別に読むファイル）

| 作業 | 先に読む |
|---|---|
| プロジェクト特定・**迷ったら** | `operations/index.md` |
| **今やること・定期作業** | `operations/work/` |
| プロジェクト内の作業全般 | 直下の `README.md`（正本・特に「## 作業ルール」） |
| **新規追加・廃止** | `guide/ops/checklist.md`（配置の決定木・命名規則・手順） |
| **アプリの設計・仕様・品質・安全** | `guide/dev/architecture.md` → `documentation.md` / `code-quality.md` / `security.md` |
| cron・サーバー作業 | `operations/state/server.md` |
| 運営コストの記録・集計 | `operations/finance/README.md` |
| サイト UI・デザイン | `product/site-kanalyzelab/frontend/docs/design-system.md` |
| 記事執筆 | `/writing` スキル |
| **調査・リサーチ** | **必ず `/research` を最初に使う**（直接 WebSearch しない） |

## 共通ルール

- **同じ事実を 2 箇所に書かない**（リンクで繋ぐ）。**規範に現況を書かない**
- セッション横断の使い捨ては `_scratch/`（gitignore 済）へ。
  **プロジェクト直下に勝手にフォルダを作らない**
- パス・フォーマットを変えたら producer / consumer / docs を同時に更新する

## 言語・文字コード

- Think in English, interact with the user in Japanese.
- `.md` は UTF-8 で読み書きする
- **文字化けした表示を根拠に内容を判断しない**（UTF-8 指定で読み直す）

長く書くほど効くわけではありません。毎回読まれるということは、関係ない話まで毎回読まれるということです。だから本文には書かず、行き先だけを表にしています。上の抜粋でも、いちばん場所を取っているのがその表です。

こう書いておくと、頼んだときに勝手にそのファイルを読んでから始めてくれます。全文を CLAUDE.md に写す必要はありません。

ファイルの種類ごとに分ける（.claude/rules/）

とはいえ「Python を書くときの決まり」を全部 CLAUDE.md に入れると、Markdown を書いているときにも毎回読まれます。

これは .claude/rules/ に分けられます。ファイルの先頭に、どのファイルを触ったときに読ませるかを書きます。

---
paths: product/**/*.py, tools/**/*.py, .claude/hooks/*.py
description: Python 実装時の規範。Ruff・型・テストの要件
---

こう書いておくと、.py を触るときだけこの決まりが入ります（エディタで開いたときではなく、AI がそのファイルを読む・書き換えるときです）。この章を書いた時点（2026 年 9 月 7 日）で、私は 6 ファイル・合わせて 395 行をこの形で持っていました。この節の数字は、以下すべてこの日のものです。

全部を CLAUDE.md に足していたら、57 行が 452 行になっていました。 そのうち大半は、そのとき書いている作業と関係ありません。

settings.json は「聞かれる回数」を決める

仕組みそのもの（3 つのファイルの優先順位・書けるパターンの一覧・settings.local.json の落とし穴）はsettings.json で権限管理してみてわかったことにまとめてあります。ここでは、どれをどのバケツに入れるかの決め方だけ書きます。

3 つのバケツに振り分ける

バケツは 3 つです。

書き方は ツール名(パターン) の形です。Bash のときだけ、括弧の中がコマンドになります。

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(bash deploy.sh staging)"
    ],
    "ask": [
      "Bash(gh pr merge *)",
      "Bash(*deploy.sh prod*)",
      "Bash(git push --force*)"
    ],
    "deny": [
      "Read(./.env)",
      "Bash(cat *.env*)",
      "Bash(git push * master*)"
    ]
  }
}

評価は deny → ask → allow の順で、最初に当たったものが勝ちます。 allow に書いても deny にも当たれば止まります。

私が止めているもの

私の場合、ask は 18 個でした（2026 年 9 月 7 日時点）。内訳はこうなっています。

deny は 55 個ありましたが、半分近くは .env を読ませないための書き方違いです（cat でも head でも scp でも止まるように並べた結果、24 個になりました）。次に多いのが、もう 1 つの AI の作業フォルダを触らせないための 15 個です。

allow を増やすと作業が止まらなくなり、ask を増やすと安心が増えます。 どちらに寄せるかは、何を壊したら困るかで決まります。私は「壊れたら自分では戻せないもの」を基準にしました。

Git に入ることだけ注意する

settings.json は Git に入ります。 パスワードや鍵が混ざったコマンドを、そのまま allow に書かないでください。自分の環境でしか使わないものは settings.local.json に分けます。こちらは Git に入りません。

私のフォルダ構成（参考）

参考までに、この章を書いた時点（2026 年 9 月 7 日）の形を出します。これが正解というより、増えるたびに散らからないよう押し込んだ結果です。

kanalyzelab/
  CLAUDE.md          毎回読ませる決まり
  AGENTS.md          Codex 用の入口。中身は CLAUDE.md へのリンクが中心
  README.md          このリポジトリは何か
  CONTRIBUTING.md    誰が・どこで・何をしてよいか
  .claude/
    settings.json    許可と確認の設定
    rules/           ファイルの種類ごとの決まり（6 ファイル）
    skills/          手順をまとめて名前を付けたもの（9 個）
    agents/          役割を分けた AI（レビュー役など）
    hooks/           ツールを使う前後に走る検査
  product/           届けるもの（サイト・アプリ・cron）
  tools/             作るための道具
  operations/        運営（計画・やること・現況・会計）
  guide/             自分たちで決めたルール
  knowledge/         調べたこと・気づいたこと
  _assets/           素材（Git に入れない）
  _secrets/          鍵と認証情報（Git に入れない・読み取り禁止）
  _scratch/          使い捨て（Git に入れない）

決めごとは 2 つだけです。

ルート直下にプロジェクトを並べない。 増えるたびに直下が散らかるので、役割ごとの箱に押し込みます。product/ の中にサイトもアプリも入っています。

同じことを 2 か所に書かない。 迷ったときに、どちらが正しいか分からなくなるからです。片方に書いて、もう片方からはリンクします。CLAUDE.md が短いのも、AGENTS.md が薄いのも、この 1 つの決まりから来ています。

次に読むもの

いきなり全部は要りません。CLAUDE.md を 1 枚置いて、同じ説明を 2 回した内容だけ書き足していくのがいちばん続きます。

決まりを書く相手が増えると、次に効いてくるのは履歴の側です。誰が何を変えたかを追える形にしておくと、AI に任せる範囲を広げられます。そこはGitHub とは何かに書きました。実際に作ったものを見たいならClaude Code に Astro サイトを作らせた記録へ。