From 5c7b262a9bdaa62b292d1b2ad87860346a74efae Mon Sep 17 00:00:00 2001 From: posimai Date: Sat, 25 Apr 2026 21:57:34 +0900 Subject: [PATCH] =?UTF-8?q?feat:=20initial=20release=20=E2=80=94=20AI?= =?UTF-8?q?=E9=96=8B=E7=99=BA=E3=83=97=E3=83=AD=E3=83=B3=E3=83=97=E3=83=88?= =?UTF-8?q?=E3=83=86=E3=83=B3=E3=83=97=E3=83=AC=E3=83=BC=E3=83=88=E9=9B=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 00_clarify / 10_breakdown / 20_implement / 30_review / 40_debug の 5プロンプトで、アイデア整理からコードレビューまで一貫して進められる。 Claude / ChatGPT / Gemini いずれでも使用可能。 Co-Authored-By: Claude Sonnet 4.6 --- .env.example | 12 +++ .gitignore | 42 ++++++++++ AGENTS.md | 21 +++++ CLAUDE.md | 10 +++ LICENSE | 21 +++++ README.md | 125 ++++++++++++++++++++++++++++++ docs/troubleshooting.md | 32 ++++++++ docs/workflow.md | 56 +++++++++++++ examples/project-brief-example.md | 61 +++++++++++++++ examples/tasks-example.md | 25 ++++++ prompts/00_clarify.md | 35 +++++++++ prompts/10_breakdown.md | 37 +++++++++ prompts/20_implement.md | 41 ++++++++++ prompts/30_review.md | 58 ++++++++++++++ prompts/40_debug.md | 33 ++++++++ 15 files changed, 609 insertions(+) create mode 100644 .env.example create mode 100644 .gitignore create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 LICENSE create mode 100644 README.md create mode 100644 docs/troubleshooting.md create mode 100644 docs/workflow.md create mode 100644 examples/project-brief-example.md create mode 100644 examples/tasks-example.md create mode 100644 prompts/00_clarify.md create mode 100644 prompts/10_breakdown.md create mode 100644 prompts/20_implement.md create mode 100644 prompts/30_review.md create mode 100644 prompts/40_debug.md diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..85d262e --- /dev/null +++ b/.env.example @@ -0,0 +1,12 @@ +# .env.example +# このファイルをコピーして .env を作成してください。 +# cp .env.example .env (macOS/Linux) +# copy .env.example .env (Windows) +# +# .env は絶対にコミットしないこと（.gitignore で除外済み）。 +# チームで共有が必要な場合は、このファイルにキー名だけ残して値は空にする。 + +# 例 +# DATABASE_URL=postgresql://localhost:5432/mydb +# API_SECRET_KEY=your_secret_here +# NODE_ENV=development diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..10506fa --- /dev/null +++ b/.gitignore @@ -0,0 +1,42 @@ +# Dependencies +node_modules/ +vendor/ +.venv/ +__pycache__/ +*.pyc +*.pyo + +# Build outputs +dist/ +build/ +out/ +.next/ +.turbo/ +target/ +*.class +*.jar + +# Test coverage +coverage/ +.nyc_output/ + +# Environment — never commit secrets +.env +.env.local +.env.*.local + +# OS +.DS_Store +Thumbs.db +Desktop.ini + +# IDE +.idea/ +.vscode/settings.json +*.swp +*.swo + +# Logs +*.log +npm-debug.log* +yarn-debug.log* diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..6dd8693 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,21 @@ +# AGENTS.md + +このリポジトリで作業するAIへの共通ルール。 + +## 基本方針 + +- 小さく作って早く確認する +- 1タスク = 1つの変更にまとめる +- 要件にないものを勝手に追加しない + +## 実装時のルール + +- 変更前に対象ファイルと影響範囲を確認する +- APIキー・パスワード・トークンをコードに直接書かない +- エラーが出た場合は原因と再現手順を残す + +## 完了の定義 + +- 実装後に「完了条件」を1つずつ確認する +- 確認できていない条件がある場合は「残課題」として残す +- 失敗したままを「完了」と報告しない diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..5be781b --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,10 @@ +# CLAUDE.md + +`AGENTS.md` のルールを遵守すること。矛盾がある場合は厳しい方を優先。 + +## Claude 固有の追加ルール + +- タスク実行前に TodoWrite でタスクを登録する +- 各タスク完了時に即座に完了マークをつける +- 迷ったら最小実装で提案し、確認してから進める +- 実装理由はコミットメッセージに残す（コード中コメントは最小限） diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..14fac91 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..7f22fad --- /dev/null +++ b/README.md @@ -0,0 +1,125 @@ +# posimai-kit + +AIに開発を頼む時の「質問テンプレート」5つのセットです。 + +アイデアをざっくり言葉にするだけで、AIがタスク分解・実装・レビューまで +一貫した流れで進めてくれるようになります。 + +--- + +## 誰のためのものか + +- AIを使って何かを作ってみたいけど、何をどう頼めばいいかわからない人 +- AIに頼むたびに出力がバラバラで、途中から迷子になる人 +- エンジニアではないけど、自分のアイデアをかたちにしたい人 + +**コードを書く必要はありません。** + +--- + +## はじめ方（3ステップ） + +**1. このリポジトリを手元に置く** + +```bash +# Git が使える場合 +git clone https://github.com/あなたのアカウント/posimai-kit.git + +# Git を使わない場合 +# 右上の「Code」→「Download ZIP」でダウンロードして解凍する +``` + +**2. `prompts/00_clarify.md` をテキストエディタで開く** + +VSCode・メモ帳・どのエディタでも構いません。 + +**3. 「私のアイデア」欄に書いて、ファイル全体を AI に貼り付ける** + +Claude・ChatGPT・Gemini、どの AI でも使えます。 +AI の回答は、メモ帳や Notion など手元に保存してください。 + +--- + +## 使い方：5つのステップ + +``` +あなたのアイデア（ざっくりでOK） + │ + ▼ +┌─────────────────────────────────────────────────────┐ +│ 00_clarify.md 「仕様を整理して」 │ +│ ↓ アイデアが言語化される │ +│ 10_breakdown.md 「タスクに分解して」 │ +│ ↓ やることリストができる │ +│ 20_implement.md 「T-001を作って」← 1つずつ繰り返す │ +│ ↓ コードが生まれる │ +│ 30_review.md 「確認して」 │ +│ ↓ 問題点が見つかる・修正する │ +│ 40_debug.md 「直して」← 何か壊れた時だけ │ +└─────────────────────────────────────────────────────┘ + │ + ▼ + 動くものができる +``` + +--- + +## 入力はざっくりでOK + +テンプレートに貼り付けるアイデアは、整理されていなくて大丈夫です。 +「整理する」のが `00_clarify.md` の役割だからです。 + +**あなたが書くもの（これで十分）** + +``` +家計簿アプリを作りたい。スマホで使いたい。 +レシートを写真で撮れたら嬉しいけど最初は手入力でも。 +家族で共有できたらいいけど後でもいい。 +``` + +**AIが整理して出してくれるもの** + +``` +目的: 支出を記録・可視化して、使いすぎを防ぐ + +スコープ内（今回作る）: + - 収支の手動入力 + - カテゴリ分類 + - 月次グラフ表示 + +スコープ外（後回し）: + - レシートの自動読み取り + - 家族共有機能 + +MVP定義: 入力→一覧→グラフの3画面が動けばリリース可 +``` + +記入済みのサンプルは [examples/](examples/) を参照してください。 + +--- + +## ファイル一覧 + +| ファイル | 何のためか | +|---|---| +| `prompts/00_clarify.md` | ぼんやりしたアイデアを仕様に変える | +| `prompts/10_breakdown.md` | 仕様を小さなタスクに分解する | +| `prompts/20_implement.md` | 1タスクをAIに実装してもらう | +| `prompts/30_review.md` | できたコードを別のAIに検査させる | +| `prompts/40_debug.md` | 動かない時に原因を切り分ける | +| `examples/` | 記入済みサンプル（参考用） | +| `docs/workflow.md` | フロー詳細 | +| `docs/troubleshooting.md` | よくある詰まりポイント | + +--- + +## AIツール（Claude Code・Cursor）を使っている場合 + +プロジェクトのルートに `AGENTS.md` と `CLAUDE.md` を置くと、 +AIが毎回同じルールで動くようになります。どちらも任意です。 + +--- + +## ライセンス + +MIT — 自由に使用・改変・配布できます。 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..522a403 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,32 @@ +# よくある詰まりポイント + +## AIの出力がぶれる + +仕様（project-brief）の曖昧な部分を埋める。 +特に「スコープ外」が定義されていないと、AIが勝手に機能を追加しやすい。 + +プロンプトの「変更してはいけない範囲」に明示的に書くと安定する。 + +## レビューAIごとに指摘が違う + +`30_review.md` の構造化フォーマット（重大度・根拠・影響・修正案）を +必ず使うことで、AIによるブレが小さくなる。 + +仕様外の提案は「Nice to have」として分けてもらうと判断しやすい。 + +## どのタスクから始めればいいかわからない + +依存関係がないタスク（「依存」列が `-` のもの）から始める。 +迷ったらAIに「どれから始めるのが最も安全ですか」と聞いてよい。 + +## 途中でアイデアが変わった + +`project-brief` を更新してから、影響するタスクを見直す。 +すでに実装済みのタスクを壊す変更は、新しいタスクとして分けて追加する。 + +## APIキーをどこに書けばいいかわからない + +`.env.example` を参考に `.env` ファイルを作って、そこに書く。 +`.env` は `.gitignore` に含まれているので、GitHubに上げても漏れない。 + +コードの中には変数名だけ書く（例: `process.env.API_KEY`）。 diff --git a/docs/workflow.md b/docs/workflow.md new file mode 100644 index 0000000..d2a4786 --- /dev/null +++ b/docs/workflow.md @@ -0,0 +1,56 @@ +# フロー詳細 + +## 全体の流れ + +``` +00_clarify → 仕様をまとめる（project-brief） + ↓ +10_breakdown → タスクに分解する（tasks） + ↓ +20_implement ←─────────────────────┐ + ↓ │ +30_review → Approve? │ + ↓ No │ + 指摘を修正 ───────────┘ + ↓ Yes + 次のタスクへ / 完了 +``` + +途中で動かなくなったら `40_debug` に寄ってから `30_review` に戻る。 + +--- + +## ステップごとの補足 + +### 00: 仕様整理 + +AIに渡す前に、自分の「作りたいもの」をメモするだけでよい。 +箇条書きでも文章でも、整理されていなくてもよい。 + +出力を手元に保存しておくと、後のステップで参照できる。 + +### 10: タスク分解 + +「1タスクが大きすぎる」場合はAIに「もっと細かく分けて」と頼む。 +目安は「完了したかどうか自分で判断できる粒度」。 + +### 20: 実装 + +必ず1タスクずつ進める。まとめて実装するとレビューが複雑になる。 + +### 30: レビュー + +`Critical` と `High` の指摘は必ず修正する。 +`Medium` 以下は「今やるか後にするか」を自分で判断してよい。 + +### 40: デバッグ + +エラーメッセージとログをそのままAIに貼るだけで、原因を絞り込んでくれる。 + +--- + +## やってはいけないこと + +- 「なんとなく動いてそう」でレビューを省略する +- 複数タスクをまとめて実装する +- APIキーを直接コードに書く（必ず `.env` を使う） diff --git a/examples/project-brief-example.md b/examples/project-brief-example.md new file mode 100644 index 0000000..d77029a --- /dev/null +++ b/examples/project-brief-example.md @@ -0,0 +1,61 @@ +# 記入例：家計簿アプリ + +> この例は `prompts/00_clarify.md` を使った後に得られる出力のサンプルです。 +> 自分のプロジェクトに合わせて書き換えてください。 + +--- + +## 目的 + +個人または家族の月次支出を記録・可視化することで、 +「気づいたら使いすぎていた」を防ぐ。 + +## スコープ + +### スコープ内（今回作る） + +- 収支の手動入力（日付・金額・カテゴリ・メモ） +- 支出一覧の表示（月別フィルタ） +- カテゴリ別の月次グラフ + +### スコープ外（後回し） + +- レシートの自動読み取り（カメラ連携） +- 家族・複数人での共有機能 +- 銀行口座との自動連携 + +## 必須機能 + +1. 収支入力フォーム（金額・カテゴリ・日付） +2. 一覧表示（最新順、月絞り込み） +3. 月次グラフ（カテゴリ別の円グラフ） + +## 非機能要件 + +- パフォーマンス：一覧は1秒以内に表示 +- セキュリティ：ログイン必須（他人のデータが見えない） +- 可用性：スマートフォンのブラウザで操作できる + +## 技術スタック + +- 言語/FW：Next.js（React） +- DB：Supabase（PostgreSQL） +- デプロイ先：Vercel +- 外部API：なし + +## MVP定義 + +入力 → 一覧 → グラフの3画面が実機（スマートフォン）で +エラーなく動作すれば、リリース可と判断する。 + +## リスクと対策 + +| リスク | 影響 | 対策 | +|---|---|---| +| Supabaseの無料プラン制限に引っかかる | DB接続が止まる | 早期に使用量を確認する | +| カテゴリ設計が後から変えにくい | データ移行が大変 | 最初にカテゴリマスタを設計する | + +## 制約 + +- 期限：1ヶ月以内に最小版を動かす +- 予算：無料プランの範囲内 diff --git a/examples/tasks-example.md b/examples/tasks-example.md new file mode 100644 index 0000000..3545880 --- /dev/null +++ b/examples/tasks-example.md @@ -0,0 +1,25 @@ +# 記入例：タスク一覧（家計簿アプリ） + +> この例は `prompts/10_breakdown.md` を使った後に得られる出力のサンプルです。 +> ステータスは作業を進めながら自分で更新してください。 + +--- + +## Backlog + +| Task ID | タイトル | 目的 | 依存 | 完了条件 | ステータス | +|---|---|---|---|---|---| +| T-001 | プロジェクト初期化 | 開発環境を整える | - | ローカルで `npm run dev` が動く | Done | +| T-002 | DB設計・テーブル作成 | データ構造を確定する | T-001 | Supabaseにテーブルができている | Done | +| T-003 | 認証機能（ログイン・ログアウト） | 本人だけが使える | T-001 | ログイン・ログアウトが動く | In Progress | +| T-004 | 収支入力フォーム | データを登録できる | T-002, T-003 | 入力してDBに保存される | Todo | +| T-005 | 一覧表示ページ | 記録を確認できる | T-004 | 月別に絞り込んで表示される | Todo | +| T-006 | 月次グラフ | 使いすぎを視覚的に把握できる | T-005 | カテゴリ別円グラフが表示される | Todo | +| T-007 | スマートフォン対応 | 実際に使える | T-006 | iPhoneのSafariで操作できる | Todo | + +## 完了済み + +| Task ID | タイトル | 完了日 | +|---|---|---| +| T-001 | プロジェクト初期化 | 2026-04-20 | +| T-002 | DB設計・テーブル作成 | 2026-04-21 | diff --git a/prompts/00_clarify.md b/prompts/00_clarify.md new file mode 100644 index 0000000..79191dd --- /dev/null +++ b/prompts/00_clarify.md @@ -0,0 +1,35 @@ +# 00 | アイデアを仕様に整理する + +--- + +## AIへの指示文（ここから下をそのままAIに貼り付けてください） + +あなたはプロダクトの仕様整理を担当しています。 +以下のアイデアをもとに、実装に必要な情報を整理してください。 + +### 私のアイデア + + + + +--- + +### 出力してほしい形式 + +以下の項目を順番に整理してください。 + +1. **目的**（1〜2文）: 何のために、誰のために作るか +2. **スコープ内・スコープ外**: 今回やることとやらないことを明確に分ける +3. **必須機能**（3〜5個）: 優先順位をつけて列挙 +4. **非機能要件**: 速さ・安全性・使いやすさの観点で気になること +5. **技術スタック**（わかれば）: 言語・FW・DB・デプロイ先 +6. **MVP定義**: 「これが動けばリリースできる」という最低ライン +7. **リスク**: 想定されるリスクと対策 + +--- + + +## 次にすること + +AIの出力を `examples/project-brief-example.md` を参考に保存したら、 +`prompts/10_breakdown.md` へ進んでください。 diff --git a/prompts/10_breakdown.md b/prompts/10_breakdown.md new file mode 100644 index 0000000..3ed176c --- /dev/null +++ b/prompts/10_breakdown.md @@ -0,0 +1,37 @@ +# 10 | 仕様をタスクに分解する + +--- + +## AIへの指示文（ここから下をそのままAIに貼り付けてください） + +あなたは開発のタスク設計を担当しています。 +以下の仕様を、AIが1つずつ実装できる最小のタスクに分解してください。 + +### 仕様 + + + + +--- + +### 分解のルール + +- 1タスクは「半日〜1日で完了できる」粒度にする +- タスク間の依存関係（「これが終わらないと始められない」）を明示する +- 各タスクに「これが完了した状態」を1行で書く + +### 出力してほしい形式 + +以下のテーブル形式で出力してください。 + +| Task ID | タイトル | 目的 | 依存 | 完了条件 | ステータス | +|---|---|---|---|---|---| +| T-001 | ... | ... | - | ... | Todo | + +--- + + +## 次にすること + +出力を `examples/tasks-example.md` を参考に保存したら、 +最優先のタスクを1つ選んで `prompts/20_implement.md` へ進んでください。 diff --git a/prompts/20_implement.md b/prompts/20_implement.md new file mode 100644 index 0000000..85c2f55 --- /dev/null +++ b/prompts/20_implement.md @@ -0,0 +1,41 @@ +# 20 | タスクを実装する + +--- + +## AIへの指示文（ここから下をそのままAIに貼り付けてください） + +あなたはシニアエンジニアとして実装を担当しています。 +**以下のタスクだけを**実装してください。指示にないことは追加しないでください。 + +### 実装するタスク + +- **Task ID**: +- **タスク内容**: +- **完了条件**: +- **変更してよいファイル**: +- **変更してはいけない範囲**: + +--- + +### 実装のルール + +- 完了条件を満たす最小の変更だけ行う +- APIキーや秘密情報をコードに直接書かない（`.env` を使う） +- できればテストも追加する + +### 出力してほしい形式 + +1. **変更するファイルの一覧**（各ファイルに変更理由を1行で） +2. **実装したコード** +3. **テスト**（書いた場合） +4. **完了条件の確認**（各条件に対して OK か NG か） +5. **残っている課題**（あれば） + +--- + + +## 次にすること + +実装が終わったら: +1. タスク一覧のステータスを `Done` に更新する +2. `prompts/30_review.md` でコードを確認してもらう diff --git a/prompts/30_review.md b/prompts/30_review.md new file mode 100644 index 0000000..2636834 --- /dev/null +++ b/prompts/30_review.md @@ -0,0 +1,58 @@ +# 30 | コードを確認する + +--- + +## AIへの指示文（ここから下をそのままAIに貼り付けてください） + +あなたは実運用前の最終レビュー担当です。 +以下のコードを**厳しく**確認してください。曖昧な褒め言葉は不要です。 + +### レビュー対象 + +- **目的・要件**: +- **変更したファイル**: +- **変更したコード**: +- **既知の制約**: + +--- + +### 確認してほしい観点 + +- **仕様通りか**: 要件・完了条件を満たしているか +- **バグがないか**: 想定外の入力・エラー処理・抜け漏れ +- **セキュリティ**: APIキーの直書き・認証の抜け・危険な入力を受け付けていないか +- **既存機能への影響**: 他の画面や機能が壊れていないか +- **読みやすさ**: 意図が伝わるコードになっているか +- **テスト不足**: 確認が必要なケースが抜けていないか + +### 出力してほしい形式 + +#### 指摘事項 + +1. [重大度] タイトル + - 問題: （何が問題か） + - 根拠: （どのコードが問題か） + - 影響: （放置するとどうなるか） + - 修正案: （どう直すか） + +重大度は `Critical`（必ず直す） / `High`（直した方がよい） / `Medium` / `Low` の4段階。 + +#### 未確認リスク + +- 動作確認できていない部分を列挙 + +#### 判定 + +`Approve`（マージしてよい） または `Request Changes`（修正が必要） +を明記して、理由を1〜2文で書いてください。 + +--- + + +## 次にすること + +- `Request Changes` の場合 → 指摘を修正してから再度レビューを依頼する +- `Approve` の場合 → マージしてタスク完了、次のタスクへ diff --git a/prompts/40_debug.md b/prompts/40_debug.md new file mode 100644 index 0000000..c12ddb7 --- /dev/null +++ b/prompts/40_debug.md @@ -0,0 +1,33 @@ +# 40 | 動かない時に原因を切り分ける + +--- + +## AIへの指示文（ここから下をそのままAIに貼り付けてください） + +あなたはデバッグ担当のエンジニアです。 +以下の状況を整理して、最短で直す方法を教えてください。 + +### 状況 + +- **症状**: +- **再現手順**: +- **期待していた動作**: +- **実際の動作**: +- **エラーログ**: +- **直近の変更**: + +--- + +### 出力してほしい形式 + +1. **原因の候補**（可能性が高い順に最大3つ） +2. **各候補の確認方法**（実行できるコマンドや確認手順） +3. **最小の修正案**（コード例があれば） +4. **再発を防ぐには** + +--- + + +## 次にすること + +修正が終わったら `prompts/30_review.md` で確認してもらってください。