Claude Codeプラグインと知識ベースで実現するチーム標準化と知識の永続化

こんにちは。認証グループ改め認証チームのいまひろです。

これまで認証チームでは、Claude Codeを活用したJiraのチケット駆動開発について、複数の記事で紹介してきました。

• Claude CodeでJiraのチケット駆動開発を強固に加速させる！
• Claude Codeの新機能で改善されるJiraのチケット駆動開発 - コマンドの再利用とプラグインによるチーム標準化
• サブエージェントのジレンマを解決する：外部状態ファイルパターンによる独立性とフィードバックの両立
• Jiraのサブタスクを活用した複数Claude Codeセッションの協調作業

今回は、Claude Codeを活用したJiraのチケット駆動開発について、認証チームにおける現在地をまとめてご紹介したいと思います。

チーム構成と開発スタイル

認証チームでは、クリティカルな機能を扱う関係上、モブプログラミングを主体とした開発スタイルを採用しています。

また、複数のリポジトリに跨って作業することが日常的です。そのため、Claude Codeは親ディレクトリで起動し、各リポジトリを横断的に操作できる環境を構築しています。

システム全体像

まず、現在構築している環境の全体像を図で示します。

システム全体像

開発フローにおけるデータの流れ

チケットに取り組む際の典型的なデータフローは以下のようになります。

開発フローにおけるデータの流れ

プラグインによるチーム環境の標準化

GitHubプライベートリポジトリでのプラグイン管理

チーム全員が同じ開発環境でClaude Codeを活用できるよう、専用のプライベートリポジトリでプラグインを管理しています。

team-plugin/
├── .mcp.json                    # MCP設定
├── rule.md                      # チーム共通ルール
├── .claude-plugin/
│   └── marketplace.json         # プラグイン定義
└── commands/
    ├── plan-ticket.md           # チケット計画コマンド
    ├── step-subtask.md          # サブタスク実行コマンド
    ├── process-ticket.md        # 統合実行コマンド
    ├── handover-subtask.md      # 作業引き継ぎコマンド
    ├── resume-subtask.md        # 作業再開コマンド
    ├── research.md              # 調査コマンド
    ├── knowledge-search.md      # 知識検索コマンド
    ├── knowledge-save.md        # 知識保存コマンド
    └── knowledge-organize.md    # 知識整理コマンド

プラグイン管理のメリット

誰がドライバーでも同じ品質

モブプログラミングでは、ドライバー（実際に操作する人）が交代することがあります。プラグインでチーム共通のコマンドとルールを共有することで、誰がドライバーを担当しても同じ品質で開発を進められるようになりました。

迅速なオンボーディング

新しいメンバーがチームに加わった際も、プラグインをインストールするだけで即座にチーム標準の開発環境を利用できます。

/plugin marketplace add リポジトリURL

継続的な改善の自動展開

コマンドの改善や新機能の追加があった場合、プライベートリポジトリを更新するだけで各メンバーに自動的に展開されます。

MCP設定の共有

プラグイン内の .mcp.json ファイルで、チームで使用するMCPサーバーの設定を一元管理しています。

{
  "mcpServers": {
    "atlassian": {
      "type": "sse",
      "url": "https://mcp.atlassian.com/v1/sse"
    },
    "serena": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oraios/serena", "serena-mcp-server", "--context", "ide-assistant"]
    }
  }
}

これにより、Jira等の外部サービス連携も、メンバー間で統一された設定で利用できます。

rule.mdとCLAUDE.mdの連携設計

プラグインにCLAUDE.mdが置けない問題への対処

現状、Claude Codeのプラグインには CLAUDE.md ファイルを直接配置することができません。

そこで、プラグイン内に rule.md としてルールを定義し、ユーザーディレクトリの CLAUDE.md から参照する形式を採用しています。

~/.claude/CLAUDE.md

# リポジトリ構成

@~/.claude/repo.md

# ルール

@~/.claude/plugins/marketplaces/team-plugin/rule.md

# キャラクター

@~/.claude/character.md

この設計により、チーム共通のルールはプラグインで管理しつつ、個人ごとのカスタマイズも可能にしています。

rule.mdで定義しているチームルールの概要

プラグイン内の rule.md には、チームで統一したい開発ルールを詳細に定義しています。主な内容を紹介します。

作業開始前のルール

Jiraチケットに着手する際の統一手順を定義しています。

