---
name: cognitive-init
description: "リポジトリに `AGENTS.md`(事実=地図)と `CLAUDE.md`(思考のレンズ=前提/状況/目的/動機/制約の 5 要素)を生成・更新するスキル。CLAUDE.md は冒頭で `@AGENTS.md` を取り込み、事実の上に意図された判断軸を重ねる構造にする。役割演技型プロンプト(「あなたはプロの〇〇です」)ではなく、プロジェクト固有の世界の捉え方を Claude に装着する=コグニティブ・デザインの方針。**特に強みを発揮する 2 つの場面**: (1) プロジェクトの「思考のレンズ」を 5 要素構造で設計したいとき、(2) 既存の CLAUDE.md が事実だけの旧形式になっているのを AGENTS.md + レンズ形式へ安全に移行したいとき。「CLAUDE.md を作って」「AGENTS.md を作って」「init して」「思考のレンズ / コグニティブデザイン」「CLAUDE.md を整理して / 分けて / 見直して」「AI 向けの設計書を書いて」といった依頼、および CLAUDE.md / AGENTS.md / 思考のレンズ という語が一度でも出てきたらこのスキルを参照する。単なる README 執筆やプロジェクト概要の要約依頼とは異なり、このスキルは「何のために動くか」という意図の層まで踏み込む点が本質。"
---

# cognitive-init

このスキルはリポジトリを 2 段階で読み解き、2 つのファイルを生成する。

| ファイル | 役割 | 比喩 | 内容 |
|---|---|---|---|
| **AGENTS.md** | 事実(What is) | 地図・マニュアル | 言語・構成・コマンド・規約。客観のみ。 |
| **CLAUDE.md** | 思考のレンズ(How to think) | 憲法・レンズ | 前提・状況・目的・動機・制約。意図された判断軸。 |

CLAUDE.md は冒頭で `@AGENTS.md` を取り込み、事実の上にレンズを乗せる構造をとる。Claude Code が CLAUDE.md を読み込むと、`@` import によって AGENTS.md が自動的に同じコンテキストに展開される。これにより:

- **Claude を起動した瞬間にレンズが装着される**(CLAUDE.md は Claude が自動で読む)
- **事実部分はベンダー中立な AGENTS.md に分離される**(Cursor / Codex など他のエージェントも同じ事実を共有できる)
- **レンズ(主)と事実(従)の依存関係がファイル構造として可視化される**

このスキルの背景にある考え方は「あなたはプロの〇〇です」型のロールプレイ・プロンプトを脱し、AI に外面的な役割ではなく **内面的な世界の捉え方=レンズ** を与える、というコグニティブ・デザインの方針に基づく。

順番が重要。**Phase 1(AGENTS.md)→ Phase 2(CLAUDE.md)** の順で進める。Phase 2 から始めてはいけない。事実の裏付けがないレンズは機能しない。

---

## 既存ファイルの取り扱い

作業を始める前に、既に `CLAUDE.md` や `AGENTS.md` が存在していないかを確認する。既存ファイルの有無によって進め方が変わる。

### ケース A: 何もない
- Phase 1 → Phase 2 の順で新規作成。

### ケース B: 旧形式の CLAUDE.md がある(事実だけが書かれている)
- これは「事実」が CLAUDE.md に入ってしまっている状態。
- ユーザーに確認したうえで、**事実部分を AGENTS.md に移し**、CLAUDE.md を Phase 2 のレンズ形式で書き直す提案をする。
- 黙ってリネームしてはいけない。移行案として diff を見せる。

### ケース C: AGENTS.md だけがある
- AGENTS.md は読み込んで Phase 1 の代替とする。Phase 1 はスキップしてもよい。
- Phase 2 で新規 CLAUDE.md を作成し、冒頭に `@AGENTS.md` を入れる。

### ケース D: 両方ある
- 内容を読んで、CLAUDE.md がレンズ形式になっているか確認する。
- なっていなければケース B と同様の移行提案を行う。
- なっていれば、追加・修正の提案を diff で提示する。上書きはしない。

---

## 出力ファイルの文体方針

**生成する AGENTS.md と CLAUDE.md の本文は、LLM が読み込む前提で簡潔に記述する**。両ファイルとも主読者は人間ではなくエージェントであり、冗長な丁寧語は読み取りの妨げになる。このスキル自身の説明文(SKILL.md)は通常の日本語で書かれているが、**出力ファイルは必ず簡潔な文体で書く**。

