要件からIssueへ。AIに作らせる前に、作るものを決める段取り

段1〜6は、GitHubを「記録の置き場」として使います。段5でIssueを作り、段6でPull Requestを作るとき、GitHub側の準備が無いとそこで止まります。ここで準備を済ませておきます。

準備は3つです。GitHubのアカウント作成、GitHubをターミナルから扱う道具 gh の導入、アプリ用リポジトリ（保管庫）の作成。このうち自分で行うのはアカウント作成だけで、残りの2つはAIに頼みます。ターミナルは開きません。

入力

メールアドレスと、アプリを置くフォルダ（AIを開いているフォルダ）。

出力

ログイン済みのGitHubアカウント、AIがGitHubを操作できる状態、中身が空のアプリ用リポジトリ。

1. github.com/signup を開き、メールアドレスとパスワードを入れる。
2. ユーザー名を決める。半角英数とハイフンだけ。後でリポジトリのURLに入るので、あとから変えにくい。
3. 届いたメールの確認コードを入れる。プランは無料（Free）で足りる。
4. 設定から二段階認証（Two-factor authentication）を有効にしておく。スマホの認証アプリで済む。

パスワードやメールの確認コードは、AIに渡さず自分で入力します。

アプリを置きたいフォルダでAIを開き、下の文をそのまま渡します。AIが道具を入れ、GitHubへのログインを案内し、リポジトリを作ってつなぎます。

GitHub を使う準備を、私の代わりにしてください。私はコードを書かない人間で、ターミナルの操作はしません。

やってほしいこと:
1. GitHub の公式コマンド gh が入っているか確認し、無ければインストールする（git も無ければ一緒に）
2. gh auth status でログイン済みか確認する。未ログインなら gh auth login を実行し、私がブラウザで押す場面になったら「今、何をどこで押すか」を一言で教える
3. このフォルダを git で管理する状態にして、README.md と、docs フォルダ（中に案内用の README.md）を作り、初回コミットする
4. gh repo create で GitHub 上に private（自分だけが見られる）のリポジトリ {アプリ名。半角英数。例: offkai-app} を作り、このフォルダとつないで push する
5. 最後に gh repo view --web でブラウザに開き、README が見えるかを私に確認してもらう

守ってほしいこと:
- 各手順で何をしたかを、私に分かる言葉で1行ずつ報告する
- 途中で私の操作が必要になったら、止まって待つ
- 私のパスワードや確認コードを聞かない

途中でAIが「ブラウザを開いてください」と言う場面が1回あります。ログインの許可です。ブラウザにGitHubのページが開くので、AIが示した8桁のコードを貼って「Authorize」を押します。これだけが自分の操作で、あとはAIが進めます。

最後にブラウザで開いたリポジトリに、README と docs が見えていれば完了です。docs は、段1〜3で作る要件定義書・仕様書・設計書の置き場になります。

# Mac
brew install gh
# Windows（PowerShell）
winget install GitHub.cli
winget install Git.Git

# GitHub にログインし、確認する
gh auth login
gh auth status

git init
echo "# {アプリ名}" > README.md
mkdir docs
echo "要件定義書・仕様書・設計書をここに置く" > docs/README.md
git add .
git commit -m "初回コミット"
gh repo create {アプリ名} --private --source=. --push
gh repo view --web

• GitHubにブラウザでログインでき、二段階認証が有効になっている
• AIに「gh auth status の結果を見せて」と頼むと、「Logged in」を含む結果が返ってくる
• ブラウザでリポジトリを開くと、README と docs が見える
• リポジトリ名の横に Private と表示されている

機能の一覧を書く段階ではありません。「困りごと」と「嬉しさ」を言葉にする段階です。ここが曖昧だと、後のすべての段が曖昧なまま進みます。

コツは、AIに書かせるのではなく、AIに聞かせることです。自分が答えているうちに要件が固まります。

入力

頭の中の構想。まとまっていなくて構いません。

出力

要件定義書。A4で1枚に収まる長さ。

• 「目的」が一文で書けている
• 使う人が立場ごとに分かれている（主催者と参加者、など）
• 「やらないこと」が3つ以上ある
• 「完成の目安」が、実際にやってみれば確認できる形になっている
• 技術の話（データベース、フレームワークなど）が一切出てこない

要件定義書は「何のために」を書いたものです。仕様書はそれを「具体的に何があるか」に翻訳します。画面が何枚あり、それぞれで何ができ、どんなデータを覚えておき、誰に何が許されるか。

ここは技術の一歩手前です。「データベースに何のテーブルを作るか」ではなく、「オフ会には名前と日程候補と会場がある」という日本語の粒度で書きます。

入力

段1の要件定義書。

出力

仕様書。画面一覧、データ、ルール、やらないこと、用語の5節。

• 画面一覧の各行に「誰が」がある
• 要件定義書の「必須」がすべて、どこかの画面に対応している
• 「ルール」に、できないことが書いてある（他人の回答は変えられない、など）
• 「やらないこと」が要件定義書と一致している
• AIが勝手に足した機能が「提案」に隔離され、本文に混ざっていない

仕様書には技術を書きませんでした。設計書は、その仕様をどんな道具で、どんな形で作るかを決める段です。ここで初めて「使う技術」「データの持ち方」「権限の実現方法」が出てきます。

技術を自分で選べる必要はありません。AIに選ばせて、理由を自分が読める言葉で書かせ、決めたことを1か所に残します。設計書が無いと、AIは会話のたびに違う技術や違うデータの形を選び、Issueをまたいだ途端に噛み合わなくなります。

入力

段2の仕様書。

出力

