昨年、私たちは 200 万ドルの価値があるプラットフォームを出荷しました。エンジニアリングチーム全体？シニアアーキテクト 1 名と Claude Code。オフショアチームなし。契約業者の軍隊なし。自分たちが何を構築しているか理解している 1 人と、実際に本番コードを書けるAIのペアだけです。

AI をアピールするために書いているわけではありません。ハイプサイクルで何度も焼かれてきました。このプロジェクトで何が起きたかが、チーム構成、プロジェクト見積もり、そして深いアーキテクチャ知識と AI 支援開発をペアリングしたときに実際に何が可能かについての考え方を根本的に変えたから書いています。数字は嘘をつきません。6～8 人のエンジニアで約 18 ヶ月かかったであろうマイルストーンを 5 ヶ月未満で達成しました。

正確にどのようにしたかを説明します。

目次

プロジェクト：実際に何を構築していたか

クライアント名は明かせません。NDA があります。ただ、プラットフォームについては説明できます。ロジスティクス分野の B2B SaaS 製品です。マルチテナント アーキテクチャ。リアルタイム追跡ダッシュボード。組織、チーム、個別ユーザーに及ぶ複雑なロールベースアクセス制御。14 の異なるサードパーティ API（キャリア、決済プロセッサ、通関データベース）との統合。顧客向けポータルと内部管理システム。

典型的なエージェンシー環境であれば、テックリード、シニアデベロッパー 2～3 名、中堅開発者数名、専任の DevOps 担当者、QA エンジニアで体制を整えるような案件です。別のエージェンシーからのクライアント側の当初見積もりは、9 名のチームで 20 ヶ月間の 320 万ドルでした。

私たちは 200 万ドル、5 ヶ月、アーキテクト 1 名を提案しました。彼らは私たちが狂っていると思いました。正直なところ、私も少し思いました。

フルチームではなく 1 人のアーキテクトを選んだ理由

小規模チームについての反直感的なことはこれです：9 人のプロジェクトでのコミュニケーション オーバーヘッドは膨大です。Fred Brooks は 1975 年にこれについて書いており、今でも当てはまります。9 人のエンジニアであれば、36 個の潜在的なコミュニケーション チャネルがあります。会議が増えます。マージ競合は日常的になります。誰かがいつも他の誰かの PR レビューを待っていてブロックされています。

1 人のアーキテクトであれば、システム全体の状態は 1 人の頭の中に存在します。プル リクエストであなたのアプローチを説明することからのコンテキスト スイッチの負担はありません。委員会による設計ではありません。2 時間のスプリント計画セッションもありません。

しかし、1 人でタイプできるのはそこまでです。1 人の作業記憶に保持できるのはそこまでです。1 人は午後 6 時に疲れ、午後 8 時に間違いを犯します。

ここで Claude Code が登場します。アーキテクトの代わりではなく、力の増幅器として機能します。アーキテクトはすべての決定を下します。Claude Code は、通常は 4～5 人の開発者が必要とするスピードで実行します。

アーキテクトの役割

このプロジェクトのアーキテクト（Marcus と呼びましょう）には 15 年の経験があります。この規模のシステムを以前構築しました。このプロジェクトでの彼の仕事は以下の通りです：

  • システム設計とアーキテクチャの決定
  • モジュール境界とデータ契約の定義
  • 重要なパスコード（認証、決済処理、データ パイプライン オーケストレーション）の記述
  • Claude Code が生成したすべての内容のレビューと改善
  • インフラストラクチャと展開アーキテクチャ
  • セキュリティ監査

彼がやらなかったこと：定型的な CRUD エンドポイントの記述、設計からの UI コンポーネント構築、単純なロジックの単体テスト作成、データベース マイグレーション作成、新しいサービスのスキャフォルディング。Claude Code がそれらをすべて処理しました。

Claude Code が実際のワークフローにどう組み込まれるか