削ぐもの:

- 敬語・丁寧語(です/ます/ございます)→ 体言止め・用言止めに置き換え
- クッション言葉・前置き・ぼかし(〜と思われます / おそらく / 一応)
- 冗長表現(〜することができる → 〜できる)
- 自明な助詞(が/の/を/に/で/は)— 意味が通じるなら省略
- 形式名詞(こと/もの/ため)— 名詞化 or 省略(「設定を変更すること」→「設定変更」)
- 接続助詞(ので/から/ため)— 矢印「→」で代替可
- 同義・類義の重複 — 片方削除
- 指示詞(この/その)— 文脈自明なら省略

そのまま残すもの:

- **技術用語・固有名詞・コマンド・ファイルパス** は原文のまま正確に
- **コードブロック(` ``` ` で囲まれた部分)** は触らない
- **エラーメッセージの引用** は原文維持
- **動機(Motive)の本文** は感情的ニュアンスを残すため簡略化を緩めてよい(「なぜ」が伝わることを最優先)
- **破壊的操作・セキュリティに関する警告文** は通常の日本語で明瞭に書く

テンプレート内の引用ブロック(`>` で始まる説明文)もこの方針に従う。以下のテンプレートはこの文体で整形済みのサンプルであり、このまま出力してよい。

---

## Phase 1: AGENTS.md を生成する(事実の地図)

### なぜこの順で読むのか

リポジトリは大きい。最初から全ファイルを読むのは無駄で、しかも誤った要約を生む。先に骨格(構造・マニフェスト・ビルド系)を掴んでから、必要な範囲だけ深掘りする。

### 1. 探索

**(a) トップレベルの俯瞰**

- `ls -la` でルート構成を見る
- `README*`, `CONTRIBUTING*`, `ARCHITECTURE*`, `docs/` の有無を確認し、あれば読む
- パッケージマニフェスト: `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` / `Gemfile` / `pom.xml` / `build.gradle` / `composer.json` など
- ビルド・CI 設定: `Makefile`, `justfile`, `Taskfile`, `.github/workflows/`, `.gitlab-ci.yml`, `Dockerfile`, `docker-compose.yml`
- Linter / Formatter / 型: `.eslintrc*`, `ruff.toml`, `.prettierrc*`, `.pre-commit-config.yaml`, `tsconfig.json`, `mypy.ini`
- テスト: `tests/`, `test/`, `__tests__/`, `pytest.ini`, `jest.config.*`, `vitest.config.*`
- 既存の `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.cursorrules` 等

**(b) ソース構造のマップ**

- 主要ディレクトリそれぞれの役割を 1 行で言えるようにする(`src/`, `lib/`, `app/`, `internal/`, `pkg/` など)
- エントリポイントは何か(`main.py`, `index.ts`, `cmd/*/main.go`, `app/main.tsx` など)
- モジュール境界・レイヤー分割がどこにあるか

**(c) 規約のシグナルを拾う**

サンプルとして数ファイルだけ開き、以下を観察する:

- 命名規則(snake_case / camelCase / PascalCase の使い分け)
- コメントの濃さ・スタイル(docstring / JSDoc / なし)
- 型注釈の厳格さ(`any` の許容度、`strict` モードか)
- エラー処理パターン(例外 / Result 型 / エラー戻り値)
- import の並び順、ファイル分割の粒度、テストファイルの配置場所
- 設定値・秘密情報の置き場所(`.env`, config モジュール, secrets manager)

**(d) 動かし方の抽出**

ユーザーが手元で実行するコマンドを、コピペで動く形で集める:

- インストール / 依存解決
- 開発サーバ起動 / ビルド
- テスト実行(全体・単体)
- Lint / Format / Typecheck
- デプロイ(あれば)

### 2. AGENTS.md のテンプレート

下記の構造で出力する。プロジェクトに該当しない章は省略してよい。空欄を埋めるために推測で書かないこと。

````markdown
# AGENTS.md

> エージェント(Claude / Cursor / Codex 等)および新規貢献者向け 前提知識。
> 事実のみ記載。判断軸・意図・哲学は CLAUDE.md(思考のレンズ)参照。

## プロジェクト概要
- 1〜3 文「何か / 誰のため / なぜ存在」

## 技術スタック
- 言語 / ランタイム / バージョン
- 主要フレームワーク・重要ライブラリ
- データストア・外部サービス

## ディレクトリ構成
- 主要ディレクトリ 役割 1 行ずつ
- エントリポイント位置

## 開発フロー
### セットアップ
```bash
# コピペで動くコマンド
```
### 起動 / ビルド
### テスト
### Lint / Format / Typecheck

## コーディング規約
- サンプル読取事実のみ(推測で「こうあるべき」記述禁止)
- 命名・ファイル分割・コメント・テスト書き方

## アーキテクチャ要点
- データフロー
- 主要モジュール責務分担
- 外部境界

## 注意点 / 既知の落とし穴
- README・既存ドキュメントから抽出
- セットアップ ハマりやすい点

## 参考資料
- 主要ドキュメントリンク
````

### 3. AGENTS.md 執筆のルール

- **事実だけを書く**。確認できなかった項目は省略するか「未確認」と明示する。
- **意図・哲学・判断軸は書かない**。それらは CLAUDE.md の領分。役割を混ぜない。
- **ベンダー中立**。「Claude は〜」のような特定エージェント向け記述を避ける。AGENTS.md は他のエージェントも読む共有資産。
- **簡潔な文体で書く**。CLAUDE.md から `@` で取り込まれる前提なので、冗長は害になる。上記「出力ファイルの文体方針」に従い、敬語を削り体言止め・助詞省略で短く整える。技術用語・コマンド・コードブロックは原文維持。
- **コマンドはコピペで動く形**で記載する。プレースホルダがあれば明示する。
- **既存の規約を尊重する**。リポジトリの実態と矛盾するベストプラクティスを持ち込まない。
- **言語は揃える**。リポジトリ内の既存ドキュメントが日本語なら日本語、英語なら英語。

---

## Phase 2: CLAUDE.md を生成する(思考のレンズ)

### 思考のレンズとは何か

「あなたはプロの〇〇です」のような **役割演技(ロールプレイ)プロンプト** は、AI に外面的な「制服」を着せるアプローチで、ステレオタイプな出力に収束しやすく、賢いモデルでは逆に推論を阻害することすらある。

**思考のレンズ(コグニティブ・デザイン)** は、外面的な役割ではなく **内面的な「世界の捉え方」** を AI に与える方法論。AI が未知の状況に直面したときに立ち返れる、プロジェクト固有の「憲法」のように機能する。

CLAUDE.md は Claude が自動的に読み込むファイルなので、ここにレンズを置くことは「Claude を起動した瞬間にプロジェクトの憲法をインストールする」ことに等しい。

CLAUDE.md(レンズ)と AGENTS.md(事実)の役割分担は厳格に区別する:

| | CLAUDE.md | AGENTS.md |
|---|---|---|
| 何を書くか | **意図された判断軸=欲動**(How to think) | **事実**(What is) |
| 比喩 | 憲法 / レンズ | 地図 / マニュアル |
| 主観性 | 意図的な主観を含む | 客観のみ |
| 関係 | 主(`@AGENTS.md` で従を取り込む) | 従(取り込まれる) |
| 更新頻度 | 方針が変わったとき | 構成変更時 |

CLAUDE.md は「意図されたバイアス(=無数の選択肢から望ましい判断を行うための指針)」をファイルとして固定する行為であり、これを他者任せにすることは思考の核を明け渡すことに等しい。**ユーザー自身の意図を引き出すこと** が Phase 2 の本質であり、Claude が勝手に書き切ってよいものではない。

### 5 要素

CLAUDE.md の本体は次の 5 要素で構成する。順番は固定。

1. **前提 (Premise)** — 思考の OS・物理法則
   このプロジェクトで疑うことのない事実・守るべき価値観。後続のすべての判断が立脚する土台。

2. **状況 (Situation)** — 思考の現在地
   今このプロジェクトで何が起きていて、どのような変数があるのか。流動的なもの。

3. **目的 (Purpose)** — 思考の目的地
   このプロジェクトで何を達成したいのか。具体的でゴール志向。

4. **動機 (Motive)** — 思考のエンジン
   なぜその目的地を目指すのか。根源的な理由・哲学。**ここが CLAUDE.md の核心**で、他の 4 要素はこれを支えるためにある。

5. **制約 (Constraint)** — 思考の行動範囲
   目的達成のために守るべきルール・越えてはならない境界線。

### CLAUDE.md を導くプロセス(承認ゲート式)

CLAUDE.md は意図された判断軸の宣言であり、ユーザー自身の意図がそのまま反映されていなければ機能しない。一気に書いて見せるのではなく、**動機 → 残り4要素 → 全体ドラフト → ファイル書き出し** という順で各段階に承認ゲートを設ける。各ゲートを通過するまで次に進まない。

#### HARD-GATE(対話可能な場合)
ユーザーと対話できる状況では、**明示的な承認なしに CLAUDE.md をファイルとして書き出してはならない**。たとえドラフトが完璧に見えても、たとえプロジェクトが小さくても、必ず段階的な確認を経る。「単純だから承認は不要」という判断は、レンズが機能しないファイルを生む最大の原因。

#### 非対話モード(サブエージェント実行・バックグラウンドジョブ・CI など)

対話的にユーザーに問えない状況では、承認ゲートは機能しない。その場合でも「黙って完成版を書く」のは禁則。代わりに **明示的に仮説モードに切り替える**:

1. **コードから読み取れる具体的なシグナル(ファイル構成・依存・命名・コミットログ・README)を根拠に、動機を仮説として 1 つ立てる**。複数の方向が見える場合は、一番ありそうなものを推奨案として選び、対立仮説を `transcript` / 報告本文にメモする。
2. CLAUDE.md の本文は通常どおり 5 要素で書く。動機の段だけは、**冒頭または末尾の注記で「これは対話できなかったため推定」「次セッションで動機の段を自分の言葉で書き換えてほしい」と明示**する。
3. 動機以外の 4 要素は、推定された動機と整合する形で淡々と埋めてよい(これらは事実寄りで、後から書き換えるコストが低いため)。
4. 報告時に **動機の確信度** を「高 / 中 / 低」で申告し、低いなら特に次セッションで要確認と伝える。

この非対話モードは**妥協ではなく設計された代替経路**。対話できない環境で「動機はユーザー確認待ちなので書きません」と止まると、後続のエージェントはレンズなしで動くことになり、スキルの価値が完全に失われる。不完全な草稿 + 明示的な「仮説」ラベルは、空ファイルよりはるかに強い足場になる。

判定の優先順位は単純で: **対話できる → ステップ 1 の承認ゲートを踏む / 対話できない → 非対話モードで仮説版を書く**。どちらのモードで動いたかを報告に 1 行で書く。

#### ステップ 1: 動機(Motive)を引き出す

AGENTS.md の事実(技術選択・ディレクトリ構成・規約)から、「なぜこのプロジェクトはこういう作り方をしているのか?」を考え、動機の手がかりを得る。

そのうえで **対話モードに入る**。基本ルール:

- **1 メッセージ 1 質問**。複数の質問を並べない。ユーザーを圧倒しない。
- **multiple choice を優先**。白紙よりも選択肢のほうが答えやすい。自由記述は最後の選択肢として常に残す。
- **Claude は中立な傍観者ではない**。コードから読み取った観察を根拠に、推奨する仮説を 1 つ持って臨む。
- **対立する選択肢を意図的に混ぜる**。同方向の仮説ばかりだと誘導になる。

最初の問いかけのテンプレート:

> AGENTS.md を読んだ印象では、このプロジェクトは <観察した事実> から、<推測した動機> を狙っているように見えます。これに近いのは以下のどれですか?
>
> A. <推奨する仮説 — Claude が一番ありそうだと考えるもの>
> B. <対立する仮説 — 方向の違う可能性>
> C. <別の角度からの仮説>
> D. 上記いずれでもない(自由に教えてください)
>
> 私は **A だと思っています**。理由は <観察した具体的なシグナル> だからです。ただ私の解釈は半分しか当たっていないはずなので、あなたの言葉で訂正してください。

ユーザーの答えを聞いたら、抽象的な答え(「使いやすくしたい」など)は必ず**具体例まで掘り下げる**。「『使いやすい』とは、誰が、どんな場面で、何を感じる状態ですか? 失敗例を 1 つ教えてください」と次の 1 問を投げる。

動機が言語化できたら、Claude が 1〜2 文に要約してユーザーに**確認する**:

> こう理解しました: 「<要約>」。これで合っていますか? 言葉づかいで違和感があれば直してください。

ユーザーの「OK」が出るまで次のステップに進まない。

#### ステップ 2: 残り 4 要素をドラフトする

動機が確定したら、それを支える形で前提・状況・目的・制約をドラフトする。**各要素を 1 つずつ提示し、それぞれに承認を得る**。全部書いてから一度に見せない。

要素ごとの問いかけの軸:

- **前提**: 動機が成立するために絶対に揺るがしてはならない事実・価値観は何か?
- **状況**: その動機を今、何が後押しし、何が阻んでいるか?
- **目的**: その動機を具体的なゴールに落とすと何になるか?(測れる粒度で)
- **制約**: その動機を実現する過程で、絶対にやってはならないことは何か?

各要素について、Claude は **2〜3 個の候補を作り、推奨案と理由を添えて**提示する。例:

> 「前提」の候補です。動機が <要約> である以上、以下のうちどれが土台になりそうですか?
>
> 1. <候補 A>
> 2. <候補 B>(★ 推奨。理由: <観察した事実>)
> 3. <候補 C>
>
> 複数選んでも、全部書き直してもかまいません。

#### ステップ 3: 全体ドラフトを提示して承認を得る

5 要素がそろったら、CLAUDE.md の全文ドラフトを **チャット内に** 表示する(まだファイルには書き出さない)。

> ドラフトはこちらです。違和感のある箇所、削りたい箇所、足したい箇所はありますか? 問題なければファイルとして書き出します。

ユーザーが「OK」「これで書いて」のような明示的な承認を出したら、はじめてファイルに書き出す。

#### ステップ 4: 書き出し後のセルフレビュー

ファイルを書いたら、Claude 自身が一度読み返して以下をチェックする:

- **プレースホルダの残存**: `TBD` / `TODO` / `<…>` が残っていないか
- **5 要素間の整合性**: 動機と他の 4 要素が矛盾していないか
- **抽象度のチェック**: 「ユーザー第一」「品質重視」のような誰でも言える言葉が紛れていないか
- **役割演技の混入**: 「あなたは〜」「プロらしく〜」のような表現が無いか
- **AGENTS.md との重複**: 事実の再記述になっていないか

問題があれば修正して、最終版をユーザーに通知する。

### 動機を引き出すための問いかけ集

ステップ 1 でユーザーから動機を引き出すのが最も難しいので、状況に応じて以下のような問いを使い分ける:

- 「このプロジェクトがこの世から消えたら、誰が一番困りますか?」
- 「似たようなツールは既にあるはずですが、それでも作る理由は何ですか?」
- 「このプロジェクトの判断で、過去に『これだけは譲れない』と思ったことはありますか?」
- 「もし予算と時間が無限にあったら、最初に何を直しますか?」
- 「ユーザーに 1 つだけ言葉を残すとしたら何ですか?」

### CLAUDE.md のテンプレート

````markdown
# CLAUDE.md — このプロジェクトの思考のレンズ

@AGENTS.md

> 上記 `@AGENTS.md` でプロジェクト事実(地図)取込。
> ここから先はそれをどう捉え、何のために動くかという
> **思考のレンズ**(コグニティブ・デザイン)定義。
>
> 役割(Role)ではなく、世界の捉え方(Lens)記述。
> このファイル = 「意図されたバイアス」宣言。
> 中立装い禁止。プロジェクトが何を欲しているか明確記述。

## 前提 (Premise) — 思考の OS
- 疑ってはならない事実
- 守るべき価値観
- (例:「ユーザープライバシー あらゆる機能要望に優先」)

## 状況 (Situation) — 思考の現在地
- 今何が起きているか
- 現在動いている変数・制約条件
- (例:「v2 移行中。v1 / v2 コード並走」)

## 目的 (Purpose) — 思考の目的地
- 達成したい具体ゴール
- 測れる粒度で記述
- (例:「3 ヶ月以内 主要ユースケース v2 移行 → v1 撤去」)

## 動機 (Motive) — 思考のエンジン  ★ 核心
- 目的地を目指す根源的理由
- 本当に欲しているもの(欲動)
- 他 4 要素全ての拠り所
- (例:「単なる技術更新ではなく、ユーザーが感じている遅さという
  痛みを取り除き、毎日の操作を軽やかにすることが本質的狙い」)

## 制約 (Constraint) — 思考の行動範囲
- 守るべきルール
- 越えてはならぬ境界線
- (例:「既存ユーザー URL 変更禁止」「外部 API キー コード混入禁止」)
````

### CLAUDE.md 執筆のルール

- **冒頭で必ず `@AGENTS.md` を取り込む**。これがレンズが事実に立脚する構造の根拠になる。`@` は Claude Code の context import 記法で、CLAUDE.md が読み込まれた際に AGENTS.md の中身が自動的に同じコンテキストに展開される。
- **動機を中心に据える**。動機が薄いレンズは機能しない。動機が決まらないうちに他の要素を埋めてはいけない。
- **ユーザー自身の言葉で書く**。Claude が代筆するときも、必ずユーザーの意図を引き出してから書く。
- **中立を装わない**。CLAUDE.md は意図的なバイアスの宣言なので、「バランスよく」「総合的に」のような無味な言葉を避ける。
- **長くしすぎない**。各要素 3〜7 項目で十分。多すぎるとレンズとして機能しなくなる。
- **簡潔な文体で書く**。上記「出力ファイルの文体方針」に従い、敬語を削り体言止め・助詞省略で短く整える。ただし**動機(Motive)の本文は感情的ニュアンスを残すため簡略化を緩めてよい**(欲動が伝わることが最優先)。
- **役割演技に逃げない**。「あなたはプロの〇〇です」のような書き方は禁止。レンズはペルソナではない。
- **AGENTS.md と内容を重複させない**。事実を再記述しない。事実が必要なら `@AGENTS.md` 経由で参照されている前提で書く。
- **既に CLAUDE.md がある場合**は上書きせず、追加・修正の提案として提示する。レンズはユーザーの哲学そのものなので特に慎重に扱う。

---

## 情報が足りないとき — ブレインストーミング

Phase 1 でも Phase 2 でも、必要な情報がそろわないことがある。例えば:

- **Phase 1**: README が無い、ビルド方法が読み取れない、ディレクトリ名から役割が特定できない、複数の解釈が成り立つ
- **Phase 2**: ユーザーが「動機」を言語化できない、答えに詰まる、まだ自分でも整理がついていない

このとき Claude は **質問を投げて待つ** だけでは不十分。そのまま黙るとユーザーは固まり、結果として薄っぺらいファイルが完成する。代わりに **能動的にブレインストーミングモードに入る**。

### 5 つの原則

1. **1 メッセージ 1 質問**
   一度に複数の質問を並べない。トピックが広いなら 1 問ずつ分解する。ユーザーの認知負荷を最小に保つ。これは絶対のルール。

2. **multiple choice を優先、自由記述は最後の選択肢として常に残す**
   白紙より選択肢のほうが答えやすい。ただし「上記いずれでもない(自由に教えてください)」は必ず最後に置く。これがないと誘導になる。

3. **Claude は推奨案を持って臨む。中立な傍観者ではない**
   仮説を 2〜4 個並べたら、必ず **★ 推奨** マークと **その理由** を 1 つ付ける。理由は観察した具体的な事実(コード・コミット・依存関係・ファイル名)に紐づける。「なんとなく」は禁止。中立を装うと、ユーザーは選びにくくなる。

4. **対立する仮説を意図的に混ぜる**
   「コスト削減」vs「体験向上」のように方向の違う仮説を並べる。同方向ばかりだと誘導になる。ユーザーは「いや、それは違う」と否定する形で本当の答えを言語化しやすくなる。

5. **抽象を必ず具体に降ろす**
   ユーザーが抽象的な答え(例: 「使いやすくしたい」)を返したら、次の 1 問で必ず具体例を詰める。「『使いやすい』とは、誰がどんな場面で何を感じる状態ですか? 失敗例を 1 つ教えてください」。抽象のままファイルに書き込んではいけない。

### 膠着したときの対処

数ラウンドやり取りしても進まないときは、**不完全なまま叩き台を書く**。空白で待ち続けるより、間違った草案を書いてユーザーに「ここが違う」と指摘してもらうほうが速い。叩き台には「ここは推測」「ここは未確認」と明示する。

埋まらなかった項目はファイルに `TBD: ユーザー確認待ち — <何が分からないか>` として残す。空欄を勝手に埋めて完成を装わない。

### Phase 別の典型的なブレスト例

**Phase 1(事実が読み取れない)**

> README が無く、`scripts/` 以下に複数のスクリプトが見えました。このプロジェクトの起動方法はどれが近いですか?
>
> 1. `scripts/dev.sh` を直接実行する(★ 推奨。`dev.sh` の冒頭に `#!/usr/bin/env bash` と引数パースがあったので最有力)
> 2. Docker 経由(`docker-compose.yml` はあるが古いタイムスタンプでした)
> 3. CI のワークフローを手元で再現する
> 4. 上記いずれでもない(教えてください)

**Phase 2(動機が言語化できない)**

> コードからは「速度を重視している」シグナル(キャッシュ層・SIMD・並列化)が読み取れました。動機の方向性として、以下のどれが近いですか?
>
> A. **競合より速いことが武器**: ベンチマークで勝つことが価値の中心
> B. **遅さがユーザーの離脱を生んでいる**: 速さは目的ではなく、離脱を防ぐ手段(★ 推奨。コミットメッセージに "retention" が頻出していたため)
> C. **開発者自身が遅いツールに耐えられない**: 自分が使うから速くしたい
> D. その他(自由記述)
>
> どれかに「半分くらい当たっている」ものはありますか?

### ブレストモードの禁則

- **ユーザーの代わりに動機を「決めて」しまう**(あくまで仮説の提示まで。最終的な選択はユーザー)
- **複数の質問を一度に投げる**(必ず 1 メッセージ 1 質問)
- **中立を装って仮説を並べるだけ**(必ず推奨案と理由を持つ)
- **「正解は一つ」と決めつける**(動機は複層的でよい。複数の並立を許す)
- **抽象的な美辞麗句で埋める**(「ユーザー第一」「品質重視」のような誰でも言える言葉は禁止)
- **無限ループする**(同じ質問を言い換えて繰り返さない。膠着したら叩き台へ進む)
- **「このプロジェクトは小さいから動機は要らない」と判断する**(プロジェクトの大小を問わず 5 要素を埋める。小ささは省略の理由にならない)

---

## 出力と報告

両ファイルの生成が終わったら、以下を出力する:

1. `AGENTS.md`(リポジトリルート)
2. `CLAUDE.md`(リポジトリルート、冒頭で `@AGENTS.md` を取り込む)

そしてユーザーに以下を簡潔に報告する:

- **AGENTS.md でカバーした項目** と、**確認できなかった項目**
- **CLAUDE.md の 5 要素それぞれの現状**(特に動機が確定しているか)
- **ユーザーに確認したい点・もっと深掘りしたい点**

CLAUDE.md は一度で完成させる必要はない。Phase 2 は対話的に進めるのが正解で、初版は不完全でもよいのでユーザーに見せてフィードバックをもらう。

---

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

- リポジトリを読まずにテンプレートだけ埋めて提出する(根拠のない AGENTS.md は害)
- Phase 1 をスキップしていきなり CLAUDE.md だけ書く(事実の裏付けがないレンズは機能しない)
- CLAUDE.md の冒頭に `@AGENTS.md` を入れ忘れる(レンズが事実から切り離されてしまう)
- 動機(Motive)をユーザーに確認せず、Claude が勝手に決めてしまう(レンズの核を奪う行為)
- 情報が足りないときに質問を投げて沈黙する(ブレストモードで仮説を提示すること)
- 1 つのメッセージに複数の質問を詰め込む(必ず 1 メッセージ 1 質問)
- 仮説を中立に並べるだけで Claude の推奨案と理由を示さない
- 対話可能な状況でユーザーの明示的な承認なしに CLAUDE.md をファイルとして書き出す(HARD-GATE 違反)。非対話モードで書き出す場合は必ず動機の段に「仮説」ラベルを付け、次セッションでの確認を要請する
- 5 要素のドラフトを全部書いてから一度に見せる(各要素ごとに承認を取ること)
- CLAUDE.md にロールプレイ的な記述を混ぜる(「あなたはプロの〇〇」の形式は禁止)
- 既存の CLAUDE.md / AGENTS.md を黙って上書きする(特に旧形式 CLAUDE.md は移行提案を経由する)
- AGENTS.md に意図や哲学を書き、CLAUDE.md に事実を書く(役割の混同)
- 「一般的な良い設計とは」のような抽象論を CLAUDE.md に持ち込む(あくまでこのプロジェクトの欲動から導く)