Open7

もうデバッグしたくない。非エンジニアがClaude Codeを調教してVibeCodingしやすくするまで。

非エンジニア
Claude Code
Vibe Coding
miyaponmiyapon

背景

  • 「VibeCodingやってみた！でも本格的なサービス作るのは難しい...」という壁をクリアするため、自分がハマっていった問題解決のための初期設定をまとめます。
  • Claude Code 自体が日々進化するので、このスクラップは更新し続けるけど追いつかないと思う。
  • 先駆者たるエンジニアのみなさんスゴすぎ...。ついていきます。

自己紹介

ITベンチャーに生息する越境デザイナーでした。
https://note.com/miyaponm/n/n5b5c29fb1354

miyaponmiyapon

MastraとSerenaについてo3 DeepResearchした。

以下本文。

Claude Code (v1.0.70) が Mastra Workflow を正しく利用できるよう、以下の観点から調査を開始します：

結果をまとめてお届けしますので、少々お待ちください。

Claude CodeがMastra Workflowを上手く扱うための改善提案

現状の課題と原因

Claude CodeでMastra Workflowを実装する際に、現在いくつかの問題が起きています。主な課題は以下の二点です:

  • APIバージョンの混乱: Claude CodeがMastraの古いAPI（getStepResultなど）と新しいAPI（resultsオブジェクト利用）の区別に失敗し、誤ったメソッドを使用しようとしています。これにより「どれが最新のAPIなのか混乱している」状態になり、コード生成時に不正確な参照が含まれてしまいます。
  • データ受け渡しとワークフロー分割の不備: 複数ステップに分けて実装すべきロジックを、一つの大きなステップに統合してしまうケースが見られます。これは、ステップ間のデータ受け渡しに失敗したClaude Codeが「データ渡しの問題を回避するために一つにまとめよう」と判断してしまった結果です。Mastra Workflowの利点である順次ステップ実行やデータマッピングが活かされておらず、ワークフロー分割の意味が失われています。

上記の問題は、適切なドキュメント参照と最新API仕様の理解不足、さらにコンテキストメモリの制約が原因と考えられます。以下では、それらを解決するための具体的な提案を示します。

必要なドキュメントだけを動的に参照する

Mastraの公式ドキュメントをClaude Codeに参照させる際、一度に大量の文章をコンテキスト投入しないことが重要です。ドキュメント全体を一括で読み込ませようとすると、モデルのメモリ（トークン）を圧迫し「メモリがパンク」する原因になります。そこで、以下のようなアプローチで必要最小限の情報をその都度与えるようにしましょう:

  • MCPドキュメントサーバーの活用: Mastraが提供するMCP Docsサーバー（@mastra/mcp-docs-server）を有効化し、Claude Codeエージェントが必要に応じて公式ドキュメントを検索・取得できるようにします。CursorやVSCodeでMCPサーバーを有効化すると、エージェントは「mastraDocs」等のツール経由でMastraの完全なドキュメントにアクセスできます。この方法なら、エージェント自身が特定のトピックに関するドキュメントを呼び出せるため、最初から全ドキュメントをコンテキストに載せる必要がありません。
  • キーワードフックによる自動コンテキスト: エージェントが自発的にツールを使わない場合、「Mastra」等のキーワードに反応してドキュメントを提示する仕組みを導入します。具体的には、Input Processor（入力処理フィルター）やフックを用いてユーザープロンプトやClaudeの発話を監視し、MastraのAPI名や重要キーワードが出現したら、その該当セクションをドキュメントサーバーから取得してエージェントに追加情報として与えます。例えば「resultsオブジェクトの形式を確認する必要があります」という出力があれば、直ちに「ワークフローの結果スキーマ」に関するドキュメント部分を提供する、といった動的コンテキスト供給が可能です。こうした必要箇所だけの参照により、大量の不要なテキストでメモリを浪費することを防げます。
  • 段階的な読み込み: 一度に長大な説明文を与える代わりに、対話的に段階を追って情報提供する手も有効です。まず「どの部分の情報が必要か」をClaudeに考えさせ（またはユーザーが指定し）、その部分に限ってドキュメントを取り寄せる方法です。これにより、より短いスニペット単位での読み込みとなり、モデルの保持すべき文脈を縮小できます。結果としてメモリ負荷が軽減し、レスポンスの安定性が向上します。実際、Serena（後述）のアプローチでもプロジェクト全体を最初から丸ごと読ませるのではなく、索引化と検索によってピンポイントに必要情報へアクセスすることでトークン消費問題を解決しています。

