zenn-article-writing

name	zenn-article-writing
description	Zenn (zenn.dev) の技術記事を、外部の人気記事の構成パターンを調査・分析した上で執筆するスキル。 記事の企画・構成・執筆・改善の全工程をカバーする。 「Zenn 記事書いて」「記事を書きたい」「ブログ書いて」「紹介記事を作って」「〇〇の記事を書いて」 「技術ブログを書きたい」「Zenn に投稿したい」「記事の構成を考えて」「記事をリライトして」 といった依頼で必ず使うこと。記事の一部修正やタイトル変更だけの場合は不要。

Zenn Article Writing - 人気記事リサーチ駆動の記事執筆スキル

Zenn 記事を書くとき、自分の感覚だけで構成を決めると「情報は正しいが読まれない記事」になりがち。人気記事には共通する構成パターンがあり、それを踏まえることで読者に届く記事になる。このスキルは「まず外を見て、それから書く」というワークフローを定着させるためのもの。

ワークフロー

Phase 1: 対象トピックのリサーチ

記事の対象（ツール、ライブラリ、技術、体験など）について十分な情報を集める。書く内容を深く理解していないと、表面的な記事になってしまう。

リポジトリ / ツール紹介の場合

• README、主要ソースコード、CHANGELOG を読む
• 技術スタック、設計思想、差別化ポイントを把握する
• npm / PyPI 等のパッケージ情報があれば確認する

技術トピック / 体験記の場合

• 関連する公式ドキュメントを確認する
• 自分が直面した課題と解決策を整理する
• 読者が再現できる具体的な手順・コードがあるか確認する

共通

• 「この記事で読者が得るもの」を1行で言えるようにする
• 足りない情報があればこの段階でユーザーに質問する

Phase 2: 既存 Zenn 記事のフォーマット確認

このリポジトリの既存記事を確認し、フォーマットとスタイルを揃える。

# 既存記事のフォーマット確認
ls articles/

確認するポイント:

• frontmatter の形式（title, emoji, type, topics, published）
• 見出しレベルの使い方（H1 / H2 の使い分け）
• トーン（カジュアル / フォーマル）
• リンクの貼り方、画像の使い方

Phase 3: 外部人気記事の調査・パターン分析（ここが核心）

記事のジャンルに合った Zenn 人気記事を WebSearch で 4〜6 本 調査し、構成パターンを抽出する。自リポジトリ内の記事だけを参考にしない。外の世界で実際に読まれている記事から学ぶ。

検索クエリ例

記事ジャンルに応じて検索を変える:

ジャンル	検索クエリ例
ツール紹介	site:zenn.dev "を作った" CLI ツール
ライブラリ紹介	site:zenn.dev "を使ってみた" {技術名}
体験記	site:zenn.dev "やってみた" OR "移行した" {技術名}
入門・解説	site:zenn.dev "入門" OR "完全ガイド" {技術名}
トラブルシュート	site:zenn.dev "ハマった" OR "解決した" {技術名}

各記事から抽出する情報

WebFetch で記事本文を取得し、以下を分析する:

1. タイトルのパターン ── 「〇〇を作った」「〇〇を解決する△△」「【完全ガイド】」等
2. セクション構成 ── H1/H2 の見出し一覧と、各セクションの役割
3. 冒頭のフック ── 最初の数行で読者をどう引き込んでいるか
4. ビジュアル要素 ── GIF デモ、スクリーンショット、図表、比較表の使い方
5. トーン ── カジュアル度合い、一人称、語尾
6. クロージング ── CTA（GitHub リンク、Star 依頼）、今後の予定、正直な自己評価

パターン分析のまとめ方

調査した記事群から、以下の形式で共通パターンをまとめる:

## 調査結果サマリ

### タイトルパターン
- ...

### 推奨セクション構成（順序）
1. ...
2. ...

### 効果的だった要素
- ...

### 記事ジャンル固有の注意点
- ...

このサマリをユーザーに共有し、構成の方向性について合意を取る。

