Pencil.dev × Claude Codeで実用レベルの開発効率とコード品質は両立できるか｜第2弾：Pencil.dev × Claude Codeで作ったコードは、実務で使えるか？

前回の第1弾では、Pencil.devで作ったデザインが実務で通用するか？を検証しました！
まだ読んでいない方は、こちらからどうぞ！

前回に引き続き、デザイナーとPM（エンジニア）の3名で検証していきます。

第2弾は、「デザイン→コード変換の実用性」にフォーカスし、シリーズ完結編としてお届けします！
早く本題を知りたいという方は「第2弾：Pencil.dev × Claude Codeで作ったコードは、実務で使えるか？」からお読みください。

---

はじめに

Pencil.dev ✕ Claude Code（第2弾）で確かめたいこと

第1弾で作成した .penファイル を使って、Claude Codeでコード生成を行います。
今回確かめたいのは以下の3点です。

• 生成されたコードの品質は、開発に乗せられるレベルか？
• 開発効率は、実際にどれくらい変わるのか？
• デザイン → フロントエンド開発までを、本当にシームレスにつなげられるか？

検証の進め方（再掲）

第1弾で提示した評価軸のうち、今回は「デザイン→コード変換の実用性」にフォーカスします。

題材は引き続き「架空の食器小売店サイト」です。
第1弾で生成した .penファイル を使用し、コード生成を行っていきます！

---

第2弾：Pencil.dev × Claude Codeで作ったコードは、実務で使えるか？

結論：Pencil.dev × Claude Codeでのコード生成は実務で通用する。

ただし、 .penファイル をそのままClaude Codeに渡しても、デザイン通りのコードは生成されない。

コード生成にも、AIに正しく作らせるための"前準備"が必要だった
— これが今回の最大の発見です。

この記事では、私たちが失敗から学んだ「 .penファイル → コード変換を成功させるためのコツ」を紹介します。

---

失敗談：.penファイルをそのまま渡したら、デザインと違うものが生成された

最初は、シンプルなフローで進めていました。

1. .pen からデザイン変数（ design-tokens.json ）を生成
   — design-tokens.json とは？
   .pen のデザイン変数（カラー・フォント・余白・角丸など）を読み取り、JSON形式のファイルに書き出したものです。
   .pen のみでは、デザイン変数の値が不明確なため、そのままコード側で参照できる形に変換する必要があります。
   　
2. アプリ仕様書（ app-spec.md ）を作成
   — app-spec.md とは？
   これから作るアプリの仕様をMarkdownでまとめたドキュメントです。
   画面構成・データ構造・機能要件などを記載し、AIが実装するときの「何を作るか」の根拠になります。
   　
3. 実装計画書を作成
   — app-spec.md と design-tokens.json をもとに、AIに実装手順を分解した計画書を生成。
   「どのファイルに、どんなコードを書くか」「コンポーネントの構造はどうするか」まで含んだ、いわば実装の設計図です。
   　
4. 実装
   — 実装計画書に沿って、Claude Codeにコードを生成させます。

つまり、「.penファイル（デザイン）」から「コード」までを、AIが読みやすい中間ファイル（design-tokens.json / app-spec.md / 実装計画書）でつないでいくフローです。

しかし、いざ実装してみると、デザインとはかけ離れたUIが出てきました。
フォントサイズが想定より小さい、本来ないはずの謎テキスト（"tetto"のような文字列）が混入する、レイアウトが崩れる…。

なぜ失敗したのか

原因を追っていく中で、いくつかの問題が見えてきました。

根本原因：AIが .penファイルを「要約」して読んでいた

これが一番大きな問題でした。
.pen はJSONベースのデータですが、Claude Codeは効率化のために内容を要約して扱おうとします。
さらに、.penファイル内に参考用に残していた別フレームの情報まで混ざり込み、本来生成したいデザインとは違うデザインを"再構成"してしまっていたのです。

その他に見えてきた課題

実装計画書のレビュー段階でも、以下のような問題が見つかりました。

• 実装計画書が1600行超
  — エンジニアがレビューするには分量が大きすぎる。これだけシンプルなサイトでこれだけの分量になるので、より複雑なページだと膨れ上がる。
  　
• DB前提が抜けてハードコード
  — 商品データが products.ts に直書きされ、実プロダクトでは使えない構成に
  　
• ファイル階層の重複
  — app/src/app/ のような不自然な構成
  　
• font-sizeがデザイントークンに反映されない
  — @theme に定義されず、text-[48px] のような任意値で書かれていた
  　
