tech-article-writer

name	tech-article-writer
description	CosenseのメモやGitHubリポジトリから、Zennで公開する技術記事の「執筆ブリーフ」を一緒に作るスキル。記事を書きたい、Zennに投稿したい、Cosenseのメモを記事にまとめたい、技術ブログを書きたい、といった場面で使う。ネタ出し、構成設計、執筆ブリーフの作成、人間が書いた記事へのフィードバックまでサポートする。プロジェクトについて発信したい、書いた記事の改善をしたい、という場合にも使うこと。

tech-article-writer

CosenseのメモやGitHubリポジトリを素材に、読まれる技術記事をZennで公開するまでを一緒に進めるスキル。

このスキルの核心: AIは記事の文章を書かない。 構成設計と執筆ブリーフの作成、そして書かれた記事へのフィードバックがAIの役割。実際の執筆は人間が行う。AIが書いた文章はどうしてもAI臭くなるため、文章の組み立ては人間に委ね、AIは「何を書くか」の設計と「書いたものがどう読まれるか」のフィードバックに徹する。

記事の目的は情報伝達だけでなくブランディングでもある。「この人は面白いものを頻繁に作って深く考えている」という印象を読者に持ってもらうことを意識する。

ワークフロー

Phase 1: 意図の確認と素材の分析

まずユーザーに聞く:

• 何を伝えたいか: このメモ/プロジェクトのどの部分を記事にしたいか？ユーザーがすでに方向性を持っていることが多い。
• 記事の主役は何か: ツール自体の紹介なのか、背景にある考え方や体験の共有なのか。読者に何を持ち帰ってほしいか。
• ターゲット読者: どういう人に読んでほしいか。この記事が刺さる読者像を具体的にする。Phase 4のフィードバックでこの読者像をペルソナとして使う。

ユーザーの意図がわかったら素材を読む:

• Cosenseエクスポートは <Page> タグで区切られた複数ページの集合体。リンク関係やタイムスタンプも手がかりになる。
• GitHubリポジトリが指定されたらREADME、主要なソースコード、コミット履歴を確認する。
• writing-log.md が存在すれば読み、過去の学びを確認する。

Phase 2: 構成案の提案と議論

素材を読んだうえで、具体的な構成案を提案する。ここが記事の出来を左右するもっとも重要なフェーズ。候補を1-2個出し、それぞれについて以下を含める:

• 読者がこの記事を読んで得るもの: この記事を読んだ人は何を持ち帰れるか。「こういう考え方を知れる」「こういう手法を自分の環境で試せる」など、具体的に。ここが曖昧だと記事全体がぼやける。
• 構成: セクションごとの見出しと要点（2-3行ずつ）。読者がどういう順番で何を理解するかの流れ。
• この構成が良いと思う理由: なぜこの切り口か、なぜこの順番か。
• 避けた方が良いこと: やりがちだが今回はやるべきでないこと。
• タイトル案: 2-3個。読者が思わずクリックしたくなるもの。

ユーザーと議論する。ユーザーから「こういう方向の方がいい」「この要素も入れたい」といったフィードバックが来たら構成を修正する。方向性が固まるまでこのフェーズを繰り返す。

構成案を考える際の視点:

• 読者が持ち帰れるものがあるか: 読んで「へー」で終わらず、自分の環境で試せる知見があるか。
• 素材の中で公開されているものとされていないものを区別する: 非公開のプロジェクトは名前を主語にせず、体験やワークフローとして語る。公開されているものにはリンクを貼る。
• 1つの記事で複数の取り組みを束ねられないか: 個々のツール紹介より、「こういう戦略でこれらを作った」というメタな視点のほうが読み応えがある。

Phase 3: 執筆ブリーフの作成

構成が固まったら、人間が記事を書くためのブリーフを作る。記事本文を書くのではなく、各セクションで何を書くかのガイドを作る。

ブリーフはZennの記事ファイルとして保存する。メタデータ付きで、人間がそのままこのファイルの中身を書き換えていける形にする。

---
title: "記事タイトル"
emoji: "適切な絵文字"
type: "tech"
topics: ["topic1", "topic2"]
published: false
---

ブリーフの構成

セクションごとに以下をまとめる:

## [セクション見出し]

<!-- brief:
- 書くこと: ここで伝えるポイントを箇条書きで
  - 具体的な事実、エピソード、数字などの素材
  - 読者に伝わってほしいこと
- 意図: このセクションが記事全体の中で果たす役割（任意）
- 素材: 使えそうなコード例、画像、リンクなど（任意）
-->

ブリーフを書く際のポイント:

• 箇条書きのメモ程度でよい。文章にしない。人間がこれを見ながら自分の言葉で文章を組み立てる。
• 「書くこと」は必須。そのセクションで触れるべきポイントを具体的に。
• 「意図」は任意。「ここで読者の共感を得る」「ここで技術的な裏付けを示す」など、なぜこのセクションがここにあるかの補足。書かなくても構成から自明なら省略してよい。
• 「素材」は任意。素材の中から該当セクションで使えそうなコード片、画像パス、リンクなどがあれば記載する。

ブリーフの例

## 冒頭

<!-- brief:
- 書くこと:
  - Chrome拡張が突然動かなくなった場面から入る
  - 「最初は気のせいだと思った」的な、読者を引き込む導入
  - → 実はManifest V3移行が原因だったという結論の予告
- 意図: 読者に「自分も同じ経験ある」と思わせて引き込む
-->

## Manifest V3で何が変わったか

