十数件のプロジェクトで半年以上Qoderを使い、仕事の進め方は、1行ずつコードを書くことから、方向性を定め、コンテキストを与え、結果を検証することへと根本的に変わりました。
「Qoderを半年以上使い、仕事の進め方は根本的に変わりました。1行ずつコードを書くのではなく、方向性を定め、コンテキストを与え、結果を検証するようになったのです。十数件のプロジェクトで失敗を重ね、その経験をチームの知見として蓄積した結果、新しい要件のたびに同じ失敗を繰り返すこともなくなり、今では返金機能を2分で実装できます。」—— Fuiou Pay シニアR&Dエンジニア 鄂建
私はFuiou PayのシニアR&Dエンジニア、鄂建です。十数件のプロジェクトでQoderを並行して使い、半年以上が経ちました。私の仕事の進め方は、1行ずつコードを書くことから、方向性を定め、コンテキストを与え、結果を検証することへと根本的に変わりました。
この変化は一日にして起きたわけではありません。多くのチームと同じように、私たちも「ツールを導入する → まずまず使えると感じる → 数多くの失敗を経験する → 方法論を見つける」という一連の過程をたどりました。ここでは、その道のりを段階ごとに紹介します。
これは、私たちが最初に見つけた鉄則です。当たり前に聞こえますが、多くのチームがつまずく原因はまさにここにあります。
「ここのコードに問題があるので直してください。」—— これは私が最もよく目にするプロンプトであり、最も役に立たない一文でもあります。隣の席の同僚にこう言っても、何をしてほしいのか分からないでしょう。AIならなおさらです。
正しい伝え方は、次のようなものです。
私は、複雑な要件を書くときには、チャットボックスへ直接入力しないようにしています。入力欄は狭く、100～200文字も書くと全体を見渡せなくなり、考えも途切れてしまうからです。
まずメモ帳を開き、プレースホルダーを使って要件を整理します。書き終えたら全体をQoderへ貼り付け、最後に関連ファイルを順番に@で指定します。構造化された入力は次のようになります。
これなら3行で済みます。200文字もの長文からAIに要点を推測させる必要はありません。
方針は明確です。まず骨格を与え、その後で詳細を補う。最初のやり取りでは目標と制約を示し、AIの出力を見てから必要な情報を追加すれば、通常は3回以内に収束します。Qoderの右下には「プロンプト強化」機能もあり、入力後にクリックすると、AIが表現の構造を改善してくれます。入力の品質が低ければ、出力の品質も上がりません。
探索型プロジェクトで私がよく使う方法があります。プロジェクトがすでに失敗したと仮定し、次の質問に答えさせるのです。最初に問題が起きたのはいつか。方向を誤らせた重要な判断は何か。本来もっと早く把握すべきだったのに見落としたリスクは何か。
さらに、「家庭菜園をしているおじいさんにも分かるように説明してください」と付け加えます。
AIはあなたの技術レベルを知りませんが、「家庭菜園をしているおじいさん」がどの程度の理解度かは分かります。そのため、専門用語でごまかさず、できるだけ分かりやすく説明します。
このプロンプトの本当の目的は、最終結果から逆算してリスクを早期に顕在化させることです。あるECプロジェクトでは、この方法によって高並行処理時の性能ボトルネックを事前に発見し、非同期キュー設計を導入できたため、リリース後の障害を回避できました。
初期に最も多く経験した失敗が「コンテキスト汚染」でした。典型的には次のように進みます。1回目にAIがNullPointerExceptionへの誤った修正案を出し、2回目もその案を前提に変更し、3回目にこちらが問題を指摘すると、4回目にはAIがまた最初の誤った仮定へ戻ってしまう。この繰り返しです。
そこで私たちは、同じ問題について3回やり取りしても収束しなければ、すぐに新しいウィンドウを開くという厳格なルールを設けました。それまでの会話を惜しまないことです。汚染されたコンテキストで何度も修正するより、クリーンなコンテキストから始める方が、コストははるかに低くなります。
同じ理由で、一度に7～8ファイルを@で指定してはいけません。1ファイルが600～1000行なら、7～8ファイルで1万行を超え、200Kのコンテキストはすぐに埋まります。圧縮が発生すると、AIは方向を見失います。会話ごとに必要なコンテキストだけを与え、無関係な話題を混ぜないことが重要です。
しばらく使ううちに、タスクに応じてモデルとモードを使い分けると、結果が大きく変わることが分かりました。
アーキテクチャ設計には最高性能モデル、バグ修正には高性能モデル、日常開発にはAutoを使用します。コーディングモードについては、Editor は自分で運転し、AIが道案内をする方式、Quest は目的地を伝え、AIが確認してから計画する方式、Experts は開発チームを雇うような方式です。
ただし、消費量の差は無視できません。QuestとExpertsの消費量はEditorのおよそ8倍です。日常的なコーディングですぐにExpertsを使うと、1～2日で2000 Creditsを使い切ることもあります。
基本を身につけると、ボトルネックが変わりました。「AIとどう会話するか」ではなく、「自分のプロジェクト環境でAIに自律的に作業させるにはどうするか」が課題になったのです。
MCP（Model Context Protocol）は、AIをローカルファイルの境界から解放する鍵です。MCPがなければ、AIが読めるのは@で指定したコードだけです。MCPがあれば、Web検索、データベース照会、ブラウザー操作、外部システムの呼び出しが可能になります。
ただし、設定では少ないほどよいという原則を守ります。MCPは8個以内に抑えてください。各MCPのツール説明はすべてコンテキストへ読み込まれるため、入れすぎると容量を圧迫します。実際の必要に応じて有効、無効を切り替えるだけで十分です。
以前はバグを調査するとき、テーブル構造を手作業でコピーしてAIへ貼り付け、AIの提案を受け取ってから、また手作業で調整していました。情報を往復させる作業だけで大半の時間を使っていました。
今では、IDEのチャットボックスからデータベース接続を直接@で指定します。AIはSchemaを読み取り、Entity、Repository、Controllerを生成し、フィールド名、型、制約も正しく対応させます。
さらに重要なのが、トラブルシューティングです。AIはコードロジックを読みながらデータベースを自動的に照会し、コードの問題なのかデータの問題なのかを直接判断します。人が仲介して情報を運ぶ必要はなく、AI自身が調査し、判断します。
従来の流れは、SSHでサーバーへログインし、ログを手作業で調べ、内容をコピーし、AIへ切り替えて問題を説明し、AIが推測した答えを受け取り、もう一度サーバーで検証するというものでした。小さな問題でも1～2時間かかります。
今ではAIがサーバーへ直接接続し、ログと設定をリアルタイムに読み取り、状況に応じた解決策を一度で提示します。
もちろん、安全原則は必ず守る必要があります。最小権限のアカウントを使用し、危険性の高いコマンドは手動で確認し、本番環境では慎重に使い、操作ログを完全に記録します。
私はHooksをJavaのアスペクトに例えています。前処理と後処理を追加する仕組みです。
なぜ必要なのでしょうか。私たちのチームでは実際に、プロンプトへ誤って
現在、私たちは十数件のプロジェクトでQoderを利用しており、ルール設定を特に重視しています。プロジェクトによって戦略は異なります。
新規プロジェクトでは共通のルールテンプレート（java.md、code.mdなど）をそのまま再利用します。既存プロジェクトではまずRepoWikiを生成し、既存コードのスタイルからAIにルール案をまとめさせ、人が確認して微調整します。複数のサブプロジェクトがある場合は、ルートディレクトリにAGENTS.mdを置いて案内図として使います。
設定原則はただ一つです。ルールが多すぎることは、ルールがないことと同じ。1ファイルは200行以内に抑え、まず重要なルールだけを追加し、会話のフィードバックに基づいて更新し、不要になったものは思い切って削除します。
メモリには、ユーザーの好み、技術スタック、命名スタイル、過去に得た教訓を記録できます。管理には遅延読み込みを採用し、必要なときだけ読み込ませ、毎回すべてを送らないようにします。グローバルメモリの件数を抑え、古い内容は定期的に整理します。
最大の価値は、知識が蓄積されることです。長く使うほどAIはプロジェクトを理解し、同じ間違いを繰り返す可能性が低くなります。
基本機能と環境設定が整うと、本当の意味で質的な変化が起きました。
私たちはOpenSpec（Spec-Driven Development）のワークフローを導入し、探索 → 提案と設計 → 実装 → アーカイブという4段階のサイクルを構築しました。Planモードより安定しており、提案はプロジェクトリポジトリへ永続化されるため、新しいウィンドウを開いても、翌日に再開しても失われません。
実際の例を紹介します。私は「注文の返金機能を開発してください」と入力しました。
探索段階では、AIがプロジェクト構造を自動的に検索し、既存のテーブルとAPIを調査して、現在の業務状況を整理します。確認段階では、どのような返金なのか、誰が返金できるのか、いつ返金できるのか、承認が必要か、とAIが自発的に質問します。提案段階では、変更提案書、設計書、開発タスク書の3つを出力し、すべてフィールド単位まで具体化します。実行段階では、23個の細かなタスクに分解し、約2分で返金Entity、Mapper、DTO、5つのAPI、1つの新規テーブルを生成し、24ファイルを変更します。アーカイブ段階では、内容に問題がないことを確認してアーカイブします。次回新しいウィンドウを開くと、AIは未アーカイブのタスクを自動的に確認して作業を続けます。
タスク分解がこれほど重要なのはそのためです。大まかな方向性では問題が起きやすくても、フィールド単位まで分解すれば、AIは正確に実行できます。
半年以上使った結果、私たちは直感に反する法則を見つけました。コンテキストを簡潔にするほどCreditsの消費は少なくなり、AIの出力はむしろ正確になるということです。
実践では、いくつかの重要な対策を取っています。AGENTS.mdは100行以内にします。長すぎるとAIはかえって従わなくなります。ルールは
半年を振り返って最も強く感じるのは、プログラマーの役割が根本的に変わりつつあるということです。
私たちはもはや「コードを書く人」ではなく、「方向性を定め、品質を管理し、判断する人」です。AIは作業を速くし、人の思考は作業を正しくします。
AI Codingを使い始めるチームに助言するなら、最初から複雑な設定を導入せず、まずコンテキスト管理を徹底的に練習してください。新しいウィンドウを開くコストを惜しまないこと。ルールは少数精鋭にして、増やしすぎないこと。まとめてコミットするのではなく、こまめにコミットすること。書き終えたらすぐに検証し、問題がなければそのままGitへコミットします。
ツールは今後ますます強力になりますが、ツールを使いこなすための方法論が古くなることはありません。
本記事は、Fuiou PayのシニアR&Dエンジニア鄂建によるオンライン講演「Qoder AI ベストプラクティス共有」の内容をもとに作成しています。
最初に得た認識：AIの出力品質は、与えるコンテキストの品質で決まる
これは、私たちが最初に見つけた鉄則です。当たり前に聞こえますが、多くのチームがつまずく原因はまさにここにあります。
「ここのコードに問題があるので直してください。」—— これは私が最もよく目にするプロンプトであり、最も役に立たない一文でもあります。隣の席の同僚にこう言っても、何をしてほしいのか分からないでしょう。AIならなおさらです。
正しい伝え方は、次のようなものです。@OrderService.java の156行目でNullPointerExceptionが発生し、注文ステータスが空の場合に再現する。具体的な位置、現象、関連ファイルのいずれも欠かせません。
この考え方自体は単純ですが、チームの習慣として定着させるまでには相当な時間がかかりました。
第1段階：基本を徹底的に身につける
「思いつくまま入力」から「構造化された入力」へ
私は、複雑な要件を書くときには、チャットボックスへ直接入力しないようにしています。入力欄は狭く、100～200文字も書くと全体を見渡せなくなり、考えも途切れてしまうからです。
まずメモ帳を開き、プレースホルダーを使って要件を整理します。書き終えたら全体をQoderへ貼り付け、最後に関連ファイルを順番に@で指定します。構造化された入力は次のようになります。
AIに「事後検証」させるプロンプトのコツ
探索型プロジェクトで私がよく使う方法があります。プロジェクトがすでに失敗したと仮定し、次の質問に答えさせるのです。最初に問題が起きたのはいつか。方向を誤らせた重要な判断は何か。本来もっと早く把握すべきだったのに見落としたリスクは何か。
さらに、「家庭菜園をしているおじいさんにも分かるように説明してください」と付け加えます。
コンテキスト汚染：私たちが払った授業料
初期に最も多く経験した失敗が「コンテキスト汚染」でした。典型的には次のように進みます。1回目にAIがNullPointerExceptionへの誤った修正案を出し、2回目もその案を前提に変更し、3回目にこちらが問題を指摘すると、4回目にはAIがまた最初の誤った仮定へ戻ってしまう。この繰り返しです。
そこで私たちは、同じ問題について3回やり取りしても収束しなければ、すぐに新しいウィンドウを開くという厳格なルールを設けました。それまでの会話を惜しまないことです。汚染されたコンテキストで何度も修正するより、クリーンなコンテキストから始める方が、コストははるかに低くなります。
同じ理由で、一度に7～8ファイルを@で指定してはいけません。1ファイルが600～1000行なら、7～8ファイルで1万行を超え、200Kのコンテキストはすぐに埋まります。圧縮が発生すると、AIは方向を見失います。会話ごとに必要なコンテキストだけを与え、無関係な話題を混ぜないことが重要です。
モデルとモード：高性能であればよいとは限らない
しばらく使ううちに、タスクに応じてモデルとモードを使い分けると、結果が大きく変わることが分かりました。
アーキテクチャ設計には最高性能モデル、バグ修正には高性能モデル、日常開発にはAutoを使用します。コーディングモードについては、Editor は自分で運転し、AIが道案内をする方式、Quest は目的地を伝え、AIが確認してから計画する方式、Experts は開発チームを雇うような方式です。
ただし、消費量の差は無視できません。QuestとExpertsの消費量はEditorのおよそ8倍です。日常的なコーディングですぐにExpertsを使うと、1～2日で2000 Creditsを使い切ることもあります。
第2段階：「使える」から「環境を整える」へ
AIに外部能力を持たせる：MCP
MCP（Model Context Protocol）は、AIをローカルファイルの境界から解放する鍵です。MCPがなければ、AIが読めるのは@で指定したコードだけです。MCPがあれば、Web検索、データベース照会、ブラウザー操作、外部システムの呼び出しが可能になります。
ただし、設定では少ないほどよいという原則を守ります。MCPは8個以内に抑えてください。各MCPのツール説明はすべてコンテキストへ読み込まれるため、入れすぎると容量を圧迫します。実際の必要に応じて有効、無効を切り替えるだけで十分です。
データベースへ直接接続：AI自身が調べ、検証する
以前はバグを調査するとき、テーブル構造を手作業でコピーしてAIへ貼り付け、AIの提案を受け取ってから、また手作業で調整していました。情報を往復させる作業だけで大半の時間を使っていました。
今では、IDEのチャットボックスからデータベース接続を直接@で指定します。AIはSchemaを読み取り、Entity、Repository、Controllerを生成し、フィールド名、型、制約も正しく対応させます。
SSHによるリモート調査：往復作業から一度で解決へ
従来の流れは、SSHでサーバーへログインし、ログを手作業で調べ、内容をコピーし、AIへ切り替えて問題を説明し、AIが推測した答えを受け取り、もう一度サーバーで検証するというものでした。小さな問題でも1～2時間かかります。
今ではAIがサーバーへ直接接続し、ログと設定をリアルタイムに読み取り、状況に応じた解決策を一度で提示します。
Hooks：横断的な仕組みでAIを制御する
私はHooksをJavaのアスペクトに例えています。前処理と後処理を追加する仕組みです。
なぜ必要なのでしょうか。私たちのチームでは実際に、プロンプトへ誤って access_key=AKIA... を貼り付け、そのままモデルへ送信してしまったことがあります。AIが rm -rf /data/ を実行しようとした際に確認を押してしまい、数GBのデータを失ったこともあります。また、AIが「完了しました」と言ったのに、テストを実行するとコンパイルエラーだらけだったこともあります。
Hooksは、送信前に機密情報を遮断する、実行後に自動でコンパイルを検証する、応答完了後に変更内容を外部システムへ蓄積する、という3つの問題を解決します。設定をGitへコミットすれば、チーム全体で同じセーフティネットを共有できます。
ルール設定：十数件のプロジェクトから得た実践知
現在、私たちは十数件のプロジェクトでQoderを利用しており、ルール設定を特に重視しています。プロジェクトによって戦略は異なります。
新規プロジェクトでは共通のルールテンプレート（java.md、code.mdなど）をそのまま再利用します。既存プロジェクトではまずRepoWikiを生成し、既存コードのスタイルからAIにルール案をまとめさせ、人が確認して微調整します。複数のサブプロジェクトがある場合は、ルートディレクトリにAGENTS.mdを置いて案内図として使います。
設定原則はただ一つです。ルールが多すぎることは、ルールがないことと同じ。1ファイルは200行以内に抑え、まず重要なルールだけを追加し、会話のフィードバックに基づいて更新し、不要になったものは思い切って削除します。
メモリシステム：使うほどAIが理解を深める
メモリには、ユーザーの好み、技術スタック、命名スタイル、過去に得た教訓を記録できます。管理には遅延読み込みを採用し、必要なときだけ読み込ませ、毎回すべてを送らないようにします。グローバルメモリの件数を抑え、古い内容は定期的に整理します。
最大の価値は、知識が蓄積されることです。長く使うほどAIはプロジェクトを理解し、同じ間違いを繰り返す可能性が低くなります。
第3段階：返金機能を2分で実装する
基本機能と環境設定が整うと、本当の意味で質的な変化が起きました。
私たちはOpenSpec（Spec-Driven Development）のワークフローを導入し、探索 → 提案と設計 → 実装 → アーカイブという4段階のサイクルを構築しました。Planモードより安定しており、提案はプロジェクトリポジトリへ永続化されるため、新しいウィンドウを開いても、翌日に再開しても失われません。
実際の例を紹介します。私は「注文の返金機能を開発してください」と入力しました。
探索段階では、AIがプロジェクト構造を自動的に検索し、既存のテーブルとAPIを調査して、現在の業務状況を整理します。確認段階では、どのような返金なのか、誰が返金できるのか、いつ返金できるのか、承認が必要か、とAIが自発的に質問します。提案段階では、変更提案書、設計書、開発タスク書の3つを出力し、すべてフィールド単位まで具体化します。実行段階では、23個の細かなタスクに分解し、約2分で返金Entity、Mapper、DTO、5つのAPI、1つの新規テーブルを生成し、24ファイルを変更します。アーカイブ段階では、内容に問題がないことを確認してアーカイブします。次回新しいウィンドウを開くと、AIは未アーカイブのタスクを自動的に確認して作業を続けます。
タスク分解がこれほど重要なのはそのためです。大まかな方向性では問題が起きやすくても、フィールド単位まで分解すれば、AIは正確に実行できます。
Creditsを節約するための基本原則
.qoder/rules に分類して置き、常時適用せず必要に応じて読み込みます。生成したRepoWikiは必ず人が整理し、使わないデプロイ方式などを削除します。.qoderignore でビルド成果物を除外します。AIの要約は100文字以内にするよう指示します。長い言い換えは読まないからです。
見落とされがちな点もあります。コーディング以外の質問には、無料かつ回数制限がなく、場合によってはより速い大規模言語モデルの公式サイトを活用します。Creditsは、プロジェクトのコンテキストを本当に必要とするコーディング作業に残しておきます。