14週間でカスタムCRMを構築する

カスタムCRMをゼロから構築するよう依頼されたことはありますか？その時、「これは不可能だ」と思いますよね？私は2年前、わずか14週間でCRMの準備が必要だったクライアントの案件でそう思いました。典型的なタイムラインではありません。しかし、ここが重要なポイントです。私たちの5段階プレイブックを使えば、単に実行可能なだけでなく、驚くほどスムーズに進みました。Stack OverflowとPostmanは毎日のお供でした。そして、その過程で思った以上のレッスンを学びました。

フェーズ1：ディスカバリーとスコーピング（第1週～第2週）

CRMプロジェクトのほとんどは、コードを1行書く前に失敗します。本当にそうです。その失敗は会議室で起こります。通常はホワイトボードの周りで、誰もが曖昧な要件に頷き、誰も不快な質問をしません。

特定のプロジェクト（バーミンガムの中規模ロジスティクス会社、スタッフ約80人）では、最初の2週間をほぼ聞くだけに費やしました。ワークショップ、録画されたZoomコール、ステークホルダーがCRMに処理させたいあらゆるワークフローを記入できる共有Notionドキュメント。そのドキュメントは47ページまで膨らみました。その多くは矛盾していました。これは実は問題ありません。ディスカバリードキュメント内の矛盾は無料ですが、11週目に発見された矛盾は1スプリントとクライアント関係を失います。

実際にマッピングしているもの

ディスカバリーの目標は、すべての機能を捉えることではありません。データ関係とユーザーロールをマッピングすることです。それらが下流のあらゆるアーキテクチャ上の決定を形作ります。このステージではWhimsicalをフロー図に使用します。迅速で、共有可能で、クライアントはアカウントが不要なままコメントできます。data relationships and the user roles that will shape every architectural decision downstream. I use Whimsical for flow diagrams at this stage. Quick, shareable, and clients can comment without needing an account.

2週目の終わりには、4つの成果物をロックする必要があります。

1. 優先度付けされた機能リスト。MVPと発売後のバケットに分割されたもの
2. エンティティ関係の概要（まだ完全なスキーマではなく、名詞だけ：contacts、deals、pipelines、tasks）
3. ユーザーロール定義。権限レベルは平文の英語で記述される
4. サインオフされたタイムライン。曖昧なフェーズではなく、名前の付いたマイルストーン

その最後のものは交渉の余地がありません。「Phase 2 complete」は何も意味しません。「Contact importと役割ベースのアクセスが28日目までにステージングに本番化」は意味があります。

---

Phase 2：アーキテクチャとテックスタック決定（Week 3）

1週間。このフェーズにはこれ以上与えません。チームがアーキテクチャ議論に1か月間消えて何も出荷しないのを見てきたからです。

このプロジェクトのスタックは、バックエンドに Node.js と Express、データベースに PostgreSQL、フロントエンドに React を使用し、全体を DigitalOcean のマネージド Kubernetes にデプロイしました。ORM として Prisma を選んだのは、スキーマが急速に進化することが予想されており、Prisma のマイグレーションワークフローがそのために本当に優れているためです。Node.js with Express on the backend, PostgreSQL for the database, React on the front end, and the whole thing deployed on DigitalOcean managed Kubernetes. We used Prisma as the ORM because the schema was going to evolve quickly and Prisma's migration workflow is genuinely good for that.

正直なところ、スタック自体はみんなが思うほど重要ではありません。もっと重要なのは：

• このプロジェクトのすべての開発者が、急な学習曲線なしでこのスタックを理解できるか？
• アーキテクチャは、Phase 1 でマッピングした権限モデルをサポートしているか？
• 週 10 に新しいエンティティタイプ（たとえば「supplier」）を追加できるか、認証レイヤーを書き直さずに？

3 番目のポイントは私が以前痛い目を見ています。2021 年、Seahawk は SaaS プロジェクトで週 9 にマルチテナンシーを無理やり追加しました。1 日で済むはずだったものをリトロフィットするのに 4 日かかりました。二度としません。

認証については、よほどの理由がない限り Auth0 をデフォルトにしています。パスワードリセット、MFA、ソーシャルログインといったエッジケースを処理してくれるので、ジュニア開発者を悩ませる問題を避けられます。Auth0 unless there's a compelling reason not to. It handles the edge cases (password resets, MFA, social login) that eat junior developers alive.

---

Phase 3：コアビルドスプリント（週 4～9）

6 週間。ここがエンジンルームです。そしてスコーピングが堅実なら、このフェーズは実際にはプロジェクト全体の中で最も直進的な部分です。

これを3週間の短いスプリント2つに分けて、中間地点で厳密な内部レビューを実施しました。

スプリントA：データレイヤーとAPI（4～6週目）