「Claude Code を使う」ことが実際に日々どのような様子だったかについて具体的に説明します。マーケティング資料では現実をキャプチャしていないからです。

Marcus は毎朝、構造化された方法で本日の作業を定義することから始めます。「ユーザー管理システムを構築してくれ」のような曖昧なプロンプトではなく、代わりに「アーキテクチャ ブリーフ」と呼び始めたドキュメントを作成します。詳細なドキュメントで、以下を指定しました：

  1. モジュールの責任と境界
  2. 正確なフィールド タイプと関係を持つデータ モデル
  3. API コントラクト（エンドポイント、リクエスト/レスポンス形式）
  4. ビジネス ルールとエッジ ケース
  5. エラー処理の期待値
  6. 統合が必要な既存モジュール

その後、彼はこれらを Claude Code にチャンクで提供します。典型的なセッションは次のようになります：

# Marcus はプロジェクト ディレクトリで Claude Code CLI を使用して作業します
# まず、コンテキストを確立します
claude "Read through /src/modules/shipment/ and /src/lib/database/schema.ts. 
I need you to understand the existing patterns before we build the 
invoicing module."

# その後、アーキテクチャ ブリーフを使用した実際のビルド指示
claude "Build the invoicing module following the architecture brief in 
/docs/briefs/invoicing.md. Follow the exact same patterns as the 
shipment module for service layer, repository layer, and route handlers. 
Use the existing error handling middleware. Write tests for all 
business logic in the service layer."

そのため、Claude Code はモジュールを生成します。通常は 15～30 ファイル（タイプ、スキーマ、サービス、リポジトリ、ルート ハンドラ、ミドルウェア、テスト を含む）。Marcus は出力をレビューし、修正を加え、反復処理を行います。中程度の複雑さのモジュール全体のサイクルは、シニア開発者がかかる 2～3 日ではなく、約 2～3 時間かかりました。

イテレーション ループ

これが AI 支援開発について誰も言わないこと：最初の出力は本番環境対応はめったにありません。おそらく 70～80% のところです。しかし、残りの 20～30% は、アーキテクトの専門知識が最も重要な場所です。

Marcus は以下のリズムを開発しました：

  1. 生成 — Claude Code は初期実装を生成します
  2. レビュー — Marcus はすべてのファイルを読み、問題にフラグを立てます
  3. 洗練 — Claude Code にフィードバックを与えて具体的な修正を行います
  4. 強化 — Marcus は手動でセキュリティ重要なセクションを処理します
  5. テスト — 生成されたテストを実行し、Claude がミスしたエッジ ケースを追加します

このループは通常、モジュールあたり 2～3 サイクル行われました。プロジェクトの 3 ヶ月目までに、Claude Code は最初のパスコードを生成していて、それは 85～90% 本番環境対応に近かったです。理由は、コードベースに Claude が従うに十分なパターンが確立されていたからです。

テックスタックとアーキテクチャの決定

AI 支援生産性を最大化するために、スタックを意図的に選択しました：

  • Next.js 14 (App Router) — 顧客ポータルと管理ダッシュボード用
  • Node.js with Fastify — API レイヤー用（Next.js とは別）
  • PostgreSQL — 主要データベース
  • Redis — キャッシング、セッション管理、リアルタイム pub/sub
  • Drizzle ORM — タイプセーフなデータベース アクセス
  • Turborepo — モノレポ管理
  • Vercel — フロントエンド展開
  • AWS (ECS Fargate) — API とバックグラウンド ワーカー

パターンが十分に確立されており、Claude Code には App Router 規約に関する深い訓練データがあるという理由で Next.js を選択しました。これは人々が考えるより重要です。Rust ベースのバックエンド with HTMX のような何か奇妙なものを選択していたなら、AI 出力の品質は大幅に低下したでしょう。

このプロジェクトでは Prisma よりも Drizzle ORM を意図的に選択しました。Claude Code は Drizzle スキーマをより良く生成します。なぜなら、それはただの TypeScript だからです。カスタム DSL ではありません。さらに、大量のスキーマ変更を迅速に生成するときのマイグレーション ストーリーはシンプルです。

