Claude Code仕様駆動開発
Markdownから本番デプロイまで
Netsujo株式会社では2026年3月からClaude Codeを全業務の中核に据え、複数プロダクトを並列運用しています。この運用を支えているのが「仕様駆動開発」という考え方です。Markdownで書いた仕様書をSub-Agents・MCP・Hooks・Skillsの組み合わせで動かし、生成と評価を分離した品質ゲートを経て公開します。本記事では、22部署+7顧問の仮想会社運営を回しながら蓄積してきた、仕様駆動開発の実践手順と失敗事例を公開します。
想定読者
Claude Codeを業務の中核に据えたいITエンジニアの方
個人開発者・1人CTOで複数プロダクトを並列運用している方
AIエージェントの運用設計・品質ゲート設計に関心のあるチームリードの方
— 01
なぜ仕様駆動開発に行き着いたか
「対話→コード」のフローには限界があります。指示は揺れ、解釈は曖昧になり、レビューは追いつかなくなります。（脳も手も追いつかなくなってくる）並列で複数案件を抱えると、この問題は指数関数的に悪化します。
Netsujo株式会社が運用しているのは、コーポレートサイト・自社メディア・受託案件・自社プロダクトなど複数のリポジトリです。「いま何が決まっていて、何が未決か」を毎回AIに確認したり説明したりするコストは膨大でした。そこで、仕様を口頭ではなくMarkdownファイルに固定し、Claude Codeが毎回そのファイルを参照する運用へ切り替えました。これが仕様駆動開発の出発点です。
仕様書はシステムのソースコードと同じ意味を持ちます。gitに履歴が残り、diffでレビューでき、参照だけで実装精度が変わります。「ここを読んでから実装して」と仕様書のパスを渡すだけで、Claudeの出力は別物になります。
ちなみに、仕様書はChatGPTで書く場合がほとんどです。（弊社の使い方がこなれていなかったり、他にやりようがある可能性はあるのですが、現時点ではChatGPTの方が品質が高い認識です。実装はまるっとClaude Codeにお願いしています）
— 02
仕様書をMarkdownで書くと何が変わるか
仕様書の効能を4点に整理します。
AIが毎回参照する判断基準になる
ですます調・「思います」禁止のような文体ルールから、品質ゲートの順序、本番反映の承認フローまで、判断に必要な情報を1カ所に集約します。
レビュー履歴がgitに残る
仕様書の変更もPull Requestとして議論できます。いつ・なぜ・誰がその判断を下したかが記録されます。
失敗の記憶が組織の財産になる
.company/lessons-learned/に「同じ失敗を2度起こさない」ためのケースを蓄積し、仕様書から逆引きできるようにします。
新しいエージェントへの引き継ぎコストが下がる
新セッションでも仕様書を読み込ませれば、過去の合意事項を瞬時に共有できます。
Netsujoの.company/CLAUDE.mdはタスクに応じた22の専門部署の運営ルール・召喚マトリクス・品質ゲート・本番反映の承認フローを1ファイルで定義しています。rootのCLAUDE.mdには基本方針・デザインルール・GSC監査ルールなどが集約されており、各部署・各プロジェクトのCLAUDE.mdがその実装を担います。階層構造を意識して書くことで、肥大化を抑えながら参照性を担保しています。
— 03
Sub-Agents — 並列実装の主役
Sub-Agentsは、メインエージェントから子エージェントを起動し、独立したコンテキストで作業させる仕組みです。Netsujo株式会社では以下の使い分けをしています。
メインエージェント
全体オーケストレーションに専念。仕様書の読み込み、振り分け判断、最終レビューを担当します。
Sub-Agent（探索系）
ファイル横断の調査、過去事例の遡及、grepベースのマップ化を担当します。「200行以内・要約のみ・引用禁止」のような分量制限を必ず明示します。
Sub-Agent（実装系）
独立した実装タスクを並列で処理します。worktreeで親リポジトリを汚さず、完了後にPRを起こします。
Sub-Agent（レビュー系）
複数視点のレビューを並列で取得します。デザイナー・編集者・法務・経営など、観点が独立している場合は1メッセージで複数Agentを同時起動します。
.company/protocols/subagent-exploration-pattern.mdには、以下の閾値を超えたら強制的にSub-Agentに分離するルールを定義しています。
- ▸3ファイル以上を読む必要がある探索
- ▸30分以上かかる単一タスク
- ▸残コンテキストが50%以下
- ▸2視点以上のレビューが必要
失敗事例: Sub-AgentがReadせずにEditを試みて失敗するパターンが頻発しました。対処として、Sub-Agentへの指示テンプレートに「Edit前に必ずReadを実行する」を明記し、Hooksで再発を検知できるようにしています。
— 04
MCP — 外部システムをAIから触る
MCP（Model Context Protocol）は、Claudeから外部システム（Google Workspace・GSC・Notion等）を呼び出すための標準プロトコルです。Netsujo株式会社で稼働している主なMCPサーバーは以下です。
google-workspace
Docs/Sheets/Slides/Gmail/Calendar/Driveを一括操作。週次GA4レポートをDocsに自動生成し、Discordに投稿する運用やスライド資料生成に使っています。
gsc
Google Search Consoleの検索パフォーマンス・URL Inspection・Sitemap状態を取得。quick winsの自動検出に活用しています。
chrome-devtools
Lighthouse監査・ネットワーク分析・パフォーマンス計測をMCPから実行できます。
memory
エンティティ・リレーションを永続化し、セッション間で参照可能にします。
notion / canva
ドキュメント連携・デザイン素材連携。
実例として、scripts/gsc-weekly-audit.pyを毎週月曜09:00 JSTにGitHub Actionsで自動実行し、Sitemap・URL Inspection・Search Analytics・canonical mismatch・CTR低迷を網羅監査してDiscordに通知しています。「人間に聞かれてからチェック」する受動運用を廃止し、週次フル監査を仕組みに組み込みました。
MCPの魅力は、Claude APIキーや別のクライアント実装を用意しなくても、Claude CodeのなかからGA4/GSCに触れられることです。アクセス分析・SEO監査・問い合わせ対応をかなり高速に運用できます。
— 05
Hooksによる品質ゲート
Hooksは特定のタイミング（session-start/pre-tool/post-tool/Stopなど）で任意のスクリプトを実行する仕組みです。Netsujo株式会社では以下を組み込んでいます。
Stop hook（Discord通知）
セッション終了時にDiscordへサマリを自動投稿。報告漏れを物理的に防止します。
自動セキュリティレビュー（security-guidanceプラグイン）
Edit/Write/commit/pushの各タイミングでClaude Code自身がコード差分をレビュー。yaml.load・pickle.load・生innerHTML・ハードコードsecret等のパターン警告を即座に出します。
conflict-marker残存検出（GitHub Actions）
マージコンフリクトの解決漏れをCIで検知。「同じ失敗を2度起こさない」を仕組みで担保します。
Hooksの本質は「人間の注意力に頼らずに品質を担保する」ことです。Claude Codeが仮に忘れたり漏らしたりしても、Hooksは忘れません。
— 06
Skills — 再利用可能なワークフロー
Skillsは頻発する作業手順を再利用可能なパッケージとして組織化する仕組みです。Claude Code標準の/verify・/code-review・/run・/loopなどに加え、Netsujo株式会社では自社Skillも整備しています。
schedule
cronで動くremote agentを作成・管理。週次・月次の定型タスクを自動化します。
fewer-permission-prompts
過去のトランスクリプトを解析し、頻出する読み取り系コマンドを.claude/settings.jsonに追加して許可確認を削減します。
Skillは組織のベストプラクティスをAIに教える機構です。1度書いた手順を全エージェントが再利用でき、属人化を防ぐことができます。「補助金申請」「GSC週次監査」「PRレビュー&merge」のような頻発業務は、いずれSkill化を進めていく方針です。
— 07
並列実装の実例：コーポレートサイトの大規模改修
Netsujo株式会社のコーポレートサイトでは、2026年3月から4月の1ヶ月で200コミットを超える改修を1人で実施しました。Sub-Agent並列起動で「ケーススタディ3件新設/SEO17施策/GA4計測/ナレッジハブ/デザイン監査」を同一スプリント内に詰め込めたのは、仕様書 + Sub-Agent + MCP + Hooksの組み合わせがあったからです。
代表的な並列実装パターン:
サイト横断デザイン監査
「デザイナー」ロールのSub-Agentに監査を投げ、14項目を一覧化。優先度順に順次修正し、人間は方針決定とPRレビューのみを担当しました。
SEO17施策の一括改善
GSC/GA4のデータをMCP経由で取得し、改善項目を1つのPRで一括適用。53ページの「検出-インデックス未登録」修正、構造化データ警告5件のcodemod一括補正、旧URL30件のリダイレクトなどを含みます。
複数CMSスキーマ拡張
Strapi v5の新規コレクション（case-study/trust-signal）のスキーマ+TypeScript型+フロントエンドfetcherを同時生成。Railwayデプロイ・Cloudinary連携・Vercelリバリデーションまで一気通貫で実施しました。
デザインの複数パターン並走検証
worktreeで別ブランチを並列生成し、Scandinavian・オーガニック・アカデミック・マルチカラーなど複数テイストを1日のうちに比較できる体制を構築しました。
build/lint/tsc→push→PR→Preview→merge→本番動作確認までを1セッションで回せます。
— 08
レビューゲート設計
生成と評価を別エージェントに分離する原則は、Claude Codeハーネス設計の核心です。Netsujoでは以下の共通ゲートを敷いています。
実装完了 → 自動レビュー基層（security-guidanceがEdit / Stop / commit / pushで常時稼働） → jobs（デザイナーレビュー: UI/CSS/フォント/レイアウト変更時必須） → customer-success（UI/UX変更時はユーザー視点で確認） → security（認証・権限変更時必須） → cto（DB / デプロイ / 認証 / 環境変数変更時必須） → ceo（build / lint / test / 本番URL動作確認） → 本番デプロイ → オーナー報告
外部公開コンテンツ（ブログ・SNS・LP・プレスリリース）には追加ゲート（editor → jobs → research fact-check → legal → ceo → オーナー下書き共有 → オーナー明示承認後に公開）を設けています。また、評価器の運用には「厳格チューニング原則」を明文化しています。
- ▸「概ね良い」「小さな問題だから大丈夫」判定は禁止
- ▸1点でも基準未達なら差し戻し
- ▸差戻し時は「どのファイル・どの行・何をどう変えるか」の具体的修正指示を必須記載
- ▸AIが弱い領域（デザイン・コピー・トーン・UX摩擦点など）には重みを置く
- ▸生成器（実装担当）と評価器は別エージェント・別セッションで起動する
本番反映の承認フローも厳格です。「進めて」「OK」「続けて」は作業継続の指示であり、merge OKではありません。「mergeして」「マージして」「本番反映して」と明示的に指示があって初めてmergeさせるようにします。
過去の失敗事例: 2026-04-22に「進めて」をmerge OKと短絡解釈し、独断で複数PRをmergeさせてしまった事例がありました。仕様書に「指示キーワードの解釈表」を追加し、再発防止策としています。
— 09
失敗事例と対処
仕様駆動開発を回すなかで蓄積した、再発防止すべき失敗を共有します。
Strapi APIトークン再発行忘れ
Railwayでenvを変更後、トークン失効で本番データ書き込みが停止しました。vercel env pullでのトークン取得手順をmemoryに固定し、トークンが絡む作業前に必ず再確認するフローにしました。
.company/lessons-learned/に記録し、INDEX.mdから逆引きできるようにしています。
まとめ — 5つの組み合わせ価値
Netsujo株式会社の運用が示していることは、Claude Codeは単体の対話ツールではなく、仕様書を中心とした開発のためのプラットフォームだということです。
仕様書
組織の判断基準をMarkdownで固定し、AIが毎回参照する
Sub-Agents
探索・実装・レビューをコンテキスト分離して並列処理する
MCP
外部システム（GSC・GA4・Notion等）をAIからシームレスに操作する
Hooks
人間の注意力に頼らず品質を自動担保する
Skills
組織のベストプラクティスを再利用可能なパッケージにする
5つの組み合わせが揃って初めて、1人で複数プロジェクトを並列実装しながら品質を落とさない運用が成立します。仕様書はAIに対する組織のソースコードです。組織が学んだことを仕様書に反映し続けることで、同じ失敗を2度起こさないガードレールを敷いて、判断の再現性を担保できます。
Netsujo株式会社は「Web3/AIを社会実装する第一人者」を目指す会社です。自社プロダクト・受託案件を回しながら、AI開発文化そのものの実装も並走させています。仕様駆動開発は、私たちにとって組織運営の方法論であると同時に、これからWeb3/AIを実装する全ての企業に対して提示できる、再現可能なフレームワークです。
Netsujo株式会社が運営するITエンジニアコミュニティ「みやこでIT」では、Claude Codeの運用知見を継続的に共有しています。仕様駆動開発の具体的な仕様書サンプル・Sub-Agent起動スクリプト・Hooks設定例に関心のある方は、ぜひお問い合わせください。