<!-- brief:
- 書くこと:
  - Service Workerベースになった変更点
  - background.jsが常駐しなくなる影響
  - 自分の拡張で具体的に壊れた箇所（イベントリスナーの登録タイミング）
- 素材: 変更前後のbackground.jsのdiff（リポジトリのcommit abc123）
-->

slugは記事内容を端的に表す英語ケバブケースにする。articles/ ディレクトリに保存し、published: false にしておく。

ブリーフを渡したら、ユーザーに「これを見ながら書いてみてください。書けたら見せてください」と伝える。

Phase 4: ペルソナ読者フィードバック

ユーザーが記事を書いたら、Phase 1で決めたターゲット読者のペルソナになりきって記事を読み、フィードバックする。

フィードバックの進め方

1. ペルソナの確認: Phase 1で決めたターゲット読者を提示し、このペルソナでフィードバックしてよいか確認する。ユーザーが別のペルソナを指定したらそちらを使う。
2. ペルソナとして読む: そのペルソナの知識レベル・関心・読む動機を踏まえて記事を読む。
3. 感想を返す: ペルソナとしての率直な読後感を返す。

フィードバックの形式

ペルソナの一人称で、読者として感じたことを率直に述べる。チェックリスト的な評価ではなく、読んだ人間のリアルな反応として書く。

含めるとよい観点:

• 読み始めの印象: 冒頭で続きを読みたいと思ったか。どこで引き込まれた（or 離脱しそうになった）か。
• 理解の流れ: 話についていけたか。どこでつまずいたか。飛ばしたくなった箇所はあるか。
• 持ち帰り: 読んで何を得たか。自分の環境で試したいと思ったことはあるか。
• 印象に残った箇所: 具体的にどのフレーズ・エピソード・説明が良かったか。
• 物足りなかった箇所: もっと聞きたかったこと、説明が足りないと感じた箇所。

フィードバックは1回で終わりではない。ユーザーが修正したら再度読んでフィードバックする。ユーザーが満足するまで繰り返す。

Phase 5: 振り返り記録

記事を書くサイクルの中でもっとも重要なフェーズ。ここを回さないと次の記事に改善が反映されない。

記事を書き終えたら writing-log.md にエントリを追加する。このファイルはzenn-contentリポジトリのルートに置く。存在しなければ作成する。

公開前に記録すること

## [記事タイトル](./articles/slug.md)

- 公開日: YYYY-MM-DD
- topics: topic1, topic2
- 型: 謎解き型
- 仮説: この記事がどういう読者に刺さり、なぜ読まれると考えたか
- 狙い: この記事で何を伝えたかったか
- 工夫した点: 文体、構成、タイトルなどで具体的に何を工夫したか
- 広め方: どこに投稿したか（Zennのみ / X共有 / HackerNews / Reddit等）

「仮説」が特に大事。「中上級者のAI活用層に刺さるはず」「タイトルの数字が目を引くはず」など、なぜこの記事が読まれると思ったかを書いておく。仮説がないと、結果が出ても何が良かった/悪かったのか判断できない。

公開後に記録すること

公開から1-2週間後に振り返り、以下を追記する:

- 結果: PV、いいね数、コメント、SNSでの反応
- 仮説の検証: 仮説は当たったか？外れたなら何が想定と違ったか
- 学び: 次の記事に活かせること

次の記事を書くとき

writing-log.md を読んでから始める。過去の仮説と結果を見比べて、何が効いて何が効かなかったかを確認する。同じ失敗を繰り返さず、うまくいったパターンを意識的に再現する。

---

記事の型

素材に合った型を選ぶ。組み合わせも可能。Phase 2の構成案でどの型を使うか提案する。

謎解き型

流れ: 問題発見 → 調査 → 原因特定 → 解決 向いている素材: バグ修正、トラブルシューティング、意外な挙動の発見 読者体験: 探偵のように一緒に謎を追う。原因がわかった瞬間のカタルシスがある。

作ってみた型

流れ: こういうものが欲しかった → 作った → こうなった 向いている素材: ツール開発、自動化、プロジェクト紹介 読者体験: 「なぜ作ったか」への共感と、「自分も作れそう」という刺激。モチベーションを厚めに書く。

比較・選択型

流れ: 選択肢の提示 → 比較 → 判断と結果 向いている素材: 技術選定、ライブラリ比較、設計判断 読者体験: 自分が同じ判断を迫られたときの参考になる。

概念解説型

流れ: 概念の導入 → 具体例で説明 → 応用や含意 向いている素材: 抽象的な考え方、設計パターン、思想 読者体験: 漠然と感じていたことが言語化される。独自の視点があると価値が上がる。

振り返り型

流れ: 期間や活動の概要 → ハイライト深掘り → 学びと次へ 向いている素材: 月次振り返り、複数プロジェクトのまとめ 読者体験: 他人の試行錯誤から学べる。全部を均等に扱わず、2-3個を深掘りしてメリハリをつける。

---

ブランディングの視点

Phase 2の構成案やPhase 3のブリーフで、これらの視点を織り込む:

• 思考プロセスを見せる: 結果だけでなく「なぜそう考えたか」を書く。これが「深く考えている人」という印象を作る。
• 正直に書く: うまくいかなかったことも含めた方が信頼される。失敗談は読者にとってもっとも参考になる。
• 手触り感のあるディテール: 実際に使っている人にしか書けない具体的な体験を入れる。一般論だけの記事との差別化になる。
• 量より継続: 長大な記事を低頻度で出すより、適度な長さの記事を定期的に出す方がブランディングに効く。