はじめに
株式会社ヘンリーでソフトウェアエンジニアをしているUGAです。
ヘンリーでは電子カルテ・レセコン一体型のクラウドサービス「Henry」を開発しています。
医療ドメインのプロダクト開発では、コードの複雑さだけでなく、その背景にある医療ドメイン知識の複雑さが大きな壁になります。
この記事では、Claude Codeを使ってコードベースから体系的な技術ドキュメント「解体新書」を自動生成するClaudeCodePluginを開発した話を紹介します。単なるドキュメント自動化の話ではなく、ドメインエキスパートAIをチームで育てるというビジョンに基づいた取り組みです。
きっかけ
ヘンリーの開発では、ドメインが複雑であるが故に、日常的にSlackで他のメンバーに質問のメンションを飛ばし、返事を待ち、回答をもらってようやく作業に取りかかるというやり取りが少なくありませんでした。これは聞かれる側も自分のタスクを中断して答える必要があり、双方にとってコストの高いやり取りでした。
コードを直接読みに行くこともできますが、医療ドメインのコードは「何をしているか」は読めても「なぜそうなっているか」が分からないことが多いです。結局、ドメイン知識を持った人に聞くしかない場面に戻ってきます。この状況をどうにかできないかと、ずっと考えていました。
複雑なドメイン開発の難しさ
医療ドメインに限らず複雑なドメイン開発では、以下のような問題があります。
- 知識の属人化: 「入院フローのことならAさん」「コスト連携ならBさん」と、特定のメンバーに知識が集中する。その人が異動や休暇になると、チームの開発速度が目に見えて落ちる
- 新メンバーのオンボーディングコスト: コードベースを読んでも全体像が掴めず、既存メンバーへの質問に頼らざるを得ない。
- 繰り返される一からの調査: 知りたいことだけをClaude Codeでコードベースを都度調査しても、同じ領域を何度も探索することになる。調査結果は個人のコンテキストに留まり、チームの資産にならない
散発的にドキュメントを残したりして対処しようとしても、コードと乖離してしまうことがほとんどです。コードベースと連動した体系的な知識基盤が求められます。
ドメインエキスパートをチームで醸成する
そんな中、同僚がClaude Codeのプロンプトを調整しながら一部機能の技術ドキュメント（後に「解体新書」と呼ぶもの）を作成しているのを見ました。コードベースを体系的に調査し、ドメインモデルやデータフロー、設計判断の背景までまとめたドキュメントです。その成果物を見て、これをチームで育てるのはどうだろうかと考えました。
ただし、個人のプロンプト作業では、品質にもバラつきが出てしまいます。そして何より、特定の人しか生成できないという属人化の問題がそのまま残ります。
そこで、この取り組みをSkill/Plugin化し、誰でも同じ品質のドキュメントを生成・活用・改善できる仕組みにすることにしました。
Pluginの全体構成
今回作成したプラグイン（henry-anatomy-skills）は、Henryプロダクトの各機能領域をコードベースから調査し、体系的にまとめた技術ドキュメント（解体新書）を作成・検索できるようにしたものです。2つのPlugin（search / editor）から構成されています。
ディレクトリ構成
henry-anatomy-skills/ ├── .claude-plugin/ │ └── marketplace.json # マーケットプレース定義 ├── plugins/ │ ├── henry-anatomy-search/ # 分析・検索系プラグイン │ │ ├── .claude-plugin/ │ │ │ └── plugin.json │ │ ├── docs/ # 解体新書ドキュメント │ │ │ ├── injection-order-anatomy/ │ │ │ ├── cost-sync-anatomy/ │ │ │ ├── hospitalization-anatomy/ │ │ │ ├── out-of-hospital-anatomy/ │ │ │ └── auto-print-anatomy/ │ │ ├── skills/ │ │ │ └── search-anatomy/ │ │ └── README.md │ └── henry-anatomy-editor/ # 作成・更新系プラグイン │ ├── .claude-plugin/ │ │ └── plugin.json │ ├── skills/ │ │ ├── generate-anatomy/ │ │ └── revise-anatomy/ │ └── README.md └── README.md
各解体新書の構成
henry-anatomy-skills/plugins/henry-anatomy-search/docs 配下の各解体新書は共通の構成に従います。
{topic}-anatomy/
├── 00-index.md # 目次・概要・読み方ガイド
├── 01-overview.md # 全体像
├── 02-xxx.md〜 # 各章
└── appendix/
├── glossary.md # 用語集
└── important-files.md # 重要ファイル一覧
なぜドキュメントをpluginに同梱したのか
ドキュメントの置き場所には他にも選択肢がありました。notionやconfluenceのようなドキュメントツールに置く方法、プロダクトのリポジトリに同梱する方法、あるいは専用のドキュメントリポジトリを用意する方法です。
それらではなくpluginへの同梱を選んだのは、解体新書の最大の利用者がclaude codeであるということに基づいています。search-anatomyスキルがドキュメントを検索して回答する際、ファイルがローカルにあればそのまま読めます。外部サービスにドキュメントがあると、api経由での取得が必要になり、レイテンシや認証の問題が生じます。
また、githubでバージョン管理されることで、解体新書の変更履歴がコードと同じワークフローで追跡できます。PRでレビューでき、誰がいつ何を変えたか分かるので透明性が得られます。
Pluginの設計：3つのSkillで回すサイクル
このPluginは、3つのSkillで「生成 → 活用 → 改善」のサイクルを回す設計になっています。
generate-anatomy：コードベースから解体新書を生成
/generate-anatomy 注射オーダー のようにトピック名を指定すると、コードベースを自動で調査し、解体新書を生成します。
内部はマルチエージェント構成で、以下のステップで動作します。
- 並列コードベース探索: バックエンド・フロントエンドそれぞれの探索エージェントが並列に起動し、ドメインモデル、DB設計、APIエンドポイント、画面構成などを徹底的に調査する
- 章立て計画: 探索結果をもとに章構成を設計し、セルフレビューの後にユーザーの承認を得る
- 章ごとの執筆: 計画に沿って各章を順に執筆する
- セルフレビュー: 生成後にコードとの整合性・網羅性・一貫性をチェックする
revise-anatomy：フィードバックに基づく修正
/revise-anatomy ADLの説明がない --anatomy cost-sync のように、自然言語のフィードバックで修正を依頼できます。
修正の際にはコードベースと突合し、ドキュメントの記述が実装と合っているかを検証します。フィードバックに基づく修正だけでなく、突合の過程で発見した乖離も合わせて修正するため、ドキュメントの鮮度が自然と保たれます。
search-anatomy：解体新書の横断検索
/search-anatomy 注射オーダー 診療科 のようにキーワードを指定すると、複数の解体新書を横断的に検索し、関連情報を統合して回答します。
ここで重要なのが、読み手の切替機能です。Claude Code の AskUserQuestion を使って、はじめにエンジニア向けなのか、非エンジニア向けなのかを質問するようにしています。エンジニア向けにはコードパスやクラス名を含めた詳細な回答を、非エンジニア向けには概念や業務フローを中心としたわかりやすい回答を返します。
これまでは、どちらかを意識したドキュメントを書かなければなりませんでしたが、AIエージェントを挟むことによって、どちらの読み手にも適した出力になるのが特徴です。
search/editorの2Plugin構成について
このPluginは、検索系（henry-anatomy-search）と編集系（henry-anatomy-editor）の2つのプラグインに分かれています。
理由はシンプルで、editor側はコードベースへのアクセスが必要ですが、search側は解体新書ドキュメントを同梱しているためコードベースが不要です。この分離により、PdMやQAなどのコードベースを持たないメンバーもsearch側だけをインストールしてドメイン知識にアクセスできます。
なお、ヘンリーではPlugin Marketplaceでチーム内に配布する運用が進んでいますが、この仕組みについては別の記事で紹介予定です。
設計で注力したポイント：ドキュメントの構成設計
search-anatomy は質問がある時に使うスキルですが、オンボーディングの時など、そもそもの機能を理解したい時にはまとまった情報を読むことが有用な場合もあります。そこで、生成されたドキュメントは人が読むことも意識して、「構造」をしっかりと設計することを行いました。
Part→章の階層構成
各解体新書は、以下のPartに分かれています。
| Part | 内容 | 目的 |
|---|---|---|
| Part 1: 概要 | 全体像、登場人物、主要概念 | まず大枠を掴む |
| Part 2: ドメインモデル | クラス設計、値オブジェクト、集約 | 設計の「なぜ」を理解する |
| Part 3: 主要フロー | 業務フローごとの処理の流れ | 実装の道筋を掴む |
| Part 4: DB設計 | テーブル構造、リレーション | データの持ち方を把握する |
| Part 5: システム連携 | 外部システムとの接続 | 影響範囲を理解する |
| Part 6: 付録 | 用語集、重要ファイル一覧 | 辞書として使う |
この構成は、読者が第1章から順に読んでも段階的に理解が深まるように設計しています。新メンバーは最初から通読し、既存メンバーは必要な章だけ参照する、という使い分けが自然にできます。
読者が迷わないための工夫
各章には以下の要素を含めるようにしています。
- 学習目標: その章で何が分かるようになるか
- 概念説明 → コード例 → まとめの繰り返し構造
- Mermaid図: フロー図、状態遷移図、シーケンス図、ER図を適宜配置
- 比較表: 類似概念の違いを明確化
また、付録の用語集と重要ファイル一覧により、「この用語の意味は？」「このロジックはどのファイルにある？」といった問いにも対応できるようにしています。
ビジョン：ドメインエキスパートAIをチームで育てる
解体新書Pluginの本質は、単にドキュメントを自動生成することではありません。チームでドメインエキスパートAIを育てる基盤を作ることです。
解体新書 = ドメインエキスパートの知識ベース
解体新書をコンテキストとして読み込んだエージェントは、そのドメインの専門家として振る舞えます。例えば「注射オーダー」の解体新書を読み込んだエージェントは、注射オーダーの専門家として以下のようなことができます。
- 「注射オーダーの実施記録を変更したいが、影響範囲は？」に対して、コスト連携や監査への波及を含めた正確な回答を返す
- 実装時のコンテキストとして機能し、ドメインの慣例に沿った設計判断を提案する
- コードレビューで、ドメインロジック上の矛盾を指摘する
コードベースを毎回探索するのとは異なり、体系的に整理された知識に基づいて回答するため、精度と速度の両方が向上します。
非エンジニアも含めた知識の民主化
search-anatomyの「読み手切替」は、この思想を体現した機能です。エンジニアはコードレベルの詳細を確認でき、PdMやQAはビジネスフローレベルで理解を深められる。同じ知識基盤を、それぞれの立場で活用できます。
コードベースを持っていなくてもsearch Pluginさえインストールすれば使えるため、ドメイン知識へのアクセスに技術的な障壁がありません。
育てるサイクル
ドキュメントは一度作って終わりにしません。revise-anatomyでフィードバックを反映し、コードとの突合で乖離を検出し、修正する。このサイクルを回すことで、解体新書は徐々に精度を上げていきます。
実際に、解体新書の内容に不足を見つけたメンバーが自発的にreviseを実行し、改善してくれるケースが生まれています。
とはいえ、現状のサイクルは人の自発性に依存しています。コードは日々変わるので、理想的にはソースコードの変更に連動して解体新書も自動更新されるべきです。現在、GitHub Actionsに組み込んで差分を検知し、影響のある章の更新を自動で走らせる仕組みを検討しています。人手による改善と自動更新の両輪が揃えば、解体新書の鮮度はより安定して維持できるようになるはずです。
そして解体新書の精度向上は、そのままドメインエキスパートAIの進化に直結します。チームのメンバーがフィードバックを通じてドキュメントを改善するたびに、エキスパートAIが賢くなっていく。これは従来のドキュメント管理とは異なる、チーム全体でAIを育てるという新しいアプローチです。
┌─────────────┐
│ generate │ コードベースから解体新書を生成
└──────┬──────┘
▼
┌─────────────┐
│ search │ ドメインエキスパートとして活用
└──────┬──────┘
▼
┌─────────────┐
│ revise │ フィードバックで精度向上
└──────┬──────┘
│
└──────▶ ドメインエキスパートAIの進化
現状の効果と今後
コードから探したり、「あの人に聞かないと分からない」が減った
解体新書の導入前、ドメイン知識を得る手段はコードを読みに行くか、詳しい人に聞くかの大きく2つしかありませんでした。しかもその「詳しい人」は別チームにいることも珍しくなく、「あの仕様どうなってましたっけ」という質問がSlackで飛び交っていました。何度も回答しているだろう質問も中にはあり、申し訳なくなる時もあります。
解体新書の導入後は、それが少しずつ改善されているように思います。まず、エンジニアがコードから探す時間が削減されました。 そして以前なら別チームのメンバーに質問していたような場面でも、解体新書を引けば答えが見つかるようになったので、問い合わせを受ける側の負荷軽減にもつながりました。
さらに嬉しかったのは、QAメンバーからの反応です。「エンジニアに聞かなくても仕様が理解できるようになった」という声をもらいました。コードベースから生成されたドキュメントが、エンジニア以外にも価値を届けられている。これは当初想定していた以上の効果でした。
自発的に広がるアクセスの輪
もうひとつ、作り手として特に嬉しい変化がありました。解体新書をNotionやSlackと連携して、エンジニア以外も含めてもっとアクセスしやすくしよう、という動きがチーム内で自発的に生まれました。ツールは作った人が「使ってください」と言い続けなければ広まらない、というのはよくある話ですが、逆に価値を感じた人が自ら広めてくれるのは、仕組みとしてうまく回り始めたサインだと感じています。
これからやりたいこと
このスキルを利用して動くドメインエキスパートエージェントとして開発フローに組み込むことです。設計レビューで「この変更、〇〇の機能に影響しませんか？」と指摘してくれるエージェント。実装時に「この領域の設計パターンはこうなっています」と教えてくれるエージェント。解体新書という知識基盤があるからこそ実現できる、ドメインを理解したAIとの協働を目指しています。
もうひとつの課題は鮮度の維持です。コードは日々変わっていくので、解体新書も放っておけば陳腐化します。コード変更を検知して、影響のある章の更新を自動で提案する仕組みを作れれば、「ドキュメントがコードに追従し続ける」という、これまで不可能だったことが現実になります。
「ドメインエキスパートAIをチームで育てる」というビジョンは、まだ道半ばです。でも、QAメンバーが仕様を自力で読み解き、チームメイトが自発的に活用の輪を広げてくれているので、そのビジョンはきっと達成できるものだと思います。
おわりに
医療ドメインのように複雑な領域では、ドメイン知識そのものが開発の生産性を左右します。Claude Code Pluginでドメイン知識を体系化し、チームで育て、エンジニアも非エンジニアも活用できる形にする。この取り組みはまだ発展途上ですが、ドメインエキスパートAIをチームで育てるというビジョンに向けて着実に歩みを進めています。
この記事が、複雑なドメインを持つプロダクトの開発に関わる方の参考になれば幸いです。
id:nabeop
