AIで作るアプリの「思ってたのと違う」をgrill-with-docsで防ぐ

AIでアプリを作ったときに、「なんか思ってたのと違う」「使いづらい」「見た目がイマイチ」となったことはないでしょうか。

原因は、要件定義をしていないことです。

この記事では、現役エンジニアのぼくが実務で使うアプリの要件定義を、Claude Codeとスキル「grill-with-docs」で行った具体的な手順を解説します。

動画で見たい方はこちら。

AIで作るアプリが思い通りにならないのは、要件定義をしていないから

要件定義とは、誰のどんな課題を、どう解決するアプリかを決めることです。

例えばタスク管理アプリでも、使うのが会社員か、主婦か、学生かで、必要な機能も見た目も変わります。会社員ならGoogleカレンダーとの連携、学生なら学生ポータルからのデータ取得が便利かもしれません。

アプリを作るときは、最初に要件をまとめた要件定義書を作ります。要件定義書でAIと認識を合わせておけば、完成したアプリが「思ってたのと全然違う」とはなりません。

Claude Codeの公式ベストプラクティスも、AIにいきなりコードを書かせると、間違った問題を解決するコードができる可能性があると指摘しています。

要件定義書には、機能要件と非機能要件をまとめる

要件定義書に書くのは、機能要件と非機能要件の2種類です。

• 機能要件：利用者の課題を解決するアプリの機能。タスク管理アプリなら、タスクの一覧表示・検索・編集・削除など
• 非機能要件：機能と直接関係ない、アプリに求める品質。同時アクセス可能数、画面表示までにかかる時間、利用可能時間など

grill-with-docsは、AIの質問に答えるだけで、やることを明確にするスキル

grill-with-docsは、海外の有名エンジニアのMatt Pocockさんが公開している、商用利用もできる無料のエージェントスキルです。エンジニアの実務でもよく使われています。

要件定義のように、まだ内容が固まっていない作業でやりたいことを伝えると、AIが必要なことを質問してきて、やることを明確にしてくれます。

インストールは、コマンド実行1つ

公式リポジトリのREADMEに、AIエージェントごとのインストール方法が書かれています。Claude Codeなら、「Claude Code」欄のコマンドを1つ実行するだけ。CodexやGitHub Copilotへの入れ方もあります。

grill-with-docsは、grillingとdomain-modelingという2つのスキルを使って動くため、これらも一緒にインストールされます。

リポジトリ名は、アプリ名を表すシンプルな名前にする

さっそくgrill-with-docsを使って要件定義を始めます。

まず、アプリのGitHubリポジトリを作ります。リポジトリ名はプロジェクト名やフォルダ名など、いろいろな場所で使うので、アプリ名を表すシンプルな名前にしましょう。

ぼくはYouTubeやSNS、Webサイトなどの分析データを一元管理するアプリを作るので、contents-analytics-dbと名付けました。

要件定義は重要で難しいので、なるべく賢いAIモデルで行う

作ったリポジトリのフォルダをClaude Codeで開き、入力欄の右下で、モデルをFable 5.1、思考レベルを高にします。

要件定義はアプリの完成度を決める重要で難しい作業なので、AIモデルはなるべく賢いものを使いましょう。

ぼくは利用枠に余裕があるのでFable 5.1を使いましたが、Opus 5.5でも十分です。

要件定義作成の指示には、決まっていること・MVPという言葉を入れる

入力欄に/grill-with-docsと入力し、続けて作りたいアプリの内容を書きます。

最近のAIは賢いので、内容が整理されていなくても、情報が足りなくても、必要なことは向こうから聞いてきます。それでも、今の時点で決まっていることは最初に書いておくと、AIとのやりとりの手間が減ります。

今回は、次の内容を伝えました。

• YouTubeとCloudflareのWebサイトのデータを一元管理
• 人が見やすいUIと、AIエージェントも使いやすい形でデータを保管
• AIからのアドバイスやコンテンツの改善に活用
• 各媒体の分析データは1日1回自動取得
• アプリを置く場所はCloudflare（コストが安く、AIエージェントも使いやすいため）

指示には、必ずMVPという言葉を入れます。MVPはMinimum Viable Productの略で、実用最小限の製品、つまり課題を解決するために最も重要な機能だけを備えたアプリのことです。

最初から機能を盛り込むと、作るのが大変になったり、ほとんど使わない機能が出てきたりと無駄が多くなります。本当に必要な機能だけを作り、使いながら改善するほうが、良いアプリになります。

AIからの質問には、推奨回答と違うものだけ答るとラク

指示を送ると、1分ほどで最初の質問がまとめて届きました。各質問には選択肢があり、AIがどれを推奨するかも書かれています。

回答では、推奨回答と自分の答えが違う質問だけ答えを書き、残りは「上記以外は推奨でOK」のようにまとめるのがラクです。

grill-with-docsは、回答に応じて次の質問を考えてきます。AIの疑問がなくなるまで答え続けると、明確になった内容をまとめてくれます。

ぼくは最初に「要件定義書を作成して」と指示していたので、質問が終わると要件定義書も自動で作られました。質問は全部で33問。15分ほどかかりました。

grill-with-docsは、要件定義書のほかに、CONTEXT.mdとADRも作成します。これらについては、後で解説します。

要件定義書には、アプリの目的から使う技術までがまとまる

完成した要件定義書は、requirements.mdというファイルです。主に次の内容が書かれています。