APIコントラクトが合意されるまで、フロントエンドには何も手をつけません。絶対です。コントローラーを書く前にPostmanですべてのエンドポイントをドキュメント化します。退屈に聞こえるかもしれませんが、後で「あ、このエンドポイントって何を返すんだ？」という会話が2週間分減ります。Postman before writing a controller, which sounds tedious but saves about two weeks of "wait, what does this endpoint return?" conversations later.

データベーススキーマはここで最初の本格的な見直しを受けます。CRMの場合、過小評価されやすいテーブルはアクティビティログテーブルとカスタムフィールドテーブルです。すべてのクライアントがカスタムフィールドを望みます。柔軟なcustom_field_definitionsテーブルを初日からきちんと構築するのは約4時間の仕事です。11週目に即興で作るのは悪夢です。custom_field_definitions table properly from day one is about four hours of work. Improvising it in week 11 is a nightmare.

スプリントB：フロントエンドとワークフロー（7～9週目）

ReactとTanStack Queryをサーバー状態管理に使用しました。2022年に小規模プロジェクトで素のuseEffectとローカル状態でやってみました。もう二度とそんなことはしません。TanStack Queryはキャッシング、バックグラウンドリフェッチ、楽観的更新を処理する方法で、CRMインターフェースを無理なく快適に感じさせます。TanStack Query for server state management. I tried rolling with plain useEffect and local state on a smaller project in 2022. Never doing that to myself again, TanStack Query handles caching, background refetching, and optimistic updates in a way that makes CRM interfaces feel snappy without heroics.

UIコンポーネントレイヤーについて、このプロジェクトではshadcn/uiを使いました。従来の意味でのコンポーネントライブラリではなく、コードを所有しているため、ライブラリと戦わずに実際にカスタマイズできます。パイプラインビュー、連絡先テーブル、タスクボードがあるCRMの場合、その柔軟性は重要です。shadcn/ui on this project. It's not a component library in the traditional sense; you own the code, which means you can actually customise it without fighting the library. For a CRM with a pipeline view, a contacts table, and a task board, that flexibility matters.

このスプリントで一貫して落ちるもの：空の状態です。データがないCRMは、ゼロ状態のスクリーンを設計していなければ壊れているように見えます。早めに構築してください。クライアントは空のデータベースで関係者にデモを行い、最初の印象は残ります。empty states. A CRM with no data looks broken if you haven't designed for zero-state screens. Build them early. Clients demo to stakeholders with empty databases and first impressions stick.

---

フェーズ4：統合とデータ移行（10～11週目）

ここはほとんどのエージェンシーが見積もりを低く出し、計画が甘くなるところだ。毎回見てきた。

バーミンガムのロジスティクスクライアントは、既存のXero会計システムと、移行予定の古いSalesforceインスタンスとの統合が必要だった。2週間は短く見えた。実際そうだったが、Phase 3の段階で統合ポイントをスタブ化していたから対応できた。Xero accounting setup and an older Salesforce instance they were migrating away from. Two weeks sounds tight. It was, but we made it because we'd stubbed the integration points back in Phase 3.

Salesforce移行に関しては、Bulk API 2.0を使ってデータを抽出し、Node スクリプトで彼らのフィールド構造を私たちのものにマッピングした。スクリプトの作成に1日、イテレーションに3日かかった。Salesforceのデータはクライアントが信じているほどきれいなことはまずないからだ。データクリーニングの予算を確保すること。常に。Bulk API 2.0 to extract the data, then ran it through a Node script that mapped their field structure to ours. The script took a day to write and three days to iterate on because Salesforce data is almost never as clean as clients believe it is. Budget for data cleaning. Always.

統合が「完了」と言う前に確認することがいくつかある：

• エラーハンドリング：サードパーティのAPIが落ちたときはどうなるか？
• Webhookのべき等性：同じイベントを2回安全に処理できるか、レコードが重複しないか？
• レート制限：現実的な負荷の下でそれに収まっているか？

Xeroの開発者ドキュメントは、実のところまともだ。OAuth 2.0フローはよくドキュメント化されているし、サンドボックス環境も信頼できる。Xero developer docs are actually decent, for what it's worth. The OAuth 2.0 flow is well documented and their sandbox environment works reliably.

---

Phase 5：QA、堅牢化、ハンドオーバー（12～14週目）

QAに3週間というのは、実際に進めるまでは余裕があるように聞こえる。

