Qoder の Repo Wiki と Skills を使用し、変更が怖かったレガシープロジェクトを自己改善できる状態へ変えた方法を紹介します。
こんにちは。バックエンド開発エンジニアの Yue Yangbo です。今回は「レガシープロジェクトで Vibe Coding をどう実践するか」を一緒に考えます。
Qoder の Repo Wiki は、プロジェクトのアーキテクチャをすばやく理解し、呼び出し関係を整理し、詳細なドキュメントを生成するのに役立ちます。新しいメンバーのオンボーディングにも利用できます。
以前は、先輩がプロジェクト全体を説明し、新しいメンバーがコードと資料を読み、その後も何度も質問と確認を繰り返す必要がありました。Repo Wiki 導入後、新しいメンバーはまず Ask モードで「プロジェクトに質問」します。およそ80%の疑問はそこで解決し、人に相談するときには残り20%の重要で具体的な質問に集中できます。学習経路は「人が人を教える」から「まず自助、その後に深い議論」へ変わりました。
プロジェクトを理解できても、それだけでコードを正しく書けるわけではありません。当初、私は AI に機能の実装を直接依頼しました。AI は大量のコードをすばやく出力しましたが、実行すると多くのバグとずれが見つかりました。説明と修正を繰り返すほど、コードは乱れ、ロジックを制御できなくなり、最後には「もう変更するのが怖い」状態になりました。
AI を新入社員の同僚として考えると、曖昧で断片的で、何度も変わる説明だけで良い仕事ができるでしょうか。問題は AI だけでなく、私たちが与える情報が明確で具体的、実行可能かどうかにもあります。そこから新しい試行を始めました。
単に「何を作るか」ではなく、背景と制約をできる限り具体的に説明しました。巨大な機能を一度に渡すと、AI の理解は私たちの期待から外れやすくなります。そこで、「発注書にフィールドを追加する」「簡単な計算ユーティリティを作る」といった小さなタスクから始めました。
これはタスクを終えるだけでなく、AI とのコミュニケーション方法を作る過程です。小さく具体的な機能を通じて、私は AI の「習慣」を理解し、AI も私の表現方法に適応しました。要件を細かく分解するほど、コミュニケーションと結果を制御しやすくなります。
AI に実装案を示したところ、盲目的に従うのではなく、「この方法は最適ではないかもしれない」と別の案を提示したことがありました。そこで「仕事をさせる」よりも「先に合意する」ことが重要だと気づきました。
コードを直接書かせる前に、要件と設計案を説明し、「この設計は妥当か」と質問します。AI は思考と背景を理解し、見落とした詳細や選択肢を補えます。質問で合意してから実装へ進むよう、ワークフローを変えました。
同じ会話に要件を積み重ね続けると、AI の理解がずれやすくなります。コンテキストが非常に長くなると、情報が混ざり、重要点が薄まり、判断力が低下します。
実践では、コンテキストを比較的制御可能な範囲、およそ20～30%に保つと結果が安定しました。要件が多く複雑な場合は、大きな要件を小さく分け、別の会話で処理します。各ステップの結果も明確になります。
一度、説明が不明確だったために、AI がすでに調整済みのコードを誤って変更し、ほぼ1日分の成果を失いました。コードが利用可能になりレビューを通過したら、すぐにコミットすべきです。後の変更で問題が起きても安定版へすばやく戻れます。
基本的な開発はできるようになりましたが、生成コードがチームのスタイルや業務規約に合わない問題が残りました。そこで Skills を使いました。私はこの仕組みを「Skill Universe」と呼んでいます。AI は単なる補助ツールではなく、要件だけでなく習慣、規約、標準を再利用する自分の分身になります。
コードスタイル、共通ロジック、業務制約を Skills として蓄積すると、毎回ゼロから調整しなくても、AI が自然に私たちの方法に沿ったコードを生成します。
Ask モードで要件を説明し、既存の設計方法、コードスタイル、ルールを Qoder に伝えて Skill を生成できます。結果が期待と異なる場合は、会話で修正し続けるのではなく、Skill ファイルの説明とルールを更新します。これは一度で完成する作業ではなく、継続的な最適化です。
例えば、業務開発では統一された例外処理ユーティリティや、特定のクエリ構築方法があります。制約がなければ、AI は動作しても規約に合わないコードを生成します。そこで「Query Skill」と「Exception Skill」を作成しました。Spring Boot の実験では、Skills なしの場合、AI は JPA の native SQL を使い、独自の Error メソッドを使用しませんでした。Skills を読み込むと、動的クエリと例外処理の両方で自社のユーティリティが自動的に使われました。
安定したワークフローは次のとおりです。
要件分解 → Ask モードで合意 → Agent モードでコード変更 → コードレビュー → すぐにコミット
結果が良ければ、有効な方法を個人の知識ベースに整理して再利用します。結果が良くなければ、根本原因を分析します。モデル能力の限界のように制御できない要因ならモデルやツールを変えます。プロンプトの曖昧さ、業務ロジックの欠陥、コード構造、Ask と Agent の使い分けのように制御できる要因なら、自分の方法を改善します。
答えは「そうとは限らない」です。コードは仕事の一部にすぎません。Qoder はスクリプト、記事の推敲、動画シナリオのブレインストーミングにも利用できます。
私は Qoder に自身を「定義」させる試みも行いました。歌詞を書き、名前を考え、サイバーパンク風のキャラクターを設計し、MV の絵コンテ用プロンプトまで作らせました。最終的に、Qoder の「頭脳」が導く完全な MV「I Am Qoder」を完成させました。
最後に伝えたいのは、まず使い始め、そこから少しずつ強くなっていこう、ということです。
エンタープライズソリューションの詳細はこちら ➔
01 レガシープロジェクトの課題と突破口
- 巨大なコードベース：レガシープロジェクトには、数万、数十万、場合によっては数百万行のコードがあります。
- 複雑な歴史的ロジック：長い運用期間中に、担当者の交代と要件変更が何度も発生しています。
- 理解コストが非常に高い：新しいメンバーがプロジェクトを理解し、改善できるようになるまで、数日から数週間かかります。
Repo Wiki：AI を指導役の「先輩」にする
Qoder の Repo Wiki は、プロジェクトのアーキテクチャをすばやく理解し、呼び出し関係を整理し、詳細なドキュメントを生成するのに役立ちます。新しいメンバーのオンボーディングにも利用できます。
02 失敗と試行錯誤
プロジェクトを理解できても、それだけでコードを正しく書けるわけではありません。当初、私は AI に機能の実装を直接依頼しました。AI は大量のコードをすばやく出力しましたが、実行すると多くのバグとずれが見つかりました。説明と修正を繰り返すほど、コードは乱れ、ロジックを制御できなくなり、最後には「もう変更するのが怖い」状態になりました。
AI を新入社員の同僚として考えると、曖昧で断片的で、何度も変わる説明だけで良い仕事ができるでしょうか。問題は AI だけでなく、私たちが与える情報が明確で具体的、実行可能かどうかにもあります。そこから新しい試行を始めました。
試行1：要件を具体化する
単に「何を作るか」ではなく、背景と制約をできる限り具体的に説明しました。巨大な機能を一度に渡すと、AI の理解は私たちの期待から外れやすくなります。そこで、「発注書にフィールドを追加する」「簡単な計算ユーティリティを作る」といった小さなタスクから始めました。
これはタスクを終えるだけでなく、AI とのコミュニケーション方法を作る過程です。小さく具体的な機能を通じて、私は AI の「習慣」を理解し、AI も私の表現方法に適応しました。要件を細かく分解するほど、コミュニケーションと結果を制御しやすくなります。
試行2：先に質問し、合意してから書く
AI に実装案を示したところ、盲目的に従うのではなく、「この方法は最適ではないかもしれない」と別の案を提示したことがありました。そこで「仕事をさせる」よりも「先に合意する」ことが重要だと気づきました。
コードを直接書かせる前に、要件と設計案を説明し、「この設計は妥当か」と質問します。AI は思考と背景を理解し、見落とした詳細や選択肢を補えます。質問で合意してから実装へ進むよう、ワークフローを変えました。
試行3：コンテキスト長を制御する
同じ会話に要件を積み重ね続けると、AI の理解がずれやすくなります。コンテキストが非常に長くなると、情報が混ざり、重要点が薄まり、判断力が低下します。
実践では、コンテキストを比較的制御可能な範囲、およそ20～30%に保つと結果が安定しました。要件が多く複雑な場合は、大きな要件を小さく分け、別の会話で処理します。各ステップの結果も明確になります。
試行4：最小コミットの原則
一度、説明が不明確だったために、AI がすでに調整済みのコードを誤って変更し、ほぼ1日分の成果を失いました。コードが利用可能になりレビューを通過したら、すぐにコミットすべきです。後の変更で問題が起きても安定版へすばやく戻れます。
03 Skill Universe：AI に自分の「習慣」を再利用させる
基本的な開発はできるようになりましたが、生成コードがチームのスタイルや業務規約に合わない問題が残りました。そこで Skills を使いました。私はこの仕組みを「Skill Universe」と呼んでいます。AI は単なる補助ツールではなく、要件だけでなく習慣、規約、標準を再利用する自分の分身になります。
コードスタイル、共通ロジック、業務制約を Skills として蓄積すると、毎回ゼロから調整しなくても、AI が自然に私たちの方法に沿ったコードを生成します。
Skill の作り方
Ask モードで要件を説明し、既存の設計方法、コードスタイル、ルールを Qoder に伝えて Skill を生成できます。結果が期待と異なる場合は、会話で修正し続けるのではなく、Skill ファイルの説明とルールを更新します。これは一度で完成する作業ではなく、継続的な最適化です。
例えば、業務開発では統一された例外処理ユーティリティや、特定のクエリ構築方法があります。制約がなければ、AI は動作しても規約に合わないコードを生成します。そこで「Query Skill」と「Exception Skill」を作成しました。Spring Boot の実験では、Skills なしの場合、AI は JPA の native SQL を使い、独自の Error メソッドを使用しませんでした。Skills を読み込むと、動的クエリと例外処理の両方で自社のユーティリティが自動的に使われました。
04 私のワークフローと自己改善の仕組み
安定したワークフローは次のとおりです。
要件分解 → Ask モードで合意 → Agent モードでコード変更 → コードレビュー → すぐにコミット
05 Qoder はコードしか書けないのか
答えは「そうとは限らない」です。コードは仕事の一部にすぎません。Qoder はスクリプト、記事の推敲、動画シナリオのブレインストーミングにも利用できます。