はじめに
こんにちは、freee振込チームでQAをしているtonchanです。
本記事では、QAプロセスにAIを活用するためにshared-knowledgeという仕組みを作った話を紹介します。
この取り組みはfreee振込チーム独自のものです。社内のAI駆動QA基盤が立ち上がる前の2025年1月頃から、独自にQA専用リポジトリを作ってAI活用を始めていました。全ての成果物をMarkdown形式で管理する方針を早い段階で採用していたため、エンジニアと同じようにAIツールにそのまま渡せるフォーマットが揃っており、社内の他チームとは独立した形で発展してきました。
最初にぶつかった壁は「AIの出力する言葉がバラつく」問題です。同じ機能なのに「申請」「依頼」「予約」と毎回違う用語が出てくる...。QAの成果物は自然言語なので、この用語のブレは品質に直結します。
2025年6月、約5ヶ月間の試行錯誤を経てshared-knowledgeを構築しました。shared-knowledgeとは、人間もAIも参照する「チームの共有知識」を一元管理する場所です。
本記事では、shared-knowledgeを導入した背景、構造、運用のコツ、得られたメリットを紹介します。
freee振込におけるQAプロセスとAIが生成する成果物
まず、freee振込チームのQAプロセスの全体像を紹介します。
- 要求分析: PRD（Product Requirements Document）やDD（Design Docs）を読み、開発内容を理解する
- テスト計画: Test Summary Reportを発行し、テスト範囲・方針・スケジュールを決定する
- リスク洗い出し会: 関係者を集め、仕様上の懸念点やテスト環境の制約を議論する
- テスト分析: PRD・DDをもとに受入基準を作成する
- 受入基準sync会: Engと受入基準の認識をすり合わせる
- テスト設計: 受入基準をもとにテストチャーターを作成する
- テスト準備・実行: テストデータの準備、APIテスト用runbookの生成、テスト実行
- テスト完了・振り返り: テスト結果の整理と改善点の洗い出し
このうち、AIコマンドで生成している成果物は以下の3つです。成果物は上流から下流へ連鎖する構造になっています。
| QAプロセス | 成果物 |
|---|---|
| テスト分析 | 受入基準 |
| テスト設計 | テストチャーター |
| テスト実行 | APIテスト用runbook |
本記事では、これらの成果物をAIで安定して生成するための仕組みであるshared-knowledgeを紹介します。
AI活用は「すぐに効率化」ではない
「AIツールを入れればすぐ効率化できる」わけではありません。準備とステップが必要です。
私が踏んだ3つのステップを紹介します。
- ステップ1: まず個人の作業で試す
- 仕様調査やテスト分析など、自分で完結する作業にAIを使うところから始めました
- QAプロセスは影響範囲が大きいので、手元で検証が終わってからでないとチームには展開できません
- ステップ2: うまくいったやり方を「コマンド」にする
- 個人で試してうまくいく場面は増えたものの、毎回AIに同じ説明をする必要があり、品質にもバラつきがありました
- そこで、再現性のあるプロンプト（AIへの指示書）をファイルとして保存して、誰が実行しても同じ品質の成果物が出る状態を目指しました
- ステップ3: チーム全員が使えるようにする
- コマンド化で個人の再現性は上がりましたが、開発プロセスやタスクの進め方、個人の環境に差分があると同じコマンドでも結果が変わりました
- これらの差分を吸収できるレベルまで汎化して、チーム標準のワークフローに組み込んでいきました
いきなりチーム全体でインパクトを出そうとしないのが大事だと思っています。「個人の成功体験」を積み重ねて広げていくのが現実的です。
AI活用のための下地作り
AI活用を始める前に、成果物の形式や保守運用を根本から見直す必要がありました。個人的にはここが一番大変で、かつ一番大事なところだと感じています。
AIが読み書きしやすい形式は Markdown + Git管理 です。スプレッドシートのテストケースやWikiの仕様書を、Gitリポジトリ内のMarkdownファイルに移行しました。AIツールはテキストファイルの読み書きが得意で、バイナリやSaaSの画面上のデータはまだ苦手なことが多いですよね。
もともとGit管理を始めたのはAI活用のためではなく、「成果物のレビューをしやすくしたい」「修正差分をわかりやすくしたい」という動機からでした。QAの成果物をテキストデータとして管理する必要があったためMarkdown形式を採用し、結果的にこれがAI活用の下地になりました。
ただ、この移行には痛みが伴います。
- 既存ツール（スプレッドシート、Wiki、Jira等）との連携をどうするか
- 運用の一部が変わるとプロセス全体に影響するので、計測や管理の見直しも必要になります
- 例えば、スプレッドシートなら会議中に全員で同時編集できましたが、Markdownファイルとgitでは同時編集やコメントの残し方に工夫が要ります。エンジニアだけでなくBizメンバーも参加する場なので、全員が使える運用を考える必要がありました
それでも、従来の形式に固執するとAI活用のボトルネックになってしまいます。チームメンバーの合意を得ることが重要で、最初は効率化の成果が出にくいです（学習コストが先行するので）。
あと、AIは万能ではないです。機械的に判定できるもの（Lint、フォーマットチェック等）はスクリプトの方が確実で安定します。AIは文脈を理解した判断が必要な場面（レビュー、分析、設計）に使う、という適材適所の使い分けが大事です。
こうして下地は整ったのですが、最初にぶつかった「用語のバラつき」問題は根本的には解決していませんでした。Markdownファイルが増えるにつれ「どのファイルが正しい情報なのか」「用語の定義はどこにあるのか」がAIにも人間にもわからなくなってきました。バラバラのファイルではなく、構造化された「チームの共有知識」として一元管理する場所が必要だと気づいたのが、shared-knowledgeの始まりです。
shared-knowledgeとは何か
shared-knowledgeとは、チームの共有知識をMarkdownファイル群として一元管理する仕組みです。
第一の目的はLLM活用の品質向上ですが、それだけでなくナレッジの明文化・脱属人化・保守運用の改善も狙っています。
管理対象の例:
- ユビキタス言語（用語辞書）: 業務用語の定義集。カテゴリごとに整理しています
- QAガイドライン: 成果物の作成ルールやレビュー基準
- テスト戦略: テスト方針やカバレッジの考え方
- 機能仕様書: 各機能の設計・仕様
- 技術情報: API仕様やDBスキーマなどシステムの構造情報
ディレクトリ構成は以下のとおりです:
shared-knowledge/ ├── domain/ # ユビキタス言語、ドメイン固有の技術知識 ├── QA/ # QAプロセス、テスト戦略、各種ルール ├── docs/ # 機能仕様書群 └── onboarding/ # 新メンバー向けガイド
shared-knowledgeはAI向けに整備したものですが、副次的に人間のオンボーディングにも効果がありました。新しいメンバーがチームに参画する際、ドメイン知識やチームの文化・ルールを体系的にinputできる資料として機能しています。「AIに教えるために整理した情報」が、そのまま人間にとってもわかりやすい資料になったのは嬉しい誤算でした。
MCPサーバーだけではダメな理由
MCP（Model Context Protocol）サーバーは便利ですが、「だけ」では解決できない問題があります。
実際にMCPでWikiやチャットの情報を取得させてみましたが、生データのまま取得されるため用語がバラバラでコンテキストも不足しており、AIの出力が安定しませんでした。
- 情報が散在（Wiki、チャット、スプレッドシート等）していて、どこを見ればいいかわからない
- 「生データ」のまま取得されるので、用語の揺れやコンテキスト不足、背景情報がない
- どれが最新情報なのかわからない
MCPサーバーとshared-knowledgeは補完関係にあります。
- MCPサーバー = 情報を「集める」手段
shared-knowledge= 情報を「整理・活用」する場所
実際の運用では、MCPで最新情報を取得してshared-knowledgeに反映・整理するという流れです。「どの情報が最も信頼できるか」は人間が明示的に定義する必要があります。
AIコマンドとの連携
shared-knowledgeが真価を発揮するのは「AIコマンド」との組み合わせです。AIコマンドとは、特定のタスクをAIに実行させるための定型的な指示のことです。Claude Codeのskills、OpenAI Codexのskills、Roo Codeのcommandなどが該当します。
AIコマンドを実行すると、AIが自動的にshared-knowledgeを参照します:
- ユビキタス言語 → 正しい業務用語で書く
- 成果物の作成ルール → 決められた形式で書く
- 機能仕様書 → 仕様に沿った内容を生成
- テンプレート → 統一されたフォーマットで出力
前述のとおり、成果物は受入基準 → テストチャーター → APIテスト用runbookと上流から下流へ連鎖する構造になっており、各成果物は相互にリンクで参照し合います。
AIコマンドで成果物の作成が容易になると、成果物の量が増えます。すると今度は人間のレビューがボトルネックになりました。そこでレビューもAIで仕組み化しました:
- Lintツールで機械的なチェック + AIレビュアーで文脈理解が必要な観点を確認
- AIは修正せず、レビューコメントと改善提案のみ提示します。最終判断は人間が行います
3つのメリット
メリット1: AI成果物の品質向上
shared-knowledgeなしの場合、AIは一般的な知識だけで成果物を作ります。ドメイン固有の用語を間違えたり、業務フローを知らなかったりします。
shared-knowledgeありの場合、正しい用語、実際の仕様、チームの方針に沿った成果物を生成してくれます。結果として人間のレビュー負荷が大幅に減りました。
メリット2: ナレッジのメンテナンス性向上
従来はメンテできる人が限られていて（属人化）、工数に見合わず放置されがちでした。
AI活用後は、新しい仕様書が追加されたら用語辞書を自動更新、コードが変わったら技術情報を自動更新できるようになりました。変更内容はPull Requestとして提出して、人間が確認してからマージします。AIが作業し、人間が承認するという安全な運用です。
メリット3: 一次資料の明確化
多くの組織で「何が最新の正しい情報なのかわからない」問題があると思います。情報がWiki、チャット、スプレッドシートなどに散在している状況です。
shared-knowledgeで「これが一次資料」と明示的に定義できるようになりました。MCPサーバー（集める）とshared-knowledge（整理する）は補完関係にあります。
保守運用をワークさせるためには
ナレッジの保守運用って、多くのチームで挫折する「永遠の課題」だと思います。
自分たちのチームでは一定ワークしています。理由は構造にあると考えています:
- 全ての成果物のinput（参照情報）として
shared-knowledgeを使う設計にしました shared-knowledgeが古い = AIが生成する成果物の品質が下がる- 品質が下がると業務に支障が出る → 更新する自然な動機が生まれます
更新が「特別な作業」ではなく「業務の一環」になる構造が大事なんですよね。
コードから自動生成できるナレッジ（DB構造等）はほぼ全自動で更新できます。手動更新が必要なもの（用語辞書、テスト戦略等）も、上記の動機付けでワークしています。
今後の展望
現在はQAプロセス（テスト分析・テスト設計・テスト実装）が中心ですが、テストプロセス以外への展開も計画しています:
- 要求分析・要件定義の作成支援: ユーザーインタビューや既存ドメイン知識をもとに要求分析
- 機能仕様書の作成支援: 既存仕様との整合性を踏まえた設計ドキュメント作成
- ヘルプドキュメントの作成: ユビキタス言語で一貫した用語のドキュメント
- エラー監視ログの分析: エラーの原因分析、品質改善項目のリストアップ
最終目標は、開発プロセス全体（企画 → 設計 → 実装 → テスト → 運用）で一気通貫に利用できる「共有知識」にすることです。
まとめ
AIに安定した成果物を出してもらうためには、AIが参照する情報の品質と構造が重要です。用語の揺れ、情報の散在、成果物の品質のバラつきといった課題に一つずつ向き合った結果、shared-knowledgeという形に辿り着きました。
shared-knowledgeは仕組みとしてはシンプルで、導入の効果も実感しやすいものです。ただ、それが「とりあえずナレッジを整備すればAIがうまく動く」という理解にとどまってしまうと、情報が古くなったときに対処できなくなる側面もあります。
大事なのは、AIがどの情報をどう解釈して成果物に反映しているのかを理解し、必要に応じてナレッジを見直していくことだと感じています。ときにはshared-knowledgeの中身を読み直して、チームの現状と合っているかを確認する。そんなナレッジのリファクタリングを日常的に意識しておくと、AI活用の幅が広がるのではないかと思いました。
