redamoon Zenn技術ブログ執筆スキル
このスキルは、Zennの技術ブログ記事を執筆・レビューする際に使用します。技術的な正確性、読みやすさ、AIっぽい文章の排除を重視したガイドラインを提供します。
When to Use
- Zennの技術記事を執筆・編集する際
- Zenn寄りのMarkdownで個人ブログ記事を執筆・編集する際
- 記事のレビューや品質チェックを行う際
- AIっぽい表現を排除し、自然な日本語表現に修正する際
- 技術的な正確性を確認する際
- コード例や手順の説明を改善する際
文章そのものの推敲（論証の厳密さ、冗長の排除、LLM っぽい表現の排除）は japanese-prose-revision に、緩急やリズムの設計は cognitive-rhythm-writing に従う。
Instructions
記事の基本構造
フロントマター（必須項目）
---
title: "記事のタイトル" # 簡潔で具体的に
emoji: "😸" # アイキャッチ絵文字（1文字のみ）
type: "tech" # tech: 技術記事 / idea: アイデア記事
topics: ["tag1", "tag2", "tag3"] # 3-5個程度、小文字で統一
published: true # true: 公開 / false: 下書き
---
topicsの注意事項
topicsに記号やスペースを使用することはできません。記号を含む技術名は、以下のように記載してください。
- C++ →
cpp - C# →
csharp - .NET →
dotnet - Node.js →
nodejsまたはnode - TypeScript →
typescript（記号なし） - React Native →
reactnativeまたはreact-native（ハイフンは使用可能）
スペースを含む場合は、ハイフンで区切るか、すべて小文字で連結してください。
記事本文の推奨構成
- 導入部: 問題提起や背景を簡潔に説明（2-3段落）
- 本論: 技術的な説明、手順、コード例
- 結び: 冒頭で立てた問いを回収し、読者がすでに持っている具体（冒頭で挙げた場面、読者自身の経験）へ着地させてから、次のステップを提示する（
cognitive-rhythm-writingの「問いの回収と結び」を参照）
上の3項目は記事の構成要素の役割名であり、そのまま見出しに書くものではありません（## 導入部 ## 結び と直書きしない）。見出しは、その節が扱う対象を指す句にします（japanese-prose-revision の「見出しの付け方」を参照）。
文章品質の基準
技術的な正確性
- 技術用語は正確に使用し、初出時に説明を追加
- コード例は動作確認済みのものを使用
- バージョン情報は明記（例: Node.js v20.18.1、npm v10.8.2）
- リンク先のURLは有効であることを確認
- 環境構築手順は再現可能な形で記載
文体（語尾）
- **ですます調（敬体）**を本文の基本とする。説明文・導入・結びは「です・ます」で統一し、読みやすい口語に近い自然な日本語を心がける。
- **である調（常体）**は、箇条書きの短い項、表のセル、コードコメントなどに限ってよい。段落の説明まで常体で続けると硬くなりやすい。同じ記事内で段落レベルの文体が混在しないよう注意する。
- 執筆者の好みで文体を変えてよいが、このリポジトリでは ですます調を推奨する。
明確性と簡潔性
- 1文は60文字以内を執筆時の目安とする（長文は分割）。機械的な上限チェックは textlint の
sentence-length（最大100文字）が担当する - ただし
cognitive-rhythm-writingの「短文化バイアスの禁止」のとおり、必要な文脈共有（範囲、観点、比較軸、未確定事項）を削って短くするのは緩急ではなく欠落である。削らずに分割できないときは60文字を超えてよい - 専門用語は初出時に説明を追加
- 箇条書きを活用して情報を整理
- 受動態より能動態を優先（「〜されます」→「〜します」）
- 文章の末尾は必ず「。」で終わる（「：」は禁止）
実践的な内容
- 実際に動作するコード例を提供
- エラーハンドリングや注意点を明記
- トラブルシューティング情報を含める
- スクリーンショットや図解を適切に使用
- スクリーンショットは Zenn の
=500x記法で幅を指定する（例:）。大きすぎると読みづらいため、設定画面やエディタ画面は 500px 前後を目安にする - 次のステップや参考資料を提示
AIっぽい文章の排除
このプロジェクトでは @textlint-ja/textlint-rule-preset-ai-writing を使用してAIっぽい文章を検出します。
このプリセットが機械的に検出する、以下のパターンを避けてください。
避けるべき表現
- 過剰な強調: 「重要」「注意」などの連続使用
- 誇張表現: 「革命的」「驚異的」「完璧な」などの絶対的表現
- AIっぽいリスト: 絵文字と太字の組み合わせ
- コロン後のブロック: 「実行します:」のような前置きを置かない。見出しにするか、前置きなしでそのまま手順・コードブロックを続ける
- 情報系プレフィックス: 「重要:」「注意:」「警告:」などのパターン
空虚な形容やダッシュ区切りは textlint では検出できません。冒頭で参照した japanese-prose-revision の「LLM っぽい表現の禁止」と「整形」に従ってください。
推奨する表現
- 事実に基づいた説明
- 具体的な数値やデータの提示（「高速な」→「50ms未満の」など）
- 読者が実際に試せる手順の提供
- 自然な日本語表現
- 簡潔で明確な説明
コードブロックの記述
言語指定
- コードブロックには必ず言語を指定（例:
bash,javascript,typescript,python,json） - シェルコマンドは
bashまたはshellを使用 - 実行結果は別のコードブロックで提示
コード例の品質
- 動作確認済みのコードのみを使用
- 不要なコードは省略し、必要な部分のみを提示
- 変数名や関数名は意味のあるものにする
- コメントは日本語で簡潔に
- 複雑なロジックには説明を追加
マークダウンの使用
見出し
- 適切な見出しレベル（
##,###,####）を使用 - 見出し構造は論理的に階層化
- 見出し内での太字は避ける（AIっぽい表現として検出される）
リストと強調
- リストには箇条書き（
-）を使用 - 強調には太字（
**text**）を使用（過剰な使用は避ける） - 技術用語にはコードフォーマット（
`text`）を使用 - 太字を使う場合は、それぞれの間に半角スペースを入れる（例: 超人です）
コード・コマンド表記と太字
- インラインコード（
`path`、`GET /upload`、ファイル名・API パスなど）は、太字で囲まない（**`/upload`**のような書き方はしない）。バッククォートだけで十分区別できる。 - フェンス付きコードブロック（
〜）内も、装飾目的の太字は使わない（言語として有効な記法のときだけ）。 - 見出しや本文にエンドポイント・コマンドを書くときは、基本は バッククォートのみ とする。
リンク
- リンクテキストは具体的に（「こちら」ではなく「公式ドキュメント」など）
- 外部リンクは参考にした記事やドキュメントに必ず貼る
- 内部リンク（関連記事）も適切に設定
- Zennの記事へのリンクは
https://zenn.dev/から始まる形式 - Zenn と note では、単独行に書いた URL（むき出しの URL）が自動的にリンクカード（OGP カード）として表示される。カード表示したい外部 URL は
[テキスト](URL)に整形せず、そのまま 1 行で URL だけ書いてよい。文中で自然に言及するときは従来どおりマークダウンリンクも可
レビュー時のチェックポイント
記事をレビューする際は、以下の観点で確認してください：
技術的な観点
- 技術的な内容が正確か
- コード例が動作するか
- バージョン情報が明記されているか
- 環境構築手順が再現可能か
- エラーハンドリングが適切か
- リンクが有効か
- topicsに記号やスペースが含まれていないか（C++は
cpp、C#はcsharpなど）
文章品質の観点
- textlintでエラーが出ないか（
npm run textlintで確認） - AIっぽい表現がないか
- 文中に
——/—/──のダッシュ区切りがないか - 本文がですます調で統一されているか（このリポジトリの推奨）
- インラインコードやコードブロックに、不要な太字（
**`code`**など）を付けていないか - 専門用語に説明があるか
- 文が長すぎないか（60文字以内が目安。文脈共有を削って短くしていないか）
- 受動態が多すぎないか
- 文章の末尾が「。」で終わっているか
読みやすさの観点
- 見出し構造が適切か（h2, h3の階層）
- 箇条書きが適切に使用されているか
- コードブロックに言語指定があるか
- 画像の配置が適切か
- セクション間に適切なスペースがあるか
実践的な観点
- 読者が実際に試せる内容か
- トラブルシューティング情報があるか
- 次のステップが示されているか
- 参考資料が充実しているか
Cursor関連の記事を書く際の注意事項
Cursorの機能（AGENTS.md、ルール、コマンド、スキル、サブエージェント）について説明する際は、以下の点に注意してください。
用語の正確性
- ルールファイル:
.cursor/rules/配下のファイルは.mdc拡張子を使用 - コマンドファイル:
.cursor/commands/配下のファイルは.md拡張子を使用 - スキル:
.cursor/skills/my-skill/SKILL.mdの形式（フォルダ内にSKILL.mdを含む） - サブエージェント:
.cursor/agents/配下のファイルは.md拡張子を使用
使い分けの説明
- 各方法の違いを明確に説明する
- 具体例を交えて説明する
- 判断フローチャートや比較表を活用する
- 適切な場面で使うべき方法を明確にする
参考リンク
- Cursorの公式ドキュメントへのリンクを必ず含める
- AnthropicのAgent Skillsに関する記事へのリンクを含める
- 関連する技術記事へのリンクも適切に追加する
記事執筆のワークフロー
- 下書き作成:
published: falseで記事を作成 - 執筆: 上記のルールに従って記事を執筆
- ローカルチェック:
npm run textlintでチェック - プレビュー:
npm run previewでZenn CLIでプレビュー - 修正: textlintの指摘を修正
- 公開準備:
published: trueに変更 - コミット: Git commit時に自動チェックが実行される
自動チェックコマンド
npm run textlint: 全記事をチェックnpm run textlint:fix: 全記事をチェックして自動修正可能な箇所を修正
技術ブログとしての心構え
- 読者の視点: 読者が実際に試せる内容を提供
- 正確性: 技術的な情報は必ず確認してから記載
- 継続性: 記事は定期的に更新・メンテナンス
- コミュニティ: コメントやフィードバックに適切に対応