// 例：Claude Code は初回パスで最小限の修正で生成した請求書スキーマ
import { pgTable, uuid, varchar, decimal, timestamp, pgEnum } from 'drizzle-orm/pg-core';
import { relations } from 'drizzle-orm';
import { shipments } from './shipments';
import { organizations } from './organizations';

export const invoiceStatusEnum = pgEnum('invoice_status', [
  'draft', 'pending', 'sent', 'paid', 'overdue', 'cancelled', 'refunded'
]);

export const invoices = pgTable('invoices', {
  id: uuid('id').primaryKey().defaultRandom(),
  organizationId: uuid('organization_id').notNull().references(() => organizations.id),
  shipmentId: uuid('shipment_id').references(() => shipments.id),
  invoiceNumber: varchar('invoice_number', { length: 50 }).notNull().unique(),
  status: invoiceStatusEnum('status').notNull().default('draft'),
  subtotal: decimal('subtotal', { precision: 12, scale: 2 }).notNull(),
  taxAmount: decimal('tax_amount', { precision: 12, scale: 2 }).notNull().default('0'),
  totalAmount: decimal('total_amount', { precision: 12, scale: 2 }).notNull(),
  currency: varchar('currency', { length: 3 }).notNull().default('USD'),
  dueDate: timestamp('due_date', { withTimezone: true }).notNull(),
  paidAt: timestamp('paid_at', { withTimezone: true }),
  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
});

export const invoiceRelations = relations(invoices, ({ one, many }) => ({
  organization: one(organizations, {
    fields: [invoices.organizationId],
    references: [organizations.id],
  }),
  shipment: one(shipments, {
    fields: [invoices.shipmentId],
    references: [shipments.id],
  }),
  lineItems: many(invoiceLineItems),
}));

Claude Code が得意だったこと

具体的に説明しましょう。Claude Code が実際に開発を加速させた場所：

定型的なコードと CRUD 操作

これは明らかなものです。REST エンドポイント、リクエスト検証スキーマ（Zod を使用）、レスポンス シリアライザ、基本的なサービス メソッドの生成。Claude Code はこれらを数分で処理します。プロジェクト全体では、おおよそ 180 個の API エンドポイントがありました。おそらく 140 個は、最小限の改訂で Claude Code が生成した標準 CRUD またはクエリ操作でした。

テスト生成

Claude Code は、プロジェクト全体で約 2,400 個のテストを作成しました。すべてが完璧でしたか？いいえ。約 15% には大幅なリワークが必要でした。しかし、テスト スイートの 85% が生成され、動作していることがあると、大幅な時間短縮です。Marcus は、統合テストと Claude Code が予期できなかったわずらわしいエッジ ケースにテスト エネルギーを集中させました。

UI コンポーネント開発

顧客ポータルには約 60 個の固有ページ ビューがありました。各については、Marcus は Figma デザイン リファレンスと API コントラクトを提供し、Claude Code は React コンポーネント、データ取得フック（TanStack Query を使用）、フォーム処理（React Hook Form + Zod）、および読み込み/エラー状態を生成します。出力は一貫性がありました。初回生成で 75% ピクセル精密でした。

データベース マイグレーションとスキーマ進化

要件が進化するにつれて（常に進化します）、Claude Code はスキーマ マイグレーションをスムーズに処理しました。必要な変更を説明すると、マイグレーション ファイルを生成し、スキーマを更新し、影響を受けるクエリを更新し、TypeScript 型を調整します。以前は 45 分の注意深いリファクタリング セッションだったのが、10 分のレビューと承認のサイクルになりました。

ドキュメンテーション

Claude Code は API ドキュメント、インラインコード コメント、README ファイル、さらには運用用ランブック ドキュメントも生成しました。Marcus はレビューして調整しますが、ベースラインの出力は真に有用でした。生成のコストがそんなに低かったため、一般的に見られる 90% のプロジェクトよりも優れたドキュメントで終わりました。