• h1タグがブランド名ではなくFVキャッチコピーに
  — SEO観点でNGな判断をAIが勝手に下していた
  　
• カテゴリーなどのデータがハードコード
  　

この失敗から学んだこと

「.penファイル と Claude Code を繋げばコードが出てくる」という単純な話ではなく、AIに正しく読ませて・正しく判断させるための仕掛けが必要だとわかりました。

具体的には次の3つです。

1. .penファイル自体を整理する
   — 要約されない／参考フレームが混ざらない状態にする。
   　
2. 実装ガイドラインを用意する
   — SEO観点、データ取得方針、ファイル構成など、AIが勝手に判断してはいけない領域を明文化する。
   　
3. 一度に全部生成しない
   — フェーズを分けて、都度目視確認を挟む。
   　

---

成功フロー：.penファイルを整えてから、段階的に生成する

成功フローに則れば、以下のようなサイトまで完成させることができます。

• ほぼピクセルパーフェクトなデザイン反映
• レスポンシブ対応の完了
• DBを差し替えるだけで実機で動くサイトの完成

失敗から得た教訓3つを実践したのが、以下の成功フローです。

Step 1：.penファイルのクリーンアップ

最初に着手したのは、 .pen 自体の整理です。

失敗の根本原因は「AIが .penファイルを要約して読んでいた」こと、そして「参考フレームが混在していた」ことでした。
どちらも、 .pen が整理されていれば防げた問題です。

具体的にやったことは3つです。

1. 確定フレームだけにする
デザイン検討段階で残していた「参考サイト準拠」フレームなどを全て削除し、確定フレームだけの状態にします。
参考フレームが残っていると、デザインの要約やテキストが混入する原因になります。

2. ノード名の統一
ノード名の命名規則が混在していたため、hero-text・intro-secのようにケバブケースへ統一しました。
AIはノード名をそのままコード上の識別子として扱うため、 .pen 上での命名の揺れが生成コードの揺れに直結します。

3. ハードコード値の変数参照化
カラーやフォントサイズが直接 hex 値やピクセル値ではなく、$foreground・$spacing-5 のような変数参照にします。
これにより、design-tokens.json への変換精度が上がり、トークンが正しくコードに反映されるようになります。

クリーンアップ前

クリーンアップ後

---

Step 2：仕様書（app-spec.md）と.penの同期

.pen を整理したあと、仕様書もそれに合わせて更新しました。

AIは .pen とapp-spec.mdの両方を参照してコードを生成するため、両者が食い違っていると混乱が生じます。
フレーム名・コンポーネント名・レイヤー名・変数をすべてを整理済みの .pen に合わせます。

---

Step 3：実装ガイドラインの整備

仕様書の同期と並行して、もう一つ準備が必要だとわかりました。AIに「何を使って書くか」を明示するガイドラインです。

今回の検証では、globals.css の @theme に CSS 変数（--color-background など）を定義していました。
しかし実装後にコードを確認すると、コンポーネントのインラインスタイルには '#111110' のような hex 値が直書きされており、CSS 変数はまったく使われていませんでした。

原因はシンプルで、「CSS 変数を使え」という指示がどこにも書かれていなかったからです。
AI は .pen のノードコメントに書かれた hex 値をそのまま参照してコードを生成します。変数を定義しておくだけでは、AI は自動的にそちらを使ってはくれません。

対策として有効なのは、CLAUDE.md や app-spec.md に以下のようなルールを明記することです。

• 色の指定は必ず var(--color-*) を使うこと。hex 値の直書き禁止
• フォントサイズは var(--font-size-*) を使うこと
• スペーシングは var(--spacing-*) を使うこと

「定義する」だけでなく「使わせる」ところまで指示して、はじめてトークンが活きます。
これも、AIに正しく書かせるための仕掛けのひとつです。

---

Step 4：段階的なコード生成

準備が整ったあとも、「一度に全部生成」はしませんでした。
以下の4フェーズに分けて、各フェーズごとにブラウザで目視確認を挟みながら進めました。

Phase 1：PC 静的再現
まず動きを一切つけず、PC サイズでデザインの見た目だけを再現します。
色・フォント・余白・レイアウトがデザインと合っているかを最初に確認することで、後続フェーズでの手戻りを防ぎます。

Phase 2：レスポンシブ対応
PC が確認できてから、Tablet・Mobile のブレークポイントを追加しました。
静的な状態で崩れがないことを先に確認できているため、レスポンシブ追加時の混乱が最小限になります。

