[ AI-driven Dev ]

Yakumo の AI 駆動開発のリアル：受託と自社プロダクトを Claude Code で並走させる

受託と複数の自社プロダクトを Claude Code で同時に運用するには、3層責務分離・config駆動・領域責任者エージェント・モデル使い分けポリシー・PreToolUse hook による設計原則が不可欠である。

Author: 森本拓見 Updated: May 11, 2026
#claude-code #ai-driven-dev #yakumo #case-study

課題：複数プロダクト並走時の AI 駆動開発を安定化させる

Claude Code でコード生成が高速化したのはもう当たり前だ。しかし受託案件と複数の自社プロダクトを同時に運用する規模で、AI 駆動開発を本番化しようとすると、別の難題が現れる。

「エージェントが判断した」「スクリプトが変更した」「AI が生成した」という作業の履歴が混在したとき、本来なら人間が追跡できるはずの因果関係が失われやすい。config が散らばっていれば、どちらが正しい設定値か曖昧になる。ガードレールがなければ、AI は躊躇なく共有外フォルダに書き込む。こうした「環境の不安定さ」がスケール時に致命的になる。

八雲が直面したのは、これらの問題だ。複数プロダクトを並走させる中で「これが無いと壊れる」と気づいた設計原則がある。その知見を整理する。

パターン：5つの設計原則

1. 3層責務分離 — SSOT の一元化

情報・データ・アクションの置き場所を 3 層に厳密に分離している。

層役割例
Notion人間のアクション・視覚管理タスク・プロジェクト進捗
リポジトリシステム・仕様・ロジックconfig/・scripts/・.claude/
Google Driveドキュメント・データ実体書類・スプレッドシート・議事録

SSOT（Single Source of Truth）は必ず 1 層のみに置く。たとえば顧客マスタは config/clients.json だけが正。Notion に見えるのはビュー。二重管理は認めない。「どちらが正か」の確認コストが組織に蓄積するから。

2. config 駆動・ハードコード禁止

マジックナンバーを禁止する。スコアリング閾値・パイプライン列定義・動画タイミング値・フォント・色・スペーシング——すべて集約 config から参照する。

具体例：

# config/scoring.yaml
thresholds:
 high: 0.8
 medium: 0.5
 low: 0.3
model_strategy:
 deterministic_rules: script
 classification: haiku
 creative: sonnet
 synthesis: opus

Claude Code に記述させる際も CLAUDE.md に明示し、AI が勝手にハードコードしないようガイドする。

3. 領域責任者エージェントパターン — 判断履歴の追跡可能性

業務実行を AI に任せる場合、必ず領域責任者エージェント経由にする。

main-thread
 ↓ (指示)
@director / @sales-director / @dev-director
 ↓ (判断)
/skill-name (実行)
 ↓ (結果・議事録・判断根拠)
Notion タスク更新

営業スキルは @sales-director が使い、開発進捗は @dev-director が見る。横断判断は @director へ。このチェーンを維持することで、「何がどのエージェントによって判断されたか」が後追い可能になる。責任の所在がコード・config で明示される。

4. モデル使い分けポリシー — 決定論的処理は LLM を使わない

決定論（テンプレート適用・書式整形・JSON 変換）に LLM を消費しない。品質が不安定な割にコストが乗るから。

処理タイプ採用モデル
定型フォーマット・書式変換・JSON 加工Script / Shell
分類・スコアリング・パターンマッチHaiku
要件理解・設計検討・リライト初版Sonnet
複雑な判断・創作・多段階推論Opus

5. PreToolUse hook — ガードレール実装

Claude Code の PreToolUse hook でリスク操作を事前ブロックする。

具体的なガードレール：

  • Drive 書き込み前に認証・スコープ確認
  • 意図しない場所へのファイル配置禁止（共有ドライブ外 NG）
  • Git force-push・branch 削除の explicit 確認
  • センシティブデータの Slack 投稿ブロック

「禁止」をドキュメントに書くだけでは AI は守らない。code で実装する姿勢が必須。

設計の核：CLAUDE.md による環境仕様化

5つの原則は、すべて CLAUDE.md に明示した仕様を前提 としている。

