blog

DeNAのエンジニアが考えていることや、担当しているサービスについて情報発信しています

2026.01.06 技術記事

育てるほど楽になる AI 開発体制を作っている話

by Koya Nagata

#ai #cursor #claude-code #llm #cicd #github-actions

こんにちは。ソリューション本部 エンタープライズ事業部 スポーツプラットフォーム部の永田です。普段の業務ではスポーツ領域の新規サービス開発に従事しています。

本記事では、複雑なドメインを持つ新規サービス開発のプロジェクトにおいて、「AI を活用して開発生産性を向上させる」 ために構築した仕組みと、その具体的な例を紹介します。

背景と課題

プロジェクトの特性

本プロジェクトには、以下のような特性があります。

  • 新規サービス開発: ゼロからの立ち上げであり、設計判断が多い
  • タイトなスケジュール: ビジネス要件上、できるだけ早く開発を進める必要がある
  • 複雑なドメイン・コード: 特有の概念や複雑な構造が多く、全体像の把握が難しい。新規メンバーが多いチーム構成も相まって、ドメイン知識の蓄積が十分でない

こうした背景から、AI をうまく活用してスピードと品質を両立して開発を効率化したいと考えていました。

AI 活用の現状

私が今年の 10 月にチームにジョインした際、チームでの AI 活用状況は以下の状態でした。

  • 開発環境としては、すでに Claude Code や Cursor といった生成 AI ツールが利用できる状態
  • しかし、あくまで「個人の開発補助ツール」としての利用に留まっていた

課題

具体的には以下の課題がありました。

  • コンテキストが共有されていない
    • README 以外のドキュメントやコンテキストファイル、設定が存在せず、AI の出力品質が安定しない
  • ガイドライン違反のコードが生成される
    • プロジェクト固有の文脈や暗黙のルールを AI が把握していない
  • レビュー精度が良くない
    • DeNA で運用されている PR-Agent1 は導入されていたが、プロジェクト固有のコンテキストを与えていなかったため汎用的なレビューに留まっていた

ワークフロー設計の指針

これらの課題に対し、やみくもにツールを導入するのではなく、「レビュー作業の量を減らす」 ことと 「開発成果物の品質を標準化する」 という 2 つの軸をベースにワークフローを設計しました。

1. レビュー作業の「量」を減らす

人間が見るべきは「ビジネスロジックの正しさ」や「アーキテクチャの妥当性」といった本質的な部分です。コーディング規約違反、単純なバグ、タイポといった機械的なチェックは AI による一次レビューで完結させ、人間がレビューする時点でノイズが除去されている状態を目指しました。

2. 開発成果物の「品質」を標準化する

チームメンバー全員が品質の高い成果物を高速に出力できる状態を目指しました。コーディング規約、設計パターン、ドメイン知識などを AI が参照できる形で整備することで、経験やスキルに依存せず、誰でも一定水準以上のコードを素早く生成できる環境を目指しました。

この指針に基づき、以下のアーキテクチャを構築しました。

全体アーキテクチャ

AI を単なる「汎用的なアシスタント」ではなく、「プロジェクトの文脈を知り尽くしたメンバー」にするため、ドキュメントやガイドラインを整備しコンテキストを一元管理する構成にしました。

ディレクトリ構成

リポジトリには、AI が参照するコンテキスト情報を集約しています。docs/ や設定ファイルを更新すれば、AI の出力精度も向上する仕組みです。

ticket-backend/
├── CLAUDE.md                        # Claude Code のメモリ（プロジェクト概要・手順）
├── AGENTS.md                        # 共通コンテキスト（技術スタック等）
├── .claude/
│   ├── agents/                      # ★サブエージェント定義
│   │   ├── api-spec-reviewer.md
│   │   ├── code-reviewer.md
│   │   ├── e2e-test-implementer.md
│   │   └── issue-solver.md
│   ├── commands/                    # カスタムコマンド
│   │   ├── api-review.md
│   │   ├── code-review.md
│   │   ├── implement-e2e.md
│   │   ├── issue-solve.md
│   │   ├── pr-create.md
│   │   └── pr-review-fix.md
│   └── skills/                      # スキル定義
│       ├── github-issue-analysis/
│       ├── github-pr-analysis/
│       ├── go-code-generation/
│       ├── go-quality-check/
│       ├── go-testing/
│       ├── pr-review-knowledge/
│       └── notion-spec-fetcher/
└── docs/                            # ドキュメント（規約）
    ├── api_development_guideline.md
    ├── coding_guidelines.md
    ├── firestore_development_guideline.md
    └── project_knowledge.md

