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

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

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

## ワークフロー

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

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

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

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

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

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

#### 共通

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

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

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

```bash
# 既存記事のフォーマット確認
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: 記事の執筆

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

#### ファイル作成

```bash
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 で作成する |