Zenn記事の書き方｜構成テンプレと手順

2026-06-15 ・ Zenn-AI+ の中の人

Zennで技術記事を書こうとして、書き出しで手が止まる。あるいは書き終えたのに何を伝えたい記事か自分でも曖昧になる。原因の多くは「型」を決めずに書き始めることです。この記事では、再現性のある構成テンプレートと、Markdown・コードブロックの実務的な使い方を手順で示します。

まず結論：記事は5つのブロックで組む

技術記事は次の順番で組むと、読者が迷わず最後まで読めます。書く前にこの見出しだけ先に並べてしまうのが近道です。

課題：何に困っていて、この記事で何が解決するか
前提：環境・バージョン・対象読者
手順：再現できる具体的なステップ
ハマりどころ：詰まった点と回避策
まとめ：要点の再掲と次の一歩

この5ブロックは、読者が検索で記事に来る動線とそのまま一致します。検索する人は「困っている → 自分の環境で再現できるか確認したい → 詰まる前に注意点を知りたい」という順で読みます。

各ブロックの書き方と例文

1. 課題：1〜2文で言い切る

冒頭で読者に「これは自分の記事だ」と感じてもらえないと離脱します。背景説明から入らず、課題から入ります。

例：「Next.jsのApp RouterでうまくCookieが読めない。原因はServer Component側の取得方法でした。同じ症状を最短で直す手順をまとめます。」

2. 前提：再現性の土台

バージョン差で手順が動かないのは技術記事で最も多いクレームです。箇条書きで明示します。

OS / ランタイム（例：macOS, Node.js 20）
主要ライブラリのバージョン（例：Next.js 14.2）
想定読者（例：Reactは触ったことがある人）

3. 手順：コピペで動く粒度に

各ステップは「何をするか」を見出しにし、その下にコマンドやコードを置きます。コードブロックは言語名を付けるとシンタックスハイライトが効きます。

```ts
// app/page.tsx
import { cookies } from 'next/headers'

export default function Page() {
  const token = cookies().get('token')?.value
  return <p>{token ?? 'no token'}</p>
}
```

ZennのMarkdownでは、ファイル名を併記すると読者が貼り付け先を間違えにくくなります（例：```ts:app/page.tsx のように書く）。注意を促したいときはメッセージ記法も使えます。

:::message
このコードは Server Component 前提です。'use client' では動きません。
:::

4. ハマりどころ：自分の失敗をそのまま書く

ここが記事の差別化点になります。きれいな手順より「自分はここで30分溶かした」という情報のほうが読者に刺さります。

出たエラーメッセージを原文で載せる（検索で見つけてもらえる）
なぜ起きたかを一言添える
回避策を具体的に書く

5. まとめ：要点と次の一歩

箇条書きで2〜3点に再圧縮し、関連記事や公式ドキュメントへのリンクで締めます。

Markdown・執筆の実務メモ

見出しは h2 から使い、h1 はタイトルが担うので本文では使わない
長い文章は3〜4文ごとに段落を分け、スマホでの可読性を確保する
コードブロックには必ず言語指定を付ける
画像はキャプチャより、可能なら図やコードで示すほうが陳腐化しにくい

下書きの段階では、まず見出しだけ全部置いて、空の各ブロックを埋めていくと迷いません。

ちなみに、書き出しや章立てで止まりがちなら、筆者が個人で作っている非公式のChrome拡張「Zenn-AI+」も選択肢のひとつです。zenn.devの執筆画面にサイドバーを足し、タイトル候補や冒頭文、章立て、コードレビュー、読みやすさ評価などを補助します。無料機能は毎日（回数上限あり）使え、無制限のProは月¥980（決済はExtensionPay）。設計はBYOK（自分のClaudeまたはOpenAIのAPIキーを使い、本文やキーは運営サーバーに送らずローカル保存、AI利用料は自分のAPI契約に直課金）です。あくまで下書きの補助で、最終的な構成と検証は自分の手で行うのが前提です。ストアページから確認できます。

まとめ

書く前に「課題→前提→手順→ハマりどころ→まとめ」の見出しを先に並べる
前提とコードブロックの言語指定で再現性を担保する
ハマりどころこそが他記事との差になる

型が決まれば、あとは各ブロックを埋めるだけです。1本目を書き上げたら、その記事自体を次のテンプレートとして再利用していきましょう。