松葉 / Matsuba での開発ワークフローの実践/ Skills & Subagents on Claude Code
松葉 / Matsuba は、AI コーディング支援ツール「Claude Code」を用いて開発しています。本資料では、まず Claude Code の中心となる4つの機能と、その土台となるプロジェクトナレッジ（docs）を説明し、続いて松葉 / Matsuba がどのような技術で組み上がっているかを紹介したうえで、その開発を「Skills（スキル）」と「Subagents（サブエージェント）」でどのように仕組み化し、日々どう実践しているかをお伝えします。専門用語には初出で短い注釈を添えています。
Claude Code の4つの機能Four building blocks
Claude Code は、対話しながらコードの調査・作成・修正を行える開発ツールです。松葉 / Matsuba の開発では、その中でも次の4つの機能を組み合わせて使っています。いずれも公式に用意されている仕組みで、それぞれ役割が異なります。
| 機能 | 一言でいうと | この開発での役割 |
|---|---|---|
| CLAUDE.mdProject instructions | プロジェクト共通の指示や前提を書いておくと、毎回自動で読み込まれるファイル。 | 全体で守る共通ルールと、各種資料への索引。すべての作業がまず参照する土台です。 |
| SkillsAgent Skills | 特定の作業のときだけ読み込ませる、手順や知識をまとめた部品。 | 「各工程のやり方」と「領域ごとの設計知識」を部品として持たせ、必要な場面でだけ開きます。 |
| SubagentsSubagents | 本体とは別に動く、役割と持ち物（参照する知識）を固定した補助の担当。 | 実装・レビュー・監査を役割ごとに切り出し、本体とは別々に作業させます。 |
| slash commandsSlash commands | よく使う操作を「/ 名前」の一語で呼び出す仕組み。 | 対話の起動や、作業の締め（変更をまとめて記録する操作）を、決まった手順で呼び出します。 |
読み方: 利用者が slash command でメインエージェント（本体）を起動します。メインは CLAUDE.md（常時の前提）を参照し、必要時に Skills を開き、一部の作業を Subagents（サブエージェント）へ委任します。金茶の矢印が示すとおり、CLAUDE.md は「索引」として、Skills は「入口」として、いずれも最終的にプロジェクトナレッジ（docs）＝必要知識をすべて収めた唯一の正解を指し示します。Subagents も同じ Skills を通じてナレッジを参照します。
プロジェクトナレッジ（docs）Project knowledge
先ほどの4機能とは別に、開発の土台となる文書群があります。これは Claude Code の機能ではなく、プロジェクトが自前で持つ知識の集まりです。設計ルールだけでなく、基本構想・要件・業務の仕様・機能や画面の詳細・実装の段取りまで、開発に必要な知識をすべて収めた「唯一の正解」で、本資料ではこれを「プロジェクトナレッジ」と呼びます。4つの機能は、いずれも最終的にこのプロジェクトナレッジを拠り所にします。
どんな情報が入っているかWhat it holds
プロジェクトナレッジは大きく次の分類で整理されています（各分類の中身の詳細は割愛します）。
| 分類 | 入っている情報 |
|---|---|
| 基本構想 | プロダクトの目的・スコープ・要件・業務の仕様、ブランドやトーンの決まり。 |
| 機能の詳細 | どんな機能（業務処理）があるかのカタログと、その仕様。 |
| 画面の詳細 | どんな画面があるかの一覧と、機能との対応関係。 |
| デザイン | 配色・字体・コンポーネントなどのデザイン方針。 |
| 設計ルール | 領域ごと（クラウド・フロント・サーバ・データベース・テスト・CI/CD）の作り方の決まり。 |
| 実装の段取り | どの順で作るか（ロードマップ）と、作業のまとまりへの分割。 |
4機能との関係How it connects
プロジェクトナレッジそのものは人が整備し、Claude Code の4機能がそれを正しく参照するように役割分担しています。
| 機能 | プロジェクトナレッジとの関係 |
|---|---|
| CLAUDE.md | どこを読めばよいかを示す「索引」。作業の前に、まずここから該当箇所へ辿ります。 |
| Skills（知識） | ナレッジへの「入口」。事実を書き写さず、読むべき箇所を指し示すことに徹します（書き写すと、後で食い違う原因になるため）。 |
| Subagents | 担当する作業のとき、知識のスキルを通じてプロジェクトナレッジを参照します。 |
要点: プロジェクトの知識はプロジェクトナレッジ（docs）に一元化し、CLAUDE.md（索引）→ Skills（入口）→ Subagents（参照）という経路で、関係者全員が同じ「唯一の正解」を見ます。知識を写して持たないことが、内容の食い違いを防ぐ鍵です。
プロジェクトの全体像と採用技術What we build, and how
ワークフローの話に入る前に、対象となるプロジェクトそのものを紹介します。松葉 / Matsuba は、お取引先と社内をつなぐ業務ファイル共有基盤です。画面・サーバ処理・データ保管・非同期処理といった性質の異なる複数の領域から成り、それぞれが守るべき決まりも異なります。この「領域ごとに決まりが違う」という性質が、後半で述べる役割分担の土台になります。
読み方: ソースコードは1つのリポジトリに集約（モノレポ）し、性質の異なる領域に分けて管理します。各領域が守る決まりは「プロジェクトナレッジ（docs）」に集約され、ここが唯一の正解です。実装は「作業のまとまり」単位で、決まった工程を順に通して進めます。
採用技術Technology stack
現在の Web 開発で主流かつ実績のある技術を、TypeScript と Go を主言語として組み合わせています。ロゴは Simple Icons（オープンソースの公式ブランドアイコン集）から、資料の配色に合わせて単色で表示しています。
| 領域 | 採用技術 | 主要ロゴ |
|---|---|---|
| Web フロントFrontend | Next.js 16（App Router） / React 19 / TypeScript。画面の静的な部分と動的な部分を1ページ内で分けて配信します。 |    |
| UI・スタイルUI | Tailwind CSS / shadcn/ui。共通の見た目の部品を、松葉のデザインに合わせて調整して使います。 |   |
| サーバ処理Backend | Hono（軽量な API フレームワーク） / Node.js。クリーンアーキテクチャ（後述）の4層構成で組みます。 |   |
| 認証・認可Auth | Better Auth。社内はシングルサインオン、社外はメールのワンタイムコードによる二要素認証で利用者を確かめます。 | BA |
| データベースDatabase | PostgreSQL（Supabase 提供）。取引先ごとの越境をデータの最下層（行単位）で遮断します。 |   |
| 型共有・ORMType sharing | Prisma / Zod（入力検証）。画面からデータベースまでを同じ型定義で貫き、ズレをビルド時に検知します。 |   |
| 保管・検査Storage & scan | Google Cloud Storage ＋ ClamAV（オープンソースのウイルス検査エンジン）。用途別にバケットを分離します。 |  AV |
| 非同期・ジョブAsync & jobs | Cloud Run（サーバレス実行基盤） / Pub/Sub（非同期メッセージング） / Go 製のワーカー。イベント駆動で連携します。 |  |
| CI/CD・基盤CI/CD | GitHub Actions（自動ビルド・デプロイ） / Docker / Terraform（構成のコード化）。デプロイは鍵ファイルを持たない認証（Workload Identity Federation）で行います。 |    |
実装の要点Implementation principles
クリーンアーキテクチャ
サーバ処理を4つの層に分け、業務のルールを中心に据えます。内側の層が外側のライブラリに依存しない構造にすることで、部品の差し替えや変更に強くなります。
端から端まで型安全
画面・サーバ処理・データベースを同じ型定義で貫きます。どこかを変更したときのズレが、動かす前（ビルド時）に自動で見つかります。
多層防御（ウイルス検査）
アップロードされたファイルは、検査前と検査後で物理的に別々の保管場所に置きます。未検査のファイルが業務の動線に紛れ込まない構造です。
行単位のアクセス制御
取引先をまたぐアクセスを、アプリだけでなくデータベースの最下層（行単位）でも遮断します。上位の処理に誤りがあっても、データベースの側で越境を防ぐ二重の備えです。
開発ワークフローの実践The workflow in practice
ここからが本題です。前述のとおりプロジェクトは領域ごとに決まりが異なり、実装は「作業のまとまり」単位で複数の工程を通して進めます。この開発を、Skills と Subagents を使って3つの層に整理し、役割を分担して回しています。全体の構成を先に図で示します。
読み方: あなたと対話できるのはメインエージェント（中枢）だけです。中枢がその工程の手順（プロセススキル）に従い、工程に応じてサブエージェント（専門役）を起用します（枠内の5役）。専門役は領域ごとの知識（ナレッジスキル）を通じて、唯一の正解であるプロジェクトナレッジ（docs）を参照します。実装役は曖昧な点があれば推測せず質問を返して止まり、レビュー役は指摘だけを行い、指摘がゼロになるまで点検を繰り返します。
3つの層の役割Three layers
| 層 | 役割 | 補足 |
|---|---|---|
| プロセススキルProcess skills | 各工程の手順の「唯一の正解」を持つ。 | 手順を改善すると、1か所の修正がすべての作業に反映されます。 |
| ナレッジスキルKnowledge skills | 領域ごとの設計知識への入口を持つ。 | 実装役とレビュー役が同じものを参照するため、知識のズレが起きにくくなります。 |
| 専門役Subagents | 役割・参照する知識・使うモデルを固定した担当。 | 実装役・レビュー役・監査役の5役に分かれています。 |
| 中枢Main | 対話・意思決定・統合・確認を担う。 | 専門役は利用者と直接対話できないため、確認の関門は中枢だけに置きます。 |
専門役（サブエージェント）The specialist roles
| 役割 | 識別子 | 担当 |
|---|---|---|
| 実装役（サーバ側） | matsuba-backend-engineer | サーバ処理とデータベースの実装。 |
| 実装役（画面側） | matsuba-frontend-engineer | 画面とデザインの実装。 |
| レビュー役（仕様・計画） | matsuba-doc-reviewer | 仕様と作業計画の点検（指摘のみ）。 |
| レビュー役（実装） | matsuba-impl-reviewer | 実装したコードの点検（指摘のみ）。 |
| 監査役（セキュリティ） | matsuba-security-auditor | 認証・認可まわりのセキュリティ点検。 |
役割の契約（振る舞いの約束）: 実装役は、仕様に曖昧な点があれば推測で進めず、質問をまとめて返していったん止まります。変更を確定・記録する操作は行いません。レビュー役は、修正はせず指摘だけを行い、根拠を引用できない指摘はしません。指摘は「修正 → 再点検」を繰り返し、ゼロになって初めて工程を終えます。
工程ごとのサブエージェントの分担Who does what
| 工程 | 中枢がやること | 起用する専門役（識別子） | 体数 |
|---|---|---|---|
| ① 仕様と計画 | 仕様の意思決定・確認 | 調査系のみ（専門役なし） | 0 |
| ② 仕様レビュー | 指摘の裁定・修正 | レビュー役（仕様・計画）matsuba-doc-reviewer | 1 |
| ③ 実装 | 作業の分解・要所の実装・統合 | 実装役 matsuba-backend-engineer ／ matsuba-frontend-engineer（並行可） | 〜2 |
| ④ 実装レビュー | 裁定・修正・手順書の出力 | レビュー役（実装）matsuba-impl-reviewer ＋必要時 監査役 matsuba-security-auditor | 1〜2 |
| ⑤ リファクタリング | 影響範囲の判断 | 機械的な適用のみ実装役へ委任 | 必要時 |
| ⑥ 改善・仕様変更 | 依頼の受領・対話 | 内容が固まった作業のみ実装役へ委任 | 必要時 |
運用の3ルールThree operating rules
1. 委任は中枢の判断で、指定があればそれを優先: どの作業を誰に任せるかは中枢が文脈から判断します。作業指示書に委任先が書かれていれば、それに従います。
2. 並行作業の衝突を防ぐ: 全体で共通の部品は中枢が先に確定させ、各担当には作業する範囲を割り当てて、同じ箇所を2人が触らないようにします。
3. 点検は再点検で閉じる: 指摘は「修正 → もう一度レビュー役で確認」を繰り返します。自己申告では終わらせず、指摘ゼロで工程を完了します。
整備した資産の全体像The organized toolset
このワークフローを支える部品の一式です。各部品の中身（具体的なルールや手順の文面）には触れませんが、種類ごとに名前・識別子・概要を一覧にします。識別子（matsuba-… など）は、実際に呼び出すときの名前です。
ナレッジスキル（設計知識の入口・6本）Knowledge skills
| 領域 | 識別子 | 概要 |
|---|---|---|
| 画面デザイン | matsuba-frontend-design | 配色・字体・トーン・使いやすさ（アクセシビリティ）の決まり。 |
| 画面実装 | matsuba-frontend-impl | 画面の配置ルール、表示の最適化、画面とサーバ間の型の受け渡し。 |
| サーバ処理 | matsuba-backend | サーバ処理の設計（4層）、処理の一貫性、エラーや記録の共通ルール。 |
| データベース・共通部品 | matsuba-db-repo | データベース設計、行単位のアクセス制御、共通部品の取り決め。 |
| テスト | matsuba-testing | テストの方針と、手元での実行／自動での実行の切り分け。 |
| 基盤 | matsuba-infra | クラウド構成、自動デプロイ、非同期処理の取り決め。 |
プロセススキル（工程の手順・6本）Process skills
| 工程 | 識別子 | 概要 |
|---|---|---|
| 仕様と計画 | matsuba-spec-and-plan | 詳細な仕様と作業計画を作る手順。 |
| 仕様レビュー | matsuba-review-spec-and-plan | 仕様と計画を点検する手順。 |
| 実装 | matsuba-implement | 実装を進める手順（分担と並行作業の管理）。 |
| 実装レビュー | matsuba-review-implement | 実装したコードを点検する手順。 |
| リファクタリング | matsuba-refactor | コードを整理・改善する手順。 |
| 改善・仕様変更 | matsuba-brush-up | あとから来た要望に対応する手順。 |
資料デザインスキル（1本）Docs design
| 用途 | 識別子 | 概要 |
|---|---|---|
| 開発過程資料の体裁統一 | matsuba-docs-design | この種の解説資料の見た目を揃える部品。本資料もこれで作成しています。 |
専門役サブエージェント（5体）と、使うスキルSubagents & their skills
| 役割 | 識別子 | 使う（読み込む）スキル | 概要 |
|---|---|---|---|
| 実装役（サーバ側） | matsuba-backend-engineer | matsuba-backend／matsuba-db-repo／matsuba-testing | サーバ処理とデータベースの実装。 |
| 実装役（画面側） | matsuba-frontend-engineer | matsuba-frontend-impl／matsuba-frontend-design／matsuba-testing | 画面とデザインの実装。 |
| レビュー役（仕様・計画） | matsuba-doc-reviewer | 対象に応じて各ナレッジスキルを参照 | 仕様・計画の点検（指摘のみ）。 |
| レビュー役（実装） | matsuba-impl-reviewer | 対象に応じて各ナレッジスキルを参照 | 実装したコードの点検（指摘のみ）。 |
| 監査役 | matsuba-security-auditor | 本番データベースの裏取りが中心 | 認証・認可まわりのセキュリティ点検。 |
コマンド（2つ）Slash commands
| 用途 | 識別子 | 概要 |
|---|---|---|
| 対話の起動 | /grill-me | 資料や計画を突き詰めるための対話を始める。 |
| 作業の締め | /wrap-up | 変更をまとめて記録する（変更を残す唯一の正規手順）。 |
このほか、作業のまとまりを始めるための「工程ファイルの雛形（テンプレート）」一式があります。
置き場所について: これらの部品はソースコードと同じリポジトリで管理しています。改善の履歴が変更の記録として残り、内容をレビューできる形で積み上がっていきます。
実現していること／今後Outcome & next
この仕組みによって、開発の進め方は次のような状態になっています。
品質の再現性
手順が一元化されているため、どの作業も同じ工程・同じ点検を通ります。担当や日をまたいでも、進め方がぶれにくくなります。
領域別の分担
画面・サーバ処理・データベースといった領域ごとに、その領域の決まりを持った専門役が実装します。
独立した再点検
実装した担当とは別のレビュー役が、実装とは別のコンテキストで点検します。指摘がゼロになるまで繰り返すため、確認前に漏れを拾えます。
中枢の集中力の温存
定型に近い作業を専門役へ切り出すことで、中枢は仕様の意思決定と統合に集中できます。
育て方と今後Growing the system
知見をためて強くする: 実装中に新しい注意点が見つかったら、該当するナレッジスキルに一行足します。一度の追記がその後のすべての作業に効くため、使うほど知見が積み上がっていきます。
横への展開: スキルの形式は他の AI 開発ツールでも利用できるため、将来の併用も設計上は可能です（互換性の詳細は、その時点の仕様を都度確認します）。