以上のように、「必要な時に、必要な情報だけを取り出す」流れを徹底することで、Context7経由で無理に全ドキュメントを詰め込もうとしていた状況を改善できます。MastraのMCPドキュメントツールはガイドやリファレンス、ブログ記事等も検索可能なので、Claude Codeに常に最新かつ正確な知識を与えられるでしょう。

Mastra Workflow最新APIに沿ったコーディング

Claude CodeにMastra Workflowを正しく使わせるには、最新版のAPI設計に基づくコードを書くよう誘導することが肝要です。具体的には以下のポイントを検討してください:

  • プロンプトでバージョン明示: Claude Codeのシステムプロンプトやユーザープロンプト内で「使用しているMastraのバージョンはv0.10以上（ワークフロー機能はvNext）」等と明示し、旧APIではなく新APIを使うよう指示します。Mastra v0.10.8以降ではワークフロー機能がvNextとして刷新されているため、Claudeにもその前提で考えさせる必要があります。例えば「getStepResultはレガシーである」「resultsオブジェクトやワークフロー変数によるデータ受け渡しを使う」といったヒントを与えると良いでしょう。
  • データマッピング機能の活用: Mastra Workflowではステップ間のデータ受け渡し方法が複数提供されています。コンテキストオブジェクト（context.inputDataやcontext.getStepResult）で直接前ステップの結果にアクセスする方法、ワークフロー変数によるマッピングで明示的に出力を次の入力に渡す方法、そして**getStepResult関数を使う方法です。新しいAPIでは、可能な限りワークフロー変数や.then()チェーンによる暗黙的な受け渡しを活用し、getStepResultに過度に依存しない実装が推奨されます。実際、公式のベストプラクティスではgetStepResultを多用するとステップ間の依存が強まり再利用性や保守性が低下しうると指摘されています。Claude Codeにも各ステップのinputSchemaとoutputSchemaを正しく定義させ、必要なデータはワークフロー定義時にマッピングする設計を促しましょう。これにより、「前ステップのデータを取得できない」といった混乱を防ぎ、自然とステップ分割された保守的な構造**のコードが生成されるようになります。
  • 誤った関数使用の検出と修正: Claudeが古いAPIを提案してきた場合（例えばcontext.getStepResultやLegacyStep/LegacyWorkflowクラスの使用）、直ちにフィードバックを与えて修正させます。「Mastra vNextではその関数は使いません。代わりにresultsオブジェクト経由でデータ参照してください」等と指摘し、再度ドキュメントを引かせるのも有効です。Mastra公式ドキュメント内の該当箇所（例: ワークフロー結果スキーマやresultsオブジェクトの構造説明）をClaudeに読ませ、正しいAPIの使い方を根拠付きで示すと効果的です。このように都度修正を繰り返すことで、Claude自身が新APIのパターンを学習し、以降の提案精度も向上していきます。

以上を徹底することで、Claude CodeがMastra Workflowの最新仕様に則ったコードを生成しやすくなります。ポイントは「古い情報を与えない・使わせない」ことと、「新APIの用法を常に参照させる」ことです。

Serenaツールの併用による性能向上

ご指摘のあった「Serena」というツールは、近頃話題のClaude Code用MCP拡張です。Serenaを導入することでClaude Codeのプロジェクト把握能力やコンテキスト管理が飛躍的に向上すると言われています。実際、ネット上では「Claude Codeが10倍便利になる無料ツール」として紹介されており、開発者コミュニティでも注目を集めています。Serena活用による主なメリットは次の通りです:

  • プロジェクト全体のインデックス化: Serenaは最初にプロジェクト全体のコードベースをスキャンして索引ファイルを作成します。これによりClaude Codeはプロジェクト内のあらゆるファイルやシンボルを把握でき、必要な箇所を瞬時に検索できるようになります。大規模プロジェクトでも、エージェントが目的の関数や定義箇所をピンポイントで見つけ出せるため、広範なコード読み込みによるトークン消費を劇的に削減できます。
  • LSPによるセマンティック検索: Serenaは内部でLanguage Server Protocol (LSP) を用いてコードの構造と意味を理解します。その結果、Claude Codeは単純なキーワードマッチではなくコードの文脈・意味に基づいた検索（セマンティック検索）が可能になります。例えば「特定のクラスを継承している全サブクラスを探す」「あるAPI呼び出し箇所をすべて列挙する」といった高度な検索も、Serena経由なら精度高く行えます。これはMastraのドキュメント参照にも応用可能で、コード内コメントや型定義から推測して関連するAPIリファレンスを引くといったことも期待できます。
  • トークン最適化と文脈保持: 上記の通り必要な情報のみを取得する仕組みのため、Claudeのワーキングメモリを有効活用できます。大量のコードやドキュメントをそのままコンテキスト投入する従来手法に比べ、Serenaはエージェントが欲しい回答に必要な断片だけを提供するため無駄がありません。結果としてメモリ上限による破綻を防ぎつつ、より長時間安定したセッションを維持できます。また、コード検索ツールとしてプロジェクト理解が深まることで、Claude自身が過去の指示を「忘れる」問題の緩和や一貫したスタイルでのコード修正を行いやすくなる副次効果も報告されています。