12週目は構造化テストだ。ClickUpボードをクライアントに渡して、すべてのテストケースをタスクとして記載し、クライアントがテストして、マークして、何か壊れたらLoomを添付する。これで実際のユーザーが実際のフローをクリックするようになり、開発者が実行するテストでは見落とすものが必ず見つかる。「メモ」フィールドに4,000文字を貼り付けようとする人もいれば、スマートクォート付きのCSVをインポートする人もいる。こういったことを今のうちに見つけたいんだ。ClickUp board with every test case written as a task, they test, they mark it, they attach a Loom if something breaks. This gets real users clicking real flows, which always uncovers things that a developer-run test misses. Someone will try to paste 4,000 characters into a "notes" field. Someone will import a CSV with smart quotes in it. You want to find this now.

13週目はフィックススプリントだ。新機能はなし。バグ修正とパフォーマンス改善のみ。主要ページすべてに対してLighthouseを実行する。APIに対してk6ロードテストも実行する。クライアントが要求したわけではないが、13週目で50同時ユーザー下の遅いクエリを見つけるほうが、本番稼働後に見つけるより遥かにいい。Lighthouse against every key page. I also run k6 load tests against the API, not because the client asked for it, but because finding a slow query under 50 concurrent users in week 13 beats finding it after go-live.

14週目は引き継ぎと本番稼働準備だ。

私が作成する引き継ぎドキュメントは以下をカバーしている：

1. インフラストラクチャ概要（何がどこで動いているのか、スケール方法）
2. データベースのバックアップと復元手順、テスト済みで検証済み
3. コードに触れずに新しいユーザーロールを追加する方法
4. 既知の制限事項と見送ったバックログアイテム

最後のものが重要だ。何がカットされたのか正直に伝えよう。クライアントはそれを尊重するし、次のフェーズをスッキリと立ち上げられるようになり、関係に重くのしかかる言わないでおく借金が残らない。

ゴーライブに関する最後のポイント

段階的に展開する。92日目に10人のユーザーを対象にソフトローンチし、Datadogを使って48時間ログを監視してから、80人のチーム全体に公開した。その48時間のウィンドウで、テスト時には出現していなかったパイプラインステージ遷移の2つのエッジケースを捕捉できた。壊滅的なものではなかったが、もしフルスケールで進めていたら初日に15件のサポートチケットが発生していただろう類の問題だ。Datadog, then opened it to the full 80-person team. That 48-hour window caught two edge cases in the pipeline stage transitions that hadn't shown up in testing. Nothing catastrophic, but the kind of thing that would have generated 15 support tickets on day one if we'd gone full-steam.

ゴーライブは終わりではない。実際のユーザー行動データが流入し始まるきっかけに過ぎない。

---

FAQ

このようなカスタムCRMは一般的にいくら程度かかるのか？

正直なところ、大きく異なるが、このレベルでスコープされた14週間のプロジェクトで、小規模チーム（バックエンド開発者2名、フロントエンド開発者1名、プロジェクトリード1名）の場合、統合とデータ移行の複雑さに応じて通常£60,000～£120,000の間で推移する。フルカスタムビルドで£30,000未満の見積もりを目にしたら、既存テンプレートから実際に構築されているものと単に設定されているものを厳しく詰問すること。

WordPressでカスタムCRMを構築できるか？

できるが、約500レコードまたは20同時ユーザーを超えるものであれば、私はやらない。WordPressのデータレイヤーはリレーショナルCRMワークロード向けに設計されていない。Seahawkでは小規模クライアント向けにWordPress上に連絡先管理層を構築したことはあるが、真剣なものであれば、リレーショナルデータベースを備えた適切なバックエンドが正しい選択肢だ。

CRMビルドでチームが犯す最大の誤りは何か？

パーミッションモデルの過度な単純化。みんなは機能に目を向けて、80人のユーザーを抱えるCRMが「誰がどの案件を見られるのか」という細かい答えを必要としていることを忘れてしまう。API ルートを1本も書く前にこれを決めておく必要があるのに、10週目にロールベースアクセス制御を後付けするのは、実際に一度やるまでは説明しがたいほどに大変だ。

その正確なテックスタックを毎回使うのか？

いや。説明したスタックはこのプロジェクトのチームと制約に合っていただけだ。LaravelとVueでCRMを構築したこともあるし、DjangoとReactでも、Next.jsのフルスタック構成でも船出させたことがある。最後のそれは当初は懐疑的だったが、実際にはうまくいった。アーキテクチャの原則は変わらない。ツールは柔軟に選ぶ。

結局のところ、このカスタムCRMプロジェクトは単なるチャレンジではなく、啓示だった。その厳しい14週間の期限？それが私たちにイノベーション、適応、そして納品を強制した。結局のところ、制約は創造性の触媒になり得るのだ。締め切りが自分たちの職人技についてこんなにも多くを教えてくれるなんて、誰が予想しただろうか。Seahawk Mediaを共同創業した理由を思い出させてくれるのは、こういったプロジェクトなのだ。