Phase 3：インタラクション追加
ホバーエフェクト・商品画像のサムネイル切替・ページ遷移を追加しました。
見た目が固まった状態で動きを乗せることで、「デザイン崩れなのか、インタラクション実装の問題なのか」が切り分けやすくなります。

Phase 4：データ層整備
最後に、ハードコードされていた商品データをサービス層（productService.ts）に切り出しました。
将来的にDBに差し替える際も、このファイルだけを変更すれば済む構造になっています。

---

結果

フェーズを分けて進めることで、デザインとの齟齬がほとんど出ませんでした。
最初の失敗と比べると、生成されたコードの品質は別物です。

コード生成における「段階的な進め方」は、エンジニアが慣れ親しんだ「小さくリリースして確認する」開発スタイルとも一致しています。
AIを使う場合も同じ考え方が有効です。

---

まとめ - 検証から見えたこと｜第2弾：Pencil.dev × Claude Codeで作ったコードは、実務で使えるか？

Pencil.dev × Claude Codeだからこそのメリット

エンジニア視点

• デザイントークンが綺麗にCSSへ落ちる
  — .pen で変数として定義された色・フォント・余白が、そのままコードのスタイル定義に反映される。手作業での値の転記や、ズレが起きにくい。
  　
• コンポーネント構造が初手から整っている
  — .penのコンポーネント構造を引き継ぐため、設計の解釈ズレが起きにくく、整合性のある実装が最初から得られる。
  　
• デザイン変更がコードに反映しやすい
  — .pen を更新すれば、変更箇所の差分が明確なため影響範囲が把握しやすく、手戻りコストが低い。
  　

PM視点

• デザインカンプの再現精度が高い
  — .pen はJSONベースで管理されているため、AIがデザインデータを把握しやすく、再現精度の高いコードが得られやすい。
  　
• デザインと実装のズレを減らせる
  — .pen がそのままコードに渡るため、きちんとドキュメントを整備しておけば認識のズレが入り込む余地が少なくなる。
  　

コード生成の課題

• .penファイル自体の整理が前提条件
  — 参考フレームの扱いなど、ナレッジが必要
  　
• 実装ガイドラインの整備コスト
  — 初回は重め
  　
• トークン消費量
  — 実務で運用するならコスト管理が必須
  　
• 実装計画書のレビュー負荷
  — 1600行を人間がレビューするのは現実的でない
  　
• AIの勝手な判断
  — SEO・データ層・ファイル構成などはガイドラインで明示する必要がある
  　

AI時代におけるエンジニアの役割変化

第1弾では「デザイナーの役割変化」を語りました。今回見えたのは、エンジニア側にも同じ変化が来ているということです。

• コードを書く人から、AIに正しく書かせる設計者へ
  — 実装ガイドラインの策定、レビュー観点の言語化が新しい仕事になる。
  　
• 判断をAIに委ねないラインを引く力
  — SEO・セキュリティ・パフォーマンスなど、AIに任せてはいけない領域を明示する。
  　
• 品質の見極め
  — AIが出したコードを鵜呑みにせず、本当に運用に耐えるかを判断する。
  　

---

シリーズ総括：Pencil.dev × Claude Codeで実用レベルの開発効率とコード品質は両立できるか

ここまで読んでいただきありがとうございました。
シリーズ最初に立てた問い「Pencil.dev × Claude Codeで実用レベルの開発効率とコード品質は両立できるか」に、私たちなりの答えを出します。

結論：両立できる。ただし、AIに正しく作らせる"設計"が前提

両立できるかどうかは、AIに何を任せ、何を任せないかの線引きにかかっています。
私たちの検証で見えたのは、ドキュメント設計・.penの整理・実装ガイドラインといった"設計"があれば、AIは確かに開発を加速させてくれるということでした。

逆に、何の前準備もせず使うと、見た目だけそれっぽいデザインや、デザインから乖離したコードが生まれます。
それは「AIが使えない」のではなく、「AIに正しく使わせる設計ができていない」だけです。

5段階評価のまとめ

職種別！ Pencil.dev × Claude Code の総評

デザイナー視点

• 「データを作成する」手作業が効率化され、上流工程に時間を割ける
  — Pencil.dev は「デザインデータを作成する」という手作業を大幅に効率化する。1ページまるごとの生成から、変数・コンポーネント・命名規則の整備まで含めて立ち上がるため、削減できた時間を UX 設計やブランド方向性検討といった上流工程に振り向けられる。
  　
