Zennのみなさん、こんにちは！
TSUKURUBAで、Web フロントエンドエンジニアをしているkiiです
最近、プロジェクトの中でAI Agent（Cursor）を活用した開発に取り組み、試行錯誤を重ねてきました。
その過程で見えてきた、効果的な開発フローやノウハウを本記事でまとめて共有します。
いろんなAI Agent利用記事あるのですが、抽象的なものが多く、もっと具体例教えてほしいな〜と思ったので書いてみました！
実際に使っているドキュメントや命令の例、運用のコツも紹介しますので、
みなさんの開発やAI活用の参考になれば幸いです。
以下の流れで紹介します。
大枠だけ理解していれば大丈夫です。
A: 要求から実装用のDocumentを作成
B: 実装用Documentから開発
現状のAI Agentを利用した開発において、いきなり開発を始めずに、要求から実装要件の詳細を詰めたり、実装方針を決めて、タスク分割することが大事なのはご存知だと思います。
実装要件や実装方針を適当に定義して、実装を開始すると手戻りが発生しがちでツライ経験ありますよね？
例えば、「実装要件ドキュメント」を作成する意図の一つは、プロダクト開発における要求をテキスト情報という形で明確に残すことです。
将来、技術の進歩によってより良い実装方法が登場したり、システム全体を作り直したりする可能性を考えると、要求仕様がテキストとして整理されていれば、それらを活用して新しいシステムを効率的に構築できるからです。
プロダクト開発では従来より、要求定義、要件定義、実装方針策定、タスク分解といったプロセスが存在します。しかし、AI Agentを活用した開発はスピードが速いため、これらのプロセスが混同しがちです。各フェーズを意図的に分離することで、人間とAIそれぞれが集中すべき点を明確にし、より質の高い検討が可能になると考えています。
当初は、要求定義からタスク化までを一連の作業として扱っていました。
また、以前はChatGPTやClaudeのプロジェクト機能を利用していましたが、現在はCursorエディタ内で要件整理なども行っています。
ということで、順に説明していきます。
以降は、以下のような、ユーザーレビューのサマリーを閲覧できるUIを作ることを通して、実際に説明します。
| Mobile | Desktop |
|---|---|
 |
 |