開発ワークフロー

チームでは、以下の 3 つのフェーズで AI を活用したワークフローを構築しています。

1. 実装フェーズ

開発者がローカル環境で AI を活用して実装。

image alt text

2. レビューフェーズ

PR が作成されると、Claude Code Actions が自動レビューを実行します。

image alt text

3. ナレッジ蓄積フェーズ

レビューでの指摘をドキュメントに反映し、AI の出力品質を継続的に向上させます。

image alt text

具体的な実装と工夫

ここからは、実際に効果の高かった 4 つの取り組みについて紹介します。

1. 特定のタスクに特化したサブエージェントの構築

すべてのコンテキストをメインエージェントに渡すと、コンテキストが肥大化し汚染されてしまいます。 小さく単一責任のエージェントとして構築すべき という原則に従い、特定のタスクに特化したサブエージェントを定義しました。

作成したサブエージェントの例

サブエージェント 役割
api-spec-reviewer OpenAPI 仕様の構造・命名規則を厳格にレビュー
code-reviewer Go 言語のベストプラクティスやプロジェクト固有の設計パターンをチェック
e2e-test-implementer 複雑な E2E テストの実装を専門に行う

実装例 API レビュー専門エージェント

以下は、実際に利用している API レビュー専門エージェント のサブエージェント定義です。

---
name: api-spec-reviewer
// ..
// 省略
// ..
---

あなたは OpenAPI 仕様書と RPC API 設計を専門とする、エキスパート API アーキテクトおよびレビュアーです。主な責務は、OpenAPI 仕様書と API 設計をレビューし、docs/api_development_guideline.md に記載されているガイドラインに厳密に準拠していることを確認することです。

## 主要な責務

1. **ガイドライン準拠レビュー**: docs/api_development_guideline.md を注意深く読んで理解し、OpenAPI 仕様書がそのドキュメントで定義されているすべてのガイドライン、標準、ベストプラクティスに従っているか体系的に検証します
2. **OpenAPI 仕様書分析**: 以下を含む OpenAPI 定義の技術的正確性をレビューします
   - スキーマ定義とデータ型
   - エンドポイントパスと HTTP メソッド
   - リクエスト/レスポンス構造
   - 認証とセキュリティスキーム
   - エラーレスポンス形式
3. **包括的なフィードバック**: 発見された各問題について、以下を提供します
   - 仕様書内の具体的な場所(パス、オペレーション、コンポーネント)
   - ガイドライン違反または問題の明確な説明
   - docs/api_development_guideline.md の関連セクションへの参照
   - 修正方法に関する具体的な提案
   - 重要度レベル(重大、重要、軽微)
4. **ベストプラクティスの適用**: API 設計が以下に従っていることを確認します
   - RPC の原則と規約
   - 一貫した命名規則
   - 適切な HTTP ステータスコードの使用
   - 明確で包括的なドキュメント
   - 適切なエラー処理パターン

## レビュープロセス

1. まず、docs/api_development_guideline.md を読んで、API ガイドラインを理解します
2. 提供された OpenAPI 仕様書ファイルを検証します
3. 現在のブランチが origin/develop の変更を含んでいるか確認します
4. HEAD から、origin/develop ブランチに対しての差分を検出します
5. 以下をカバーする構造化されたレビューを作成します
   - 修正が必要な箇所の提示
   - 修正が必須の重大な問題
   - 対処すべき重要な改善点
   - 軽微な提案
6. API の使いやすさ、セキュリティ、保守性への影響によって問題を優先順位付けします
7. 可能な場合はコード例を含む推奨事項を提供します

## 出力形式

以下の形式で日本語でレビューを提供してください

- 重要度別に整理された調査結果をリストアップ
- 各調査結果には、コードの場所、問題の説明、ガイドライン参照、推奨される修正を含める
- 具体的な次のステップで締めくくる

API 設計のいずれかの側面があいまいな場合、または追加のコンテキストがあればレビューの質が向上する場合は、明確化のための質問をしてください。

一貫性があり、安全で、保守しやすい高品質な API の構築をチームが実現できるよう、徹底的かつ建設的であることを心がけてください。

