# AI 協働開発の設計思想（Cursor 向け）

Cursor は強力ですが、次の 3 点は「仕様に近い制約」として扱うと期待値が合います。

| 課題 | 根本にあること |
|------|----------------|
| デグレードの多さ | コンテキストは有限で、変更の「全体像」と「既存の約束」が常に入るとは限らない |
| 確認不足 | 推論が速い一方、環境で実際に動かす・差分を検証するステップが省略されやすい |
| 秘密情報の再質問 | チャットは長期記憶ではない。別セッションではこれまでの会話は原則として引き継がれない |

以下は、この制約を前提にした**運用設計**です。

---

## 1. デグレードを減らす思想

### 1.1 「小さく確実に」をデフォルトにする

- 一度に触る範囲（ファイル数・責務）を小さくする
- 「動いていたこと」のリスト（受け入れ条件・回帰しやすい箇所）を**テキストで残す**（仕様の断片でもよい）
- 変更理由と「触ってはいけない境界」をルールや `AGENTS.md` に短く書く

### 1.2 読む → 変える → 検証する の順を崩さない

- いきなり広く書き換えない。まず影響範囲を読む
- 既存の命名・パターン・エラーハンドリングに合わせる（エージェント向けルールで明文化すると効く）

### 1.2.1 「読んだだけ」で着手しない

デグレが多発する場合、原因は「仕様書を開いたか」ではなく、**既存挙動・受け入れ条件・回帰リスクが作業前に言語化されていないこと**になりやすい。

そのため、コード編集前に次の 5 点を短く残す。

- 読んだ正本と該当章
- 変更前に守る既存挙動
- 今回の受け入れ条件
- デグレしやすい箇所
- 検証計画（自動テスト、手動確認、DB 影響確認、差分確認）

この 5 点が書けないときは、仕様書確認が不足している。追加でコード・マイグレーション・ルート・画面を読むか、仕様書へ確認観点を追記してから進める。

### 1.3 回帰しやすい変更には明示的なチェックを置く

例（プロジェクトに合わせて書き換える）：

- ビルド・型チェック
- 自動テスト（あれば最短セット）
- 手触り確認（該当画面・API のみでよい）

「通ったら完了」ではなく、「**意図した挙動の確認**まで」を完了の定義に含める。

---

## 2. 確認不足を防ぐ思想

### 2.1 完了の定義（Definition of Done）を短く固定する

エージェントにも人にも同じ基準を適用する例：

- 変更後、**エラーなくビルド／実行**できる
- 変更箇所に関係する**テストまたは手動確認**をした
- 不要なファイル・デバッグ出力・コメントゴミを増やしていない

### 2.2 「レポートよりログ」

- 推論の説明より、**実行結果**（コマンド出力の要点、再現手順）を重視する

### 2.3 人間のレビューは「差分の意味」に集中する

- 機械で取れる品質（Lint、Format、Test）は機械に任せ、人は設計・例外・セキュリティを見る

---

## 3. 秘密情報とコンテキストの扱い（再質問を減らす）

### 3.1 チャットは「記録庫」にしない

- パスワード・API キー・個人トークンを**チャットに貼らない**のが基本
- 必要なら **環境変数**や OS のシークレットストア、チームの秘密管理を使う

### 3.2 Cursor が毎回読める場所に「参照先」だけ書く

- **User Rules**（Cursor 設定）: 言語・文体・禁止事項など全プロジェクト共通
- **Project Rules**（`.cursor/rules/*.mdc`）: リポジトリ固有の建て付け・コマンド・環境変数名の一覧（**値は書かない**）
- **本リポジトリの必須ドキュメント（Monaka）**
  - `docs/README.md` … `docs/` 内のファイル一覧と役割（索引）
  - `docs/funnel-spec.md` … ファネル・ページ・取り込み・プレビューの技術仕様と受け入れ観点
  - `docs/manual.md` … 利用者向け運用マニュアル
  - `docs/rule.mdc` … AI 向け共通ルール（上記参照の明示）
- **`AGENTS.md` や `README` の一部**: セットアップ手順、どの `.env.example` をコピーするか、どこに設定を置くか

「値」ではなく **名前と場所**を書くと、エージェントは「ユーザーに値を聞く」代わりに「`.env` を読む・テンプレートに従う」動きに寄せやすくなります。

### 3.3 セッションをまたぐときの「引き継ぎ」

長い作業は、チャットの要約に頼らず **短命のメモ**（例：`docs/session-handoff.md`、または Issue コメント）に：

- 目的・未完了・次の 1〜3 ステップ・既知の制約

を書く。秘密は入れない。

---

## 4. Cursor に「覚えさせる」の意味

Cursor が参照するのは主に次です。

- **ユーザー／プロジェクトのルール**（`.mdc` など）
- **開いているファイル・最近の編集・@ 参照**
- **リポジトリ内のドキュメントとコード**

つまり「覚えさせる」= **会話に依存せず、ワークスペースと設定に残す**ことです。  
本ドキュメントは**人間が読む設計書**、`docs/funnel-spec.md` は**ファネル領域の仕様・検証リスト**、`.cursor/rules/` 内の `.mdc` は**エージェント向けの圧縮ルール**、という役割分担が扱いやすいです。

---

## 5. まとめ（一行ポリシー）

- **変更は小さく、検証は先に型・ビルド・該当テスト／手動確認で固定化する**
- **秘密はチャットやルールに平文で書かず、環境とテンプレートで参照する**
- **方針と手順はリポジトリ／Cursor ルールに書き、セッションをまたいで再利用する**

---

*最終更新: 2026-05-03（docs/README.md を索引に追加）*