こんにちは、PortalKey の植森です。
今回は弊社で行っている AI を使った開発ワークフローについて書きたいと思います。
AI コーディング導入の難しさ
皆さん、こう思ったことはないでしょうか？
「AI にコーディングさせてみたけど使い物にならない」
「これって本当に効率上がってるの？」
ネット上などで見かけるサンプルコードレベルの例を見て「こんなシンプルな例で参考にならない」と感じたり、導入事例を見て「どういう使い方をしたら効率が上がったのかを知りたい」と感じることも多いでしょう。
僕も以前はそう感じていました。
実際のところ、「AI を使えばあらゆるシーンで誰でも効率が上がる」というのは嘘だと思います。
そこで、今回は実際に導入してみて感じた AI コーディングへの課題と自分なりの AI を使った効率的なワークフローについて書きたいと思います。
AI を使った開発ワークフロー
例えば、 Google の VibeCoding の説明には以下のようなことが書かれています。
「純粋な」バイブ コーディング: 最も探索的な形式では、ユーザーは AI の出力が意図したとおりに動作すると完全に信頼します。Karpathy 氏が説明したように、これは「コードの存在を忘れる」ようなもので、迅速なアイディエーションや、同氏が「使い捨ての週末プロジェクト」と呼ぶような、スピードが主な目標となる場合に最適です。
責任ある AI を活用した開発: これは、このコンセプトを実務に適用するものです。このモデルでは、AI ツールは強力なコラボレーター、つまり「ペア プログラマー」として機能します。ユーザーは AI をガイドしますが、AI が生成したコードをレビュー、テスト、理解し、最終的な製品の完全な所有権を持ちます。
小さな機能ではあまり複雑なワークフローは必要としませんが、大きな機能を実装する場合はそうではありません。
GitHub が公開した spec-kit では、以下のようなワークフローが紹介されています。
- Establish project principles: /speckit.constitution コマンドを使用して、その後のすべての開発のガイドとなるプロジェクトの管理原則と開発ガイドラインを作成します。
- Create the spec: /speckit.specify コマンドを使って、何を構築したいのかを説明しましょう。技術スタックではなく、何を、なぜ構築したいのかに焦点を当てましょう。
- Create a technical implementation plan: /speckit.plan コマンドを使用して、技術スタックとアーキテクチャの選択肢を指定します。
- Break down into tasks: /speckit.tasks コマンドで実装計画から実行可能なタスクリストを作成するために使用します。
- Execute implementation: /speckit.implement ですべてのタスクを実行し、計画に従って機能を構築するために使用します。
これは Google が述べている「責任ある AI を活用した開発」でのワークフローにあたると考えられます。
実際のプロダクト開発では「純粋なバイブコーディング」よりも「責任ある AI を活用した開発」の占める割合が多く、これらを場面に応じて適切に使い分けることが重要となってきます。
今回は、「責任ある AI を活用した開発」について重点的に考えてみます。
LLM の特性への理解
AI を利用した開発では、 LLM の特性に注意して開発を行う必要があります。
初期の生成 AI ではハルシネーションと呼ばれる、現実には存在しない情報や誤った内容を生成する現象が問題視されました。
ハルシネーションは技術の進歩により改善傾向にありますが、それに代わり**「Sycophancy（迎合、忖度）」**と呼ばれる、 LLM がユーザの意見や期待に過度に寄り添ったり、客観的な正しさよりも同調を優先してしまうという問題も起こっています。
また、2025/05/09 に投稿された「LLMs Get Lost In Multi-Turn Conversation」では、マルチターンの会話ではシングルターンよりも大幅にパフォーマンスが低下するという研究結果が報告されました。
この研究では LLM は対話の早い段階で得た前提に過度に依存して最終結論を出す傾向にあるとも述べられており、とても興味深い内容です。
また、これらは実際に AI によるコーディングを行った経験においても共感できる内容です。すなわち、
- AI は指示の内容が誤っていた場合もそれに合わせたコーディングを行ってしまう
- AI は初期の頃に前提が間違っていた場合、後から修正するのが苦手
- AI はユーザが見落としている内容や制約を指摘してくれない
- 長期間のセッションでは、出力内容が段々と劣化していく
といった傾向です。
責任ある AI を活用した開発をするために必要なこと
これらの特性から、個人的に 「責任ある AI を活用した開発」を行うためには以下のようなことが必要だと考えています。
- 可能な限り完全な仕様の要求と意図を AI に伝えること
- 技術的なコンテキストや実装のために必要な情報を AI に対し十分に提供する、あるいは収集させること
- 仕様や実装を明確にするために AI と十分な対話を行い、整合性チェックを行うこと
- 作業ステップを分割し、反復的な実装を行うこと
これは、 spec-kit で仕様駆動開発（Specification Driven Development）と呼ばれている考え方にも通じる内容です。
spec-kit ではこう述べられています。
数十年にわたり、コードは王様でした。仕様はコードに仕えるものであり、私たちが構築した足場であり、コーディングという「本当の仕事」が始まると捨て去られました。開発を導くために PRD を書き、実装を伝えるために設計書を作成し、アーキテクチャを視覚化するために図を描きました。しかし、これらは常にコード自体に従属するものでした。コードこそが真実であり、それ以外のものはせいぜい善意に過ぎませんでした。コードは真実の源であり、コードが進化するにつれて、仕様はほとんど追いついていませんでした。資産（コード）と実装は一体であるため、コードから構築しようとせずに並行して実装を行うことは容易ではありません。
仕様駆動開発（SDD）は、この力関係を逆転させます。**仕様はコードに仕えるのではなく、コードが仕様に仕えるのです。**製品要件ドキュメント（PRD）は実装のガイドではなく、実装を生み出す源泉です。技術計画はコーディングを指示する文書ではなく、コードを生成するための正確な定義です。これは、ソフトウェア開発方法の漸進的な改善ではなく、開発の原動力となるものを根本的に再考するものです。
(Google 翻訳)
「責任ある AI を活用した開発」を行うには、仕様と技術コンテキストをユーザ自身が理解し、それを AI に正しく伝えることが重要となってきます。
AI コーディング導入への課題
こうした開発を実際に現場で行うにあたってはいくつかの課題が存在します。
それは、こうしたワークフローを一から構築するには多大なコストがかかるという点です。
こうしたワークフローには以下のようなものが必要となります。
- プロジェクトのドメイン知識や技術コンテキストといった事前情報
- メンバーが一貫とした「責任ある AI を活用した開発」を行うための明確なワークフロー
- 仕様検討と整合性チェック、実装計画の策定、実装の実行といった一連のステップを安定して実行させるための指示
- これらを構築するために必要な MCP Server や Agent, Slash Commands といった技術への知識
これらを満たせていない状態で開発を行うと、AI の活用が効率的に行えるかどうかはメンバー 1 人 1 人の知識や能力、技術によって大きく左右されてしまいがちです。
PortalKey でのアプローチ - SuperClaude Framework の導入
そこで、弊社では SuperClaude Framework を導入することでこれらの課題を改善しました。
※実際のところ、弊社では Cursor を利用していたり、 SuperClaude が Python + TypeScript のプロジェクト向けだったりするためこれらをカスタマイズして利用しています。
SuperClaude は、Claude Code を構造化された開発プラットフォームにするためのフレームワークです。
SuperClaude は以下のようなものを提供し、開発者の AI コーディングをサポートします。
- Slash Commands
- 組み込み Agent
- MCP 連携
SuperClaude Framework を利用することで、これらを開発者が大きく意識することなく自然に利用することが可能となり、前述したような導入コストを大きく下げることが出来ます。
SuperClaude Framework のコンセプト
SuperClaude の機能は多岐に渡りますが、今回はコアとなっている考え方や技術について紹介します。
まず、 SuperClaude のプロンプトは以下のベストプラクティスにしたがって構築されています。
Keep Context Focused: ファイルごとに 1 つのコンテキスト
Clear Triggers: コンテキストがアクティブになるタイミングを定義する
Workflow Patterns: ステップバイステップのガイダンスを提供する
Examples: 実際の使用例を含める
Metadata: 設定にはフロントマター(*Markdown ファイルの先頭に記述されるメタデータのこと)を使用する
SuperClaude Framework では、これらを遵守することでシンプルかつ、構造化された命令を提供することを目的としています。
そして、 Slash Commands や Agent, MCP Server, (ここでは説明しませんが)Mode といった概念と体系的に組み合わせて利用することを想定されており、複雑な AI の制御をなるべくシンプルに行うことが出来るように構築されています。
各プロンプトは人間でも読みやすい形となっており、SuperClaude Framework を実際に利用しない場合でも、 Slash Commands のプロンプトを読むことでより良いプラクティスを理解することが出来るため余裕があれば読んでみることをおすすめします。
Slash Commands
Slash Commands とは、 /sc:brainstorm のようにスラッシュで始まる指示を出すことで、事前に登録しておいたプロンプトを特定の機能として呼び出すことができる仕組みです。
SuperClaude では、 Slash commands を利用することで、開発者が自然にワークフローを構築することが可能となります。
SuperClaude の Slash Commands は以下のようなステップでコマンドを処理するように構成されています。
- Claude reads commands/sc/implement.md
- Adopts implementation workflow pattern
- May auto-activate related agents
- Follows defined workflow steps
すなわち、 AI が定義された動作パターンを取り入れ、自動的に関連する Agent を起動し、定義されたワークフローステップに従って処理を行います。
リポジトリの以下の場所で実際に定義されているコマンドを確認することができます。
Agent
SuperClaude は 16 種類の Agent を提供しており、それぞれが特定の機能を担当しています。
Agent を利用することで、AI の行動を専門分野のドメインエキスパートとして特化した内容に変更することが出来ます。
Agent を利用するには 2 つの使用方法が存在します。
1. @agent- プレフィックスを使用した手動呼び出し
@agent-security のように直接呼び出すことにより、 AI に特定のエージェントとしてふるまわせることが出来ます。
# Directly invoke a specific agent
@agent-security "review authentication implementation"
@agent-frontend "design responsive navigation"
@agent-architect "plan microservices migration"
2. 自動アクティベーション
SuperClaude では、リクエスト内のキーワードやパターンに基づいて動作指示を読み取って、適切なエージェントを自動的にアクティベートする仕組みが存在します。
仕組みとしてはコンテキストファイル内に動作指示として直接書いてあり、コマンドなどを経由して呼び出されます。
# These commands auto-activate relevant agents
/sc:implement "JWT authentication" # → security-engineer auto-activates
/sc:design "React dashboard" # → frontend-architect auto-activates
/sc:troubleshoot "memory leak" # → performance-engineer auto-activates
以下のドキュメントでは、各 Agent の詳細な説明が書かれています。
MCP Server
AI を利用した開発では、 MCP Server を利用することで、 AI に特定の機能を提供することが出来ます。
しかし、最初はどういった MCP Server を利用するのが良いのかあまり分からないと思いのではないでしょうか。
SuperClaude では、以下の MCP Server が Core Server として定義されており、さらに AI がコマンド経由で自動アクティベーションされたり、簡単に利用するための方法も提供されています。
- context7: Official library documentation and patterns
- sequential-thinking: Multi-step reasoning and analysis
- magic: Modern UI component generation
- playwright: Browser automation and E2E testing
- morphllm-fast-apply: Pattern-based code transformations
- serena: Semantic code understanding and project memory
- tavily: Web search and real-time information retrieval
- chrome-devtools: Performance analysis and debugging
このうち、以下の MCP Server は特定のサービスを利用するものであり、また利用しなくても大きく利便性が下がらなかったり特定の利用シーンやワークフロー・アーキテクチャに限定されるものです。
また、利用には API Key が必要となるものもあります。必要に応じてセットアップを行うのがおすすめです。
- tavily: Web 検索の構造化・効率化、インテリジェントデータの抽出
- chrome-devtools: Chrome DevTools との連携
- magic: AI による UI コンポーネントの生成
- playwright: ブラウザ自動化と E2E テスト
- morphllm-fast-apply: パターンベースのコード変換、大規模なコード変換の最適化
それに対し、以下の MCP Server は特定のアーキテクチャや利用シーンに依存せず、また SuperClaude のコア機能を利用するためのものでもあるので必ず利用するのをおすすめします。
Context7
Context7 は、公式ライブラリのドキュメントとパターンを提供する MCP Server です。
LLM は仮定や推定に基づいてコードを生成しますが、 Context7 を利用することで正しいライブラリの情報を構造的に取得することが出来ます。
これによって、誤ったライブラリの使い方や不適切なパターンの使用を防ぐことが出来ます。
Sequential Thinking
Sequential Thinking は、複雑な分析や問題解決を行うための MCP Server です。
Sequential Thinking についてはこちらの記事も参考にしてみてください。
Sequential Thinking を指定することによって、より AI の推論結果を信頼性の高いものにすることが出来ます。
SuperClaude では、プロンプトに --think や --ultrathink といったフラグを指定することで Sequential Thinking を利用することが可能になっており、「Sequential Thinking を利用して推論を行ってください」のような長い指示を出さなくても良いようになっています。
Serena
Serena MCP Server は、セマンティックコード理解とセッション永続化を行うための MCP Server です。
Serena については複雑なので公式ドキュメントや紹介記事も参考にしてほしいのですが、要約すると以下のような機能を提供しています。
コードのセマンティック理解: Language Server Protocol (LSP) と連携することで IDE のように構造的にコードを理解することが出来る
Serena は LSP と連携することで、コードのセマンティック理解を行うことが出来ます。
IDE のようにシンボル検索を利用した関数やクラス定義の参照を行い、コードベースの文脈を正確に把握することが可能になります。
また、Serena は LSP から得た情報を構造的に検索インデックスとして保存し、より構造的なコンテキストを AI が理解することを支援します。
これによる副次的な効果として、消費されるトークン数を削減することが可能になります。消費されるトークン数が減ることにより、コンテキスト量の圧迫や利用料金の増加を抑えられるというのも大きなメリットです。
セッション永続化: セッション外へのコンテキストの永続化
もう 1 つの機能として、Serena はセッション外へのコンテキストの永続化を行うことが出来ます。
Serena はプロジェクトのローカルに memories というディレクトリを作成し、その中にファイルを作成することでセッション外へのコンテキストの永続化を行うことが出来ます。
通常、 LLM はセッション内でやり取りしたデータをコンテキストとして利用しますが、 Serena を利用することでセッションを超えてコンテキストをやり取りしたり、複数回参照するようなコンテキストを永続化して参照することが可能になります。
こういったデータで活用しやすい例としては以下のようなものがあります。
- 実装のパターンやベストプラクティス: プロジェクト内でのコーディングルールや実装パターンを LLM 自身が再度参照可能な情報として保存することで、人間がインストラクションファイルを作成する手間を省ける
- 実装記録: 実装の過程や結果を LLM 自身が再度参照可能な情報として保存することで、仕様や実装の詳細を記録することが出来る
- 作業セッションの管理: 作業経過を記録することで、別セッションで作業の再開を行うことが出来る
- 技術的なアーキテクチャ: 後述
特に作業セッションの管理は、前述した長期間セッションでの AI の劣化問題を避けるのに役立ちます。
大きなタスクを行うときに、作業計画をメモリとして記録し、複数のセッションを通して作業を進めることが出来るようになります。
技術的なアーキテクチャ: プロジェクトの技術的なアーキテクチャを永続化する
Serena の利用を開始する際、 Serena は AI に対してプロジェクトのオンボーディングを指示します。
オンボーディングではプロジェクト内のディレクトリ構成、技術スタック、アーキテクチャ、仕様などをある程度読み取ってメモリとして永続化します。
これにより、技術詳細などのインストラクションファイルを書く手間を大幅に削減することが可能です。
また、前述したように学習内容を永続化させることも可能なため、「これ何回も同じ指示を出しているな」というようなことを実装パターンとして永続化させることで、同じ実装を行う際に実装パターンをメモリから取得させることも可能です。
SuperClaude Framework を利用したワークフロー
SuperClaude では、ここまで説明した構成要素を利用してワークフローが組み立てられています。
エントリポイントとなるのが Slash Commands で、 SuperClaude Framework には大きく分けて二種類の Slash Commands が存在します。
- 事前定義された操作を行わせる実行可能なコマンド
- 事前定義された動作パターンをアクティブ化するコンテキストトリガー
例えば、 SuperClaude Framework のコアコマンドの 1 つである /sc:brainstorm には以下のように書かれています。
Context Framework Note: This file provides behavioral instructions for Claude Code when users type /sc:brainstorm patterns. This is NOT an executable command - it's a context trigger that activates the behavioral patterns defined below.
このように、いくつかのコマンドは事前定義された動作パターンをアクティブ化するコンテキストトリガーとして利用されています。
基本的なワークフロー
SuperClaude の利用パターンは多すぎて紹介しきれないので、ここでは基本的なパターンを紹介します。
# Step 1: Explore and understand requirements
/sc:brainstorm "web dashboard for project management"
# Expected: Requirements discovery, feature prioritization, technical scope
# Step 2: Analyze technical approach
/sc:analyze "dashboard architecture patterns" --focus architecture --c7
# Expected: Architecture patterns, technology recommendations, implementation strategy
# Step 3: Implement core functionality
/sc:implement "React dashboard with task management and team collaboration"
# Expected: Complete dashboard implementation with modern React patterns
これはドキュメントで Discovery -> Implementation Pattern として紹介されているパターンです。
/sc:brainstorm はソクラテス式問答法を使って体系的な問題の探索を行うブレインストーミングモードをアクティベートするコマンドです。
このコマンドによって、 AI からユーザに対し体系的な質問が投げかけられ、問題の曖昧な部分を明確になるように導いてくれます。
/sc:analyze は、技術的なアプローチを分析するコマンドです。
このコマンドはプロジェクトに対し静的解析やヒューリスティック評価を使ってソースファイルの分析を行い、技術的なアプローチを分析してくれます。
/sc:implement は、機能開発リクエストを行うためのコマンドです。
このコマンドを実行すると、分野に対応したエージェントや MCP Server を自動起動し、機能開発に特化したモードとして行動するようになります。
このように、 SuperClaude ではコマンドを通して AI の行動を複雑に制御しつつ、特定の行動に特化したモードをアクティベートすることが可能となります。
またコマンドの定義を読むとわかるのですが、コマンドは一定の幅を持った利用も可能なようになっています。
例えば、 /sc:analyze ではセキュリティリスクの分析やコード品質の分析といった指示も受け入れ、対応したエージェントを起動するようなプロンプトの調整が行われています。
以下の画像は二段階認証の実装で発生した OAuth 認証の考慮漏れが発生したときに対応方法を検討したときの /brainstorm コマンドの様子です。
途中を省略していますが、こちらの返答に対し Sequential Thinking を利用して分析を行っている様子がわかります。
セッションマネジメント
前述した Serena MCP Server の機能を利用することでセッションの管理も簡単に行うことが可能になっています。
Load Project Sessions
# Managing context in long conversations
# Start with context
/sc:load project/
# Work progressively
/sc:implement "feature A"
/sc:implement "feature B"
# Context accumulates
# Create checkpoint
/sc:save "session-checkpoint"
# Creates summary for your notes
# Continue work
/sc:implement "feature C"
# Final summary
/sc:reflect
# Reviews conversation progress
Context Refresh Pattern
# When conversation gets too long
# Save current state
/sc:save "work-complete"
# Copy output for next conversation
# In new conversation:
/sc:load project/
"Previous work: [paste summary]"
# Manually restore context
# Continue work
/sc:implement "next feature"
/sc:save や /sc:load といったコマンドを使うことにより長期化したセッションを別セッションで再開することが出来たり、セッションのコンテキストのリフレッシュを行うことが出来ます。
これによって長期セッションによる AI の劣化問題を軽減することが出来ます。
まとめ
今回は、 PortalKey での AI 開発ワークフローについて紹介しました。
AI を活用したワークフローを 0 から構築するのは大きなコストがかかり難易度も高いですが、ワークフロー構築用のフレームワークを利用することで導入コストを大幅に削減することが可能です。
実際、弊社でも SuperClaude 導入後は AI によるコーディングの効率が大きく上がった、使い方が分かってきたといった声が多かったです。
また、ここでは SuperClaude Framework について紹介しましたが、 spec-kit を始めこういったワークフローのためのフレームワークは積極的に開発されています。
「ちょっと試してみたけどうまく活用できないと諦めてしまった」ような人が少なくないと思っていますが、
こうした体系的なアプローチを取ることで VibeCoding による効率化の恩恵を最大限に受けることが出来るのではないでしょうか。
ぜひ、いろいろ調べてみて自分たちにあったワークフローを検討して試してみてはいかがでしょうか。
それでは。
Discussion