# Project CLAUDE.md

## 層別責務
- Notion: タスク・進捗ビュー（read-only for scripts）
- Repository: config/scripts/.claude/ は SoT
- Drive: 記事・決算データの実体

## ハードコード禁止ルール
- フォントサイズ → design-tokens.ts
- パイプライン列名 → config/pipelines/*.json
- エージェント判定基準 → config/audience-tracks.json

## エージェント責任者
- @director: 事業判断
- @sales-director: 営業・提案
- @dev-director: 開発・技術判断

## モデル使い分け
- Haiku: 分類・スコアリング（<50ms）
- Sonnet: コード生成・リライト
- Opus: 多段階判断・複雑設計検討

AI はこの仕様を読み、それに従う。仕様が曖昧だと、AI も迷う。

Yakumo の適用例：3プロダクト + コーポレートサイト

Synapse — 業務横断エージェント基盤

Drive・GitHub・Gmail・Notion 横断の内部 OS。営業パイプライン・スクレイピング・提案生成・定型レポート。

config 駆動の例：

# config/pipelines/sales.json
{
 "stages": [
 {
 "id": "lead_classification",
 "agent": "@sales-director",
 "model": "haiku",
 "criteria": "config/scoring/lead-scoring.yaml"
 },
 {
 "id": "proposal_generation",
 "agent": "@sales-director",
 "model": "sonnet",
 "template": "templates/proposal-v2.yaml"
 }
 ],
 "hooks": ["PreToolUse/drive-write-guard", "PostExecution/notion-update"]
}

各 stage の責任者・モデル・ガードレールが config で明示される。

montage — AI コンテンツ生成パイプライン

動画大量生成エンジン。Researcher → Analyst → Scriptwriter → Composer → Reviewer → Thumbnailer の 6 段。

問題と対応：

Block Schema + Zod でバリデーション済みの出力も、視覚的に成立しているか別問題だ。

// Reviewer agent に指標を config で与える
const reviewCriteria = {
 visual_coherence: { min: 0.85, metric: "thumbnail_aesthetics" },
 script_readability: { min: 0.9, metric: "text_pacing" },
 audio_sync: { max_drift_ms: 200 }
};

データは valid → 視覚品質も valid という仕組みにした。Reviewer の判定基準を config で manage 可能にすることで、「バリデーション強化したい」という要望に対応速度が上がった。

medallion — 金融データ基盤

JPX・TDnet・IR から決算短信を抽出・蓄積。銘柄ごとに config/companies/*.yaml で IR 仕様を持つ。

構造化例：

# config/companies/9999-sample-corp.yaml
company_id: 9999
xbrl_endpoint: "https://disclosure.edinet-fsa.go.jp/..."
pdf_fallback: true
accounting_standard: IFRS
fiscal_year_end: March
special_handling:
 - rename_field: "revenue_adjusted" → "net_sales"
 - threshold_change: 20% # alert if > 20%

汎用パーサーは作ったが、端の挙動は個別対応。IFRS/JGAAP の差異吸収コストは残る。「完全ゼロタッチ」は理想。現実はそこまで行かない。

コーポレートサイト — Astro + ブログ

Astro 5 + React 19 + Tailwind。Three.js Point Cloud 背景・i18n（日英）・GAS 連携フォーム。

ハードコード禁止の実装：

// src/config/design-tokens.ts
export const tokens = {
 colors: { primary: "#0f766e", ... },
 spacing: { sm: "0.5rem", md: "1rem", ... },
 typography: { heading: "Noto Sans JP", body: "Inter", ... }
};

// コンポーネント内
import { tokens } from "@/config/design-tokens";
<div style={{ color: tokens.colors.primary }} /> // ✓ Good
<div style={{ color: "#0f766e" }} /> // ✗ 禁止

ブログメタも config 駆動。

# config/sites/corporate.json
{
 "blog": {
 "tracks": ["tech", "case"],
 "categories": ["engineering", "business", "community"],
 "metadata_schema": "src/content/config.ts",
 "publish_gate": { "tech": "cto_bar >= 7", "case": "editor_approval" }
 }
}

記事は tech/case に振り分け、track ごとに異なる review gate。

落とし穴：ドメイン差異と「完全自動化」の幻想

同じ設計原則を守っていても、ドメインが違えば現実的な調整は必ず生じる。全部一発で決まることはない。

montage の教訓：バリデーション ≠ 品質

Block Schema + Zod でデータ形式は valid。だが映像として成立するか、スクリプトのテンポは自然か——それは別の評価軸。

parse_valid && schema_valid && visual_appealing?
→ 最後の 1 つは Reviewer が都度チューニング

「バリデーション統一したら自動化完了」ではない。ドメイン特有の美的判断が残る。

medallion の教訓：汎用化の限界

XBRL 対応銘柄と PDF のみの銘柄で処理パス分岐。新しい上場企業が加わるたび、IR サイト構造が異なる。

対応パターンコスト頻度
既知スキーム（XBRL）低月 1-2 件
PDF 解析中月 2-3 件
新フォーマット対応高四半期 1-2 件

「銘柄別 YAML を置く」は pragmatic な選択。汎用パーサーで 80% カバーし、個別カスタマイズで 100% 目指す。trade-off を明示している。

Synapse の教訓：完全自動化は責任を曇らせる

営業の最終承認は人間が持つ設計。「AI がすべて判断する」と責任が曖昧になる。

営業スキル実行
 ↓ draft 提案生成
提案確認（人間）← 判断権を明示
 ↓ approve / revise
Notion 更新

AI は「判断を支援」する立場。最終 sign-off は人間。この分離がいま機能している。

非自明な洞察：環境設計が実装を支える

AI 駆動開発の本当の難しさはコード生成速度ではない。AI が安定して動く環境を設計すること だ。

CLAUDE.md のルール整備・hook の実装・config 整理——これらは地味で自動化しがたい作業。しかし ここがエージェント信頼性の決定要因 になる。

曖昧な環境で AI に作業させると：

  • スクリプトがハードコード値を埋める
  • エージェントが自分の判断基準で枝分かれする
  • 同じ入力に出力がぶれる

仕様を明確にすると：

  • AI は一貫性を保つ
  • エラーは明示的で追跡可能
  • チーム全体が何が起きているか理解できる

八雲はこの実装を内部で回しながら、同じ設計を受託プロジェクトにも反映させている。プロダクト開発と受託の並走は互いのフィードバックループ。設計が実装を支え、実装が設計を検証する。

まとめ

複数プロダクト・受託案件を Claude Code で並走させるには、3層責務分離・config 駆動・領域責任者・モデル使い分け・ PreToolUse hook という 5 つの設計原則が不可欠。

これらは理想的なアーキテクチャではなく、現場で「無いと壊れた」ことから学んだ pragmatic な設計。ドメイン差異への個別対応は残るが、基盤が明確ならそれが isolated で、全体が揺らがない。

AI 駆動開発を安定化させるのは、コード生成の精度ではなく、運用設計を文書化し、ガードレールを敷き、判断履歴を残す という一見つまらない作業。CLAUDE.md の品質・hook の整備・config 構造の丁寧さ——そこに本当の競争力がある。

実装で語る。それが八雲のスタイルだ。

ShareShare on X

Related Posts

[ AI-driven Dev ]

Claude Code で AI 駆動開発を本番運用する：ドキュメント自動更新ルールの設計

コードを AI が書く時代に「ドキュメントが追従しない問題」をどう解決するか。SSOT の発想を docs に拡張し、変更と更新対象の対応表を CLAUDE.md に持つアプローチを実例とともに解説します。

[ AI-driven Dev ]

ハードコード禁止と config 駆動設計 — Claude Code に書かせるコードのガード

AI に書かせるとハードコードが頻発する。マジックナンバー禁止・config 集約の設計で品質を担保する八雲の運用ルール。

[ AI-driven Dev ]

system-developer エージェント常用パターン — コード実装は必ず委譲する

メインスレッドが直接コードを書くと仕様参照・テスト先行・パス厳守のいずれかが省略されるため、system-developer エージェントへの委任によって構造的に省略を防ぐ必要がある。