Serenaの導入は、Claude CodeがMastra Workflowを含む複雑なコードを自律的かつ正確に操作できるようにする強力なサポートとなるでしょう。具体的に導入するには、GitHub上のSerena公式リポジトリからMCPサーバーを入手し、自身のIDE（CursorやVSCode等）でMCP設定に組み込む必要があります。Claude CodeのカスタムコンテキストでSerena用ツールを有効化する際には、例えばswitch_modesなど一部ツールがデフォルト無効になっている点に留意し、included_optional_tools設定で有効化するなどの手順が必要です。多少セットアップに手間はかかりますが、その効果は大きく、Mastraドキュメント参照と組み合わせることで**「必要な知識を必要な瞬間に引き出す」開発スタイル**が実現できるでしょう。

結論: ベストプラクティスの組み合わせで改善

以上の提案を組み合わせることで、Claude CodeがMastra Workflowを正しく使いこなし、かつメモリ制限内で効率良く動作するようになると期待できます。

  1. ドキュメントは小出しにする: MCPドキュメントツールやフックを活用し、Mastraの公式情報を必要に応じて参照させます。大量のテキストを一括投入せず、モデルの質問に応じて関連部分のみを提示することで、高負荷による失敗を防ぎます。
  2. 最新APIに誘導する: プロンプト設計と対話を通じて、Claudeに常に最新のMastra Workflow API（vNext）の文法・機能を使わせます。レガシーな記述が出たら都度修正させ、正しい実装例やリファレンスを参照して改善します。
  3. 高度なツールの活用: 可能であればSerena MCPサーバーを導入し、プロジェクト全体の知識をClaudeが自在に検索できる環境を整えます。これによりコード理解力とコンテキスト管理能力が飛躍的に向上し、結果としてMastra Workflowのような外部ライブラリ利用時の精度も上がります。

これらの施策により、Claude CodeはMastra Workflowのドキュメントに忠実でミスの少ない実装を行えるようになり、メモリ制限によるセッション切断や誤回答も大幅に減るでしょう。特にMastraのように機能拡張が活発なフレームワークでは、ドキュメントとの同期が欠かせません。最新情報を効率よく参照させつつ、人間エンジニアのような文脈理解を補うツール（Serena等）を組み合わせることで、Claude Codeをより信頼できるペアプログラマーとして活用できるはずです。ぜひ一度これらのアプローチを試し、Claude Codeの出力品質向上を実感してみてください。

Mastra MCP, Serena MCP 利用方法

Claude Code で Mastra MCP（公式ドキュメント検索） と Serena MCP（コード検索＆編集強化） を使うための、いちばん実用的な手順をまとめます。全部ターミナルから数行で有効化できます。

前提

  • Claude Code v1.0.70（Sonnet 4.0）
  • macOS 前提で記載（Windows は cmd /c ラッパーが必要な場合あり）。(Anthropic)

1) Mastra MCP（@mastra/mcp-docs-server）をつなぐ

Mastra 公式が配布している MCP サーバーです。Mastra の Docs/リファレンス/ブログ/Changelog を LLM から検索して取りに行けるようになります。大量に貼る必要がなく、必要な節だけを随時読ませられます。(Mastra)

インストール（Claude Code 側）

# プロジェクトスコープに追加（チーム共有したい場合に便利）
claude mcp add --scope project mastra-docs -- npx -y @mastra/mcp-docs-server
  • npx -y @mastra/mcp-docs-server が ローカル stdio モードで MCP サーバーを起動するコマンド。(Mastra)
  • --scope は local / project / user の 3 種。用途で決めてOK。(Anthropic)

動作確認

claude mcp list

Claude Code のチャット内で /mcp と打つとサーバーの状態や認可を確認できます。(Anthropic)

使い方のコツ

  • チャット本文で @mastra-docs のリソース補完を使って、関連ドキュメントをピン留めする（@入力で出る候補にMCPのリソースが混ざります）。(Anthropic)
  • あるいは「このコードの results オブジェクトの正しいスキーマを @mastra-docs から引いて」と依頼して、必要部分だけ添付させる。メモリ圧迫を避けられます。(Mastra)