• 知識ベースリポジトリを最新化してから作業開始
• 対象リポジトリに .serena フォルダがある場合はSerena MCPを使用
• リポジトリごとにベースブランチを切り替え（develop、main等）
• 最新を取得してからブランチを作成

ブランチ命名規則

ブランチ名のフォーマットを統一することで、チケットとの紐付けを明確にしています。

feature/{チケット番号}

親チケットが存在する場合は親チケット番号を使用するルールにより、複数サブタスクの変更が同一ブランチにまとまります。

コミットルール

意図しないファイルの混入を防ぐためのルールを定義しています。

• git add . や git add -A は使用禁止
• 対象ファイルのみを明示的に git add する
• リポジトリによってはコミット前にフォーマッターを実行

コミットメッセージ規則

チケットとの紐付けを明確にするフォーマットを定義しています。

{チケット番号}: {変更内容}

プルリクエストのルール

レビューしやすいプルリクエストを作成するためのルールです。

• draftで作成する
• 日本語で作成する
• タイトルは {チケット番号}: {Jiraのタイトル} 形式
• 冒頭にJiraのURLを記載
• 末尾にClaude Codeの署名を入れる
• レビュー対応後はプルリクエストの概要も更新する

作業ルール

テスト駆動の開発を促すルールを定義しています。

• 実装時はJiraチケットの内容だけでなく、該当チケットのGherkinテストも参照
• テストリポジトリへのテスト追加は常に最優先で実施

知識ベースの自動活用ルール

詳細は後述しますが、知識ベースの検索・保存に関するルールも定義しています。

• タスク開始時のキーワードによる自動検索
• 知見を得た際の保存提案トリガー条件
• 既存知識の修正が必要な場合の対応

これらのルールをプラグインで共有することで、誰がドライバーを担当しても同じ手順・同じ品質で開発が進められるようになりました。

CLAUDE.mdの設計方針：最小限の記述

ユーザーディレクトリの CLAUDE.md は、各設定ファイルへのマッピングのみを記述し、コンパクトに保っています。

repo.md（リポジトリマッピング）

複数リポジトリに跨る作業を行うため、各リポジトリのローカルディレクトリ位置を明示的に記述しています。

### gitリポジトリのローカル配置場所

- ~/dev/git配下

### 知識ベースリポジトリに対応するローカルディレクトリ

- 知識ベースリポジトリ
  - ./knowledge-base

### 代表的なリポジトリに対応するローカルディレクトリ

- リポジトリA
  - ./repo-a
- リポジトリB
  - ./repo-b
...

これにより、Claude Codeがチケットの内容から適切なリポジトリを特定し、複数リポジトリへの変更を一つのセッションで行えるようになっています。

知識ベースリポジトリによる知識の永続化

知識ベース導入の背景

Claude Codeを活用した開発を続ける中で、以下の課題に直面しました。

セッションごとの調査コスト

Claude Codeは新しいセッションを開始するたびに、コードベースの調査を一から行います。同じような調査を何度も繰り返すことで、時間とトークンのコストが膨らんでいく問題がありました。

調査結果の不安定さ

同じチケットに取り組んでいても、セッションによって調査結果や実装方針が異なることがありました。過去のセッションで得られた知見が引き継がれないため、一貫性のある開発が難しい状況でした。

ナレッジの属人化

モブプログラミングで得られた知見が、その場にいたメンバーの頭の中にしか残らず、チーム全体の資産として蓄積されない問題もありました。

これらの課題を解決するため、知識ベースリポジトリを導入しました。

知識ベースの構造

チームで得られた知見を永続化するため、専用のGitHubプライベートリポジトリで知識ベースを管理しています。

knowledge-base/
├── batch/           # バッチ処理関連の知見
├── infrastructure/  # インフラ関連の知見
├── auth/            # 認証関連の知見
├── development/     # 開発プロセス・環境構築
├── misc/            # 一時的な分類先
├── .knowledge-meta.json  # 参照追跡メタデータ
└── README.md

知識ベース機能の導入状況

知識ベースの機能は、実用段階のものと検証段階のものがあります。現状を整理すると以下のようになります。

機能	導入状況	説明
知識の蓄積	✅ 実用段階	調査結果や知見をMarkdownファイルとして保存
知識の参照	✅ 実用段階	タスク開始時に関連知識を自動検索
保存の自動提案	✅ 実用段階	知見を得た際にClaude Codeが保存を提案
定期メンテナンス	🔄 検証段階	忘却曲線に基づく整理、情報の検証など
参照追跡メタデータ	🔄 検証段階	参照頻度に基づく優先度調整