2. Claude Code Actions による自動レビュー

整備したサブエージェントを利用してレビューを行う ワークフロー（GitHub Actions）を作成しました。 PR が作成されると、変更ファイルの種類（openapi/、*.goなど）に応じて適切なエージェントが起動し、自動レビューを行います。

以下は、実際に Claude Code Actions が PR に対してレビューを行った様子です。

レビュー専門エージェントによる指摘

このように、重要度ラベル付きで具体的な指摘が入るため、人間はガイドライン違反などのチェックから解放され、本質的な設計やロジックのレビューに集中できるようになりました。

3. Serena MCP の導入

また ローカル開発において AI の精度を高めるため、LSP（Language Server Protocol）を活用した MCP サーバー Serena を導入しました。

モノレポのような巨大なコードベースでは、単純なファイル検索だけでは AI が必要なコンテキストを見つけるのに時間がかかったり、必要な情報を見つけることができず精度の低い回答や実装をすることがありました。Serena を導入したことで、AI がコードのシンボルや依存関係などを正確に把握できるようになり、アウトプットの速度・品質が向上しました。

これらの工夫により、レビューや実装時の精度が大きく向上しました。

4. ドキュメント自動更新フロー

また、人によるレビューでの指摘事項を確実にナレッジ化する仕組みを作成しました。

  1. PR のレビューコメントの返信でメンション
  2. Claude Code Actions が起動し、レビューコメントや議論を分析
  3. docs/coding_guidelines.md などの適切なドキュメントを更新する別 PR を作成

このフローにより、レビュー指摘事項をドキュメントへ簡単に反映させることが可能になり、「レビュー → ドキュメント更新 → AI の出力品質向上」 というサイクルが回るようになりました。

ガイドラインへの追記が別 PR として作成されている

結果と効果

この仕組みを整備したことで、以下のような効果が得られました。

  • レビュー負荷の軽減
    • コードの書き方や API ガイドライン違反など機械的な指摘が AI レビューで完結し、人間は本質的な設計議論に集中できるようになった
      指標 導入前の平均 導入後の平均
      人間のレビュー回数 7.2 回/PR 2.7 回/PR
      人間のコメント数 6.0 件/PR 1.9 件/PR
  • コード品質の標準化
    • AI がガイドラインを参照して生成・レビューするため、経験やスキルに依存せず一定水準のコードが出力されるようになった
  • ナレッジの蓄積
    • レビュー指摘がドキュメントに反映される仕組みにより、AI を含むチーム全体の知識が継続的に向上するようになった

まとめ

本記事では、AI を活用した開発の仕組みづくりについて紹介しました。

ポイントは以下の 3 つです。

  • コンテキストの一元管理
    • ドキュメント やエージェント定義をリポジトリで管理し、品質を向上させる
  • サブエージェント・Skills による分業
    • API、コード、E2E など役割ごとにサブエージェントを定義する
  • ナレッジ循環の仕組み化
    • レビューでの指摘をドキュメント化し、AI の精度を継続的に向上させる仕組みを構築する

AI を個人の補助ツールにとどめず、チーム全体で活かすには、プロジェクト固有のコンテキストをどう整備・共有するかがポイントになります。

今後の展望

本記事では設計・実装・レビューフェーズでの AI 活用を紹介しましたが、最近ではチーム内のビジネス職メンバーや PdM（プロダクトマネージャー）なども Cursor を使い始めており、仕様策定や書類内容の確認といった業務にも活用が広がっています。

こうした上流工程は人手がかかる一方で、ビジネスインパクトが大きい領域です。仕様の抜け漏れ検出や要件整理などを AI で効率化できれば、チーム全体の生産性向上につながります。エンジニアに限らず、職種を超えてビジネス価値に直結する AI との協働体制を築いていきたいと考えています。

  1. PR-Agent は、Pull Request を自動でレビューしてくれるツールです。DeNA では全社向けにセルフホストで運用しています。詳しくは「 OSS の AI レビューツール「PR-Agent」を全社導入し、コスト効率の高い開発支援を実現した話 」を参照してください。 ↩︎

最後まで読んでいただき、ありがとうございます！
この記事をシェアしていただける方はこちらからお願いします。

related articles

recruit

DeNAでは、失敗を恐れず常に挑戦し続けるエンジニアを募集しています。

See more→