補足（Cursor/Windsurf を使う場合）
.cursor/mcp.json を置いて IDE 側から有効化 → 設定で「Mastra MCP を Enable」でもOK。(Mastra, MagicSlides)

2) Serena MCP をつなぐ（コード理解と編集の「筋力」をブースト）

Serena は セマンティック検索 + LSP 連携で、巨大リポジトリでも必要なシンボルや参照元を素早く特定し、安全確認付きで編集まで進められる MCP サーバーです。Claude Code の探索→編集→検証の一連が安定します。(GitHub)

インストール（Claude Code 側）

一番ラクなのは uvx でそのまま実行する方法：

# Serena MCP を stdio で起動するコマンドを、Claude Code に登録
claude mcp add --scope user serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server
  • uvx 方式は ローカルインストール不要で最新を起動できます（uv は別途インストール）。(GitHub)
  • もちろん git clone + uv run serena start-mcp-server でもOK。(GitHub)

便利ポイント

  • 初回ヘルプの読み込み：Claude が自動で Serena の初期説明を読むはずですが、読めてない時はチャットで
    /mcp__serena__initial_instructions を実行。(GitHub)
  • 巨大コードでもブレにくい：LSP によるシンボル理解と関係追跡で、関数や型の正しい定義源を当てやすく、トークン消費も節約。(GitHub, Playbooks)

3) Claude Code での共通 Tips（MCP 全般）

  • 追加/管理コマンド（公式）

    • 追加（stdio）：claude mcp add <name> -- <command> ...
    • 一覧：claude mcp list / 取得：claude mcp get <name> / 削除：claude mcp remove <name>
    • スコープ：--scope local|project|user
    • チャット内ヘルプ：/mcp（認証・状態チェック）
      参考：Anthropic 公式「Connect Claude Code to tools via MCP」(Anthropic)

  • @リソース参照：@server:protocol://path 形式で必要ドキュメントだけを添付。一括投入を避ける。(Anthropic)

4) あなたの「Mastra × Claude Code」課題に効く運用レシピ

  1. Mastra ドキュメントは常に MCP で“点滴投与”

    • まず Mastra MCP を有効化。疑問が出た瞬間に @mastra-docs で該当節だけを添付させる（results スキーマ、Workflow 入出力、Legacy API との違い等）。“全部貼る”は禁止。(Mastra)

  2. コード理解は Serena に丸投げ

    • 「このワークフローの各ステップで受け渡している値の実体を洗い出して」と頼むと、Serena のセマンティック参照探索で定義→使用箇所が出てきます。受け渡しの誤解で“単一巨大ステップ化”する悪手を防げます。(GitHub)

  3. 古い Mastra API を見つけたら即・是正

    • Claude が getStepResult などレガシーAPIを口走ったら、@mastra-docs で 最新のワークフロー API 節を添付し、「results オブジェクト/ワークフロー変数マッピングで実装して」と明示。(Mastra)

5) よくあるトラブルと対処

  • Windows で stdio サーバーが落ちる
    → claude mcp add … -- cmd /c npx -y @mastra/mcp-docs-server のように cmd /c を挟む。(Anthropic)

  • Serena が指示文を読んでくれない
    → /mcp__serena__initial_instructions を手動実行する。(GitHub)

  • プロジェクト横断で使いたい
    → --scope user で登録しておく（どのリポでも即使える）。(Anthropic)

必要なら、あなたの環境に合わせて 一発セットアップ用のスクリプト（Mastra/Serena をまとめて user スコープ登録 + 動作テスト）も作ります。声かけてください。

miyaponmiyapon

非エンジニアがプロジェクト初回でKiro的なアプローチをするのは時間泥棒かも

Kiro的なアプローチを雑にいうと、LLMがステップ踏んで設計を支援してくれること。
でも初回のプロジェクト立ち上げには向いてないかも。

なぜなら、それっぽい初期設計ができてしまって、レビューするのにコストがかかるため。
特に非エンジニアとして自分は辛かった。

頑張ってレビューして問題なく動作するならいいけど、動作するアウトプットができるまで1週間くらい粘り続ける必要がある。しんどい。

そもそも画面で動作確認して改善点に気付くという開発スタイルを、僕が脱却できないのが原因でもある。でもそれって普通じゃないの？デザイナーだからなのかな。

機能追加でスコープ狭めて、プロンプトを頑張れば、Kiro良いのかも。これはまだ試してない。