設計書。使う技術と理由、画面の遷移、データの構造、権限の実現方法、外部サービス、動作確認の方法の6節。

• 使う技術ごとに、理由が一文で書いてあり、自分が人に説明できる
• 「データの構造」の表が、仕様書の「扱うデータ」と一対一で対応している
• 仕様書の「ルール」がすべて、「権限の実現方法」のどこかで扱われている
• 仕様書に無い機能が増えていない。変えたい点は「仕様書への相談」に隔離されている
• 読んで分からない用語が残っていない（残っていたらAIに説明を足させる）

仕様書と設計書をそのままAIに渡して「全部作って」と言うと、途中で壊れたときに戻る場所がありません。仕様書の機能を、設計書の順序に沿って、1つずつ完成させて確認できるタスクに切り、順番を決めます。

切り方の基準は一つです。そのタスクだけが終わった状態で、自分で動かして「できた」と言えるか。言えないなら、大きすぎるか、依存する別のタスクが先です。

入力

段2の仕様書と、段3の設計書。

出力

タスク一覧。各タスクに、名前、完了条件、順番、依存があるもの。

• タスク1が「一本道」になっている（ログインして何か1画面が出る、程度）
• すべてのタスクに、自分が触って確認できる完了条件がある
• 依存関係が一方向で、順に進めれば詰まらない
• 要件定義書の「必須」がすべて、どれかのタスクに含まれている
• 本数が3〜10本に収まっている（超えるなら仕様が大きすぎる）
• 設計書に無い技術や外部サービスが、タスクの中に出てきていない

段4で作ったタスク一覧を、GitHubのIssueとして1本ずつ登録します。チャットのログやメモ帳ではなくIssueにする理由は4つあります。

• 番号が付く。「#3をやって」とAIにも人にも一言で渡せる
• 完了条件がチェックリストとして残り、終わったかどうかを後から見返せる
• 変更（Pull Request）と自動で結びつき、「この機能はどの変更で入ったか」を辿れる
• 閉じたIssueが、そのまま開発の履歴になる

入力

段4のタスク一覧。

出力

GitHub Issue。子Issueがタスクの本数分と、それを束ねる親Issueが1本。

子Issueの本文は、いつも同じ4節にします。この型は、著者が実際に運用しているプロジェクトのIssueの形をそのまま一般化したものです。

## 概要
{何を作るか、1〜3文}

## 背景と目的
{要件定義書のどの困りごとに効くか。仕様書のどの画面・ルール、設計書のどの表に対応するか}

## 対応チェックリスト
- [ ] {作業の区切り1}
- [ ] {作業の区切り2}

## 完了条件（Acceptance Criteria）
- [ ] {自分が触って確認できる文1}
- [ ] {自分が触って確認できる文2}

Refs #{親Issueの番号}

タイトルには種類を接頭辞で付けます。新機能は feat:、不具合の修正は fix:、文書は docs:。一覧で見たときに種類が揃って読めます。

Issueは自分でGitHubの画面から作っても構いませんが、本文をタスク一覧から起こす作業はAIに任せられます。

下のタスク一覧を、GitHub Issue の本文に書き起こしてください。

- 子Issueは、タスク1本につき1つ。下のテンプレートの4節で書く
- タイトルは「feat: {何ができるようになるか}」の形
- 「完了条件」は、タスク一覧の完了条件をそのまま使う。私が触って確認できる文になっていなければ直す
- 親Issueを1つ作り、子Issueを並べる。親の本文には「子から親へは Refs で参照」と明記する
- 書き終えたら、私に一度見せて確認を取る。確認後に gh issue create で登録する。親を先に作り、返ってきた番号を子の Refs に入れる
- 登録が終わったら gh issue list の結果を見せる

子Issueのテンプレート:
## 概要
## 背景と目的
## 対応チェックリスト
## 完了条件（Acceptance Criteria）
Refs #{親の番号}

タスク一覧:
{段4で作ったタスク一覧をここに貼る}

GitHubの画面でIssueを5本作るのは、手作業としては意外に重いです。段0で入れた gh（GitHub公式のコマンドラインツール）があると、AIがIssueの登録、一覧、内容の確認、書き換えをすべて代行できます。上のプロンプトの最後の2行が、その指示です。

登録後の確認や手直しも、AIに頼みます。

登録した Issue を確認したい。
- gh issue list で一覧を見せて
- Issue #{番号} の本文を見せて
- 親 Issue #{親の番号} の「子Issue」の一覧を、確定した番号で書き直して

うまくいかないときは、たいてい段0のログインが切れています。AIに「gh auth status を確認して、未ログインなら案内して」と頼めば直ります。

# 親Issueを作る（本文はファイルから渡す。番号が返ってくる）
gh issue create --title "chore: オフ会アプリ v1（親）" --body-file parent.md

# 子Issueを作る（ラベルも同時に付ける）
gh issue create --title "feat: 日程候補への出欠回答" --body-file issue-4.md --label enhancement

# 一覧を見る / 1本を見る
gh issue list
gh issue view 4

# 親Issueの本文を、子の番号が決まったあとで書き直す
gh issue edit 1 --body-file parent.md

# 終わったIssueを閉じる（PRの Closes #4 で自動的に閉じるなら不要）
gh issue close 4

• 子Issueがタスクの本数分あり、それぞれに完了条件がある
• 親Issueに子が全部並び、「Refs で参照」と書いてある
• 子Issueの本文に Refs #親 があり、Closes #親 になっていない
• タイトルに feat: などの接頭辞がある
• 要件定義書・仕様書・設計書の置き場所が、親Issueからリンクされている