---

【実用段階】知識の蓄積と参照

以下の機能は既に日常的に活用しており、効果を実感しています。

自動知識検索（タスク開始時）

チームのルールとして、特定のキーワードを含むタスクを受けた場合、作業開始前に知識ベースを自動検索するよう設定しています。

キーワード	検索対象ディレクトリ
バッチ, worker, job	batch/
インフラ, Terraform	infrastructure/
認証, ログイン	auth/
リリース, デプロイ	development/

これにより、過去に蓄積した知見を活用しながら作業を進められます。

知識保存の自動提案

作業中にチームで共有すべき知見を得た場合、Claude Codeが自動的に保存を提案します。

保存提案のトリガー条件

• 調査・分析を行い、新しい発見があった場合
• 問題解決のノウハウを得た場合
• 判断基準・選択指針を明確にした場合
• 複数チケットに共通するパターンを発見した場合

提案フォーマット例

💡 チームで共有すべき知見が得られました。知識ベースに保存しますか？

【内容】APIリトライ処理のパターンと注意点
【保存先】knowledge-base/development/api-retry-pattern.md

実用段階で得られた効果

調査コストの削減

過去の調査結果を知識ベースから参照できるため、毎回一から調査する必要がなくなりました。特に、複雑な仕様や設定値については、過去の知見が大きな助けになっています。

結果の安定化

知識ベースに蓄積された情報を元に判断することで、セッションによる結果のばらつきが減少しました。チーム内で合意した判断基準や実装パターンが、一貫して適用されるようになっています。

チームナレッジの形式知化

暗黙知として個人の中に留まりがちなノウハウが、形式知としてチーム全体で共有されます。

---

【検証段階】人間の記憶メカニズムに基づくメンテナンス

以下の機能は設計・実装済みですが、まだ本格運用には至っておらず検証段階です。

知識ベースは、人間の記憶メカニズムを模倣した管理機能を目指しています。

機能	人間の記憶	説明
analyze	自己認識	知識ベース全体の健全性分析レポートを生成
forget	忘却曲線	古い/参照されない情報をアーカイブまたは削除
consolidate	記憶の統合	類似・重複情報を検出し統合を提案
verify	記憶の検証	古い情報の正確性確認、更新が必要な情報を検出
prioritize	優先度付け	重要度タグ付け、参照頻度に基づく整理
associate	関連付け	関連ドキュメント間のリンク付け

参照追跡メタデータ

知識を参照するたびに、メタデータファイル（.knowledge-meta.json）が自動更新される仕組みを用意しています。

{
  "files": {
    "batch/worker-pattern.md": {
      "created": "2025-01-10",
      "lastModified": "2025-01-15",
      "lastReferenced": "2025-01-24",
      "referenceCount": 8,
      "priority": "high",
      "tags": ["バッチ", "ワーカー"]
    }
  }
}

これにより、以下が可能になる想定です。

• 忘却曲線の適用: 長期間参照されない知識をアーカイブ候補として検出
• 優先度の自動調整: よく参照される知識を高優先度に
• 関連性の分析: 一緒に参照される知識の関連付け

定期メンテナンスの構想

頻度	実行内容
週1回	analyze でレポート確認
月1回	verify で情報の正確性確認
月1回	forget で不要情報の整理
四半期	consolidate で情報の統合

現状は知識の蓄積と参照が軌道に乗った段階であり、メンテナンス機能はこれから本格的に検証していく予定です。情報が定期的にメンテナンスされるようになると、知識ベースの品質が維持され、より開発の質を上げることができると期待しています。

実行計画の作成と承認フロー

plan-ticketコマンドの進化

以前は、/plan-ticket コマンドでJiraチケットをサブタスクに分割する際、コードベースの調査からサブタスク作成までを一気に実行していました。

現在は、実行計画の作成とユーザー承認のステップを明確に分離しています。

新しいワークフロー

1. Jira情報の取得
       ↓
2. 知識ベースの検索
   - 関連する過去の知見を参照
   - 類似チケットでの対応パターンを確認
       ↓
3. コードベースの調査
   - 変更が必要なリポジトリの特定
   - 既存の実装パターンの確認
   - 変更対象のファイル・クラス・関数の特定
       ↓
4. 実行計画の作成と提示（Jiraへの変更は行わない）
       ↓
5. ユーザーのフィードバック待ち
   - 承認 or 修正依頼
       ↓
