コーディング指示書の書き方｜手戻りを減らす6項目と渡し方

コーディング指示書を渡したのに、実装者から質問が何度も返ってくる。そんな往復に時間を取られていませんか。

手戻りを減らす鍵は、項目の数ではありません。数値・状態・画像の書き出し・確認先が、実装者が推測せずに手を動かせる粒度で決まっているかどうか。分かれ目はそこです。

この記事では、指示書を受け取って実装する側の視点から、即着手できる6項目、手戻りが増える書き方との比較、Figma前提で省ける部分、CMS案件で足したい4項目をまとめます。デザインデータはFigmaを前提にしています。

実装者は静止画でなく「決めごと」を読んでいる

私が指示書を開いてまず探すのは、きれいなデザイン画そのものではなく、その画面を作るために決まっていること、つまり数値・状態・書き出しルール・確認先です。

デザインカンプは、たいてい一番整った「通常時の一枚」ですが、実装はそこに描かれていない部分まで全部コードにしないと動きません。余白が何pxか、押せないボタンはどう見せるか、画像はどの形式で出すか。ここが指示書で決まっていないと、実装者は二択を迫られます。推測で作ってズレるか、質問して手を止めるか。どちらもプロジェクトの時間を削ります。

だから良い指示書とは、実装者が推測しなくて済む指示書です。項目の多さではありません。次の6項目は、受け取る側として、これが書いてあると即着手できると感じる要素です。

推測の数だけ、往復が増えます。

即着手できる指示書の6項目

上から順に、なぜ実装者がそこを見るのかを添えます。

• 対応範囲 ― どのページを、どの画面幅まで作るか。ここが曖昧だと見積もりも実装も始まらないので、「PCとスマホ」ではなく、対象ページと対応する画面幅の下限・上限まで書いてあると助かります。
• フォント・余白の数値 ― 「いい感じの余白」では実装できません。上下32pxのように数値で。Figmaなら数値は入っているので、「感覚で調整せずカンプの数値どおりに」と一言あるだけで、私は迷いなく写せます。
• 状態の指定 ― hover・focus・error・空・送信中など、動いたときの見た目。ここは特に抜けやすい箇所です。抜けると必ず確認の往復が起きます。
• 画像の書き出し ― どれをSVGで、どれを写真として出すかと、形式・倍率・ファイル名の付け方まで決まっていると、書き出しで止まりません。
• 挙動・アニメーション ― どこが動くのか、どのくらいの速さで。参考にしたい既存サイトのURLが1本あると、言葉より早く伝わります。
• 確認の窓口 ― 迷ったとき誰に、どのくらいで返事がもらえるかが決まっているだけで、実装者は止まらずに質問を投げられます。

すべてを完璧に埋める必要はなく、埋まっていない箇所は「ここはお任せ」と一言あれば、こちらで決めて確認しながら進められます。困るのは、決まっていないのに決まっているように見える状態です。

たとえば余白の欄に32pxとあり、カンプの実測がそれと少し違うとき、どちらを正にするかの確認が一往復増え、その間そのセクションの実装は止まったままになります。

同じ内容でも、書き方で手戻りは変わる

同じことを伝えるのでも、言葉の粒度で実装のしやすさは大きく変わります。左のように書かれると推測が入ります。右のように書かれると、推測は要りません。

たとえば「スマホでは縦に」。そのスマホが何pxまでを指すのかは、人によってずれますが、画面幅で「640px以下のとき縦」と書いてあれば、実装はそのまま一意に決まります。この考え方はレスポンシブ指示を画面幅で渡す話に詳しくまとめています。

状態についても同じで、通常時だけのカンプだと、hoverやエラーの見た目を実装者が勝手に決めることになります。渡す前に主要な状態を洗い出しておけば、後戻りは減るでしょう。これは実装前に返したい状態の抜けチェックリストで具体的に扱っています。

決まっていれば、写すだけ。

Figmaなら、指示書は「補足」でよくなる