Claude Code が失敗した場所とそれにどう対処したか

このセクションは成功事例よりも重要です。このようにAIを使用する予定であれば、壁がどこにあるかを知る必要があります。

複数の依存関係を持つ複雑なビジネス ロジック

出荷ルーティング エンジン（キャリア利用可能性、コスト最適化、通関要件、配送ウィンドウ、容量制約を同時に考慮する必要がある）は、Claude Code が十分に処理できるもの以上のものでした。見た目は妥当に見えるものを生成しますが、実際のお金を失う可能性のある微妙なロジック エラーがありました。

Marcus はこのモジュールを手で書きました。約 2 週間かかりました。これはまさに、すべてを AI 経由で行おうとするのではなく、シニア アーキテクトを持つ価値を正当化する種類の作業です。

セキュリティ重要なコード

Auth フロー、決済処理、暗号化については、Claude Code を行の詳細なレビューなしに信頼しませんでした。それは良いことです。時々 JWT 検証を技術的に機能していたが、トークン有効期限クロック スキューのような エッジケースを見落としたり、ORM を使用しているにもかかわらずデータベース クエリの前に入力を適切にサニタイズしないコードを生成することがありました。

経験則：このコードのバグが お金を失ったりデータを公開したりする可能性がある場合、人間が書き、別の人間が検査します。

長距離アーキテクチャ一貫性

3 ヶ月目までに、コードベースが大きくなり、提供されたコンテキストでも、Claude Code は時々以前に確立されたパターンを「忘れ」ます。あるモジュールでは異なるエラー処理アプローチを使用し、別のモジュールでは別のアプローチを使用する場合があります。Marcus はこれらの矛盾を捉えることについて警戒する必要がありました。

私たちはこれを軽減するために、すべての Claude Code セッションに含まれる生きた「規約」ドキュメントを維持しました。アーキテクチャ パターンのスタイル ガイドとして考えてください。

パフォーマンス最適化

Claude Code は 動作する コードを生成しますが、必ずしも 高速 コードを生成するわけではありません。N+1 フェッチを行うデータベース クエリ。不要に再レンダリングする React コンポーネント。必要以上のデータを読み込む API エンドポイント。

Marcus は、レビュー時間の約 20% をパフォーマンス最適化に費やしました。不可解ではありませんが、予算として計上する価値があります。

経済学：コスト分析と ROI

これが誰もが見たい部分です。実数です。

コストカテゴリ 従来のチーム（推定） AI 加速（実際）
エンジニアリング給与（18 ヶ月 / 5 ヶ月） $1,890,000 $175,000
Claude Code API / サブスクリプション $0 $12,400
インフラストラクチャ（開発/ステージング） $48,000 $8,200
プロジェクト管理 $216,000 $0*
QA / テスト $180,000 $22,000**
デザイン（契約） $120,000 $95,000
DevOps / インフラストラクチャ セットアップ $96,000 $35,000
合計 $2,550,000 $347,600

Marcus が Linear を使用してタスク追跡を自己管理しました。PM のオーバーヘッドなし。

*契約的な QA スペシャリストが最後の 6 週間に参加しました。

Claude Code のコストは月々約 $2,500 に細分化されます。それは Max プラン（サブスクリプション $100/月）と拡張セッションの API コスト。ある日は Marcus は重い生成セッション中に API コールで $150～200 を消費します。ほとんどの日は $40～80 でした。

このプロジェクトは 200 万ドルで請求されました。配信の総コストは 35 万ドル未満でした。利益率の計算は自分でしてください。

スピード比較

マイルストーン 従来のタイムライン AI 加速タイムライン
アーキテクチャ & デザイン 6 週間 3 週間
コア プラットフォーム（認証、マルチテナンシー、基本 API） 10 週間 3 週間
機能開発（すべてのモジュール） 32 週間 10 週間
統合（14 個のサードパーティ API） 12 週間 4 週間
テスト & QA 8 週間 3 週間
デプロイメント & 強化 4 週間 2 週間
合計 72 週間 25 週間

