--- title: "さよならFigma MCP。Pencil.devでデザインをGit管理する開発フロー【実践ガイド】" description: "Pencil.devの.penファイルをGitで管理し、PRベースでデザインレビューする実践的な開発フローを解説。Figma MCPとの比較、チーム運用パターン、Figmaからの段階的移行ガイドも網羅。" url: "https://shiftb.dev/articles/pencil-git-workflow" publishedAt: "2026-04-05" updatedAt: "2026-04-05" author: "立川修平（ぶべ）" category: "tools" tags: ["Pencil.dev", "Git管理", "Design as Code", "デザインツール", "開発フロー"] --- # さよならFigma MCP。Pencil.devでデザインをGit管理する開発フロー【実践ガイド】 「デザインの最新版ってどこにあるの？」「Figmaのリンク、どれが正しいの？」——チーム開発でこの問題、何度経験しただろう。コードはGitで完璧に管理しているのに、**デザインだけが別世界で漂流している**。これが、僕がFigma MCPに限界を感じた最大の理由です。 2026年、[Pencil.dev](https://shiftb.dev/articles/pencil-dev-guide)の登場で状況が一変しました。デザインデータが**.penファイル（JSON形式のテキスト）**としてリポジトリに直接格納されることで、コードとデザインを**完全に同じGitワークフローで管理**できるようになったんです。 僕自身、ShiftBの開発チームでPencil × Gitフローを3ヶ月運用してきました。デザインレビューがPR上で完結するようになり、**デザイン起因の手戻りが約80%削減**。Figma時代に毎週3時間かけていた「デザイン同期作業」がゼロになりました。 この記事では、Pencilでデザインをgit管理する具体的なフロー構築から、チーム運用のパターン、Figmaからの移行手順まで、**実践で使えるレベルで徹底解説**します。 ## なぜデザインをGit管理すべきなのか ### コードとデザインの「二重管理」問題 現代のWeb開発では、コードは当然Gitで管理しています。ブランチを切り、PRを出し、レビューを経てマージする。このワークフローは**10年以上かけて磨かれた最適解**です。 ところが、デザインだけはこのフローの外にあります。Figma、Sketch、Adobe XD——いずれもクラウドやローカルの独自フォーマットでデータを保持し、**Gitの恩恵を一切受けられません**。この「二重管理」が引き起こす問題は深刻です。 | 問題 | 具体例 | 影響度 | | --- | --- | --- | | バージョンの不一致 | Figmaは最新だがコードが古い、またはその逆 | 高 | | 変更履歴の分断 | 「なぜこのUIに変わったのか」をFigmaとGitの両方を見ないと追えない | 高 | | レビューの非効率 | デザインレビューはFigma、コードレビューはGitHub、と2箇所で実施 | 中 | | ロールバックの困難 | コードはgit revertで戻せるが、デザインは手動で巻き戻す必要がある | 高 | | オフライン不可 | クラウド依存のため、飛行機内やネット不安定時にデザインを確認できない | 中 | ### IaCの成功から学ぶ——「コードで管理」の威力 インフラの世界では、かつてサーバー設定は手作業でした。それがTerraformやAWS CDKの登場で**Infrastructure as Code（IaC）**に進化し、インフラ構成もGitで管理できるようになりました。結果として、インフラの変更は**PR経由でレビュー可能**になり、事故が激減しました。 デザインも同じ道をたどるべきです。**Design as Code**——デザインデータをテキストベースでGit管理することで、コードと同じレベルの追跡性・再現性・コラボレーションが実現します。 ### Git管理がもたらす5つのメリット 1. **Single Source of Truth**：リポジトリが唯一の正解。「Figmaのどのページが最新？」問題が消滅 2. **アトミックな変更**：デザインとコードを1つのコミットで同時に変更できる 3. **完全な変更履歴**：git logで「誰が・いつ・なぜ」デザインを変えたか100%追跡可能 4. **ブランチ運用**：feature/redesign-topのようにデザイン実験をブランチで安全に試せる 5. **CI/CD統合**：デザイン変更をトリガーにビジュアルリグレッションテストを自動実行 ![従来のFigma管理とPencilのGit管理の比較図](https://shiftb.dev/images/articles/pencil-git-workflow-comparison.png) ## Figma MCPの限界——外部依存のリスク ### Figma MCPとは何だったのか Figma MCPは、AIエージェントがFigmaのデザインデータにアクセスするためのプロトコル接続です。Claude CodeやCursorからFigmaのデータを参照し、コード生成に活用できる——これ自体は画期的でした。 僕も最初は「これでデザインとコードの連携問題が解決する！」と期待しました。しかし**3ヶ月間実際に運用してみて**、根本的な限界が見えてきたんです。 ### Figma MCPの3つの構造的問題 **問題1：データが外部に依存している** Figma MCPはあくまでFigmaのクラウドからデータを「読み取る」だけです。デザインデータの実体はFigmaのサーバーにあり、**リポジトリには存在しません**。つまり、Gitの管理対象外です。 **問題2：読み取り専用の一方通行** Figma MCPは基本的にFigma→コードの一方通行です。コード側の変更をFigmaに反映する仕組みはなく、**デザインとコードの双方向同期ができません**。結果、時間が経つほどFigmaとコードが乖離していきます。 **問題3：API制限とレート制限** FigmaのAPIにはレート制限があり、大きなプロジェクトでは**1日あたりのリクエスト上限に引っかかる**ケースがあります。チーム全員がAIエージェント経由でFigmaにアクセスすると、レート制限に達して作業が止まることもありました。 ### 比較：Figma MCP vs Pencil Git管理 | 比較項目 | Figma MCP | Pencil Git管理 | | --- | --- | --- | | データの所在 | Figmaクラウド（外部） | Gitリポジトリ内（ローカル） | | バージョン管理 | Figma独自の履歴（30日制限あり） | Gitの完全な履歴（無制限） | | 差分の確認 | Figmaの比較機能（限定的） | git diff（行単位で精密） | | ブランチ運用 | Figma Branchesあり（有料プラン） | Gitのブランチをそのまま利用（無料） | | オフライン対応 | 不可 | 完全対応 | | レビューフロー | Figma上でコメント→GitHub PRは別 | GitHub PR一箇所で完結 | | CI/CD統合 | 別途構築が必要 | Git hookで自然に統合 | | コスト | Figma Professional $15/月 + MCP設定工数 | Pencil無料 + 既存Gitインフラ | Bad：Figma MCPに依存したフロー Figmaでデザイン → MCP経由でAIがデータ取得 → コード生成 → PR作成。デザイン変更時はFigma側を更新して再度MCP経由で取得。**デザインの変更履歴はFigma上にしか残らず、GitのPRにはコードの差分だけが表示される。** Good：Pencil Git管理フロー Pencilでデザイン → .penファイルの変更がgit diffで確認可能 →コード変更と一緒にcommit → PR作成。**デザインとコードの変更が1つのPRで同時にレビューでき、完全な変更履歴がGitに残る。** ## Pencil.devのDesign as Codeアプローチ ### .penファイルの構造——なぜGitと相性が良いのか [Pencil.dev](https://shiftb.dev/articles/pencil-dev-guide)のデザインデータは**.pen拡張子のJSONテキストファイル**として保存されます。バイナリではなくテキストだからこそ、Gitの強力な差分管理が機能します。 ``` // header.pen の中身（実際のJSONデータ） { "type": "frame", "name": "Header", "width": 1440, "height": 72, "background": "#ffffff", "children": [ { "type": "text", "content": "ShiftB", "fontSize": 24, "fontWeight": "700", "color": "#1a1a2e" }, { "type": "frame", "name": "Navigation", "layout": "horizontal", "gap": 32, "children": [ { "type": "text", "content": "記事", "fontSize": 16 }, { "type": "text", "content": "コース", "fontSize": 16 }, { "type": "text", "content": "お問い合わせ", "fontSize": 16 } ] } ] } ``` このJSONは**人間が直接読める**レベルに整理されています。「Headerのフォントサイズが24pxで、Navigation内のリンク間隔が32pxのgap」——デザインの意図がテキストで明確に表現されています。 ### git diffで見るデザイン変更 例えば、ヘッダーの背景色を白から濃紺に変更した場合、git diffは以下のように表示されます。 ``` diff --git a/design/header.pen b/design/header.pen --- a/design/header.pen +++ b/design/header.pen @@ -4,7 +4,7 @@ "name": "Header", "width": 1440, "height": 72, - "background": "#ffffff", + "background": "#1a1a2e", "children": [ { "type": "text", - "color": "#1a1a2e" + "color": "#ffffff" ``` **1行ごとに何が変わったかが一目瞭然**です。Figmaの「バージョン履歴」では画面全体のスナップショットを比較するしかありませんが、Pencilなら**プロパティ単位で変更を追跡**できます。 ### マージコンフリクトも怖くない チーム開発では、複数人が同じファイルを変更してコンフリクトが発生することがあります。.penファイルはテキストなので、**通常のJSONファイルと同じ方法でコンフリクトを解決**できます。 ``` <<<<<<< HEAD "fontSize": 28, "fontWeight": "800" ======= "fontSize": 24, "fontWeight": "700", "letterSpacing": 1.2 >>>>>>> feature/typography-update ``` VS CodeやCursorのマージエディタで、どちらの変更を採用するか（あるいは両方を組み合わせるか）を視覚的に選択できます。**Figmaではコンフリクト解決がブラックボックスですが、Pencilなら完全に透明**です。 ![PRでのデザイン差分レビューのイメージ](https://shiftb.dev/images/articles/pencil-git-workflow-pr.png) ## 実践：Pencil × Git開発フローの構築手順 ### ステップ1：プロジェクト構成を設計する まず、リポジトリ内での.penファイルの配置を決めます。僕が実際に使っている構成はこちらです。 ``` my-project/ ├── design/ # デザインファイル置き場 │ ├── pages/ │ │ ├── top.pen # トップページ │ │ ├── login.pen # ログインページ │ │ └── dashboard.pen # ダッシュボード │ ├── components/ │ │ ├── header.pen # ヘッダー │ │ ├── sidebar.pen # サイドバー │ │ └── button.pen # ボタン群 │ └── tokens/ │ └── design-tokens.pen # カラー・フォント定義 ├── src/ # ソースコード │ ├── components/ │ ├── pages/ │ └── ... ├── .gitattributes # .pen用の設定 └── package.json ``` ポイントは、**design/ディレクトリをsrc/と並列に配置する**こと。コードとデザインが同じ階層にあることで、「このコンポーネントのデザインはどこ？」が直感的にわかります。 ### ステップ2：.gitattributesを設定する .penファイルのGit管理を最適化するため、.gitattributesに以下を追加します。 ``` # .gitattributes *.pen text diff=json *.pen linguist-language=JSON ``` **text diff=json**を指定することで、GitHubのPR画面でJSON形式のシンタックスハイライトが適用されます。**linguist-language=JSON**でGitHubの言語統計にもJSONとして表示されます。 ### ステップ3：Pencilをインストールして初期デザインを作成 Pencilの[インストール手順](https://shiftb.dev/articles/pencil-dev-guide)は別記事で詳しく解説していますが、基本は以下の3ステップです。 ![Pencil.devダウンロードページ。VS Code / Cursor拡張機能またはデスクトップアプリから選択](https://shiftb.dev/images/articles/pencil-dev-guide-ss-downloads.png) 1. VS CodeまたはCursorの拡張機能マーケットプレイスで「Pencil」を検索してインストール 2. コマンドパレット（Cmd+Shift+P）から「Pencil: New Design File」を実行 3. 保存先をdesign/ディレクトリに指定 初期デザインを作成したら、最初のコミットを作ります。 ``` git add design/ git commit -m "feat(design): add initial design files with Pencil" git push origin main ``` ### ステップ4：featureブランチでデザインとコードを同時に変更 ここからがPencil × Gitフローの真骨頂です。新しいUIの実装は、必ずfeatureブランチで行います。 ``` # 1. featureブランチを作成 git checkout -b feature/redesign-header # 2. Pencilでデザインを編集（IDEのキャンバス上で操作） # → design/components/header.pen が自動更新される # 3. デザインに合わせてコードを実装 # → src/components/Header.tsx を変更 # 4. デザインとコードをまとめてコミット git add design/components/header.pen src/components/Header.tsx git commit -m "feat: redesign header with new navigation layout" # 5. PRを作成 git push origin feature/redesign-header ``` このフローの最大の利点は、**デザイン変更とコード変更が1つのコミット・1つのPRに含まれる**こと。「デザインは更新されたけどコードがまだ」という中間状態が原理的に発生しません。 ![Pencil × Gitの開発フロー図](https://shiftb.dev/images/articles/pencil-git-workflow-flow.png) ### ステップ5：コミットメッセージのルール デザイン変更を含むコミットには、わかりやすいプレフィックスを付けることを推奨します。 | プレフィックス | 用途 | 例 | | --- | --- | --- | | `feat(design):` | 新しいデザインの追加 | feat(design): add pricing page layout | | `fix(design):` | デザインの修正 | fix(design): adjust button padding on mobile | | `refactor(design):` | デザイントークンの整理 | refactor(design): consolidate color tokens | | `feat:` | デザイン+コードの同時変更 | feat: redesign header with new nav | ## チーム開発での運用パターン（PR・レビュー・CI/CD） ### PRテンプレートにデザインセクションを追加 チームでPencilを運用する際は、PRテンプレートにデザイン変更の説明欄を設けると効果的です。 ``` ## デザイン変更 - [ ] design/ 配下のファイルに変更あり - 変更したデザインファイル: `design/components/header.pen` - 変更内容: ヘッダーのナビゲーションを3項目→5項目に拡張 - スクリーンショット:（変更前/変更後を貼付） ## コード変更 - ...（通常のPR説明） ``` ### レビューの3ステップフロー デザインを含むPRのレビューは、以下の3ステップで行います。 1. **差分チェック（5分）**：.penファイルのgit diffを確認。プロパティの変更が意図通りか確認 2. **ビジュアル確認（3分）**：Pencilのプレビュー機能またはVercelのプレビューデプロイでUIを目視確認 3. **コード整合性チェック（5分）**：.penファイルの変更とコードの変更が整合しているか確認 合計**約13分**でデザイン＋コードのレビューが完了します。Figma時代は「Figmaを開いてコメント→GitHubに移動してコードレビュー→Figmaに戻って確認」と**30分以上**かかっていたので、半分以下に短縮できました。 ### CI/CDパイプラインへの統合 デザインファイルがGit管理されていれば、CI/CDパイプラインに組み込むのも簡単です。以下は僕が実際に使っているGitHub Actionsの設定例です。 ``` # .github/workflows/design-check.yml name: Design Check on: pull_request: paths: - 'design/**/*.pen' jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Validate .pen files (JSON syntax) run: | for file in $(git diff --name-only origin/main...HEAD -- 'design/**/*.pen'); do echo "Validating $file..." cat "$file" | python3 -m json.tool > /dev/null done - name: Check design tokens consistency run: | node scripts/check-design-tokens.js ``` このワークフローは、design/配下の.penファイルが変更されたPRに対して自動で実行されます。JSONのバリデーションとデザイントークンの整合性チェックを行い、**壊れたデザインファイルのマージを防止**します。 ### ブランチ戦略とデザインの関係 チーム開発では、以下のブランチ戦略を推奨します。 Good：推奨ブランチ戦略 - **main**：本番のデザイン＋コード - **feature/xxx**：機能単位でデザイン＋コードをセットで変更 - **design/xxx**：デザインのみの大規模リニューアル時に使用 - **hotfix/xxx**：緊急のUI修正（文字化け、レイアウト崩れ等） Bad：避けるべきパターン - デザイン変更とコード変更を別々のブランチで行い、後からマージ（乖離の原因） - mainブランチに直接デザイン変更をpush（レビューをスキップ） - .penファイルを.gitignoreに入れてしまう（管理対象外にする意味がない） ## 移行ガイド：FigmaからPencilへの段階的移行 ### 一括移行はNG——段階的アプローチが正解 すでにFigmaで大量のデザインを管理しているチームが、いきなり全てをPencilに移行するのは現実的ではありません。僕が推奨するのは**4段階の移行プラン**です。 | フェーズ | 期間 | 内容 | リスク | | --- | --- | --- | --- | | Phase 1 | 1〜2週間 | 新規ページのみPencilで作成。既存はFigmaのまま | 低 | | Phase 2 | 2〜4週間 | 頻繁に更新するコンポーネントをPencilに移行 | 低〜中 | | Phase 3 | 4〜8週間 | 主要ページのデザインをPencilに移行。Figmaは参照用に維持 | 中 | | Phase 4 | 8週間〜 | Figmaを完全に参照用アーカイブに。Pencilがメインに | 低 | ### Phase 1：新規ページから始める（1〜2週間） 最もリスクが低いのは、新しく作るページやコンポーネントだけをPencilで作成する方法です。既存のFigmaデータには一切触れません。 1. Pencilをチーム全員のIDEにインストール（**所要時間：1人あたり5分**） 2. プロジェクトにdesign/ディレクトリを作成 3. 新規タスクのデザインをPencilで作成し、PRに含める 4. 2週間後に振り返り：メリット/デメリットを共有 ### Phase 2：高頻度コンポーネントの移行（2〜4週間） Phase 1で感触を掴んだら、**更新頻度の高いコンポーネント**からPencilに移行します。例えば： - ヘッダー／フッター（月に2〜3回変更があるもの） - CTAボタン（A/Bテストで頻繁に変わるもの） - フォーム（バリデーションUI等の改善が多いもの） FigmaからPencilへの変換は手作業になりますが、[Pencil MCPとClaude Codeを連携](https://shiftb.dev/articles/pencil-mcp-claude-code)すれば、自然言語で「Figmaのこのコンポーネントを再現して」と指示するだけで**AIが.penファイルを生成**してくれます。1コンポーネントあたり**5〜15分**で移行できます。 ### Phase 3-4：本格移行とFigmaのアーカイブ化 主要ページの移行が完了したら、Figmaは「過去のデザインを参照するためのアーカイブ」として位置づけます。新しいデザイン作業は全てPencilで行い、Figmaの有料プランはダウングレードまたは解約できます。 ShiftBの場合、**Phase 1開始から約10週間**でPhase 4に到達しました。Figma Professionalプラン（**$15/月 × 3名 = $45/月**）の削減にもつながっています。 移行時のTips - FigmaのデザインをスクリーンショットとしてPRに添付しておくと、移行の「Before/After」が明確に残る - デザイントークン（色、フォントサイズ、余白等）はPhase 2の最初に統一しておくと後工程が楽 - [非デザイナー向けのPencil活用](https://shiftb.dev/articles/pencil-prototype-nondesigner)ガイドを事前に共有しておくと、PM・マーケターの混乱を防げる ## よくある質問（FAQ） ### Q1. デザイナーがいるチームでもPencilは使えますか？ 使えます。Pencil自体がデザインキャンバスを備えているため、デザイナーもIDE上で作業できます。ただし、Figmaの高度な機能（Auto Layout、コンポーネントバリアント等）に強く依存しているチームは、Phase 1-2で並行運用しながら徐々に移行するのがおすすめです。[Pencil vs Figmaの詳細比較](https://shiftb.dev/articles/pencil-vs-figma)も参考にしてください。 ### Q2. .penファイルが大きくなりすぎてリポジトリが重くならない？ 一般的なWebアプリのデザインであれば、.penファイル全体で**1〜5MB程度**です。JSONテキストなので、Gitの差分圧縮が非常に効率的に機能します。100ページ規模のプロジェクトでも、リポジトリサイズへの影響は**2〜3%以下**に収まります。画像アセットは別途管理する設計なので、バイナリファイルでリポジトリが肥大化する心配もありません。 ### Q3. .penファイルのコンフリクトが頻発しませんか？ 実運用上、コンフリクトの発生頻度はTypeScriptのコードファイルと同程度です。.penファイルはコンポーネント単位で分割するため、同じファイルを複数人が同時に編集するケースは限られます。万が一コンフリクトが発生しても、**JSONなのでテキストエディタで解決可能**です。3ヶ月の運用で発生したコンフリクトは**合計4回**で、全て5分以内に解決できました。 ### Q4. Figmaのプラグインやコミュニティ資産は使えなくなりますか？ はい、FigmaのプラグインはPencilでは使えません。ただし、Pencilには**MCP経由でAIエージェントが直接操作できる**という強力な代替手段があります。Figmaプラグインで実現していた自動化は、[Claude Code + Pencil MCP](https://shiftb.dev/articles/pencil-mcp-claude-code)で同等以上のことが可能です。 ### Q5. 既存のデザインシステム（Figma）はどうすればいい？ Phase 2で説明した通り、高頻度で使うコンポーネントから段階的に移行します。デザイントークン（色・フォント・余白）は**design/tokens/design-tokens.pen**にまとめ、コードのCSS変数やTailwind設定と同期させます。移行期間中は、Figmaのデザインシステムは**読み取り専用のリファレンス**として残しておくのがベストプラクティスです。 ### Q6. Pencilの学習コストはどれくらい？ エンジニアなら**30分〜1時間**で基本操作は習得できます。.penファイルの構造はJSONなので、フロントエンドエンジニアにとっては馴染みのある形式です。Figmaの学習に**10〜20時間**かかることを考えると、大幅に学習コストが低いと言えます。[Pencil.devの使い方ガイド](https://shiftb.dev/articles/pencil-dev-guide)を見ながら進めれば、つまずくポイントはほぼありません。 ### Q7. PencilでデザインしたUIをFigmaにエクスポートできる？ 2026年4月時点では、Pencilから直接Figma形式にエクスポートする公式機能はありません。ただし、.penファイルがJSONなので、変換スクリプトを自作することは可能です。また、Pencilの開発ロードマップには**他ツールへのエクスポート機能**が含まれており、今後対応される可能性が高いです。 ### まとめ：Design as Codeは「次の当たり前」 IaCがインフラの標準になったように、Design as Codeはフロントエンド開発の標準になると僕は確信しています。Pencil.devとGitを組み合わせることで： - **デザインとコードの一元管理**が実現する - **PRベースのデザインレビュー**でチームのコミュニケーションが効率化する - **完全な変更履歴**で「なぜこのUIになったのか」が100%追跡可能になる - **CI/CD統合**でデザイン品質の自動チェックが可能になる 「さよならFigma MCP」——これは決してFigmaを否定する言葉ではありません。Figmaは素晴らしいツールです。しかし、**エンジニアのワークフローにネイティブに統合されたDesign as Code**の世界を一度体験すると、もう戻れません。 まずはPhase 1として、次に作るページのデザインをPencilで作ってみてください。.penファイルをgit addした瞬間、「あ、これが正しい姿だったんだ」と感じるはずです。