• AIとの対話で詰めていく、新しいデザインワークフロー
  — AIとの対話を通じてデザインを詰めていくという、新しいワークフローが生まれる。自分の判断基準やデザインルール、禁止事項を言語化して AI に渡すことが、そのままデザインを形にする作業になる。
  　
• .penは「デザインの最終形」ではなく「コードの一次ソース」になる
  — Claude Codeが .pen を直接読みに行くため、.pen はエンジニアに渡す前の中間成果物ではなく、コードを生み出す一次仕様になる。.penファイルという成果物の位置づけが、デザインデータからコードの仕様書へと格上げされる。
  　
• デザイナーの整理が、実装まで「ロスなく」届くようになる
  — 変数化・コンポーネント・命名規則を整える仕事は、Figmaでも行われてきた。ただ、実装に渡るタイミングでズレが生じたり、変換のコストがかかったりしていた。Pencil.dev × Claude Codeでは Claude Codeが.penファイルをそのまま読むため、デザインと実装のズレが構造的に小さくなる。
  　
• デザインの意図が、妥協なく実装まで届く
  — 第1弾では「デザインを作る」フェーズで、デザイナーが上流工程に集中できる環境が手に入ることを見た。
  第2弾で見えたのは、その先 ── しっかりとしたフローに則れば、デザイナーが1pxの単位までこだわった意匠が、解釈ズレや調整に飲み込まれず、そのまま実装まで残るということ。Pencil.dev × Claude Codeは、デザインの意図を妥協なく実装まで届けるための仕組みになり得る。
  　

エンジニア視点

• どこをスコープにAIに任せるかの見極めが重要
  — 一度に全部生成しようとすると品質が下がりやすい。実装のどこをスコープにAIに任せるかを見極めながら、フェーズを分けて都度確認を挟む進め方が品質向上につながった。
  　
• 実装ガイドラインの整備という新しい仕事が増える
  — SEO・データ層・ファイル構成など、AIに勝手に判断させてはいけない領域を明文化する必要がある。そのためには要求・要件をきちんと理解した上で、AIへの指示に落とし込む力が求められる。
  　
• AIの生成結果をレビューする目が求められる
  — AIが出したコードや実装計画書を鵜呑みにせず、品質・設計・デザイン再現性の観点で判断できるスキルが、これまで以上に重要になる。
  　

PM視点

• デザイン・ドキュメント・コードをGitで一元管理できる
  — .penがJSONベースであるため、デザインのバージョン管理がコードやドキュメントと同じリポジトリで行える。変更の経緯が一箇所で追えるため、プロジェクトの透明性が上がる。
  　
• コスト管理の観点が新たに加わる
  — デザインから実装まで一気通貫で進める性質上、トークン消費が積み重なりやすい。実務で運用するにはProプラン以上、場合によってはMaxプランが前提になる。
  　
• 上流での言語化・明文化がプロジェクトの質を左右する
  — デザインから実装まで一気通貫で進む分、上流で定義されていないものがそのままコードに反映されやすい。要件・判断軸・禁止事項を事前に言語化しておくことが、成果物の質に直結する。
  　
• 生成ドキュメントのレビュー体制が課題
  — AIが生成するドキュメントは分量が大きくなりやすく、誰がどのようにレビューするかの体制整備が今後の課題として残る。
  　

AI時代の開発チームに必要なもの

検証を通じて、AI時代の開発チームに必要なものが見えてきました。

• ドキュメントを書く文化
  — AIへの指示は、結局ドキュメントの質に依存する。
  　
• ルールを言語化する力
  — デザイナーがすでに持っているスキルが、チーム全体に求められる。
  　
• AIに正しく書かせる設計力
  — エンジニアに求められる新スキル。
  　
• 任せる/任せないの判断軸
  — PMやリーダーが全体を見渡して引くべき線。
  　

Pencil.dev × Claude Code を武器にできるかは、使う側の設計力次第

Pencil.dev × Claude Codeは、デザインの民主化ではなく、デザイナー・エンジニアの武器化に向かうツールセットだと、この検証を通じて感じました。

AIは仕事を奪うのではなく、本質的な判断にフォーカスさせてくれる存在です。
そのためには、ドキュメント・ルール・整理という"地味な設計"を私たち自身が積み上げていく必要があります。

私たちの結論として、Pencil.dev × Claude Code は十分に実務の武器になり得る。
ただし、それを引き出せるかどうかは、使う側のチーム設計にかかっている。

— これが、3名のデザイナー・PMで取り組んだシリーズ検証の最終的な答えです。
最後までお読みいただき、ありがとうございました！