otomatty/write-zenn-article

Zenn 記事の執筆スキル

体験ベースで読みやすく、AIっぽさのない技術記事を書く。 詳細なアンチパターンと言い換え例は tone-guide.md を参照。

記事の基本方針

• トーン: 「やってみてこうだった」という実践報告。上から教えるのではなく、同僚に共有する距離感
• 主語: 「自分」「自分たちのチーム」を使う。「我々」「筆者」は使わない
• 文体: 敬体（です・ます調）。体験を端的に語る文や体言止めでリズムを出すのは可
• 読了時間の目安: 1本あたり 8〜12 分（3,000〜5,000 字程度）

絶対に使わないフレーズ（AI臭の排除）

以下は AI が多用しがちな表現。記事に含まれていたら必ず書き換える。

| 使わない表現 | 代わりに使う表現 | | ------------------------------- | ----------------------------------- | | 〜を実現します | 〜できるようにしました | | 本記事では〜を紹介します | この記事では〜を書きます | | 〜することが可能です | 〜できます | | 〜について解説します | 〜について書きます / 〜を共有します | | 非常に重要です | 大事だと感じました / ここが肝でした | | 〜を活用します | 〜を使います | | 〜を実施します / 〜を実行します | 〜をやります / 〜を試します | | 〜が不可欠です | 〜がないと困ります / 〜が要ります | | 〜を網羅的に | まんべんなく / ひと通り | | 〜を包括的に | 全体的に / まとめて | | 〜のメリット・デメリット | 良かった点・困った点 | | 〜に寄与します | 〜に役立ちました | | 〜を担保します | 〜を守れます / 〜を保てます | | 結論として | まとめると | | 〜という課題があります | 〜で困っていました | | 〜が求められます | 〜が要ります | | 〜を通じて | 〜で / 〜をきっかけに | | シームレスに | スムーズに / 自然に |

文章の書き方ルール

1. 体験を先に、一般論は後に

❌ Mutation Testing は重要な手法です。我々のプロジェクトでも導入しました。
✅ Stryker を走らせたら、テスト 109 行で守れていたつもりの Effect が実はザルでした。

具体的な数字やエピソードから入り、読者に「どういうこと？」と思わせてから説明する。

2. 短い文を連ねる

1 文は 60 字以内を目安にする。長い文は 2 つに切る。

❌ AIにテストを書かせるとカバレッジは高いが実質的に何も検証していないテストが
   量産されてしまうという問題に気づいたため、Mutation Testingを導入しました。
✅ AI にテストを書かせると、カバレッジだけは高くなります。
   でも実際にロジックを壊してもテストが落ちません。
   その問題に気づいて Mutation Testing を入れました。

3. 読者への問いかけを入れる

セクションの冒頭で読者を引き込む。

✅ カバレッジ 100% のテスト、信用していいと思いますか？
✅ AI が書いたテスト、本当にバグを見つけてくれるでしょうか。

4. Before / After を見せる

施策の効果は必ず「やる前」と「やった後」のペアで示す。 数字があればなお良い。なくても体感レベルで書く。

✅ テストファイル：109 行 → 887 行。
   コミットメッセージにも「Target Stryker survivors」と書いてあります。
   Mutation Test がなければ、この 2 ケースで安心していたはずです。

5. 図・表・コードは「1 つのことだけ」伝える

コードブロックに長いファイルを貼らない。伝えたい箇所だけ抜粋し、 省略部分は // ... で示す。表のカラムは 3〜4 列まで。

6. 接続詞のバリエーション

「しかし」「また」「さらに」の連打を避ける。

| 避けたい連打 | 代替 | | --------------------- | ------------------------------- | | しかし / しかしながら | でも / ただ / とはいえ / 一方で | | また | それと / あとは / もう一つ | | さらに | 加えて / その上 / ついでに | | そのため | だから / なので / そこで | | なお | ちなみに / 補足すると |

記事の構成テンプレート

---
title: "（体験が伝わる具体的なタイトル）"
emoji: "（内容に合った絵文字 1 つ）"
type: "tech"
topics: ["トピック1", "トピック2", "トピック3"]
published: false
---

## はじめに

（2〜3 文で「自分がどういう状況で何に困っていたか」を書く）
（読者が「あるある」と思える導入にする）

## 問題：〜が起きていた

（困っていたことを具体的に。エピソード・数字があるとベスト）
（参考にした記事があればここで引用）

## やったこと 1: 〜

（施策の説明 → コード例 → Before/After）

## やったこと 2: 〜

（同上。施策が複数ある場合はストーリーとして繋げる）

## やったこと N: 〜

## 結果

（定量データを中心に。表で整理するとわかりやすい）
（「こう変わった」だけでなく「こう感じた」も書く）

## 振り返り

### うまくいったこと

（箇条書き。体験ベースで）

### まだ課題なこと

（正直に書く。完璧なストーリーより信頼される）

## まとめ

（3〜4 文で締める。長い要約は不要）

## 参考

（引用した記事・ツールへのリンク）

推敲チェックリスト

記事を仕上げる前に以下を確認する。

• [ ] タイトルが「やったこと＋結果」を伝えている（抽象的な名詞止めでない）
• [ ] 冒頭 3 行で「何の話か」「なぜ読むべきか」が分かる
• [ ] tone-guide.md の NG フレーズが残っていない
• [ ] 「です・ます」と「だ・である」が混在していない（体言止め・引用除く）
• [ ] コードブロックが 30 行を超えていない（超える場合は分割 or 省略）
• [ ] 表のカラムが 5 列以内
• [ ] 読了 8〜12 分に収まっている（文字数 3,000〜5,000 字目安）
• [ ] Before/After が最低 1 箇所ある
• [ ] 「〜することが可能です」「〜を実現します」「〜が不可欠です」が残っていない
• [ ] 最後に「参考」セクションでリンクを挙げている

出力先

docs/plan/ 配下に Markdown ファイルとして出力する（Git 追跡外）。 ファイル名は zenn-<slug>.md（例: zenn-tdd-mutation-test.md）。