FigmaのDev Mode（開発者向けの表示モード）では、要素を選ぶと寸法・余白・CSSの値を確認でき、フレームに「Ready for Dev」の印を付けたり、注釈を添えたりも可能です。つまりFigmaを渡してもらえるだけで、数値の多くは指示書に書き写さなくても実装者が読み取れます。

だからFigma前提なら、指示書の役割はカンプから読み取れないことに絞れ、具体的には動きの意図、状態の見せ方、画像をどう書き出すか、そして優先順位です。

逆に、Figmaに入っている数値がデザイナーの意図とずれているなら、指示書の一言のほうが優先されるので、「カンプの数値どおりに」と書くかどうかは渡す前に決めておいてください。

画像の書き出しは補足しておくと親切です。Figmaが標準で書き出せるのはPNG・JPG・SVG・PDFで、WebPは標準では出せません（プラグインを使えば可能です）。またSVGの書き出しは等倍のみとされています。写真は用途に応じた倍率を指定してもらえると、こちらで書き出しの判断に迷いません。ロゴやアイコンはSVG、写真はPNGやJPG、といった振り分けを一言添えてもらえるだけで十分です。

デザインデータの渡し方そのものはFigmaからのコーディング依頼で見ているポイントにもまとめています。

CMSが絡む案件は「あとから編集できる範囲」まで書く

更新をクライアント側でやる案件だと、指示書にもう一段いります。どこを編集できるようにするか、です。

カンプは完成した一枚なので、そこからは、この見出しが差し替わるのか、この3枚のカードが4枚に増えるのかが読み取れません。決まっていないと、実装者はとりあえず全部固定で組むか、逆に全部を編集可にするかのどちらかに寄せます。前者は公開後に「ここ直せないんですか」と言われ、後者は管理画面が入力欄だらけになって誰も触らなくなる。

自分のサイトの実績ページでは、本文のリッチテキスト1本に詰め込むのをやめ、課題と目的・担当範囲・使用技術・実装した機能を、それぞれ別の項目に分けています。分けたおかげで、空の項目はセクションごと消せる。1本に詰め込んでいたら、中身が無くても見出しだけ残ります。

分けた理由は、空の扱いが決まるから。

指示書に一言あると助かるのは、この4つ。

• 編集できる箇所 ― 文言だけか、画像も差し替えるか、セクションごと非表示にする必要があるか
• 繰り返しの最小と最大 ― カードが1枚のときと6枚のときで、組み方は変わります
• 文字数の想定 ― 見出しが1行で収まる前提のデザインは、2行になった瞬間に崩れる
• 画像の差し替え規則 ― 縦横比を固定するのか、はみ出しをどう処理するのか

項目の分け方そのものはヘッドレスCMSのフィールド設計に、誰が公開までできるかの整理はCMSの権限設計にまとめています。分け方はサイト内検索にも効いてきて、本文1本に全部入れていると検索の対象を絞ることもできません。

指示書は完璧でなく「決まっている」がゴール

まとめると、手戻りの少ない指示書は、項目が網羅されている指示書ではありません。実装者が推測せずに一手を打てる状態まで、数値・状態・書き出し・確認先が決まっている指示書です。

私自身、粒度の細かい指示書をいただいた案件ほど、質問の往復が少なく、仕上がりもカンプに近づくと感じています。逆に、決まっていない部分は無理に書き込むより「ここは相談」と明示してもらえたほうが、こちらから提案しながら埋められます。

指示書の粒度から一緒に整えたい、今ある資料で実装に足りるか見てほしい——そんなときはお問い合わせからお気軽にご相談ください。実装者の目線で、どこを足すと着手が速くなるかをお伝えします。

本記事は2026年7月に公開し、2026年9月にCMS案件についての節を加筆しました。Figmaの機能や書き出し仕様、CSSフレームワークの初期設定は変わる場合があるため、最新の情報もあわせてご確認ください。