Phase 4: 記事の執筆

パターン分析の結果に基づいて記事を書く。

ファイル作成

npx zenn new:article --slug {スラッグ名}

スラッグ名は記事の内容を端的に表す英語のケバブケース（例: ziku-bidirectional-template-manager）。

ジャンル別の推奨構成

調査結果から得た構成を最優先するが、以下はジャンル別のベースライン。調査で見つけたパターンでこれを上書き・拡張する。

「〇〇を作った」系（ツール/ライブラリ紹介）

順序	セクション	内容
1	はじめに	プロダクトの1行紹介 + リポジトリリンク + インストールコマンド
2	なぜ作ったのか	個人的な課題・ストーリー
3	既存ツールとの比較	比較表で差分を明示
4	主な機能	コマンド例・GIF デモ・スクリーンショット
5	使い方の流れ	実際の運用を追う具体的なステップ（セットアップ→日常利用のサイクル）
6	技術スタック	使用技術の一覧と選定理由
7	設計・こだわり	技術的に面白いポイントの深掘り
8	想定ユーザー	誰に使ってほしいか（3パターン程度）
9	今後の予定	ロードマップ
10	おわりに	正直な自己評価 + CTA（GitHub リンク、Star/Issue 歓迎）

「〇〇してみた / 入門」系

順序	セクション	内容
1	はじめに / TL;DR	何をしたか・結論を先に
2	背景・動機	なぜこれをやったのか
3	環境・前提	バージョン、OS、前提知識
4	手順	ステップバイステップ（コードブロック + 出力例）
5	ハマったポイント	トラブルと解決策
6	まとめ	学び・感想
7	参考リンク	公式ドキュメント等

執筆時のルール

• タイトル: 調査で見つけた人気パターンに合わせる。内容が伝わり、クリックしたくなるもの
• 冒頭3行: 記事の価値を明確にする。読者はここで読むか判断する
• コードブロック: 言語指定を必ず付ける。実行結果も併記する
• 比較表: 既存手法との差分は表で視覚化する
• トーン: 既存記事のトーンに合わせる（このリポジトリはカジュアル寄り）
• 長さ: 2,000〜3,500 語が目安（人気記事の分析から）
• published: false で作成し、ユーザーの確認後に true にする

Phase 5: ビジュアル要素の提案

CLI ツール紹介記事では GIF デモが読者の理解を大きく助ける。人気記事の大半が GIF を使っている。

記事執筆後、以下を提案する:

• どのコマンド/操作を GIF で撮るべきか
• スクリーンショットがあると効果的な箇所
• 図解（Mermaid 等）で説明した方が良い箇所

ビジュアルの撮影・作成自体はユーザーに委ねるが、「ここに GIF があると記事の訴求力が上がる」という具体的な提案を行う。

Phase 6: レビュー・改善

記事を書き終えたら、以下の観点でセルフレビューする:

1. 構成: 調査した人気記事のパターンに沿っているか
2. 冒頭: 最初の3行で記事の価値が伝わるか
3. 比較・差別化: 既存手法/ツールとの違いが明確か
4. 具体性: コード例、コマンド例、実行結果が十分か
5. 読了感: 読み終わった後に「試してみよう」と思えるか
6. CTA: リポジトリリンク、インストールコマンドが末尾にあるか

改善点があれば修正し、ユーザーに完成版を報告する。

アンチパターン

やりがち	なぜダメか	代わりに
自リポジトリ内の記事だけ参考にする	サンプルが少なく、偏った構成になる	外部の人気記事を 4〜6 本調査する
機能一覧を並べるだけ	カタログ的で読者が「自分に関係ある」と思えない	課題 → 解決の流れで書く
技術的正確さだけ追求	正しいが読まれない記事になる	共感できるストーリーを入れる
GIF/画像なしで CLI を説明	読者がイメージを掴めない	ビジュアル要素を必ず提案する
published: true で即公開	ユーザーが確認する前に公開される	必ず false で作成する