AI 加速開発を検討しているチームへのレッスン

このプロジェクトの後、これが今後のソフトウェア構築方法に何を意味するかについて考えています。このアプローチを検討しているチームまたはエージェンシーに言いたいことはここにあります。

依然としてシニア アーキテクトが必要です。これまで以上にそうかもしれません。

AI は専門知識の必要性を排除しません。持っている専門知識（または専門知識の欠落）を増幅します。Claude Code を使用している junior デベロッパーは、junior 品質のコードをより高速に出荷します。Claude Code を使用しているシニア アーキテクトは、以前は不可能だった速度でシニア品質のコードを出荷します。

最悪のシナリオは、自分たちが シニア だと 考えている 中堅開発者が Claude Code を使用してコードを評価できないコードを生成することです。それは見た目は良さそうに見えるが負荷がかかると崩壊するコードベースです。

すべての場所に慣例優先設定

あなたのコードベースのパターンがより予測可能であればあるほど、AI はより良く実行します。すべてのモジュールで同じファイル構造、命名規則、コード編成を使用しました。この一貫性は、Claude Code が既存パターンに合わせることを学ぶ際の大きな配当を払いました。

ヘッドレス CMS アーキテクチャを使用する場合、コンテンツ タイプ、API ルート、コンポーネント構造の厳密な規約により、AI 生成コードははるかに信頼性が高くなります。

アーキテクチャ ブリーフに投資する

Claude Code の出力の品質は、Marcus のアーキテクチャ ブリーフの品質に直接関連していました。曖昧な指示は曖昧なコードを生成しました。明確なデータ モデル、ビジネス ルール、統合要件を持つ詳細なブリーフは、ほぼ本番環境対応のコードを生成しました。

Marcus はアーキテクチャ ブリーフの作成と出力のレビューに約 30% の時間を費やし、従来のチームが実装に費やしたであろう時間の 70% が Claude Code によって処理されたと推定しています。

AI 支援開発は価格モデルを変更します

エージェンシーの場合、これは厄介な会話です。1 人のアーキテクトが、8 人のチームが必要だったものを配信できる場合、価格はどうなりますか？私たちは価値ベースの価格設定を信じています。クライアントは、構築に 1 人か 10 人かかったかに関わらず、結果のために支払います。プラットフォームは 200 万ドルの価値があります。

このようなアプローチがあなたのプロジェクトにどのように機能するかに関心がある場合、当社の価格設定ページでは、この新しい現実におけるプロジェクト範囲の考え方の詳細を説明しています。

すべてのプロジェクトがこのモデルに適しているわけではありません

これは以下の理由で機能しました：

  • 要件は明確に定義されていた（ロジスティクスは成熟した領域）
  • 私たちには実際のシニア アーキテクトがいました
  • テック スタックは主流でした（AI 訓練データが豊富）
  • クライアントはチーム規模をマイクロ管理せずに配信を信頼しました

曖昧な要件、多くの R&D コンポーネント、または特殊化されたドメイン（医療機器、規制要件を持つ金融商品）を持つプロジェクトは、より多くの人間の判断が必要で、それに応じて配置する必要があります。

新しいエコシステムで構築されたプロジェクト（Astro など）では、AI トレーニング データがより薄く、React/Next.js プロジェクトと比較して AI ツールからの加速が少なくなります。

FAQ

Claude Code は実際に月単位の重い開発用途でどのくらいの費用がかかりますか？

このプロジェクトでは、平均月額 $2,500 を使用しました。Claude Max サブスクリプション（2025 年初めの時点で月額 $100、またはより高い層で月額 $200）と、生成するコード量に応じて API 使用は合計します。重い日は API コストで $150～200。軽いレビューと改善の日は $40～80 でした。Anthropic は Max プランを月額 $200 で導入しており、これには変動コストを削減する可能性がある重要な使用量が含まれています。