6. 承認後：サブタスクの分割
       ↓
7. Jiraチケットへのプラン内容の出力

知識ベースを先に検索することで、過去の調査結果や判断基準を踏まえた上でコードベースの調査を行えるようになりました。これにより、調査の効率化と結果の一貫性が向上しています。

実行計画の提示フォーマット例

## 実行計画

### チケット概要
- チケット番号: XXX-XXXX
- タイトル: 機能Aの改善

### 参照した知識ベース
- development/xxx-pattern.md（関連する実装パターン）

### 作成予定のサブタスク

#### 1. [テストリポジトリ] テストの追加
- **対象機能**: 機能A
- **テストシナリオ**:
  - 正常系の動作確認
  - 異常系の動作確認
- **参考にする既存テスト**: 既存のテストファイル

#### 2. [実装リポジトリ] ロジックの実装
- **変更対象ファイル**:
  - ファイルA: 処理Xの追加
  - ファイルB: 処理Yへの組み込み
- **実装詳細**:
  - ステップ1の実装
  - ステップ2の実装

---
この計画でよろしければ「OK」または「進めてください」と入力してください。
修正が必要な場合は、修正内容をお知らせください。

実行計画の記録と活用

承認された実行計画は、親チケットのコメントに記録されます。

これにより、後続の step-subtask コマンドで実行計画を参照でき、重複した調査を避けられるようになりました。

## 実行計画（Claude Codeにより作成）

{承認された実行計画の内容}

---
作成日時: YYYY-MM-DD HH:MM

実行計画導入の効果

実装前の方針確認が可能に

以前は、Claude Codeが実際に実装を始めるまで、どのような方針で実装するかがわかりませんでした。実装結果を見てから「そうじゃない」となることもあり、手戻りが発生するリスクがありました。

実行計画の導入により、実装に着手する前に方針をチームで確認できるようになりました。どのファイルをどう変更するのか、どのような順序で作業するのかが事前に明確になるため、チーム内で認識を合わせた上で実装を進められます。

チームでの精査が可能に

モブプログラミングで開発方針を決定する際、実行計画をチームメンバー全員で確認し、必要に応じて修正を加えることができます。Claude Codeが調査した結果と知識ベースの情報をベースに議論できるため、根拠に基づいた意思決定が可能になりました。

作業の透明性向上

実行計画がJiraチケットに記録されることで、何を、どのように実装するかが明文化されます。チームメンバーの誰がレビューする際にも、計画と実装の整合性を確認できます。

step-subtaskとの連携

step-subtask コマンドは、親チケットのコメントから実行計画を取得し、計画に沿った実装を行います。実装完了後には、プランとの整合性を自己検証し、乖離がある場合はユーザーに報告します。

その他の特筆すべき点

Serena MCPによる効率的なコード探索

大規模なコードベースや知識ベースを扱う際、ファイル全体を読み込むのではなく、シンボル単位での探索を可能にするSerena MCPを活用しています。

これにより、コンテキストウィンドウを効率的に使用しながら、必要な情報だけを取得できます。

まとめ

認証チームでは、Claude Codeを活用したJiraのチケット駆動開発を継続的に改善してきました。

現在の取り組みをまとめると、以下のようになります。

プラグインによるチーム標準化

• GitHubプライベートリポジトリでコマンド・ルール・MCP設定を一元管理
• モブプログラミングにおいて、誰がドライバーでも同じ品質で開発可能
• rule.mdとCLAUDE.mdの連携により、プラグインにCLAUDE.mdが置けない制約を回避

知識ベースによる知識の永続化

• 【実用段階】自動検索と保存提案によるナレッジマネジメントの効率化
• 【実用段階】セッションごとの調査コストと結果の不安定さを解決
• 【検証段階】人間の記憶メカニズムに基づくメンテナンス（忘却曲線、統合、検証）
• 【検証段階】参照追跡メタデータによる優先度の自動調整

実行計画の作成と承認フロー

• 知識ベースとコードベースの調査後、実行計画をチームで精査してから着手
• 計画がJiraチケットに記録され、透明性と追跡性が向上
• step-subtaskとの連携により、計画に沿った実装を担保

これらの取り組みにより、AIと人間がそれぞれの強みを活かして協調する、チーム開発の新しい形が見えてきました。

Claude Codeは日々進化しており、今後も新機能を活用しながら、より良い開発体験の実現を目指していきたいと考えています。