このフェーズの目的: 様々な形式の要求情報を集約し、明確な実装要件を定義すること。
ゴール: 要求の抜け漏れを防ぎ、開発の方向性を定める specification.md を完成させること。
このフェーズの目的は、いろんな実装要求情報を1つの実装要件Documentにまとめることです。
事前に、要求から実装要件を作成するためのDocumentをレポジトリに用意しておきます。
事前に用意してある、Figmaのデザイン要求やタスクにまとめられたビジネス要求などの情報をInputしながら、不明確な要求が無く、実装の要件が明確になるように詰めていきます。
まずは、以下のように、デザインデータ(MCP)とデザインのキャプチャ画像、今回作りたいUIの名前情報を渡してみました。
すると、下記のように不明瞭な要求をピックアップしてくれます。
さて、上記の問に回答していきます。
補足: まとまった質問への回答やレビューの入力方法
添付画像を見ると、まとまった質問への回答(赤色)と参照ファイルの添付(青色)が見えますね。
ChatGPTのProjectにて、「音声入力をまとめる君」というProjectを用意してありそれを利用しています。
指示はシンプルです。
### 役割
あなたは、Web Frontendアプリケーションの開発のプロフェッショナルで、
Product開発に精通しています。
また、音声入力で渡されたテキストをまとめる能力があります。
特に、Product開発における要求や要件をまとめる能力に長けています。
### 行うタスク
音声入力で入力された要件整理用の口頭のメモを、まとめてください。
情報は全く減らさないでください。
あくまで、言い淀みを減らすだけにとどめて下さい。
また、各コメントに対して行ってください。前回のコメントの内容は一切反映しないで、各コメントに対して言い淀みを減らすタスクをおこなってください。
まとめたOutputは、コピー&ペーストしやすいように、codeブロック内にmarkdown形式でまとめてください。
先ほどの質問に対する利用事例を見てみます。
添付画像を見てみると以下のように、入力を入れています。
すると、以下のようにまとめられるので、それをAppleのユニバーサルクリップボード伝いでCursorにコピペする。
音声入力専用のアプリケーションを導入することも考えているのですが、現状の品質で一定満足しているので、切り替えの優先度としては上がっていません。
さて、何度かやり取りを行って、仕上げていきましょう。
これは、実際に作ってくれた実装要件Doc(specification.md)を見て意見を述べています。
実装要件Doc(specification.md)ができました。
このフェーズの目的: 実装要件に基づき、具体的な技術選定や設計アプローチを決定すること。
ゴール: 開発チームが共通認識を持てる実装方針を記した design-doc.md を完成させること。
このフェーズの目的は、実装要件Documentや既存codeをベースに実装方針を一緒に考えて、1つのDocumentを作るフェーズです
事前に、作成するためのDocumentをレポジトリに用意しておきます。
作成した要件ドキュメントをベースに、実装方針を決める助けになる情報をInputして、実装方針を決めていきます。
今回は、実装方針において論点がなさそうだったので、一旦丸投げしてみました。
すると、以下のように質問を投げてくれています。
で、A1の実装要件作成セクションで説明したような回答方法で、実装方針について意見を述べていきます。
その後も、仮の実装方針案を提案してくれているので、一緒に調整して完成させます。
下の画像のように、完成済みの別のdesign-doc.mdと実装を参照させています。
大きく実装方針が変わらなくて、まだ、docsやrulesでドキュメント化していない場合に、この方法は使えると思います。
お手本の事例を用意しておくと助かりそうですね。
ということで、実装方針Docができました。
今回のケースでいうと、Component自身の実装方針のほかに、既存のcomponentにある定数を共通の場所に引っ越したいな〜と思ったのでその方針も下部に書いています。
このフェーズの目的: 実装方針を具体的な作業単位に分解し、開発手順を計画すること。
ゴール: 実装順序や依存関係が明確なタスクリスト task.md を完成させること。
このフェーズの目的は、実装要件定義書（specification.md）と設計方針書（design-doc.md）に基づき、開発タスクを分割・整理し、実装順序を考えます。
事前に、作成するためのDocumentをレポジトリに用意しておきます。
作成した実装方針ドキュメントをベースに、実装タスクの分解や参考実装になる情報をInputして、実装タスクの粒度や順番を考えていきます。
今回も、実装タスクにおいて、論点がなさそうだったので、一旦丸投げしてみました。
で、不明瞭な点について質問してくれているので回答していきます。
仮のタスクドキュメントを作ってくれたので、レビューして一緒に作っていきます。
という感じで、実装方針Docができました。
最初にリファクタリングタスク切り出してくれているので、Tidy First?でいう「先に整頓」をしてcommit/PRを切り出せてありがたい。
段階的に作ってくれているので、小さく動作確認しながら作成できる。
ここまでで、要求情報を整理し、具体的な実装要件 (specification.md)、技術的な方針 (design-doc.md)、そして開発手順を示すタスクリスト (task.md)の3つのドキュメントを作成しました。
これらのドキュメントを作成するプロセスを通じて、AI Agentと対話しながら不明瞭な点を解消し、開発の方向性を固めることができました。
特に、各フェーズで目的とゴールを意識することで、手戻りを減らし、効率的な開発準備を進めることを意識しています。
Component単位だから出来ただけではないか？大きい粒度だとできる？と疑問に思うでしょう。僕も思いました。
ただ実際試してみるとPage単位とかでも出来ます。
イメージでいうと、以下みたいな方法をしてました。
ということで、要求から実装用のDocumentを作成できました。
実際に開発していきます
ここまでしていると、基本的にはDocumentに沿って実行していくだけです。
先ほどの3つのDocumentは、commitしてcodeベース内に入れます。
このフェーズの目的: 分割されたタスクに基づき、AI Agentと協調しながら段階的に実装を進めること。
ゴール: task.md に記載された各タスクが完了し、コードが期待通りに動作すること。
タスクDocに沿って、実行していきます。
タスク1は、分かりやすいタスクだったので、タスク１やって！ぐらいの指示を投げました。
タスク１完了報告が来ました。
実行内容や差分を確認した感じ、期待通りだったので、
特に微調整することなく、僕の方でcommitして次のタスクに進みます。
言及した通り、修正時のcommitは人間がするようにしています。
理由
ただし、以下のようなツールを利用してcommit作成時の手間は少し省いています。
※上記を行わずに、docs/git-commit.mdを参照させて、１リクエスト消費する形であればcommitは大体うまくいくのですが、さすがにコスパ悪いので、手動でやってます。
さて、別のタスクの事例も見てみましょう。
今回は以下を行っています。
すると、以下を行ってくれました。エラいですね〜
実装してもらったものに対して、意見を述べながら、一緒に作っていきます。
という感じで実装タスク分を一緒に作りきります。
実装タスクが終わったら、
実装用Documentをcommitしていましたが、PRのDiffとして表示したくないので、削除commitを作ります。
PRを作成/更新する作業です
B-1. 実装用の3つのDocumentをcommitのcommit Idを伝えて、機能するDocumentのリンクを一緒に置いてもらうようにしています。@pull-request.md
issue id なし。
pr id 123
commitId hugahoge7857q91に、要件や実装方針まとめたDocumentあるので、参考リンクとして利用して。
このPRのDescription更新Docは結構便利で、おすすめです。
ベースのDescriptionを書いてもらう事もそうですが、最新のdiffを下にDescriptionを更新してもらう事にも利用できます。
リファクタリングやレビュー修正で、Descriptionを書いた時からcodeの差分が出たけど、Descriptionが古いdiff前提で書いたままってこと無いですか？
そういうの、さっと直す時に便利です。
実際には、一度のA→Bのサイクルで、レビュー依頼やマージOK状態にするわけではないです。
GitHubのDiffを見ながらセルフレビューして、リファクタリングDocを作って、再度Bのサイクルを回します。まぁ、AI Agentがいない時代と同じですね。
イメージ: A→B→C→B→C→B→C
この記事では、Aセクションで3つのドキュメント (specification.md, design-doc.md, task.md) 作成し、それをもとに、BセクションでAI Agentと協調しながら実際の開発を進める手順を説明しました。
ここまで紹介しましたが、まだまだ改善の余地がたくさんあります。
今回は、開発途中で導入したこともあり、開発影響の大きい要求の確認や要件の整理、実装方針の大枠の決定、見積もり、開発スコープの決定は済んでいたので、実装フェーズにて、AI Agentのために改めて要件整理から行っていました。
0から要求整理をする場合は、以下のようなチームワークが必要でしょう。
ベースの要件整理や実装方針を一緒にAI Agentと考えるやり方のベースは変わらなくても、粒度や、段階が変わると思います。ここは模索中です🤔
ということで、実際のProject事例を通じた、AI活用のリアルなノウハウをいくつか共有してみました！
具体的な部分は陳腐化する可能性が高いですが、みなさんの手を動かすベースの１つとして参考になれば嬉しく思います。
チーム開発における、要求整理から実装までのいいやり方を僕も模索中です。
いい方法あるよ〜とかあれば、ぜひ世の中に共有してください🙏
Be the first to comment