• アプリの目的
• 利用者
• アプリに含むもの・含まないもの
• 具体的な利用場面
• データの取得元と取得方法
• ドメインモデル
• テーブル定義
• データ量の見込み
• 機能要件
• 非機能要件（プログラミング言語やフレームワーク、デプロイ先、開発ツールなど）

ドメインモデルで、アプリの中の概念を整理する

ドメインモデルとは、アプリの中で概念をどう構造化して整理するかを表したものです。grill-with-docsでは、この図も質問に答えるだけで作られます。

例えば今回は、YouTubeチャンネルの中に動画があり、動画には本編とショート動画があります。その動画と記事が1対1でつながり、日次で分析されるといったドメインモデルになりました。

テーブル定義で、データベースへの保管方法を決める

テーブル定義とは、データベースでデータをどう整理して保管するかを決めたものです。

例えばchannelsテーブルにはYouTubeのデータ、episodesテーブルには記事のデータが入ります。各テーブルには、タイトルや公開日のような値の列（カラム）が並びます。

CONTEXT.mdで用語を定義すると、AIも人も迷わない

grill-with-docsは、要件定義書以外のドキュメントも作ります。1つは、アプリで使う用語を定義するCONTEXT.mdです。

例えばこのアプリでは、YouTube本編から切り出した縦長の動画を「ショート動画」と定義しています。縦動画や切り抜き動画とも呼べますが、このアプリではショート動画に統一しました。

CONTEXT.mdには、使う言葉とその意味に加えて、「切り抜き」のような使わない言葉も書かれます。

用語を決めないと、ショート動画、切り抜き動画、縦動画と書き方がぶれて、何が何を指すのか分からなくなります。プログラムは勘違いからバグを生みやすくなり、ドキュメントも読みづらくなります。

grill-with-docsは、議論の中で決まった用語をCONTEXT.mdに定義していきます。なお、スキルのv1.3.0（2026年10月公開）以降では、ファイル名がGLOSSARY.mdに変わりました。

ADRで判断の理由を残すと、AIが決定を覆さない

grill-with-docsが作るもう1つのドキュメントは、ADR（Architecture Decision Record）です。ADRとは、アーキテクチャの決定記録という意味。アプリの機能をなぜそうしたのか、決めたことと理由を記録します。

例えば今回のADRには、アプリは読み取り専用のデータ基盤に絞り、施策の提案は外部のAIエージェントに任せると書かれています。データを見て改善を提案するのは、Claude CodeやCodexの役割です。

提案機能までアプリに含めると、実装量が増えるうえ、Claude CodeやCodexが進化するたびにアプリ側も直さなければなりません。この手間を避けるため、提案機能は外部に任せると決めました。

ADRを残すのは、ソースコードだけでは、なぜそのコードになっているかが分からないからです。ADRがなければ、AIは実装時に提案機能まで作ってしまうかもしれません。

一方で、決定の記録があれば、AIがその決定を無視して実装することはほぼないと言えます。

grill-with-docsは、議論で決まった内容を、ADRとして自動で残してくれます。

実装の前に、AIが対応しやすいPR単位へ作業を分ける

要件定義ができたら、さっそく実装、といきたいところですが、一気に全部を実装させると、バグが起こりやすく確認も大変です。そこで、Claude Codeに追加で以下の指示をしました。

今後の作業をAIエージェントが対応しやすいPR単位でドキュメントにまとめて

こうすると、AIが作業しやすい粒度に作業計画を分けてくれます。今回はplan.mdに、PR（プルリクエスト）を13本に分けて開発する計画がまとまりました。

あとは計画に沿って「PR1番を対応して」と指示し、結果を確認したら次はPR2番、という流れでアプリを作り上げていけます。

まとめの前に、お知らせを。

公式LINEの友だち追加特典で、無料30分相談を受付中。オンライン（顔出し不要）で、AI活用のお困りごとに答えます。

友だち追加後、「相談」と送ると予約リンクが届きます。余裕がなくなったら締め切るので、お早めにどうぞ。

はたらクラフト公式LINELINElin.ee

無料メルマガで実務で使えるAI活用を毎日配信中。1分で登録できます。

超実践AI論Substacktaichiaiworker.substack.com

まとめ：アプリは、grill-with-docsで要件定義を固めてから作る

この記事の要点は次の5つです。

• AIで作るアプリが「思ってたのと違う」となる原因は、要件定義をしていないこと
• 要件定義はアプリが誰のどんな課題を解決するかを決めること
• 機能要件でアプリの機能を決め、非機能要件で求められる品質を定義する
• grill-with-docsは、AIの質問に答えるだけで要件を明確にし、用語と判断の理由も残すスキル
• 要件定義作成の指示には決まっていることとMVP（実用最小限の製品）という言葉を入れる
• AIからの質問には推奨回答と違うものだけを答え、それ以外は「上記以外は推奨でOK」と答えるとラク
• grill-with-docsの成果物は要件定義書、CONTEXT.md（用語の定義）、ADR（意思決定の記録）
• 実装は、AIが対応しやすいPR単位に分けてから1本ずつ進める

まずはあなたも、grill-with-docsで自分が作りたいアプリの要件定義書を作ってみてください。AIと認識を合わせてから作れば、完成したアプリに「思ってたのと違う」と悩まずに済みます。

以下の記事では、このアプリを作りながら、ブランチ運用やレビュー、CI/CDな、セキュリティなどのアプリ開発の基盤を、どんな順番でどう整えるかについて解説しています。

（後日公開予定）