Junior デベロッパーが同じ方法で Claude Code を使用できますか？

いいえ、これは重要です。Claude Code はあなたの既存のスキル レベルを増幅します。アーキテクチャ知識に代わることはありません。Claude Code を使用している junior デベロッパーはより高速にコードを生成しますが、シニア エンジニアがすぐに捉える微妙なバグ、セキュリティ問題、パフォーマンス問題、またはアーキテクチャの矛盾は捉えません。出力を評価できる人が必要で、単にそれを受け入れるのではなく。

コード品質について — AI 生成コードは保守可能ですか？

あなたが与える制約に完全に依存します。生成されたコードは、人間が書いたコードと同じリンティング ルール、型チェック、コード レビュー標準を通過しました。トリックは、AI が従う良い例を持つように、プロジェクトの早期に強いパターンを確立することです。すべての Claude Code セッションに含まれた規約ドキュメントを保持しました。デプロイ後 6 ヶ月間、プラットフォームを保持しているチームは異常なメンテナンス負担を報告していません。

このアプローチはフロントエンド集約的なプロジェクトで機能しますか？

はい、注意点はあります。Claude Code は React コンポーネント、フォーム処理、データ取得フック、状態管理コードの生成に優れています。デザインからピクセルパーフェクトな CSS レイアウトを生成するのは信頼性が低いです。視覚的なポーランド化には、より多くのイテレーション サイクルが必要です。UI 生成は、バックエンド コードの 85～90% と比較して初回生成の約 75% 精密でした。

開発者が 1 人しかいないときのコード レビューはどのように処理しますか？

Marcus はすべての AI 生成コードを自分でレビューしました。プロジェクト中（12 週目と 22 週目）に、契約セキュリティ スペシャリストを 2 回の集中監査セッションに連れて来ました。最終段階では、QA スペシャリストが 6 週間参加しました。同期的コード レビューの欠落は本当のリスクです。私たちは自動化ツール（TypeScript strict mode、aggressive ルールを持つ ESLint、カバレッジしきい値を持つ Vitest）と外部監査で軽減しました。

Claude Code がバグ コードを生成するとどうなりますか？

それは定期的に起こります。最初のパスはめったに完璧ではありません。生成、レビュー、改善、強化を期待しました。ほとんどのバグは Marcus のレビュー サイクル中に捉えられました。自動テスト スイート（大きく AI 生成だが人間で確認）は回帰の問題を捉えました。重要な洞察は、AI 生成コードのデバッグは、スクラッチからコードを正しく書くより高速だということです。ほぼ正しい何かから始まるからです。

これはグリーンフィールド プロジェクトにのみ実行可能ですか、または既存のコードベースで機能しますか？

Claude Code は実際に既存のコードベースで適切に機能します。既存のパターンを読んで理解できるからです。このプロジェクトでは、後のモジュールは参照として以前のモジュールからメリットを受けました。それ以来、既存のクライアント プロジェクトでの機能追加に Claude Code を使用しており、良い結果が出ています。重要なのは、既存の規約とパターンについて十分なコンテキストを提供することです。コードベースが矛盾しているまたは不十分に文書化されている場合、AI 生成の追加は矛盾を継承します。

これをもう一度やりますか？

絶対に。もう既にやっています。2 つ以上のプロジェクトは現在このモデルで実行中です。1 人のアーキテクトを持つもの、より複雑なシステムの場合は 2 人のエンジニア。経済学は無視するにはあまりに説得力があります。しかし、これがデベロッパーの置き換えについてではないことを明確にしたいです。シニア アーキテクトから出力への比率を変更することです。あなたはまだ人間の専門知識が必要です。あなたはただ人間の入力が必要になります。プロジェクトを検討していて、このモデルで何が起こる可能性があるかを探りたい場合は、私たちに連絡してください。フィットするかどうかについて話し合うのを非常に満足しています。